{"_id":"582979b61392bb0f00725297","project":"54eb50e5615ffc1900305a16","version":{"_id":"54eb63b859b1172100334fae","project":"54eb50e5615ffc1900305a16","forked_from":"54eb63a1867e1917009b711d","__v":26,"createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03","589b19b4fec2730f0082e040","58b04a023529383900a759b5","58b92d1598157a0f004869bf","592e7685c58275000f20174f","59392839e376d4002f8a0474","59393064e376d4002f8a05a1","5947ae0d4005e2000f3a4fec","594a74df1d1de5001ab3517a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"__v":3,"category":{"_id":"58172386715dce0f00da4aa0","project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-31T10:57:10.541Z","from_sync":false,"order":14,"slug":"facebook-messages","title":"Facebook messenger"},"user":"54eb4fdedf7add210007b29b","parentDoc":null,"updates":["585130748969482300a09706"],"next":{"pages":[],"description":""},"createdAt":"2016-11-14T08:45:42.716Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"**Facebook messenger API** connects your CRM software, website or application to the Facebook's messaging platform.\n\nIt enables direct communication with your customers on Facebook using the same platform that they already use when talking to their friends. It allows you to personally interact with them, keep them engaged with your business, and drive them to perform actions. The messages can be personal, informative, transactional, or promotional, and support text, images, buttons, and links.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Facebook OMNI\",\n  \"body\": \"Facebook API is available also as a part of our [OMNI experience](/docs/omni-channel-facebook-messenger-example).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Facebook page\"\n}\n[/block]\n**Facebook pages** are used by brands, businesses, organizations and public figures to create a presence on Facebook, whereas profiles represent individual people. Anyone with an account can create a Page or help in managing one if they have a role of page admin or editor. If you don't have a Facebook page yet, you can create one [here](https://www.facebook.com/pages/create).\n\nFacebook users can use **Facebook messenger** to contact your organization through your Facebook page.\n\nBy using the Infobip API you can integrate your own solution for receiving and sending messages to your subscribers by using two simple API methods:\n  * [Send message](/docs/send-single-facebook-messenger-message)\n  * [Receive message](/docs/receive-facebook-message)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Initial setup\",\n  \"body\": \"In order to start using an API for messaging you have to go through the initial setup which consists of:\\n1. **Creating the application on Facebook platform** and connecting it to your Facebook page\\n2. **Creating the application on Infobip platform** and connecting it to the Facebook application\\n3. **Setting up the configuration options** for incoming messages\"\n}\n[/block]\nAssuming that you already have your organization page up and running, you are ready to start with the setup steps listed below.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Application setup\"\n}\n[/block]\n1. Visit https://developers.facebook.com/apps and create new Application. \n2. Name it, select a category and click **Create App ID**. You should end up on application dashboard.\n3. Obtain the **App secret** by clicking on the `Show` button\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"App secret and App ID\",\n  \"body\": \"Copy and save your **App secret** and **App ID** somewhere convenient as you will need it in next steps.\"\n}\n[/block]\n4. From the menu choose **Products **-> **Add product** and select **Messenger** -> **Get started**\n5. In Token Generation section select your page and new **Page Access Token** will be generated\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Page Access Token\",\n  \"body\": \"Copy and save your **Page Access Token** somewhere convenient as you will need it in next steps.\"\n}\n[/block]\n- - - -\nBefore continuing setting up webhooks, you have to** create the application on Infobip platform** which must be associated with this Facebook application. \n\nA new application can be created with the single API call. Use **Page Access Token** from the previous step as a value of `accessToken` parameter, and **App secret** as a value of `secret` property.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Infobip application\",\n  \"body\": \"You can access your previously created application through other API calls described [here](/docs/facebook-messenger-application#list-all-applications).\"\n}\n[/block]\nCreate an Infobip application request example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /facebook/1/applications HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\\nAccept: application/json\\n\\n{\\n  \\\"facebook\\\": {\\n    \\\"page\\\": {\\n        \\\"accessToken\\\": \\\"EAAXggzrE7uYBAM38UXko5vWxi98mZCgH2klIHSwd...\\\"\\n    },\\n    \\\"application\\\": {\\n        \\\"id\\\": 1654219114885622,\\n        \\\"secret\\\": \\\"cf074b2e96390b3600031c751d9bf590\\\"\\n        }\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"key\\\": \\\"0F3C3F29829FAB88714BA205BEC6D28F\\\",\\n  \\\"facebook\\\": {\\n    \\\"page\\\": {\\n        \\\"accessToken\\\": \\\"EAAXggzrE7uYBAM38UXko5vWxi98mZCgH2klIHSwd...\\\"\\n    },\\n    \\\"application\\\": {\\n        \\\"id\\\": 1654219114885622,\\n        \\\"secret\\\": \\\"cf074b2e96390b3600031c751d9bf590\\\",\\n        \\\"name\\\": \\\"My application name\\\",\\n        \\\"imageUrl\\\": \\\"https://scontent.xx.fbcdn.net/t39...0696#_n.png\\\"\\n        }\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse will contain supplied `accessToken`, 'name` and `key` values.\n\nBesides new Infobip application, a **webhook **will also be created automatically inside of the Facebook application. You can see it by visiting Webhooks in your Facebook application dashboard. Callback URL will have this format `https://api.infobip.com/facebook/1/applications/{key}/webhook`.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Infobip applicaton key\",\n  \"body\": \"Copy and save your `key` as you will need it in the next  steps. You will use the same `key` later when sending messages. The 'key' can always be retrieved by calling the ['List all applications'](/docs/facebook-messenger-application#list-all-applications) method.\"\n}\n[/block]\n**That's it!** You are now ready to send test messages over an API by performing a ['Send message API' method](/docs/send-single-facebook-messenger-message). Before you can receive inbound messages you need to go through the [Configuration process for receiving messages](#configuration-process-for-receiving-messages).\n[block:html]\n{\n  \"html\": \"<div id=\\\"how-can-my-organisation-contact-people-over-Facebook\\\"></div>\\n\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"You can reach out to anyone who registered or agreed to be contacted by phone number (Customer Matching).\\n\\nPeople can register by entering into a conversation with you from a number of different places or entry points.\\n  * If your app is Public, you can be discovered through **Search in Messenger**\\n  * By clicking on the **Send Message** button on your Page\\n  * By scanning your **Messenger Code** using their phone camera\\n  * By clicking on your **Messenger Link** with the format https://m.me/PAGE_USERNAME\\n  * Through the **[Send To Messenger](https://developers.facebook.com/docs/messenger-platform/plugin-reference/send-to-messenger)** or** [Message Us](https://developers.facebook.com/docs/messenger-platform/plugin-reference/message-us)** web plugins\\n  * **Phone Number** (Customer Matching) - send a message to a user without requiring the user interacting with the page first, by specifying a phone number. In order to use Customer Matching, the Page must have a United States address or have at least one admin who is in the United States.\\n\\nWhen registering the user is assigned with the unique **user key**. These keys are page-scoped IDs (PSID) which means that the keys are unique for a given page.\",\n  \"title\": \"How can my organisation contact people over Facebook?\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"At this point Facebook application is still in **test mode**, so only administrator and the testers specified under the **Roles** section in the left sidebar can actually use this Messenger integration.\\n\\nAt this point you should apply for **[Facebook approval](#facebook-application-approval-process)** since it may take up to two weeks.\\n\\nWhile waiting for the approval from Facebook you can continue with the integration by configuring the [**process for receiving messages**](#configuration-process-for-receiving-messages).\",\n  \"title\": \"Test mode\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Facebook application approval process\"\n}\n[/block]\nWhen the Application is ready for the production use it needs to be submitted to Facebook for a review.\nThe following steps need to be taken:\n\n1. Go to https://developers.facebook.com/apps/ and select the Application ready for review. In the left sidebar, click on ‘App Review’.\n2. On the ‘App Review’ page click on the ‘Start a Submission’ button.\n    2.1. Inside the pop-up, select ‘pages_messaging’ and click on the blue ‘Add 1 Item’.\n    2.2. You will be notified If something is missing in order to put the Application for review (example. missing App Icon)\n3. On the left sidebar Click on the 'Settings' page   \n    3.1. At the bottom, click on ‘+ Add Platform’\n    3.2. Choose ‘Website’ as your platform, then simply enter the URL of your website.\n4. Go back to the to the ‘App Review’ page.\n    4.1. Under ‘pages_messaging’ click on 'notes' in the ‘Complete the notes for this item before submitting.’ the text below pages_messaging.\n    4.2. Pop-up form with questions about the goal of your Application will appear.\n    4.3. Upload a screencast of how the Application should work.\n    4.4. The screencast mandatory and must be done well, because Facebook will test your Application and reject it if it doesn’t meet the provided description and screencast.\n5. After providing all the necessary information click on ‘Save’, following by click on ‘Submit for review’ button.\n6. Accept Facebook’s Terms & Conditions.\n7. Click on Submit.\n\nFacebook reviews all submissions within 2 weeks, but it often takes less than that. Facebook can reject the submission if it doesn’t meet the Facebook Messenger guidelines or doesn’t match the functionality as described and shown in the screencast.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration process for receiving messages\"\n}\n[/block]\nWhile waiting for the approval, you are free to continue with the API integration and testing. You have successfully configured **message sending**, and now it's time to configure **message receiving** options:\n\n###Incoming message setup steps\n1. [**Configuration**](/docs/facebook-messenger-configuration) represents a container for a set of different Actions.\n2. [**Action**](/docs/facebook-messenger-action) represents collection of methods used to trigger different HTTP actions. Through the 'Action configuration' you can define how would you like to receive incoming messages - by Pull or Forward method.","excerpt":"","slug":"facebook-messenger-introduction","type":"basic","title":"Introduction and setup"}

Introduction and setup


**Facebook messenger API** connects your CRM software, website or application to the Facebook's messaging platform. It enables direct communication with your customers on Facebook using the same platform that they already use when talking to their friends. It allows you to personally interact with them, keep them engaged with your business, and drive them to perform actions. The messages can be personal, informative, transactional, or promotional, and support text, images, buttons, and links. [block:callout] { "type": "info", "title": "Facebook OMNI", "body": "Facebook API is available also as a part of our [OMNI experience](/docs/omni-channel-facebook-messenger-example)." } [/block] [block:api-header] { "type": "basic", "title": "Facebook page" } [/block] **Facebook pages** are used by brands, businesses, organizations and public figures to create a presence on Facebook, whereas profiles represent individual people. Anyone with an account can create a Page or help in managing one if they have a role of page admin or editor. If you don't have a Facebook page yet, you can create one [here](https://www.facebook.com/pages/create). Facebook users can use **Facebook messenger** to contact your organization through your Facebook page. By using the Infobip API you can integrate your own solution for receiving and sending messages to your subscribers by using two simple API methods: * [Send message](/docs/send-single-facebook-messenger-message) * [Receive message](/docs/receive-facebook-message) [block:callout] { "type": "warning", "title": "Initial setup", "body": "In order to start using an API for messaging you have to go through the initial setup which consists of:\n1. **Creating the application on Facebook platform** and connecting it to your Facebook page\n2. **Creating the application on Infobip platform** and connecting it to the Facebook application\n3. **Setting up the configuration options** for incoming messages" } [/block] Assuming that you already have your organization page up and running, you are ready to start with the setup steps listed below. [block:api-header] { "type": "basic", "title": "Application setup" } [/block] 1. Visit https://developers.facebook.com/apps and create new Application. 2. Name it, select a category and click **Create App ID**. You should end up on application dashboard. 3. Obtain the **App secret** by clicking on the `Show` button [block:callout] { "type": "warning", "title": "App secret and App ID", "body": "Copy and save your **App secret** and **App ID** somewhere convenient as you will need it in next steps." } [/block] 4. From the menu choose **Products **-> **Add product** and select **Messenger** -> **Get started** 5. In Token Generation section select your page and new **Page Access Token** will be generated [block:callout] { "type": "warning", "title": "Page Access Token", "body": "Copy and save your **Page Access Token** somewhere convenient as you will need it in next steps." } [/block] - - - - Before continuing setting up webhooks, you have to** create the application on Infobip platform** which must be associated with this Facebook application. A new application can be created with the single API call. Use **Page Access Token** from the previous step as a value of `accessToken` parameter, and **App secret** as a value of `secret` property. [block:callout] { "type": "info", "title": "Infobip application", "body": "You can access your previously created application through other API calls described [here](/docs/facebook-messenger-application#list-all-applications)." } [/block] Create an Infobip application request example: [block:code] { "codes": [ { "code": "POST /facebook/1/applications HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nAccept: application/json\n\n{\n \"facebook\": {\n \"page\": {\n \"accessToken\": \"EAAXggzrE7uYBAM38UXko5vWxi98mZCgH2klIHSwd...\"\n },\n \"application\": {\n \"id\": 1654219114885622,\n \"secret\": \"cf074b2e96390b3600031c751d9bf590\"\n }\n }\n}", "language": "json" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"key\": \"0F3C3F29829FAB88714BA205BEC6D28F\",\n \"facebook\": {\n \"page\": {\n \"accessToken\": \"EAAXggzrE7uYBAM38UXko5vWxi98mZCgH2klIHSwd...\"\n },\n \"application\": {\n \"id\": 1654219114885622,\n \"secret\": \"cf074b2e96390b3600031c751d9bf590\",\n \"name\": \"My application name\",\n \"imageUrl\": \"https://scontent.xx.fbcdn.net/t39...0696#_n.png\"\n }\n }\n}", "language": "json" } ] } [/block] Response will contain supplied `accessToken`, 'name` and `key` values. Besides new Infobip application, a **webhook **will also be created automatically inside of the Facebook application. You can see it by visiting Webhooks in your Facebook application dashboard. Callback URL will have this format `https://api.infobip.com/facebook/1/applications/{key}/webhook`. [block:callout] { "type": "warning", "title": "Infobip applicaton key", "body": "Copy and save your `key` as you will need it in the next steps. You will use the same `key` later when sending messages. The 'key' can always be retrieved by calling the ['List all applications'](/docs/facebook-messenger-application#list-all-applications) method." } [/block] **That's it!** You are now ready to send test messages over an API by performing a ['Send message API' method](/docs/send-single-facebook-messenger-message). Before you can receive inbound messages you need to go through the [Configuration process for receiving messages](#configuration-process-for-receiving-messages). [block:html] { "html": "<div id=\"how-can-my-organisation-contact-people-over-Facebook\"></div>\n" } [/block] [block:callout] { "type": "warning", "body": "You can reach out to anyone who registered or agreed to be contacted by phone number (Customer Matching).\n\nPeople can register by entering into a conversation with you from a number of different places or entry points.\n * If your app is Public, you can be discovered through **Search in Messenger**\n * By clicking on the **Send Message** button on your Page\n * By scanning your **Messenger Code** using their phone camera\n * By clicking on your **Messenger Link** with the format https://m.me/PAGE_USERNAME\n * Through the **[Send To Messenger](https://developers.facebook.com/docs/messenger-platform/plugin-reference/send-to-messenger)** or** [Message Us](https://developers.facebook.com/docs/messenger-platform/plugin-reference/message-us)** web plugins\n * **Phone Number** (Customer Matching) - send a message to a user without requiring the user interacting with the page first, by specifying a phone number. In order to use Customer Matching, the Page must have a United States address or have at least one admin who is in the United States.\n\nWhen registering the user is assigned with the unique **user key**. These keys are page-scoped IDs (PSID) which means that the keys are unique for a given page.", "title": "How can my organisation contact people over Facebook?" } [/block] [block:callout] { "type": "warning", "body": "At this point Facebook application is still in **test mode**, so only administrator and the testers specified under the **Roles** section in the left sidebar can actually use this Messenger integration.\n\nAt this point you should apply for **[Facebook approval](#facebook-application-approval-process)** since it may take up to two weeks.\n\nWhile waiting for the approval from Facebook you can continue with the integration by configuring the [**process for receiving messages**](#configuration-process-for-receiving-messages).", "title": "Test mode" } [/block] [block:api-header] { "type": "basic", "title": "Facebook application approval process" } [/block] When the Application is ready for the production use it needs to be submitted to Facebook for a review. The following steps need to be taken: 1. Go to https://developers.facebook.com/apps/ and select the Application ready for review. In the left sidebar, click on ‘App Review’. 2. On the ‘App Review’ page click on the ‘Start a Submission’ button. 2.1. Inside the pop-up, select ‘pages_messaging’ and click on the blue ‘Add 1 Item’. 2.2. You will be notified If something is missing in order to put the Application for review (example. missing App Icon) 3. On the left sidebar Click on the 'Settings' page 3.1. At the bottom, click on ‘+ Add Platform’ 3.2. Choose ‘Website’ as your platform, then simply enter the URL of your website. 4. Go back to the to the ‘App Review’ page. 4.1. Under ‘pages_messaging’ click on 'notes' in the ‘Complete the notes for this item before submitting.’ the text below pages_messaging. 4.2. Pop-up form with questions about the goal of your Application will appear. 4.3. Upload a screencast of how the Application should work. 4.4. The screencast mandatory and must be done well, because Facebook will test your Application and reject it if it doesn’t meet the provided description and screencast. 5. After providing all the necessary information click on ‘Save’, following by click on ‘Submit for review’ button. 6. Accept Facebook’s Terms & Conditions. 7. Click on Submit. Facebook reviews all submissions within 2 weeks, but it often takes less than that. Facebook can reject the submission if it doesn’t meet the Facebook Messenger guidelines or doesn’t match the functionality as described and shown in the screencast. [block:api-header] { "type": "basic", "title": "Configuration process for receiving messages" } [/block] While waiting for the approval, you are free to continue with the API integration and testing. You have successfully configured **message sending**, and now it's time to configure **message receiving** options: ###Incoming message setup steps 1. [**Configuration**](/docs/facebook-messenger-configuration) represents a container for a set of different Actions. 2. [**Action**](/docs/facebook-messenger-action) represents collection of methods used to trigger different HTTP actions. Through the 'Action configuration' you can define how would you like to receive incoming messages - by Pull or Forward method.