/messenger-platform-postman-collection

A delicious Postman collection for all your Messenger Platform needs.

MIT LicenseMIT

Postman Collection for Messenger Platform     Run in Postman

Collection Last Updated: 5/30/18 - Added get thread control for handover protocol

This is a Postman collection that covers pretty much every API request available for the Messenger Platform. This collection should be useful for getting started working with your bot to try out features and send all the different message types. You can also use it once you are in production to send messages!

Using this Collection

Basic Usage

To use this collection, do the following:

  1. Download Postman
  2. Click the 'Run in Postman' button at the top of this Readme to import the collection and a 'Messenger Platform Environment Variables' environment into Postman.
  3. Add the appropriate environment variables to the 'Messenger Platform Environment Variables' environment.
  4. Run some of the API calls.

Collection Runner

Want to see evvvveeerrryyttthhhiinnnggg run? Do the following:

  1. Set the appropriate environment variables in the 'Messenger Platform Environment Variables' environment.
  2. Open the Postman collection runner.
  3. Select the 'Messenger Platform' collection and 'Messenger Platform Environment Variables' environment.
  4. Click the 'Run' button.

This is pretty cool because your environment will also be auto-populated with various responses from the API that are needed for other calls.

DANGER, WILL ROBINSON: Postman will run all of the API calls in order. This means that if you re-arrange them in the collection, a full test run may not work as expected.

Updating this Collection

Postman collections do not automatically sync when they are updated. So if you like this, you should come back periodically to download it. I'll try to keep a 'last updated' date at the top of this readme and maybe some kind of changelog.

Environment Variables

This collection makes liberal use of Postman environment variables to automate API requests to the greatest extent possible. Basically, anytime you see {{SOME_VAR_NAME}} in a request body or URI that's a Postman env var.

When you load this collection into Postman, it will also load a 'Messenger Platform Environment Variables' environment that includes all the possible env vars used by this collection.

Required Environment Variables

At a minimum you should set these environment variables, since they are needed for almost all Messenger Platform API requests, especially message sends.

Env Var Type Description What's it For?
PSID String A page-scoped ID Specifies the user to target. This will be used as the default user for all requests. To get this, send a message to your bots and extract the id property from the messages webhook event.
PAGE_TOKEN String Your Page access token Almost all API requests. Available in the 'Token Generation' section of your app's Messenger settings.
SET_ENV Boolean Sets whether other env vars will be automatically set from API responses when you use Postman's collection runner. This is a convenience so that you don't have to manually set a bunch of IDs for all the different API requests.

If you want to run the whoooollleeee collection in the collection runner, you'll also need to set these:

Optional Environment Variables

Many of the optional vars will be set for you if you set the SET_ENV env var to TRUE and run Postman's collection runner. You can also set these manually in each call if you want.

Reusable Assets

Env Var Type Description What's it For?
IMAGE_ATTACHMENT_ID String An attachment_id of an uploaded image The attachment_id to use for message sends with an image.
VIDEO_ATTACHMENT_ID String An attachment_id of an uploaded video The attachment_id to use for message sends with a video.

Handover Protocol

Env Var Type Description What's it For?
APP_ID_PRIMARY String An app ID The app ID for the Facebook app you want to use as the Primary Receiver for your bot.
APP_ID_SECONDARY String An app ID The app ID for the Facebook app you want to use as the Secondary Primary Receiver for your bot.

Broadcast API

Env Var Type Description What's it For?
MESSAGE_CREATIVE_ID_ALL String A message_creative_id The message_creative_id of a message creative to broadcast to all open conversations.
MESSAGE_CREATIVE_ID_TARGETED String A message_creative_id The message_creative_id of a message creative to broadcast to open conversations associated with a custom label.
REACH_ESTIMATION_ID String A reach_estimation_id The reach_estimation_id to start a reach estimation for.
CUSTOM_LABEL_ID String A custom_label_id The custom_label_id to associate with PSIDs or to target a broadcast to. When SET_ENV is set to TRUE, the value will be 'custom_label_'.
CUSTOM_LABEL_ID_TO_DELETE String A custom_label_id When SET_ENV is set to TRUE, this is set when the 'Create Custom Label' call happens. It is deleted when 'Delete Custom Label' call happens.

ID Matching

Env Var Type Description What's it For?
ASID String A user's app-scoped ID The app-scoped ID to match with the ID Matching API.
APP_TOKEN String An app token The app token to use with the ID Matching API.
APP_SECRET String An app secret The app secret to use with the ID Matching API.

Built-in NLP

Env Var Type Description What's it For?
WIT_TOKEN String A Wit.ai server access token Connects your Messenger bot to a Wit.ai custom model. Available in the settings for your Wit.ai app.

Messenger Profile API

Env Var Type Description What's it For?
EXTENSIONS_URL String A HTTPS URL Used for Messenger Profile API calls that require a URL.

Behold!

(Click to see the YouTube video)

Useful Resources

Never used Postman or the Messenger Platform before? Here's some useful links to get you started and to get help when you have questions or run into problems. <3

Messenger Platform

Postman