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!
To use this collection, do the following:
- Download Postman
- 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.
- Add the appropriate environment variables to the 'Messenger Platform Environment Variables' environment.
- Run some of the API calls.
Want to see evvvveeerrryyttthhhiinnnggg run? Do the following:
- Set the appropriate environment variables in the 'Messenger Platform Environment Variables' environment.
- Open the Postman collection runner.
- Select the 'Messenger Platform' collection and 'Messenger Platform Environment Variables' environment.
- 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.
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.
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.
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:
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.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| Env Var | Type | Description | What's it For? |
|---|---|---|---|
EXTENSIONS_URL |
String | A HTTPS URL | Used for Messenger Profile API calls that require a URL. |
(Click to see the YouTube video)
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