Instagram Messaging

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 event. 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 below channels...Instagram.

MessageDelete

This event occurs when a message is deleted by the end-user on Instagram.

Example MessageDelete event

{
    "from": {
        "number": "<IGSID>"
    },
    "to": {
        "number": "<IGID>"
    },
    "event": {
        "type": "MessageDelete",
        "reference": "453563216"
    },    
    "timeUtc": "2021-07-05T17:08:45",
    "channel": "Instagram"
}

StoryMention

An Instagram business account can be notified when a user mentions them in a story.

Note A Story mentioning webhook will only flow in if the user mentioning the business has their account setup as public. Story mentions from a private account will only flow in if the business follows the said account.

Example StoryMention event

{
    "from": {
        "number": "<IGSID>"
    },
    "to": {
        "number": "<IGID>"
    },
    "event": {
        "type": "StoryMention",
        "reference": "453563217",
        "custom": {
               "url": "<CDN_URL>"
        }
    },
    "timeUtc": "2021-07-05T17:08:45",
    "channel": "Instagram"
}

Marketing Messages events

There are various types of events that can occur when using Marketing Messages.

Opt-In event

There are two scenarios for which you will receive this event:

When the user opts-in to receive your Marketing Messages based on a set frequency. (OptInSubscribed)
When the user clicks on the Continue messages button just before the token expires. This will refresh the NotificationToken of the user and extend the TokenExpiryTimestamp. (OptInExtended)

Example Opt-In Event (OptInSubscribed)

{ 
  "from": { 
    "number": "Recipients IGSID" 
  }, 
  "to": { 
    "number": "Your IGID" 
  }, 
  "event": {
        "type": "OptInSubscribed",
        "reference": "A reference to the object or message that triggered the event",
        "custom": {
          "notificationToken": "123456789987654321",
          "tokenExpiry" : "2023-04-10T12:00:00Z"
        }
    },    
    "timeUtc": "2022-10-10T12:00:00",
    "channel": "Instagram"
}

Re Opt-In event

Just before the token associated with the Marketing Message opt-in is about to expire, users will automatically receive a re opt-in request. Users will then have the choice of whether to continue receiving the Marketing Messages. The re opt-in request will only be sent to the user when the reoptin field of the original opt-in notification is set to True, otherwise the opt-in will stop automatically.

Marketing Messages Frequency	Re Opt-In Request Sent
Daily	After six months
Weekly	After nine months
Monthly	After twelve months

Example Re Opt-In Event (OptInExtended)

{ 
  "from": { 
    "number": "Recipients IGSID" 
  }, 
  "to": { 
    "number": "Your IGID" 
  }, 
  "event": {
        "type": "OptInExtended",
        "reference": "A reference to the object or message that triggered the event",
        "custom": {
          "notificationToken": "123456789987654321",
          "tokenExpiry" : "2023-04-10T12:00:00Z"
        }
    },    
    "timeUtc": "2022-10-10T12:00:00",
    "channel": "Instagram"
}

Manage Opt-In Event

Once users opt-in, they can easily manage their Marketing Messages, including stopping and resuming them, by clicking the “Manage” button. This will result in the following scenario’s:

When a user presses the Stop these messages button. Resulting in a temporary block of your messages. (OptInSuspended)
When a user presses the Resume these messages button after they have suspended your messages. (OptInResumed)

Example Manage Opt-In Event (OptInSuspended)

{ 
  "from": { 
    "number": "Recipients IGSID" 
  }, 
  "to": { 
    "number": "Your IGID" 
  },
  "event": {
        "type": "OptInSuspended",
        "reference": "A reference to the object or message that triggered the event",
        "custom": {
          "notificationToken": "123456789987654321",
          "tokenExpiry" : "2023-04-10T12:00:00Z"
        }
    },    
    "timeUtc": "2022-10-10T12:00:00",
    "channel": "Facebook Messenger"
}

Example Manage Opt-In Event (OptInResumed)

{ 
  "from": { 
    "number": "Recipients IGSID" 
  }, 
  "to": { 
    "number": "Your IGID" 
  },
  "event": {
        "type": "OptInResumed",
        "reference": "A reference to the object or message that triggered the event",
        "custom": {
          "notificationToken": "123456789987654321",
          "tokenExpiry" : "2023-04-10T12:00:00Z"
        }
    },    
    "timeUtc": "2022-10-10T12:00:00",
    "channel": "Instagram"
}