Incoming Events

Introduction

You can receive your incoming events for channels supported by the CM.com Business Messaging API in your own systems, by registering a webhook in the Channels-app. After registering an HTTPS web address you will start receiving the incoming events.

Note These events do not include the receiving of messages; please refer to the following docs for that: Incoming messages.

Note In the case of offboarding, the registered webhook(s) are removed and any incoming events will therefore not be forwarded to the webhook(s) any longer.


Receiving events

In order to receive the incoming events, you need to build a web service where our systems can deliver the events. This is called a webhook. Via the webhook, you will be notified by CM.com of the new event content and metadata using a POST call to your registered web service in the JSON content format. To indicate you have received the events you need to reply with an HTTP 200 OK status code. You do not need to send any content back in the reply. You can receive incoming events from Instagram using these webhooks.

If your web service returns anything else other than response code 200 OK, we will consider the event as not having been delivered. Our services will retry delivery (for a maximum of three times). In case of a timeout, we will consider the event delivered.

Contents format

Webhook calls are made using HTTP POST with the Content-Type application/json and are in the UTF-8 character set. You will receive a JSON object like this on the registered URLs:

FieldDescription
fromInformation about the sender. (See below)
toInformation about the recipient of the event. (See below)
eventThe event that occurred. (See below)
timeUtcThe time (yyyy-MM-ddTHH:mm:ss) of the event in UTC.
channelThe event channel. (e.g. "Instagram")

From:

FieldDescription
numberIdentifier of the source from where the event originated.

To:

FieldDescription
numberIdentifier to which the event was sent.

Event:

ValueTypeDescriptionInstagram MessagingGoogle Business MessagingMobilePush
referenceA reference to the object or message that triggered the event.
typeMessageDeleteOccurs when a message is deleted by the end-user.x
StoryMentionOccurs when a story mention is received.xx
UserAgentRequestedOccurs when a user agent is requested by the end-user.xx
ClientInstalledOccurs when a new client is installed by an end-user.xx
ClientUpdatedOccurs when an existing client has been updated by the end-user.xx
MessageDismissedOccurs when a message is dismissed/swiped away by the end-user.xx
MessageOpenedOccurs when a message is opened by the end-user.xx
customCan contain information in context of the event.
StoryMentionStory url
ClientInstalled/UpdatedProfile data

🚧

Note

Not all channels support the same events. For details and documentation on an event type, we ask you to refer to documentation of the specific channel.

Example event

{
    "from": {
        "number": "6f2de4d4cc6aa17da2e11c3bff5843aa"
    },
    "to": {
        "number": "5d68d44a356b72b899221e45c676cc23"
    },
    "event": {
        "type": "MessageDelete",
        "reference": "453563216"
    },    
    "timeUtc": "2021-07-05T17:08:45",
    "channel": "Instagram"
}

Whitelisting

If you want your systems to be certain that requests are sent from CM.com's systems and are not initiated by a spoofing third party, you can limit the reception of events to those originating from our IP ranges.

The IP ranges of the services that send events and could be used for our outbound traffic are:

  • 31.169.56.0/21
  • 85.119.48.0/21
  • 188.94.184.0/22

Note You should whitelist all these IP ranges. We cannot guarantee an exact IP address of specific services within these ranges as the servers can change IP within this range at any time.


Instagram

Instagram uses a numeric identifier for a sender and recipient. So-called "Instagram Scoped User ID (IGSID)" for the sender and a "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"
}

Google Business Messages

Google Business Messages uses a GUID/UUID identifier for a sender and recipient. So-called "Agent ID " for the sender and a "Conversation ID" for the recipient of the event. A person is assigned a unique Conversation ID for each agent they start a conversation with.

Human-agent request

This event occurs when a user request to speak to a human agent instead of a bot.

Example Human-agent request event

{
    "from": {
        "number": "<CONVERSATION_ID>"
    },
    "to": {
        "number": "<AGENT_ID>"
    },
    "event": {
        "type": "HumanAgentRequested",
        "reference": "83855c95-e598-48ca-8e2e-44f11520cbfc"
    },
    "timeUtc": "2021-07-05T17:08:45",
    "channel": "Google Business Messages"
}

MobilePush

Push uses a GUID/UUID identifier for a sender and recipient. So-called "Installation " for the sender and "AppKey" for the recipient without hyphens of the event.

Events are only supported if your app at least makes use of CMPush SDK v2.

Client installed

This event occurs when a user has registered within your app and is now capable of receiving push messages via installation id.

If you want to reach the user via phone number, you'll need to wait for a 'ClientUpdated' event where the user can potentially register a verified phone number.

Profile data

The following profile data is included in the event as custom data:

FieldDescriptionRemarks
clientIdIdentifier of installed clientIdentifier of your mobile app
clientVersionVersion of installed clientVersion number of your mobile app
msisdnVerified phone number registered by the end-userCan only be potentially filled for a "ClientUpdated" event
deviceOsPlatform of the deviceEither "Android", "iOs" or "iPadOS"
deviceOsVersionOS version of device platform
deviceModelName of device model used by the end-user
pushAuthorizationPush authorization chosen by the userEither "Authorized", "NotAuthorized" or "Provisional"
preferredLanguagesArray of preferred languages of the user that are configured on their device

Example Client installed event

{
    "from": {
        "number": "<INSTALLATION_ID>"
    },
    "to": {
        "number": "<APP_KEY>"
    },
    "event": {
        "type": "ClientInstalled",
        "custom": {
            "clientId": "com.cm.notifire",
            "clientVersion": "3.0.0",
            "msisdn": null,
            "deviceOs": "Android",
            "deviceOsVersion": "12",
            "deviceModel": "SM-A515F",
            "pushAuthorization": "Authorized",
            "preferredLanguages": [
                "nl"
            ]
        }
    },
    "timeUtc": "2022-06-01T17:08:45",
    "channel": "MobilePush"
}

Client updated

This event occurs when a user has updated settings within your app such as registering a verified phone number or updating the app version.

Profile data

The included profile data in the "ClientUpdated" event matches with the profile data from the "ClientInstalled" event.

Example Client updated event

{
    "from": {
        "number": "<INSTALLATION_ID>"
    },
    "to": {
        "number": "<APP_KEY>"
    },
    "event": {
        "type": "ClientUpdated",
        "custom": {
            "clientId": "com.cm.notifire",
            "clientVersion": "3.0.0",
            "msisdn": "0031612345678",
            "deviceOs": "Android",
            "deviceOsVersion": "12",
            "deviceModel": "SM-A515F",
            "pushAuthorization": "Authorized",
            "preferredLanguages": [
                "nl"
            ]
        }
    },
    "timeUtc": "2022-06-01T17:08:45",
    "channel": "MobilePush"
}

Message dismissed

This event occurs when a message is dismissed by the end-user in the notification center on their mobile device.

This doesn't guarantee the user has actually read the message as the user can just dismiss notifications without ever reading them.

Example MessageDismissed event

{
    "from": {
        "number": "<INSTALLATION_ID>"
    },
    "to": {
        "number": "<APP_KEY>"
    },
    "event": {
        "type": "MessageDismissed",
        "reference": "5dbc0313-9031-4f4f-8dc8-5ab712b20722"
    },    
    "timeUtc": "2022-06-15T17:08:45",
    "channel": "MobilePush"
}

Message opened

This event occurs when a message is tapped by the end-user in the notification center on their mobile device and will be opened in your mobile app.

Example MessageOpened event

{
    "from": {
        "number": "<INSTALLATION_ID>"
    },
    "to": {
        "number": "<APP_KEY>"
    },
    "event": {
        "type": "MessageOpened",
        "reference": "5dbc0313-9031-4f4f-8dc8-5ab712b20722"
    },    
    "timeUtc": "2022-06-15T17:08:45",
    "channel": "MobilePush"
}

Message deleted

This event occurs when a message is deleted by the end-user in your mobile app.

Example MessageDelete event

{
    "from": {
        "number": "<INSTALLATION_ID>"
    },
    "to": {
        "number": "<APP_KEY>"
    },
    "event": {
        "type": "MessageDelete",
        "reference": "5dbc0313-9031-4f4f-8dc8-5ab712b20722"
    },    
    "timeUtc": "2022-06-15T17:08:45",
    "channel": "MobilePush"
}

Did this page help you?