messaging-api-messenger
Version:
Messaging API client for Messenger
434 lines (305 loc) • 21.6 kB
Markdown
# messaging-api-messenger
> Messaging API client for Messenger
<img src="https://static.xx.fbcdn.net/rsrc.php/v3/yh/r/p6_sqYxQ9ch.png" alt="Messenger" width="150" />
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Send API](#send-api)
- [Content Types](#content-types)
- [Templates](#templates)
- [Quick Replies](#quick-replies)
- [Sender Actions](#sender-actions)
- [Attachment Upload API](#attachment-upload-api)
- [Message Batching](#message-batching)
- [Custom Labels](#custom-labels)
- [User Profile API](#user-profile-api)
- [Messenger Profile API](#messenger-profile-api)
- [Persistent Menu](#persistent-menu)
- [Get Started Button](#get-started-button)
- [Greeting Text](#greeting-text)
- [Whitelisted Domains](#domain-whitelist)
- [Account Linking URL](#account-linking-url)
- [Handover Protocol API](#handover-protocol-api)
- [Page Messaging Insights API](#page-messaging-insights-api)
- [Built-in NLP API](#built-in-nlp-api)
- [Event Logging API](#event-logging-api)
- [ID Matching API](#id-matching-api)
- [Persona API](#persona-api)
- [Others](#others)
- [Debug Tips](#debug-tips)
- [Testing](#testing)
## Installation
```sh
npm i --save messaging-api-messenger
```
or
```sh
yarn add messaging-api-messenger
```
<br />
## Usage
### Initialize
```js
const { MessengerClient } = require('messaging-api-messenger');
const client = new MessengerClient({
accessToken: ACCESS_TOKEN,
appId: APP_ID,
appSecret: APP_SECRET,
version: '6.0',
});
```
If the `version` option is not specified, `6.0` will be used by default.
### Verifying Graph API Calls with `appsecret_proof`
If `appSecret` is provided, `MessengerClient` will enable this feature automatically and include `appsecret_proof` in every Graph API requests. To skip it, set the `skipAppSecretProof` option to `true`:
```js
const client = new MessengerClient({
accessToken: ACCESS_TOKEN,
appId: APP_ID,
appSecret: APP_SECRET,
skipAppSecretProof: true,
});
```
### Error Handling
`messaging-api-messenger` uses [axios](https://github.com/axios/axios) as HTTP client. We use [axios-error](https://github.com/Yoctol/messaging-apis/tree/master/packages/axios-error) package to wrap API error instances for better formatting error messages. Directly calling `console.log` with the error instance will return formatted message. If you'd like to get the axios `request`, `response`, or `config`, you can still get them via those keys on the error instance.
```js
client.sendRawBody(body).catch((error) => {
console.log(error); // formatted error message
console.log(error.stack); // error stack trace
console.log(error.config); // axios request config
console.log(error.request); // HTTP request
console.log(error.response); // HTTP response
});
```
<br />
## API Reference
All methods return a Promise.
<br />
<a id="send-api" />
### Send API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference)
- [sendRawBody](/messaging_api_messenger.messengerclient-1.html#sendrawbody)
- [sendMessage](/messaging_api_messenger.messengerclient-1.html#sendmessage)
<a id="content-types" />
### Content Types - [Content types](https://developers.facebook.com/docs/messenger-platform/send-api-reference/contenttypes)
- [sendText](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendtext)
- [sendAttachment](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendattachment)
- [sendAudio](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendaudio)
- [sendImage](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendimage)
- [sendVideo](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendvideo)
- [sendFile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendfile)
<a id="templates" />
### Templates - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/templates)
- [sendTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendtemplate)
- [sendButtonTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendbuttontemplate)
- [sendGenericTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendgenerictemplate)
- [sendMediaTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendmediatemplate)
- [sendReceiptTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendreceipttemplate)
- [sendAirlineBoardingPassTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendairlineboardingpasstemplate)
- [sendAirlineCheckinTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendairlinecheckintemplate)
- [sendAirlineItineraryTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendairlineitinerarytemplate)
- [sendAirlineUpdateTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendairlineupdatetemplate)
- [sendOneTimeNotifReqTemplate](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendonetimenotifreqtemplate)
<br />
<a id="quick-replies" />
### Quick Replies - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies)
<img src="https://user-images.githubusercontent.com/3382565/37411344-91c8ad54-27dd-11e8-82fc-fd9adf896301.png" alt="Quick Replies" width="750" />
To send messages with quick replies to the specified user using the [Send API](https://developers.facebook.com/docs/messenger-platform/reference/send-api#request), pass `quickReplies` option to send message methods, for example, with `sendText`:
```js
await client.sendText(USER_ID, 'Pick a color:', {
quickReplies: [
{
contentType: 'text',
title: 'Red',
payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED',
},
],
});
```
with the `sendImage` option:
```js
await client.sendImage(USER_ID, 'https://example.com/vr.jpg', {
quickReplies: [
{
contentType: 'text',
title: 'Red',
payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED',
},
],
});
```
It works with all of message sending methods.
<br />
<a id="sender-actions" />
### Sender Actions - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/sender-actions)
<img src="https://user-images.githubusercontent.com/3382565/37411363-9b65ecaa-27dd-11e8-8f51-7aac7fd0bd2f.png" alt="Sender Actions" width="250" />
- [sendSenderAction](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendsenderaction)
- [markSeen](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#markseen)
- [typingOn](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#typingon)
- [typingOff](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#typingoff)
<a id="attachment-upload-api" />
### Attachment Upload API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/attachment-upload)
> Note: Only attachments that were uploaded with the `isReusable` property set to `true` can be sent to other message recipients.
- [uploadAttachment](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#uploadattachment)
- [uploadAudio](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#uploadaudio)
- [uploadImage](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#uploadimage)
- [uploadVideo](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#uploadvideo)
- [uploadFile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#uploadfile)
<br />
<a id="message-batching" />
### Message Batching - [Official Docs](https://developers.facebook.com/docs/graph-api/making-multiple-requests)
- [sendBatch](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#sendbatch)
There are a bunch of factory methods can be used to create batch requests:
- `MessengerBatch.sendRequest`
- `MessengerBatch.sendMessage`
- `MessengerBatch.sendText`
- `MessengerBatch.sendAttachment`
- `MessengerBatch.sendAudio`
- `MessengerBatch.sendImage`
- `MessengerBatch.sendVideo`
- `MessengerBatch.sendFile`
- `MessengerBatch.sendTemplate`
- `MessengerBatch.sendButtonTemplate`
- `MessengerBatch.sendGenericTemplate`
- `MessengerBatch.sendReceiptTemplate`
- `MessengerBatch.sendMediaTemplate`
- `MessengerBatch.sendAirlineBoardingPassTemplate`
- `MessengerBatch.sendAirlineCheckinTemplate`
- `MessengerBatch.sendAirlineItineraryTemplate`
- `MessengerBatch.sendAirlineUpdateTemplate`
- `MessengerBatch.sendSenderAction`
- `MessengerBatch.typingOn`
- `MessengerBatch.typingOff`
- `MessengerBatch.markSeen`
- `MessengerBatch.getUserProfile`
- `MessengerBatch.passThreadControl`
- `MessengerBatch.passThreadControlToPageInbox`
- `MessengerBatch.takeThreadControl`
- `MessengerBatch.requestThreadControl`
- `MessengerBatch.associateLabel`
- `MessengerBatch.dissociateLabel`
- `MessengerBatch.getAssociatedLabels`
Those methods have exactly same argument signature with the methods on client.
<br />
<a id="custom-labels" />
### Custom Labels - [Official Docs](https://developers.facebook.com/docs/messenger-platform/identity/custom-labels)
- [createLabel](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#createlabel)
- [associateLabel](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#associatelabel)
- [dissociateLabel](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#dissociatelabel)
- [getAssociatedLabels](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getassociatedlabels)
- [getLabelDetails](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getlabeldetails)
- [getLabelList](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getlabellist)
- [deleteLabel](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletelabel)
<br />
<a id="user-profile-api" />
### User Profile API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/user-profile)
- [getUserProfile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getuserprofile)
<br />
<a id="messenger-profile-api" />
### Messenger Profile API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile)
- [getMessengerProfile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getmessengerprofile)
- [setMessengerProfile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setmessengerprofile)
- [deleteMessengerProfile](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletemessengerprofile)
<a id="persistent-menu" />
### Persistent Menu - [Official Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu)
- [getPersistentMenu](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getpersistentmenu)
- [setPersistentMenu](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setpersistentmenu)
- [deletePersistentMenu](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletepersistentmenu)
<a id="get-started-button" />
### Get Started Button - [Official Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/get-started-button)
<img src="https://scontent-tpe1-1.xx.fbcdn.net/v/t39.2365-6/14302685_243106819419381_1314180151_n.png?oh=9487042d8c0067eb2fda1efa45d0e17b&oe=59F7185C" alt="Get Started Button" width="500" />
- [getGetStarted](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getgetstarted)
- [setGetStarted](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setgetstarted)
- [deleteGetStarted](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletegetstarted)
<a id="greeting-text" />
### Greeting Text - [Officail docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text)
<img src="https://scontent-tpe1-1.xx.fbcdn.net/v/t39.2365-6/14287888_188235318253964_1078929636_n.png?oh=a1171ab50f04d3a244ed703eafd2dbef&oe=59F01AF5" alt="Greeting Text" width="250" />
- [getGreeting](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getgreeting)
- [setGreeting](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setgreeting)
- [deleteGreeting](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletegreeting)
<a id="domain-whitelist" />
### Whitelisted Domains - [Official Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/domain-whitelisting)
- [getWhitelistedDomains](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getwhitelisteddomains)
- [setWhitelistedDomains](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setwhitelisteddomains)
- [deleteWhitelistedDomains](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletewhitelisteddomains)
<a id="account-linking-url" />
### Account Linking URL - [Official Docs](https://developers.facebook.com/docs/messenger-platform/reference/messenger-profile-api/account-linking-url)
- [getAccountLinkingURL](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getaccountlinkingurl)
- [setAccountLinkingURL](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setaccountlinkingurl)
- [deleteAccountLinkingURL](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deleteaccountlinkingurl)
### Handover Protocol API
- [passThreadControl](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#passthreadcontrol)
- [passThreadControlToPageInbox](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#passthreadcontroltopageinbox)
- [takeThreadControl](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#takethreadcontrol)
- [requestThreadControl](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#requestthreadcontrol)
- [getThreadOwner](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getthreadowner)
- [getSecondaryReceivers](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getsecondaryreceivers)
<br />
<a id="page-messaging-insights-api" />
### Page Messaging Insights API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/insights/page-messaging)
Requirements for insights API:
- The page token must have `read_insights` permission.
- Insights are only generated for a Facebook Page that has more than `30` people that like it.
- [getInsights](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getinsights)
- [getBlockedConversations](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getblockedconversations)
- [getReportedConversations](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getreportedconversations)
- [getTotalMessagingConnections](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#gettotalmessagingconnections)
- [getNewConversations](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getnewconversations)
<br />
<a id="built-in-nlp-api" />
### Built-in NLP API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/built-in-nlp)
- [setNLPConfigs](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#setnlpconfigs)
- [enableNLP](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#enablenlp)
- [disableNLP](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#disablenlp)
<br />
<a id="event-logging-api" />
### Event Logging API - [Official Docs](https://developers.facebook.com/docs/app-events/bots-for-messenger#logging-custom-events)
- [logCustomEvents](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#logcustomevents)
<a id="id-matching-api" />
### ID Matching API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/identity/id-matching)
- [getIdsForApps](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getidsforapps)
- [getIdsForPages](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getidsforpages)
<br />
<a id="persona-api" />
### Persona API - [Official Docs](https://developers.facebook.com/docs/messenger-platform/send-messages/personas)
- [createPersona](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#createpersona)
- [getPersona](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getpersona)
- [getPersonas](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getpersonas)
- [getAllPersonas](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getallpersonas)
- [deletePersona](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#deletepersona)
<br />
### Others
- [debugToken](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#debugtoken)
- [createSubscription](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#createsubscription)
- [getSubscriptions](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getsubscriptions)
- [getPageSubscription](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getpagesubscription)
- [getPageInfo](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getpageinfo)
- [getMessagingFeatureReview](https://yoctol.github.io/messaging-apis/latest/classes/messaging_api_messenger.messengerclient-1.html#getmessagingfeaturereview)
<br />
## Debug Tips
### Log Requests Details
To enable default request debugger, use following `DEBUG` env variable:
```sh
DEBUG=messaging-api:request
```
If you want to use a custom request logging function, just provide your own `onRequest`:
```js
const client = new MessengerClient({
accessToken: ACCESS_TOKEN,
onRequest: ({ method, url, headers, body }) => {
/* */
},
});
```
## Testing
### Point Requests to Your Dummy Server
To avoid sending requests to real Messenger server, specify the `origin` option when constructing your client:
```js
const { MessengerClient } = require('messaging-api-messenger');
const client = new MessengerClient({
accessToken: ACCESS_TOKEN,
origin: 'https://mydummytestserver.com',
});
```
> Warning: Don't do this on your production server.
[send-api-reference#recipient]: https://developers.facebook.com/docs/messenger-platform/send-api-reference#recipient