Version: 1.5

MessengerClient

Usage
Methods
Debug Tips
Test

Usage

Get the MessengerClient instance using the getClient function:

const { getClient } = require('bottender');

const client = getClient('messenger');

// `client` is a `MessengerClient` instance
await client.sendRawBody(body);

Or, get the MessengerClient instance from the context:

async function MyAction(context) {
  if (context.platform === 'messenger') {
    // `context.client` is a `MessengerClient` instance
    await context.client.sendRawBody(body);
  }
}

Error Handling

MessengerClient uses axios as HTTP client. We use axios-error package to wrap API error instances for better formatting error messages. Calling console.log with the error instance returns the 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.

client.sendRawBody(body).catch((error) => {
  console.log(error); // the formatted error message
  console.log(error.stack); // stack trace of the error
  console.log(error.config); // axios request config
  console.log(error.request); // axios HTTP request
  console.log(error.response); // axios HTTP response
});

Methods

All methods return a Promise.

Send API - Official Docs

`sendRawBody(body)`

Send request raw body using the Send API.

Param	Type	Description
body	`Object`	Raw body to be sent.

Example:

client.sendRawBody({
  recipient: {
    id: USER_ID,
  },
  message: {
    text: 'Hello!',
  },
});

`sendMessage(userId, message [, options])`

Send messages to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
message	`Object`	message object.
options	`Object`	Other optional parameters. For example, messaging types or tags.

Example:

client.sendMessage(USER_ID, {
  text: 'Hello!',
});

You can specify messaging type using options. If messagingType and tag is not provided, UPDATE will be used as default messaging type.

Example:

client.sendMessage(
  USER_ID,
  {
    text: 'Hello!',
  },
  {
    messagingType: 'RESPONSE',
  }
);

Available messaging types:

UPDATE as default
RESPONSE using { messagingType: 'RESPONSE' } options
MESSAGE_TAG using { tag: 'ANY_TAG' } options

Content Types - Content types

`sendText(userId, text [, options])`

Send plain text messages to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
text	`String`	Text of the message to be sent.
options	`Object`	Other optional parameters. For example, messaging types or tags.

Example:

client.sendText(USER_ID, 'Hello!', { tag: 'CONFIRMED_EVENT_UPDATE' });

`sendAttachment(userId, attachment [, options])`

Send attachment messages to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
attachment	`Object`	attachment object.
options	`Object`	Other optional parameters. For example, messaging types or tags.
options.filename	`String`	Required when upload from buffer.

Example:

client.sendAttachment(USER_ID, {
  type: 'image',
  payload: {
    url: 'https://example.com/pic.png',
  },
});

`sendAudio(userId, audio [, options])`

Send sounds to specified user by uploading them or sharing a URL using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
audio	`String \| Buffer \| ReadStream \| AttachmentPayload`	The audio to be sent.
options	`Object`	Other optional parameters. For example, messaging types.
options.filename	`String`	Required when upload from buffer.

Example:

Send audio using a URL string:

client.sendAudio(USER_ID, 'https://example.com/audio.mp3');

Use AttachmentPayload to send cached attachment:

client.sendAudio(USER_ID, { attachmentId: '55688' });

Use ReadStream created from local file:

const fs = require('fs');

client.sendAudio(USER_ID, fs.createReadStream('audio.mp3'));

Use Buffer to send attachment:

client.sendAudio(USER_ID, buffer, { filename: 'audio.mp3' });

`sendImage(userId, image [, options])`

Send images to specified user by uploading them or sharing a URL using the Send API. Supported formats are jpg, png and gif.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
image	`String \| Buffer \| ReadStream \| AttachmentPayload`	The image to be sent.
options	`Object`	Other optional parameters. For example, messaging types.
options.filename	`String`	Required when upload from buffer.

Example:

Send image using a URL string:

client.sendImage(USER_ID, 'https://example.com/vr.jpg');

Use AttachmentPayload to send cached attachment:

client.sendImage(USER_ID, { attachmentId: '55688' });

Use ReadStream created from local file:

const fs = require('fs');

client.sendImage(USER_ID, fs.createReadStream('vr.jpg'));

Use Buffer to send attachment:

client.sendImage(USER_ID, buffer, { filename: 'vr.jpg' });

`sendVideo(userId, video [, options])`

Send videos to specified user by uploading them or sharing a URL using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
video	`String \| Buffer \| ReadStream \| AttachmentPayload`	The video to be sent.
options	`Object`	Other optional parameters. For example, messaging types.
options.filename	`String`	Required when upload from buffer.

Example:

Send video using a URL string:

client.sendVideo(USER_ID, 'https://example.com/video.mp4');

Use AttachmentPayload to send cached attachment:

client.sendVideo(USER_ID, { attachmentId: '55688' });

Use ReadStream created from local file:

const fs = require('fs');

client.sendVideo(USER_ID, fs.createReadStream('video.mp4'));

Use Buffer to send attachment:

client.sendVideo(USER_ID, buffer, { filename: 'video.mp4' });

`sendFile(userId, file [, options])`

Send files to specified user by uploading them or sharing a URL using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
file	`String \| Buffer \| ReadStream \| AttachmentPayload`	The file to be sent.
options	`Object`	Other optional parameters. For example, messaging types.
options.filename	`String`	Required when upload from buffer.

Example:

Send file using a URL string:

client.sendFile(USER_ID, 'https://example.com/receipt.pdf');

Use AttachmentPayload to send cached attachment:

client.sendFile(USER_ID, { attachmentId: '55688' });

Use ReadStream created from local file:

const fs = require('fs');

client.sendFile(USER_ID, fs.createReadStream('receipt.pdf'));

Use Buffer to send attachment:

client.sendFile(USER_ID, buffer, { filename: 'file.pdf' });

Templates - Official Docs

`sendTemplate(userId, template [, options])`

Send structured message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
template	`Object`	Object of the template.
options	`Object`	Other optional parameters. For example, messaging types or tags.

Example:

client.sendTemplate(USER_ID, {
  templateType: 'button',
  text: 'title',
  buttons: [
    {
      type: 'postback',
      title: 'Start Chatting',
      payload: 'USER_DEFINED_PAYLOAD',
    },
  ],
});

`sendButtonTemplate(userId, title, buttons [, options])` - Official Docs

Send button message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
title	`String`	Text that appears above the buttons.
buttons	`Array<Object>`	Array of button. Set of 1-3 buttons that appear as call-to-actions.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendButtonTemplate(USER_ID, 'What do you want to do next?', [
  {
    type: 'web_url',
    url: 'https://petersapparel.parseapp.com',
    title: 'Show Website',
  },
  {
    type: 'postback',
    title: 'Start Chatting',
    payload: 'USER_DEFINED_PAYLOAD',
  },
]);

`sendGenericTemplate(userId, elements [, options])` - Official Docs

Send generic message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
elements	`Array<Object>`	Array of element. Data for each bubble in message.
options	`Object`	Other optional parameters, such as `imageAspectRatio`, messaging types and tags.

Example:

client.sendGenericTemplate(
  USER_ID,
  [
    {
      title: "Welcome to Peter's Hats",
      imageUrl: 'https://petersfancybrownhats.com/company_image.png',
      subtitle: "We've got the right hat for everyone.",
      defaultAction: {
        type: 'web_url',
        url: 'https://peterssendreceiveapp.ngrok.io/view?item=103',
        messengerExtensions: true,
        webviewHeightRatio: 'tall',
        fallbackUrl: 'https://peterssendreceiveapp.ngrok.io/',
      },
      buttons: [
        {
          type: 'postback',
          title: 'Start Chatting',
          payload: 'DEVELOPER_DEFINED_PAYLOAD',
        },
      ],
    },
  ],
  { imageAspectRatio: 'square' }
);

Adding a tag to a message allows you to send it outside the 24+1 window, for a limited number of use cases, per Messenger Platform policy.

Example:

client.sendGenericTemplate(
  USER_ID,
  [
    {
      // ...
    },
  ],
  { tag: 'CONFIRMED_EVENT_UPDATE' }
);

Available tags:

CONFIRMED_EVENT_UPDATE
POST_PURCHASE_UPDATE
ACCOUNT_UPDATE
HUMAN_AGENT (Closed BETA)

`sendMediaTemplate(userId, elements [, options])` - Official Docs

Send media message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
elements	`Array<Object>`	Array of element. Only one element is allowed.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendMediaTemplate(USER_ID, [
  {
    mediaType: 'image',
    attachmentId: '1854626884821032',
    buttons: [
      {
        type: 'web_url',
        url: 'https://en.wikipedia.org/wiki/Rickrolling',
        title: 'View Website',
      },
    ],
  },
]);

`sendReceiptTemplate(userId, receipt [, options])` - Official Docs

Send receipt message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
receipt	`Object`	payload of receipt template.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendReceiptTemplate(USER_ID, {
  recipientName: 'Stephane Crozatier',
  orderNumber: '12345678902',
  currency: 'USD',
  paymentMethod: 'Visa 2345',
  orderUrl: 'http://petersapparel.parseapp.com/order?order_id=123456',
  timestamp: '1428444852',
  elements: [
    {
      title: 'Classic White T-Shirt',
      subtitle: '100% Soft and Luxurious Cotton',
      quantity: 2,
      price: 50,
      currency: 'USD',
      imageUrl: 'http://petersapparel.parseapp.com/img/whiteshirt.png',
    },
    {
      title: 'Classic Gray T-Shirt',
      subtitle: '100% Soft and Luxurious Cotton',
      quantity: 1,
      price: 25,
      currency: 'USD',
      imageUrl: 'http://petersapparel.parseapp.com/img/grayshirt.png',
    },
  ],
  address: {
    street1: '1 Hacker Way',
    street2: '',
    city: 'Menlo Park',
    postalCode: '94025',
    state: 'CA',
    country: 'US',
  },
  summary: {
    subtotal: 75.0,
    shippingCost: 4.95,
    totalTax: 6.19,
    totalCost: 56.14,
  },
  adjustments: [
    {
      name: 'New Customer Discount',
      amount: 20,
    },
    {
      name: '$10 Off Coupon',
      amount: 10,
    },
  ],
});

`sendAirlineBoardingPassTemplate(userId, attributes [, options])` - Official Docs

Send airline boarding pass message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
attributes	`Object`	payload of boarding pass template.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendAirlineBoardingPassTemplate(RECIPIENT_ID, {
  introMessage: 'You are checked in.',
  locale: 'en_US',
  boardingPass: [
    {
      passengerName: 'SMITH/NICOLAS',
      pnrNumber: 'CG4X7U',
      travelClass: 'business',
      seat: '74J',
      auxiliaryFields: [
        {
          label: 'Terminal',
          value: 'T1',
        },
        {
          label: 'Departure',
          value: '30OCT 19:05',
        },
      ],
      secondaryFields: [
        {
          label: 'Boarding',
          value: '18:30',
        },
        {
          label: 'Gate',
          value: 'D57',
        },
        {
          label: 'Seat',
          value: '74J',
        },
        {
          label: 'Sec.Nr.',
          value: '003',
        },
      ],
      logoImageUrl: 'https://www.example.com/en/logo.png',
      headerImageUrl: 'https://www.example.com/en/fb/header.png',
      qrCode: 'M1SMITH/NICOLAS  CG4X7U nawouehgawgnapwi3jfa0wfh',
      aboveBarCodeImageUrl: 'https://www.example.com/en/PLAT.png',
      flightInfo: {
        flightNumber: 'KL0642',
        departureAirport: {
          airportCode: 'JFK',
          city: 'New York',
          terminal: 'T1',
          gate: 'D57',
        },
        arrivalAirport: {
          airportCode: 'AMS',
          city: 'Amsterdam',
        },
        flightSchedule: {
          departureTime: '2016-01-02T19:05',
          arrivalTime: '2016-01-05T17:30',
        },
      },
    },
    {
      passengerName: 'JONES/FARBOUND',
      pnrNumber: 'CG4X7U',
      travelClass: 'business',
      seat: '74K',
      auxiliaryFields: [
        {
          label: 'Terminal',
          value: 'T1',
        },
        {
          label: 'Departure',
          value: '30OCT 19:05',
        },
      ],
      secondaryFields: [
        {
          label: 'Boarding',
          value: '18:30',
        },
        {
          label: 'Gate',
          value: 'D57',
        },
        {
          label: 'Seat',
          value: '74K',
        },
        {
          label: 'Sec.Nr.',
          value: '004',
        },
      ],
      logoImageUrl: 'https://www.example.com/en/logo.png',
      headerImageUrl: 'https://www.example.com/en/fb/header.png',
      qrCode: 'M1JONES/FARBOUND  CG4X7U nawouehgawgnapwi3jfa0wfh',
      aboveBarCodeImageUrl: 'https://www.example.com/en/PLAT.png',
      flightInfo: {
        flightNumber: 'KL0642',
        departureAirport: {
          airportCode: 'JFK',
          city: 'New York',
          terminal: 'T1',
          gate: 'D57',
        },
        arrivalAirport: {
          airportCode: 'AMS',
          city: 'Amsterdam',
        },
        flightSchedule: {
          departureTime: '2016-01-02T19:05',
          arrivalTime: '2016-01-05T17:30',
        },
      },
    },
  ],
});

`sendAirlineCheckinTemplate(userId, attributes [, options])` - Official Docs

Send airline checkin message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
attributes	`Object`	payload of checkin template.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendAirlineCheckinTemplate(USER_ID, {
  introMessage: 'Check-in is available now.',
  locale: 'en_US',
  pnrNumber: 'ABCDEF',
  flightInfo: [
    {
      flightNumber: 'f001',
      departureAirport: {
        airportCode: 'SFO',
        city: 'San Francisco',
        terminal: 'T4',
        gate: 'G8',
      },
      arrivalAirport: {
        airportCode: 'SEA',
        city: 'Seattle',
        terminal: 'T4',
        gate: 'G8',
      },
      flightSchedule: {
        boardingTime: '2016-01-05T15:05',
        departureTime: '2016-01-05T15:45',
        arrivalTime: '2016-01-05T17:30',
      },
    },
  ],
  checkinUrl: 'https://www.airline.com/check-in',
});

`sendAirlineItineraryTemplate(userId, attributes [, options])` - Official Docs

Send airline itinerary message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
attributes	`Object`	payload of itinerary template.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendAirlineItineraryTemplate(USER_ID, {
  introMessage: "Here's your flight itinerary.",
  locale: 'en_US',
  pnrNumber: 'ABCDEF',
  passengerInfo: [
    {
      name: 'Farbound Smith Jr',
      ticketNumber: '0741234567890',
      passengerId: 'p001',
    },
    {
      name: 'Nick Jones',
      ticketNumber: '0741234567891',
      passengerId: 'p002',
    },
  ],
  flightInfo: [
    {
      connectionId: 'c001',
      segmentId: 's001',
      flightNumber: 'KL9123',
      aircraftType: 'Boeing 737',
      departureAirport: {
        airportCode: 'SFO',
        city: 'San Francisco',
        terminal: 'T4',
        gate: 'G8',
      },
      arrivalAirport: {
        airportCode: 'SLC',
        city: 'Salt Lake City',
        terminal: 'T4',
        gate: 'G8',
      },
      flightSchedule: {
        departureTime: '2016-01-02T19:45',
        arrivalTime: '2016-01-02T21:20',
      },
      travelClass: 'business',
    },
    {
      connectionId: 'c002',
      segmentId: 's002',
      flightNumber: 'KL321',
      aircraftType: 'Boeing 747-200',
      travelClass: 'business',
      departureAirport: {
        airportCode: 'SLC',
        city: 'Salt Lake City',
        terminal: 'T1',
        gate: 'G33',
      },
      arrivalAirport: {
        airportCode: 'AMS',
        city: 'Amsterdam',
        terminal: 'T1',
        gate: 'G33',
      },
      flightSchedule: {
        departureTime: '2016-01-02T22:45',
        arrivalTime: '2016-01-03T17:20',
      },
    },
  ],
  passengerSegmentInfo: [
    {
      segmentId: 's001',
      passengerId: 'p001',
      seat: '12A',
      seatType: 'Business',
    },
    {
      segmentId: 's001',
      passengerId: 'p002',
      seat: '12B',
      seatType: 'Business',
    },
    {
      segmentId: 's002',
      passengerId: 'p001',
      seat: '73A',
      seatType: 'World Business',
      productInfo: [
        {
          title: 'Lounge',
          value: 'Complimentary lounge access',
        },
        {
          title: 'Baggage',
          value: '1 extra bag 50lbs',
        },
      ],
    },
    {
      segmentId: 's002',
      passengerId: 'p002',
      seat: '73B',
      seatType: 'World Business',
      productInfo: [
        {
          title: 'Lounge',
          value: 'Complimentary lounge access',
        },
        {
          title: 'Baggage',
          value: '1 extra bag 50lbs',
        },
      ],
    },
  ],
  priceInfo: [
    {
      title: 'Fuel surcharge',
      amount: '1597',
      currency: 'USD',
    },
  ],
  basePrice: '12206',
  tax: '200',
  totalPrice: '14003',
  currency: 'USD',
});

`sendAirlineUpdateTemplate(userId, attributes [, options])` - Official Docs

Send airline flight update message templates to specified user using the Send API.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
attributes	`Object`	payload of update template.
options	`Object`	Other optional parameters. For example, messaging types.

Example:

client.sendAirlineUpdateTemplate(USER_ID, {
  introMessage: 'Your flight is delayed',
  updateType: 'delay',
  locale: 'en_US',
  pnrNumber: 'CF23G2',
  updateFlightInfo: {
    flightNumber: 'KL123',
    departureAirport: {
      airportCode: 'SFO',
      city: 'San Francisco',
      terminal: 'T4',
      gate: 'G8',
    },
    arrivalAirport: {
      airportCode: 'AMS',
      city: 'Amsterdam',
      terminal: 'T4',
      gate: 'G8',
    },
    flightSchedule: {
      boardingTime: '2015-12-26T10:30',
      departureTime: '2015-12-26T11:30',
      arrivalTime: '2015-12-27T07:30',
    },
  },
});

Quick Replies - Official Docs

To send messages with quick replies to specified user using the Send API, pass quickReplies option to send message methods, for example, with sendText:

client.sendText(USER_ID, 'Pick a color:', {
  quickReplies: [
    {
      contentType: 'text',
      title: 'Red',
      payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED',
    },
  ],
});

with sendImage:

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 send message methods.

Sender Actions - Official Docs

`sendSenderAction(userId, action)`

Send sender actions to specified user using the Send API, to let users know you are processing their request.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.
action	`String`	Name of the action.

Example:

client.sendSenderAction(USER_ID, 'typing_on');

`markSeen(userId)`

Mark last message as read for specified user.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.

Example:

client.markSeen(USER_ID);

`typingOn(userId)`

Turn typing indicators on for specified user.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.

Example:

client.typingOn(USER_ID);

`typingOff(userId)`

Turn typing indicators off for specified user.

Param	Type	Description
userId	`String \| Object`	Page-scoped user ID of the recipient or recipient object.

Example:

client.typingOff(USER_ID);

Attachment Upload API - Official Docs

Note: Only attachments that were uploaded with the isReusable property set to true can be sent to other message recipients.

`uploadAttachment(type, attachment, options)`

Upload specified type attachment using URL address, buffer, or stream.

Param	Type	Description
type	`String`	Must be one of `image`, `video`, `audio` or `file`.
attachment	`String \| Buffer \| ReadStream`	Attachment to be uploaded.
options	`Object`	Other optional parameters.
options.isReusable	Set to `true` to make the saved asset sendable to other message recipients. Defaults to `false`.
options.filename	Required when upload from buffer.

Example:

client.uploadAttachment('image', 'http://www.example.com/image.jpg', {
  isReusable: true,
});

Or using read stream:

const fs = require('fs');

client.uploadAttachment('image', fs.createReadStream('image.jpg'), {
  isReusable: true,
});

Or using buffer:

client.uploadAttachment('image', buffer, {
  isReusable: true,
  filename: 'image.jpg',
});

`uploadAudio(audio, options)`

Upload audio attachment using URL address, buffer, or stream.

Param	Type	Description
audio	`String \| Buffer \| ReadStream`	The audio to be uploaded.
options	`Object`	Other optional parameters.

Example:

client.uploadAudio('http://www.example.com/audio.mp3', { isReusable: true });

Or using read stream:

const fs = require('fs');

client.uploadAudio(fs.createReadStream('audio.mp3'), { isReusable: true });

Or using buffer:

client.uploadAudio(buffer, {
  isReusable: true,
  filename: 'audio.mp3',
});

`uploadImage(image, options)`

Upload image attachment using URL address, buffer, or stream.

Param	Type	Description
image	`String \| Buffer \| ReadStream`	The image to be uploaded.
options	`Object`	Other optional parameters.

Example:

client.uploadImage('http://www.example.com/image.jpg', { isReusable: true });

Or using read stream:

const fs = require('fs');

client.uploadImage(fs.createReadStream('image.jpg'), { isReusable: true });

Or using buffer:

client.uploadImage(buffer, {
  isReusable: true,
  filename: 'image.jpg',
});

`uploadVideo(video, options)`

Upload video attachment using URL address, buffer, or stream.

Param	Type	Description
video	`String \| Buffer \| ReadStream`	The video to be uploaded.
options	`Object`	Other optional parameters.

Example:

client.uploadVideo('http://www.example.com/video.mp4', { isReusable: true });

Or using read stream:

const fs = require('fs');

client.uploadVideo(fs.createReadStream('video.mp4'), { isReusable: true });

Or using buffer:

client.uploadVideo(buffer, {
  isReusable: true,
  filename: 'video.mp4',
});

`uploadFile(file, options)`

Upload file attachment using URL address, buffer, or stream.

Param	Type	Description
file	`String \| Buffer \| ReadStream`	The file to be uploaded.
options	`Object`	Other optional parameters.

Example:

client.uploadFile('http://www.example.com/file.pdf', { isReusable: true });

Or using read stream:

const fs = require('fs');

client.uploadFile(fs.createReadStream('file.pdf'), { isReusable: true });

Or using buffer:

client.uploadFile(buffer, {
  isReusable: true,
  filename: 'file.pdf',
});

Message Batching - Official Docs

`sendBatch(requests)`

Sends multiple requests in one batch.

Param	Type	Description
requests	`Array<Object>`	Subrequests in the batch.

Example

const { MessengerBatch } = require('messaging-api-messenger');

client.sendBatch([
  MessengerBatch.sendText(USER_ID, '1'),
  MessengerBatch.sendText(USER_ID, '2'),
  MessengerBatch.sendText(USER_ID, '3'),
  MessengerBatch.sendText(USER_ID, '4'),
  MessengerBatch.sendText(USER_ID, '5'),
]);

There are a bunch of factory methods can be used to create batch messages:

MessengerBatch.sendRequest
MessengerBatch.sendMessage
MessengerBatch.sendText
MessengerBatch.sendAttachment
MessengerBatch.sendAudio
MessengerBatch.sendImage
MessengerBatch.sendVideo
MessengerBatch.sendFile
MessengerBatch.sendTemplate
MessengerBatch.sendButtonTemplate
MessengerBatch.sendGenericTemplate
MessengerBatch.sendListTemplate
MessengerBatch.sendOpenGraphTemplate
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 exactly have same argument signature with client methods.

Custom Labels - Official Docs

`createLabel(name)`

Creating a Label.

Param	Type	Description
name	`String`	name of the custom label.

Example:

client.createLabel('awesome').then((label) => {
  console.log(label);
  // {
  //   id: 1712444532121303
  // }
});

`associateLabel(userId, labelId)`

Associating a Label to a PSID.

Param	Type	Description
userId	`String`	Page-scoped user ID of the recipient.
labelId	`String`	ID of the custom label.

Example:

client.associateLabel(USER_ID, LABEL_ID);

`dissociateLabel(userId, labelId)`

Removing a Label From a PSID.

Param	Type	Description
userId	`String`	Page-scoped user ID of the recipient.
labelId	`String`	ID of the custom label.

Example:

client.dissociateLabel(USER_ID, LABEL_ID);

`getAssociatedLabels(userId)`

Retrieving Labels Associated with a PSID.

Param	Type	Description
userId	`String`	Page-scoped user ID of the recipient.

Example:

client.getAssociatedLabels(USER_ID).then((result) => {
  console.log(result);
  // {
  //   data: [
  //     {
  //       name: 'myLabel',
  //       id: '1001200005003',
  //     },
  //     {
  //       name: 'myOtherLabel',
  //       id: '1001200005002',
  //     },
  //   ],
  //   paging: {
  //     cursors: {
  //       before:
  //         'QVFIUmx1WTBpMGpJWXprYzVYaVhabW55dVpycko4U2xURGE5ODNtNFZAPal94a1hTUnNVMUtoMVVoTzlzSDktUkMtQkUzWEFLSXlMS3ZALYUw3TURLelZAPOGVR',
  //       after:
  //         'QVFIUmItNkpTbjVzakxFWGRydzdaVUFNNnNPaUl0SmwzVHN5ZAWZAEQ3lZANDAzTXFIM0NHbHdYSkQ5OG1GaEozdjkzRmxpUFhxTDl4ZAlBibnE4LWt1eGlTa3Bn',
  //     },
  //   },
  // }
});

`getLabelDetails(labelId, options)`

Retrieving Label Details.

Param	Type	Description
labelId	`String`	ID of the custom label.
options.fields	`Array<String>`	fields to retrieve with its ID.

Example:

client.getLabelDetails(LABEL_ID, { fields: ['name'] }).then((result) => {
  console.log(result);
  // {
  //   id: "1001200005002",
  //   name: "myLabel",
  // }
});

`getLabelList()`

Retrieving a List of All Labels.

Example:

client.getLabelList().then((result) => {
  console.log(result);
  // {
  //   data: [
  //     {
  //       name: 'myLabel',
  //       id: '1001200005003',
  //     },
  //     {
  //       name: 'myOtherLabel',
  //       id: '1001200005002',
  //     },
  //   ],
  //   paging: {
  //     cursors: {
  //       before:
  //         'QVFIUmx1WTBpMGpJWXprYzVYaVhabW55dVpycko4U2xURGE5ODNtNFZAPal94a1hTUnNVMUtoMVVoTzlzSDktUkMtQkUzWEFLSXlMS3ZALYUw3TURLelZAPOGVR',
  //       after:
  //         'QVFIUmItNkpTbjVzakxFWGRydzdaVUFNNnNPaUl0SmwzVHN5ZAWZAEQ3lZANDAzTXFIM0NHbHdYSkQ5OG1GaEozdjkzRmxpUFhxTDl4ZAlBibnE4LWt1eGlTa3Bn',
  //     },
  //   },
  // }
});

`deleteLabel(labelId)`

Deleting a Label.

Param	Type	Description
labelId	`String`	ID of the custom label.

Example:

client.deleteLabel(LABEL_ID);

User Profile API - Official Docs

`getUserProfile(userId, options)`

Retrieving a Person's Profile.

Param	Type	Description
userId	`String`	Page-scoped user ID of the recipient.
options.fields	`Array<String>`	Value must be among `id`, `name`, `first_name`, `last_name`, `profile_pic`, `locale`, `timezone`, `gender`, default with `id`, `name`, `first_name`, `last_name`, `profile_pic`,

Example:

client.getUserProfile(USER_ID).then((user) => {
  console.log(user);
  // {
  //   id: '5566'
  //   firstName: 'Johnathan',
  //   lastName: 'Jackson',
  //   profilePic: 'https://example.com/pic.png',
  // }
});

Messenger Profile API - Official Docs

`getMessengerProfile(fields)`

Retrieves the current value of one or more Messenger Profile properties by name.

Param	Type	Description
fields	`Array<String>`	Value must be among `account_linking_url`, `persistent_menu`, `get_started`, `greeting`, `whitelisted_domains`, `target_audience`, `home_url`.

Example:

client
  .getMessengerProfile(['get_started', 'persistent_menu'])
  .then((profile) => {
    console.log(profile);
    // [
    //   {
    //     getStarted: {
    //       payload: 'GET_STARTED',
    //     },
    //   },
    //   {
    //     persistentMenu: [
    //       {
    //         locale: 'default',
    //         composerInputDisabled: true,
    //         callToActions: [
    //           {
    //             type: 'postback',
    //             title: 'Restart Conversation',
    //             payload: 'RESTART',
    //           },
    //         ],
    //       },
    //     ],
    //   },
    // ]
  });

`setMessengerProfile(profile)`

Sets the values of one or more Messenger Profile properties. Only properties set in the request body will be overwritten.

Param	Type	Description
profile	`Object`	Object of Profile.

Example:

client.setMessengerProfile({
  getStarted: {
    payload: 'GET_STARTED',
  },
  persistentMenu: [
    {
      locale: 'default',
      composerInputDisabled: true,
      callToActions: [
        {
          type: 'postback',
          title: 'Restart Conversation',
          payload: 'RESTART',
        },
      ],
    },
  ],
});

`deleteMessengerProfile(fields)`

Deletes one or more Messenger Profile properties. Only properties specified in the fields array will be deleted.

Param	Type	Description
fields	`Array<String>`	Value must be among `account_linking_url`, `persistent_menu`, `get_started`, `greeting`, `whitelisted_domains`, `target_audience`, `home_url`.

Example:

client.deleteMessengerProfile(['get_started', 'persistent_menu']);

`getPersistentMenu`

Retrieves the current value of persistent menu.

Example:

client.getPersistentMenu().then((menu) => {
  console.log(menu);
  // [
  //   {
  //     locale: 'default',
  //     composerInputDisabled: true,
  //     callToActions: [
  //       {
  //         type: 'postback',
  //         title: 'Restart Conversation',
  //         payload: 'RESTART',
  //       },
  //       {
  //         type: 'web_url',
  //         title: 'Powered by ALOHA.AI, Yoctol',
  //         url: 'https://www.yoctol.com/',
  //       },
  //     ],
  //   },
  // ]
});

`setPersistentMenu(menu)`

Sets the values of persistent menu.

Param	Type	Description
menu	`Array<Object>`	Array of menu.

Example:

client.setPersistentMenu([
  {
    locale: 'default',
    callToActions: [
      {
        title: 'Play Again',
        type: 'postback',
        payload: 'RESTART',
      },
      {
        title: 'Language Setting',
        type: 'nested',
        callToActions: [
          {
            title: '中文',
            type: 'postback',
            payload: 'CHINESE',
          },
          {
            title: 'English',
            type: 'postback',
            payload: 'ENGLISH',
          },
        ],
      },
      {
        title: 'Explore D',
        type: 'nested',
        callToActions: [
          {
            title: 'Explore',
            type: 'web_url',
            url: 'https://www.youtube.com/watch?v=v',
            webviewHeightRatio: 'tall',
          },
          {
            title: 'W',
            type: 'web_url',
            url: 'https://www.facebook.com/w',
            webviewHeightRatio: 'tall',
          },
          {
            title: 'Powered by YOCTOL',
            type: 'web_url',
            url: 'https://www.yoctol.com/',
            webviewHeightRatio: 'tall',
          },
        ],
      },
    ],
  },
]);

Note: You must set a get started button to use the persistent menu.

`deletePersistentMenu`

Deletes persistent menu.

Example:

client.deletePersistentMenu();

Get Started Button - Official Docs

`getGetStarted`

Retrieves the current value of get started button.

Example:

client.getGetStarted().then((getStarted) => {
  console.log(getStarted);
  // {
  //   payload: 'GET_STARTED',
  // }
});

`setGetStarted(payload)`

Sets the values of get started button.

Param	Type	Description
payload	`String`	Payload sent back to your webhook in a `messaging_postbacks` event when the 'Get Started' button is tapped.

Example:

client.setGetStarted('GET_STARTED');

`deleteGetStarted`

Deletes get started button.

Example:

client.deleteGetStarted();

Greeting Text - Officail docs

`getGreeting`

Retrieves the current value of greeting text.

Example:

client.getGreeting().then((greeting) => {
  console.log(greeting);
  // [
  //   {
  //     locale: 'default',
  //     text: 'Hello!',
  //   },
  // ]
});

`setGreeting(greeting)`

Sets the values of greeting text.

Param	Type	Description
greeting	`Array<Object>`	Array of greeting.

Example:

client.setGreeting([
  {
    locale: 'default',
    text: 'Hello!',
  },
]);

`deleteGreeting`

Deletes greeting text.

Example:

client.deleteGreeting();

Whitelisted Domains - Official Docs

`getWhitelistedDomains`

Retrieves the current value of whitelisted domains.

Example:

client.getWhitelistedDomains().then((domains) => {
  console.log(domains);
  // ['http://www.example.com/']
});

`setWhitelistedDomains(domains)`

Sets the values of whitelisted domains.

Param	Type	Description
domains	`Array<String>`	Array of whitelisted_domain.

Example:

client.setWhitelistedDomains(['www.example.com']);

`deleteWhitelistedDomains`

Deletes whitelisted domains.

Example:

client.deleteWhitelistedDomains();

Account Linking URL - Official Docs

`getAccountLinkingURL`

Retrieves the current value of account linking URL.

Example:

client.getAccountLinkingURL().then((accountLinking) => {
  console.log(accountLinking);
  // {
  //   accountLinkingUrl:
  //     'https://www.example.com/oauth?response_type=code&client_id=1234567890&scope=basic',
  // }
});

`setAccountLinkingURL(url)`

Sets the values of account linking URL.

Param	Type	Description
url	`String`	Account linking URL.

Example:

client.setAccountLinkingURL(
  'https://www.example.com/oauth?response_type=code&client_id=1234567890&scope=basic'
);

`deleteAccountLinkingURL`

Deletes account linking URL.

Example:

client.deleteAccountLinkingURL();

Target Audience - Official Docs

`getTargetAudience`

Retrieves the current value of target audience.

Example:

client.getTargetAudience().then((targetAudience) => {
  console.log(targetAudience);
  // {
  //   audienceType: 'custom',
  //   countries: {
  //     whitelist: ['US', 'CA'],
  //   },
  // }
});

`setTargetAudience(type, whitelist, blacklist)`

Sets the values of target audience.

Param	Type	Description
type	`String`	Audience type. Valid values include `all	custom	none`.
whitelist	`Array<String>`	List of ISO 3166 Alpha-2 codes. Users in any of the blacklist countries won't see your bot on discovery surfaces on Messenger Platform.
blacklist	`Array<String>`	List of ISO 3166 Alpha-2 codes. Users in any of the whitelist countries will see your bot on discovery surfaces on Messenger Platform.

Exmaple:

client.setTargetAudience('custom', ['US', 'CA'], ['UK']);

`deleteTargetAudience`

Deletes target audience.

Example:

client.deleteTargetAudience();

Chat Extension Home URL - Official Docs

`getHomeURL`

Retrieves the current value of chat extension home URL.

Example:

client.getHomeURL().then((chatExtension) => {
  console.log(chatExtension);
  // {
  //   url: 'http://petershats.com/send-a-hat',
  //   webviewHeightRatio: 'tall',
  //   inTest: true,
  // }
});

`setHomeURL(url, attributes)`

Sets the values of chat extension home URL.

Param	Type	Description
url	`String`	The URL to be invoked from drawer.
attributes	`Object`	Other properties of home URL.

Exmaple:

client.setHomeURL('http://petershats.com/send-a-hat', {
  webviewHeightRatio: 'tall',
  inTest: true,
});

`deleteHomeURL`

Deletes chat extension home URL.

Example:

client.deleteHomeURL();

Handover Protocol API

`passThreadControl(userId, targetAppId, metadata)` - Official Docs

Passes thread control from your app to another app.

Param	Type	Description
userId	`String`	The PSID of the message recipient.
targetAppId	`Number`	The app ID of the Secondary Receiver to pass thread control to.
metadata	`String`	Metadata passed to the receiving app in the `pass_thread_control` webhook event.

Example:

client.passThreadControl(USER_ID, APP_ID, 'free formed text for another app');

`passThreadControlToPageInbox(userId, metadata)` - Official Docs

Passes thread control from your app to "Page Inbox" app.

Param	Type	Description
userId	`String`	The PSID of the message recipient.
metadata	`String`	Metadata passed to the receiving app in the `pass_thread_control` webhook event.

Example:

client.passThreadControlToPageInbox(
  USER_ID,
  'free formed text for another app'
);

`takeThreadControl(userId, metadata)` - Official Docs

Takes control of a specific thread from a Secondary Receiver app.

Param	Type	Description
userId	`String`	The PSID of the message recipient.
metadata	`String`	Metadata passed back to the secondary app in the `take_thread_control` webhook event.

Example:

client.takeThreadControl(USER_ID, 'free formed text for another app');

`requestThreadControl(userId, metadata)` - Official Docs

Requests control of a specific thread from a Primary Receiver app.

Param	Type	Description
userId	`String`	The PSID of the message recipient.
metadata	`String`	Metadata passed to the primary app in the `request_thread_control` webhook event.

Example:

client.requestThreadControl(USER_ID, 'free formed text for primary app');

`getThreadOwner` - Official Docs

Get the current thread owner.

Param	Type	Description
userId	`String`	The PSID of the message recipient.

Example:

client.getThreadOwner(USER_ID).then((threadOwner) => {
  console.log(threadOwner);
  // {
  //   appId: '12345678910'
  // }
});

`getSecondaryReceivers` - Official Docs

Retrieves the list of apps that are Secondary Receivers for a page.

Example:

client.getSecondaryReceivers().then((receivers) => {
  console.log(receivers);
  // [
  //   {
  //     "id": "12345678910",
  //     "name": "David's Composer"
  //   },
  //   {
  //     "id": "23456789101",
  //     "name": "Messenger Rocks"
  //   }
  // ]
});

Page Messaging Insights API - Official Docs

Requirements for insights API:

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(metrics, options)`

Retrieves the insights of your Facebook Page.

Param	Type	Description
metrics	`Array`	The metrics you want to check.
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client
  .getInsights(['page_messages_reported_conversations_unique'])
  .then((counts) => {
    console.log(counts);
    // [
    //   {
    //     "name": "page_messages_reported_conversations_unique",
    //     "period": "day",
    //     "values": [
    //       {
    //         "value": "<VALUE>",
    //         "endTime": "<UTC_TIMESTAMP>"
    //       },
    //       {
    //         "value": "<VALUE>",
    //         "endTime": "<UTC_TIMESTAMP>"
    //       }
    //     ]
    //   }
    // ]
  });

`getBlockedConversations(options)`

Retrieves the number of conversations with the Page that have been blocked.

Param	Type	Description
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client.getBlockedConversations().then((counts) => {
  console.log(counts);
  //   {
  //     "name": "page_messages_blocked_conversations_unique",
  //     "period": "day",
  //     "values": [
  //       {
  //         "value": "<VALUE>",
  //         "endTime": "<UTC_TIMESTAMP>"
  //       },
  //       {
  //         "value": "<VALUE>",
  //         "endTime": "<UTC_TIMESTAMP>"
  //       }
  //    ]
  //   }
});

`getReportedConversations(options)`

Retrieves the number of conversations from your Page that have been reported by people for reasons such as spam, or containing inappropriate content.

Param	Type	Description
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client.getReportedConversations().then((counts) => {
  console.log(counts);
  //   {
  //     "name": "page_messages_reported_conversations_unique",
  //     "period": "day",
  //     "values": [
  //       {
  //         "value": "<VALUE>",
  //         "endTime": "<UTC_TIMESTAMP>"
  //       },
  //       {
  //         "value": "<VALUE>",
  //         "endTime": "<UTC_TIMESTAMP>"
  //       }
  //     ]
  //   }
});

`getOpenConversations(options)`

Deprecated

getOpenConversations() is deprecated on May 11, 2018. Currently this method returns the same result as the replacing method getTotalMessagingConnections()

Retrieves the total number of open conversations between your Page and people in Messenger. This metric excludes blocked conversations.

Param	Type	Description
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client.getOpenConversations().then((result) => {
  console.log(result);
  // {
  //   name: 'page_messages_total_messaging_connections',
  //   period: 'day',
  //   values: [
  //     { value: 1000, endTime: '2018-03-12T07:00:00+0000' },
  //     { value: 1000, endTime: '2018-03-13T07:00:00+0000' },
  //   ],
  //   title: 'Messaging connections',
  //   description:
  //     'Daily: The number of people who have sent a message to your business, not including people who have blocked or reported your business on Messenger. (This number only includes connections made since October 2016.)',
  //   id:
  //     '1386473101668063/insights/page_messages_total_messaging_connections/day',
  // }
});

`getTotalMessagingConnections(options)`

Retrieves the number of people who have sent a message to your business, not including people who have blocked or reported your business on Messenger. (This number only includes connections made since October 2016.)

Param	Type	Description
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client.getTotalMessagingConnections().then((result) => {
  console.log(result);
  // {
  //   name: 'page_messages_total_messaging_connections',
  //   period: 'day',
  //   values: [
  //     { value: 1000, endTime: '2018-03-12T07:00:00+0000' },
  //     { value: 1000, endTime: '2018-03-13T07:00:00+0000' },
  //   ],
  //   title: 'Messaging connections',
  //   description:
  //     'Daily: The number of people who have sent a message to your business, not including people who have blocked or reported your business on Messenger. (This number only includes connections made since October 2016.)',
  //   id:
  //     '1386473101668063/insights/page_messages_total_messaging_connections/day',
  // }
});

`getNewConversations(options)`

Retrieves the number of messaging conversations on Facebook Messenger that began with people who had never messaged with your business before.

Param	Type	Description
options	`Object`	Optional arguments.
options.since	`number`	Optional. UNIX timestamp of the start time to get the metric for.
options.until	`number`	Optional. UNIX timestamp of the end time to get the metric for.

Example:

client.getNewConversations().then((result) => {
  console.log(result);
  // {
  //   name: 'page_messages_new_conversations_unique',
  //   period: 'day',
  //   values: [
  //     { value: 1, endTime: '2018-03-12T07:00:00+0000' },
  //     { value: 0, endTime: '2018-03-13T07:00:00+0000' },
  //   ],
  //   title: 'Daily unique new conversations count',
  //   description:
  //     'Daily: The number of messaging conversations on Facebook Messenger that began with people who had never messaged with your business before.',
  //   id:
  //     '1386473101668063/insights/page_messages_new_conversations_unique/day',
  // }
});

Built-in NLP API - Official Docs

`setNLPConfigs(config)`

Set values of NLP configs.

Param	Type	Description
config	`Object`	Configuration of NLP.
config.nlpEnabled	`Boolean`	Optional. Either enable NLP or disable NLP for that Page.
config.model	`String`	Optional. Specifies the NLP model to use. Either one of `{CHINESE, CROATIAN, DANISH, DUTCH, ENGLISH, FRENCH_STANDARD, GERMAN_STANDARD, HEBREW, HUNGARIAN, IRISH, ITALIAN_STANDARD, KOREAN, NORWEGIAN_BOKMAL, POLISH, PORTUGUESE, ROMANIAN, SPANISH, SWEDISH, VIETNAMESE}`, or `CUSTOM`.
config.customToken	`String`	Optional. Access token from Wit.
config.verbose	`Boolean`	Optional. Specifies whether verbose mode if enabled, which returns extra information like the position of the detected entity in the query.
config.nBest	`Number`	Optional. The number of entities to return, in descending order of confidence. Minimum 1. Maximum 8. Defaults to 1.

Example:

client.setNLPConfigs({
  nlpEnabled: true,
});

`enableNLP`

Enabling Built-in NLP.

Example:

client.enableNLP();

`disableNLP`

Disabling Built-in NLP.

Example:

client.disableNLP();

Event Logging API - Official Docs

`logCustomEvents(activity)`

Log custom events by using the Application Activities Graph API endpoint.

Param	Type	Description
activity	`Object`
activity.appId	`Number`	ID of the app.
activity.pageId	`String`	ID of the page.
activity.pageScopedUserId	`String`	Page-scoped user ID of the recipient.
activity.events	`Array<Object>`	Custom events.

Example:

client.logCustomEvents({
  appId: APP_ID,
  pageId: PAGE_ID,
  pageScopedUserId: USER_ID,
  events: [
    {
      _eventName: 'fb_mobile_purchase',
      _valueToSum: 55.22,
      _fbCurrency: 'USD',
    },
  ],
});

ID Matching API - Official Docs

`getIdsForApps({ userId, appSecret, ...options })`

Given a user ID for an app, retrieve the IDs for other apps owned by the same business

Param	Type	Description
userId	`String`	Page-scoped user ID.
appSecret	`String`	Secret of the app.
options.app	`String`	The app to retrieve the IDs.
options.page	`String`	The page to retrieve the IDs.

Example:

client
  .getIdsForApps({
    userId: USER_ID,
    appSecret: APP_SECRET,
  })
  .then((result) => {
    console.log(result);
    // {
    //   data: [
    //     {
    //       id: '10152368852405295',
    //       app: {
    //         category: 'Business',
    //         link: 'https://www.facebook.com/games/?app_id=1419232575008550',
    //         name: "John's Game App",
    //         id: '1419232575008550',
    //       },
    //     },
    //     {
    //       id: '645195294',
    //       app: {
    //         link: 'https://apps.facebook.com/johnsmovieappns/',
    //         name: 'JohnsMovieApp',
    //         namespace: 'johnsmovieappns',
    //         id: '259773517400382',
    //       },
    //     },
    //   ],
    //   paging: {
    //     cursors: {
    //       before: 'MTQ4OTU4MjQ5Nzc4NjY4OAZDZDA',
    //       after: 'NDAwMDExOTA3MDM1ODMwA',
    //     },
    //   },
    // };
  });

`getIdsForPages({ userId, appSecret, ...options })`

Given a user ID for a Page (associated with a bot), retrieve the IDs for other Pages owned by the same business.

Param	Type	Description
userId	`String`	Page-scoped user ID.
appSecret	`String`	Secret of the app.
options.app	`String`	The app to retrieve the IDs.
options.page	`String`	The page to retrieve the IDs.

Example:

client
  .getIdsForPages({
    userId: USER_ID,
    appSecret: APP_SECRET,
  })
  .then((result) => {
    console.log(result);
    // {
    //   data: [
    //     {
    //       id: '12345123', // The psid for the user for that page
    //       page: {
    //         category: 'Musician',
    //         link:
    //           'https://www.facebook.com/Johns-Next-Great-Thing-380374449010653/',
    //         name: "John's Next Great Thing",
    //         id: '380374449010653',
    //       },
    //     },
    //   ],
    //   paging: {
    //     cursors: {
    //       before: 'MTQ4OTU4MjQ5Nzc4NjY4OAZDZDA',
    //       after: 'NDAwMDExOTA3MDM1ODMwA',
    //     },
    //   },
    // };
  });

Persona API - Official Docs

`createPersona(persona)` - Official Docs

Creates a persona.

Param	Type	Description
persona.name	`String`	name of the persona.
persona.profilePictureUrl	`String`	profile picture of the persona.

createPersona({
  name: 'John Mathew',
  profilePictureUrl: 'https://facebook.com/john_image.jpg',
}).then((persona) => {
  console.log(persona);
  // {
  //  "id": "<PERSONA_ID>"
  // }
});

`getPersona(personaId)` - Official Docs

Retrieves the name and profile picture of a persona.

Param	Type	Description
personaId	`String`	ID of the persona.

getPersona(personaId).then((persona) => {
  console.log(persona);
  // {
  //   "name": "John Mathew",
  //   "profilePictureUrl": "https://facebook.com/john_image.jpg",
  //   "id": "<PERSONA_ID>"
  // }
});

`getPersonas(cursor?: string)` - Official Docs

Retrieves personas associated with a Page using the cursor.

Param	Type	Description
cursor	`String`	pagination cursor.

getPersonas(cursor).then((personas) => {
  console.log(personas);
  // {
  //   "data": [
  //     {
  //       "name": "John Mathew",
  //       "profilePictureUrl": "https://facebook.com/john_image.jpg",
  //       "id": "<PERSONA_ID>"
  //     },
  //     {
  //       "name": "David Mark",
  //       "profilePictureUrl": "https://facebook.com/david_image.jpg",
  //       "id": "<PERSONA_ID>"
  //     }
  //   ],
  //   "paging": {
  //     "cursors": {
  //       "before": "QVFIUlMtR2ZATQlRtVUZALUlloV1",
  //       "after": "QVFIUkpnMGx0aTNvUjJNVmJUT0Yw"
  //     }
  //   }
  // }
});

`getAllPersonas()` - Official Docs

Retrieves all the personas associated with a Page.

getAllPersonas().then((personas) => {
  console.log(personas);
  //   [
  //     {
  //       "name": "John Mathew",
  //       "profilePictureUrl": "https://facebook.com/john_image.jpg",
  //       "id": "<PERSONA_ID>"
  //     },
  //     {
  //       "name": "David Mark",
  //       "profilePictureUrl": "https://facebook.com/david_image.jpg",
  //       "id": "<PERSONA_ID>"
  //     }
  //   ]
});

`deletePersona(personaId)` - Official Docs

Deletes a persona.

Param	Type	Description
personaId	`String`	ID of the persona.

deletePersona(personaId);

Others

`debugToken` - Official Docs

Gets token information.

Example:

client.debugToken().then((pageInfo) => {
  console.log(pageInfo);
  // {
  //    appId: '000000000000000',
  //    application: 'Social Cafe',
  //    expiresAt: 1352419328,
  //    isValid: true,
  //    issuedAt: 1347235328,
  //    scopes: ['email', 'user_location'],
  //    userId: 1207059,
  //  }
});

`createSubscription`

Create new Webhooks subscriptions.

Param	Type	Description
accessToken	`String`	App access token.
callbackUrl	`String`	The URL that will receive the POST request when an update is triggered, and a GET request when attempting this publish operation.
verifyToken	`String`	An arbitrary string that can be used to confirm to your server that the request is valid.
fields	`Array<String>`	One or more of the set of valid fields in this object to subscribe to.
object	`String`	Indicates the object type that this subscription applies to. Defaults to `page`.
includeValues	`Boolean`	Indicates if change notifications should include the new values.

Example:

client.createSubscription({
  accessToken: APP_ACCESS_TOKEN,
  callbackUrl: 'https://mycallback.com',
  fields: ['messages', 'messaging_postbacks', 'messaging_referrals'],
  verifyToken: VERIFY_TOKEN,
});

Or provide app id and app secret instead of app access token:

client.createSubscription({
  accessToken: `${APP_ID}|${APP_SECRET}`,
  callbackUrl: 'https://mycallback.com',
  fields: ['messages', 'messaging_postbacks', 'messaging_referrals'],
  verifyToken: VERIFY_TOKEN,
});

Default Fields:

messages
messaging_postbacks
messaging_optins
messaging_referrals
messaging_handovers
messaging_policy_enforcement

`getSubscriptions`

Get the current Webhook subscriptions set up on your app.

Param	Type	Description
accessToken	`String`	App access token.

Example:

client.getSubscriptions({
  accessToken: APP_ACCESS_TOKEN,
});

Or provide app id and app secret instead of app access token:

client.getSubscriptions({
  accessToken: `${APP_ID}|${APP_SECRET}`,
});

`getPageSubscription`

Get the current page subscriptions set up on your app.

Param	Type	Description
accessToken	`String`	App access token.

Example:

client.getPageSubscription({
  accessToken: APP_ACCESS_TOKEN,
});

Or provide app id and app secret instead of app access token:

client.getPageSubscription({
  accessToken: `${APP_ID}|${APP_SECRET}`,
});

`getPageInfo`

Get page name and page id using Graph API.

Example:

client.getPageInfo().then((page) => {
  console.log(page);
  // {
  //   name: 'Bot Demo',
  //   id: '1895382890692546',
  // }
});

`getMessagingFeatureReview`

Programmatically check the feature submission status of Page-level Platform features.

Example:

client.getMessagingFeatureReview().then((data) => {
  console.log(data);
  // [
  //   {
  //     "feature": "subscription_messaging",
  //     "status": "<pending|rejected|approved|limited>"
  //   }
  // ]
});

Debug Tips

Log Requests Details

To enable default request debugger, use following DEBUG env variable:

DEBUG=messaging-api-messenger

Test

Send Requests to Your Dummy Server

To avoid sending requests to the real Messenger server, provide the origin option in your bottender.js.config file:

module.exports = {
  channels: {
    messenger: {
      enabled: true,
      path: '/webhooks/messenger',
      pageId: process.env.MESSENGER_PAGE_ID,
      accessToken: process.env.MESSENGER_ACCESS_TOKEN,
      appId: process.env.MESSENGER_APP_ID,
      appSecret: process.env.MESSENGER_APP_SECRET,
      verifyToken: process.env.MESSENGER_VERIFY_TOKEN,
      origin:
        process.env.NODE_ENV === 'test'
          ? 'https://mydummytestserver.com'
          : undefined,
    },
  },
};

Warning: Don't do this on the production server.

Usage​

Error Handling​

Methods​

Send API - Official Docs​

sendRawBody(body)​

sendMessage(userId, message [, options])​

Content Types - Content types​

sendText(userId, text [, options])​

sendAttachment(userId, attachment [, options])​

sendAudio(userId, audio [, options])​

sendImage(userId, image [, options])​

sendVideo(userId, video [, options])​

sendFile(userId, file [, options])​

Templates - Official Docs​

sendTemplate(userId, template [, options])​

sendButtonTemplate(userId, title, buttons [, options]) - Official Docs​

sendGenericTemplate(userId, elements [, options]) - Official Docs​

sendMediaTemplate(userId, elements [, options]) - Official Docs​

sendReceiptTemplate(userId, receipt [, options]) - Official Docs​

sendAirlineBoardingPassTemplate(userId, attributes [, options]) - Official Docs​

sendAirlineCheckinTemplate(userId, attributes [, options]) - Official Docs​

sendAirlineItineraryTemplate(userId, attributes [, options]) - Official Docs​

sendAirlineUpdateTemplate(userId, attributes [, options]) - Official Docs​

Quick Replies - Official Docs​

Sender Actions - Official Docs​

sendSenderAction(userId, action)​

markSeen(userId)​

typingOn(userId)​

typingOff(userId)​

Attachment Upload API - Official Docs​

uploadAttachment(type, attachment, options)​

uploadAudio(audio, options)​

uploadImage(image, options)​

uploadVideo(video, options)​

uploadFile(file, options)​

Message Batching - Official Docs​

sendBatch(requests)​

Custom Labels - Official Docs​

createLabel(name)​

associateLabel(userId, labelId)​

dissociateLabel(userId, labelId)​

getAssociatedLabels(userId)​

getLabelDetails(labelId, options)​

getLabelList()​

deleteLabel(labelId)​

User Profile API - Official Docs​

getUserProfile(userId, options)​

Messenger Profile API - Official Docs​

getMessengerProfile(fields)​

setMessengerProfile(profile)​

deleteMessengerProfile(fields)​

Persistent Menu - Official Docs​

getPersistentMenu​

setPersistentMenu(menu)​

deletePersistentMenu​

Get Started Button - Official Docs​

getGetStarted​

setGetStarted(payload)​

deleteGetStarted​

Greeting Text - Officail docs​

getGreeting​

setGreeting(greeting)​

deleteGreeting​

Whitelisted Domains - Official Docs​

getWhitelistedDomains​

setWhitelistedDomains(domains)​

deleteWhitelistedDomains​

Account Linking URL - Official Docs​

getAccountLinkingURL​

setAccountLinkingURL(url)​

deleteAccountLinkingURL​

Target Audience - Official Docs​

getTargetAudience​

setTargetAudience(type, whitelist, blacklist)​

deleteTargetAudience​

Chat Extension Home URL - Official Docs​

getHomeURL​

setHomeURL(url, attributes)​

deleteHomeURL​

Handover Protocol API​

Usage

Error Handling

Methods

Send API - Official Docs

`sendRawBody(body)`

`sendMessage(userId, message [, options])`

Content Types - Content types

`sendText(userId, text [, options])`

`sendAttachment(userId, attachment [, options])`

`sendAudio(userId, audio [, options])`

`sendImage(userId, image [, options])`

`sendVideo(userId, video [, options])`

`sendFile(userId, file [, options])`

Templates - Official Docs

`sendTemplate(userId, template [, options])`

`sendButtonTemplate(userId, title, buttons [, options])` - Official Docs

`sendGenericTemplate(userId, elements [, options])` - Official Docs

`sendMediaTemplate(userId, elements [, options])` - Official Docs

`sendReceiptTemplate(userId, receipt [, options])` - Official Docs

`sendAirlineBoardingPassTemplate(userId, attributes [, options])` - Official Docs

`sendAirlineCheckinTemplate(userId, attributes [, options])` - Official Docs

`sendAirlineItineraryTemplate(userId, attributes [, options])` - Official Docs

`sendAirlineUpdateTemplate(userId, attributes [, options])` - Official Docs

Quick Replies - Official Docs

Sender Actions - Official Docs

`sendSenderAction(userId, action)`

`markSeen(userId)`

`typingOn(userId)`

`typingOff(userId)`

Attachment Upload API - Official Docs

`uploadAttachment(type, attachment, options)`

`uploadAudio(audio, options)`

`uploadImage(image, options)`

`uploadVideo(video, options)`

`uploadFile(file, options)`

Message Batching - Official Docs

`sendBatch(requests)`

Custom Labels - Official Docs

`createLabel(name)`

`associateLabel(userId, labelId)`

`dissociateLabel(userId, labelId)`

`getAssociatedLabels(userId)`

`getLabelDetails(labelId, options)`

`getLabelList()`

`deleteLabel(labelId)`

User Profile API - Official Docs

`getUserProfile(userId, options)`

Messenger Profile API - Official Docs

`getMessengerProfile(fields)`

`setMessengerProfile(profile)`

`deleteMessengerProfile(fields)`

Persistent Menu - Official Docs

`getPersistentMenu`

`setPersistentMenu(menu)`

`deletePersistentMenu`

Get Started Button - Official Docs

`getGetStarted`

`setGetStarted(payload)`

`deleteGetStarted`

Greeting Text - Officail docs

`getGreeting`

`setGreeting(greeting)`

`deleteGreeting`

Whitelisted Domains - Official Docs

`getWhitelistedDomains`

`setWhitelistedDomains(domains)`

`deleteWhitelistedDomains`

Account Linking URL - Official Docs

`getAccountLinkingURL`

`setAccountLinkingURL(url)`

`deleteAccountLinkingURL`

Target Audience - Official Docs

`getTargetAudience`

`setTargetAudience(type, whitelist, blacklist)`

`deleteTargetAudience`

Chat Extension Home URL - Official Docs

`getHomeURL`

`setHomeURL(url, attributes)`

`deleteHomeURL`

Handover Protocol API