Instagram Messaging

The main difference from other channels is the fact that Instagram uses a numeric identifier for a sender and recipient. So-called "Instagram Scoped User ID (IGSID)" for the sender and an "Instagram account ID" for the recipient of the MO message. A person is assigned a unique IGSID for each Instagram Business account they start a conversation with.

These identifiers are visible in the CM.com platform as the userid under channels...Instagram.

Instagram also provides the account username such

Media Message

See also receiving media messages

Instagram leverages CDN URLs which allow you to retrieve rich media content shared by users.
It is not allowed to download, retain, or otherwise store the media content sent or made accessible by any user (or enable any third party to do so) and you, or any third party, must not do anything to circumvent expiration and/or removal of any link to such media content.

CM only provides the CDN URL so Instagram has full control of the content. This means the CDN URL will not return the media when the content is deleted or expired at Instagram.
If you want to make use of the media content, you are only allowed to store the privacy-aware CDN URL in your system and use this link to render the media made accessible.

Example message

{
  "reference": "my-reference",
  "messageContext": "",
  "from": {
    "number": "87654321",
    "name": "John Doe"
  },
  "to": {
    "number": "12345678"
  },
  "message": {
    "text": "",
    "media": {
      "mediaUri": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=1234&signature=AAAA",
      "contentType": "",
      "title": ""
    },
    "custom": {
    	"username": "john.doe"
    }
  },
  "groupings": ["", "", ""],
  "time": "2021-05-27 15:47:52",
  "timeUtc": "2021-05-27T13:47:52",
  "channel": "Instagram"
}

Metadata

Username

This is the account name associated with the end-users Instagram profile.

"custom": {
  "username": "john.doe"
}

Example message

{
  "reference": "my-reference",
  "messageContext": "",
  "from": {
    "number": "87654321",
    "name": "John Doe"
  },
  "to": {
    "number": "12345678"
  },
  "message": {
    "text": "",
    "custom": {
    	"username": "john.doe"
    }
  },
  "time": "2021-05-27 15:47:52",
  "timeUtc": "2021-05-27T13:47:52",
  "channel": "Instagram"
}

Suggestions

When the customer clicks on an item in a quick reply suggestion list, the reply will have the original action, and the original "postbackData" in the custom/suggestions item:

"custom": {
  "suggestions": [
    {
      "action": "Reply",
      "postbackData": "EDIT_APPOINTMENT"
    }
  ]
}

Example message

{
  "reference": "my-reference",
  "messageContext": "",
  "from": {
    "number": "87654321",
    "name": "John Doe"
  },
  "to": {
    "number": "12345678"
  },
  "message": {
    "text": "Edit appointment",
    "media": {
      "mediaUri": "",
      "contentType": "",
      "title": ""
    },
    "custom": {
      "username": "john.doe",
      "suggestions": [
        {
          "action": "Reply",
          "postbackData": "EDIT_APPOINTMENT"
        }
      ]
    }
  },
  "groupings": ["", "", ""],
  "time": "2021-05-27 15:47:52",
  "timeUtc": "2021-05-27T13:47:52",
  "channel": "Instagram"
}

Story reply

When an end-user replies to one of your Instagram stories, Instagram returns metadata in a "reply_to" item containing a reference to the story the user replied to.
This metadata contains information such as the id and the media URL of your Instagram story. This is Instagram-specific data, and we return it in a "custom/rawPayload" item.

Keep in mind: the media url of the Instagram story follows the same CDN rules of an Instagram media messages.

In addition, its only available for 24 hours before Instagram will expire the media url.

Below is an example of the "rawPayload" containing "reply_to" data.

"custom": {
  "rawPayload": {
    "reply_to": {
      "story": {
        "id": string,
        "url": string
      }
    }
  }
}

Message Example

{  
  "reference": "my-reference",
  "messageContext": "",
  "from": {
    "number": "87654321",
    "name": "John Doe"
  },
  "to": {
    "number": "12345678"
  },
  "message": {
    "text": "Nice Instagram story",
    "media": {
      "mediaUri": "",
      "contentType": "",
      "title": ""
    },
    "custom": {
      "username": "john.doe",
      "rawPayload": {
        "reply_to": {
          "story": {
            "id": "1234",
            "url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=1234&signature=AAAA"
          }
        }
      }
    }
  },
  "groupings": ["", "", ""],
  "time": "2021-05-27 15:47:52",
  "timeUtc": "2021-05-27T13:47:52",
  "channel": "Instagram"
}

Story mention

An end-user can mention your Instagram business account in one of its Instagram stories. By doing so, an event will be triggered. Because it's an event, no MO message will be sent. Instead, an event is sent out, as described in our events webhook documentation.

For receiving this event, please read on how to set up this separate webhook.