Messenger Platform

Ice Breakers

Ice Breakers provide a way for users to start a conversation with a business with a list of frequently asked questions. A maximum of 4 questions can be set via the Ice Breaker API.

Starting Oct 19th, 2021, Ice Breakers supports localization to allow businesses to set custom questions depending on the user locale. The API will have a new format and we encourage developers to leverage the new format to set and retrieve Ice Breakers information. The list of supported locales can be found here.

This feature is currently not available on desktop.

Setting Ice Breakers

New format (recommended)

curl -X POST -H "Content-Type: application/json" -d '{
     "platform": "instagram",
     "ice_breakers":[
       {
          "call_to_actions":[
             {
                "question":"<QUESTION>",
                "payload":"<PAYLOAD>"
             },
             {
                "question":"<QUESTION>",
                "payload":"<PAYLOAD>"
             }
          ],
          "locale":"default" // default locale is REQUIRED
       },
       {
          "call_to_actions":[
             {
                "question":"<QUESTION>",
                "payload":"<PAYLOAD>"
             },
             {
                "question":"<QUESTION>",
                "payload":"<PAYLOAD>"
             }
          ],
          "locale":"en_GB"
       }
    ]
}' "https://graph.facebook.com/v11.0/me/messenger_profile?platform=instagram&access_token=<PAGE_ACCESS_TOKEN>"

Old format (should not be used for new Icebreaker setup)

curl -X POST -H "Content-Type: application/json" -d '{
  "platform": "instagram",
  "ice_breakers":[
     {
        "question": "<QUESTION>",
        "payload": "<PAYLOAD>"
     },
     {
        "question": "<QUESTION>",
        "payload": "<PAYLOAD>"
     },
     ...
      
  ]
}' "https://graph.facebook.com/v11.0/me/messenger_profile?platform=instagram&access_token=<PAGE_ACCESS_TOKEN>"

Getting Ice Breakers

Depending on how the Ice Breaker is setup, GET request will return a different format. The following behavior applies:

  • If the Ice Breaker is setup using the Old format, GET request will return Old format response.
  • If the Ice Breaker is setup using the New format, GET request will return New format response.

We encourage developer to migrate to the new format as we will be deprecating the old format in the future.

curl -X GET "https://graph.facebook.com/v11.0/me/messenger_profile?fields=ice_breakers&platform=instagram&access_token=<PAGE_ACCESS_TOKEN>"

New format response

{
   "data": [
        {
          "call_to_actions" : [
               {
                "question": "<QUESTION>",
                "payload": "<PAYLOAD>",
             
               },
               {
                "question": "<QUESTION>",
                "payload": "<PAYLOAD>",
             
               },
          ],
          "locale": "<LOCALE>",
      },
      {
          "call_to_actions" : [
               {
                "question": "<QUESTION>",
                "payload": "<PAYLOAD>",
             
               },
               {
                "question": "<QUESTION>",
                "payload": "<PAYLOAD>",
             
               },
          ],
          "locale": "<LOCALE>",
      }
   ]
}

Old format response

{
   "data": [
        {
          "ice_breakers": [
            {
                "question": "<QUESTION>",
                "payload": "<PAYLOAD>",
            },
            ...
        ]
      }
   ]
}

Deleting Icebreakers

curl -X DELETE -H "Content-Type: application/json" -d '{
  "fields": [
    "ice_breakers",
  ]
}' "https://graph.facebook.com/v11.0/me/messenger_profile?platform=instagram&access_token=%lt;PAGE_ACCESS_TOKEN>"

Webhook Event

In order to receive postback webhooks from Icebreakers, the app needs to be subscribed to messaging_postbacks v8.0+ webhook under Instagram topic on the app settings.

The webhook will receive a json payload similar to the example below.

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1502905976377,
          "postback": {
            "title": "<SELECTED_ICEBREAKER_QUESTION>",
            "payload": "<USER_DEFINED_PAYLOAD>",
          }
        }
      ]
    }
  ]
}

Developer Support