Postman Collection for Messenger Platform    

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:

• Handover protocol
• ID Matching
• Wit.ai
• Messenger Profile

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

• Messenger Platform Developer Group

• Facebook Messenger Bot Tag on Stack Overflow

• Messenger Platform Update Bot

• Messenger Platform Docs

• Messenger Platform Quick Start Tutorial

Postman

• Download Postman

• Postman Collection Docs

• Postman Environment Docs

• Postman Scripting Docs

• Postman Scripting API Reference