App Messaging

Channel Identifier

In the API this channel can be referenced using: appMessaging

This identifier can be used in the rules array, and customBody sections.

Sending messages

Sending in-app messages via App Messaging is simple using the Omnichannel API; simply ensure that in your rules or ruleSet you include the appMessaging channel, and follow the guidance below:

Addressing your messages

To target who a App Messaging message is delivered to include a profileId in the to section of the request. For more information on profile Ids see the Omnichannel API overview.

Conversations

Messages are grouped together by a conversationId into conversations. If you don't specify a conversationId on a send a unique one will automatically be assigned therefore starting a new conversation. If you reference an existing conversationId then the new message will be appended to that conversation.

{
  "body": "App Messaging send from the Omnichannel API",
  "to": {
    "profileId": "[email protected]"
  },
  "rules": [
    "appMessaging"
  ]
}
{
  "body": "App Messaging send from the Omnichannel API",
  "to": {
    "profileId": "[email protected]"
  },
  "conversationId": "[email protected]",
  "rules": [
    "appMessaging"
  ]
}
{
  "to": {
    "profileId": "[email protected]"
  },
  "channelOptions": {
    "appMessaging": {
      "from": {
        "profileId": "Acme-Support",
        "name": "Support"
      }
    }
  },
  "conversationId": "[email protected]:Acme Support",
  "rules": [
    "appMessaging"
  ],
  "messageParts": [
    {
      "type": "application/json",
      "data": "{\r\n\"myData1\": \"My custom data 1\",\r\n\"moreMyDate\": \"Put what you like in here\"\r\n}"
    }
  ]
}

Sending messages compatible with Chat

If you would like to send messages using the Omnichannel API into the web widget or chat SDK it will need specific sender profile id and conversation ids to work.

Chat compatible conversation id

The conversation id will be structured as follows:

{Team name}_{Profile Id}

The team name will be the Chat team name you want to send from e.g. Customer Services with any spaces replaced by _ , so for "Customer Services" it would be "Customer_Services".

The profile id is the users profile id with any spaces replaced with a _ , so a complete conversation id for a chat between Customer Services and [email protected] would be:

[email protected]

Chat compatible team profile id

All chat SDK compatible conversations will have only 2 participants the chat team and the end customer. To ensure that messages you send via the Omnichannel API are seen as sent from a chat team you must specify the optional channelOptions section (described below) specifying the message is from the correct profile id for the chat team you are sending on behalf of. The profileId will be structured as follows:

TEAM\{Team name}

The team name will be the Chat team name you want to send from e.g. Customer Services with any spaces replaced by _ , so for "Customer Services" it would be "Customer_Services" e.g.

TEAM\Customer_Services

See below for an example of a Chat compatible send using the Omnichannel API:

{
  "body": "Test from the Omnichannel API",
  "to": {
    "profileId": "anon_1dae9f4e-23a2-4b1e-9bdd-03490c2133b3"
  },
  "channelOptions": {
    "appMessaging": {
      "from": {
        "profileId": "Team\\Customer_Services",
        "name": "Customer Services"
      }
    }
  },
  "conversationId": "Customer_Services_anon_1dae9f4e-23a2-4b1e-9bdd-03490c2133b3",
  "rules": [
    "appMessaging"
  ]
}

Channel Options

The following additional channel options can be used to control the App Messaging channels most common options. To use the channel options create a object with your options in the requests channelOptions section in the appMessaging property:

PropertyTypeDescription
fromfrom objectThe profile Id the message is being sent from, if not set the profile Id from the access token is used

from object

PropertyTypeDescription
profileId*stringThe profile Id the message is being sent from, if not set the profile Id from the access token is used
namestringThe name to display to the user
{
  "body": "How can we help you today?",
  "to": {
    "profileId": "[email protected]"
  },
  "channelOptions": {
    "appMessaging": {
      "from": 
      {
      	"profileId": "Acme-Support",
      	"name": "Support"
      }
    }
  },
  "conversationId": "[email protected]:Acme Support",
  "rules": [
    "appMessaging"
  ]
}

Custom Body

The Omnichannel API automatically creates a text based App Messaging message if you only define the body property when sending a message, but you can specify advanced options if you use the customBody property and define a appMessaging object within it using the details below:

PropertyTypeDescription
fromfrom objectWho the message is being sent from
metadataobjectAny JSON meta data you want to send with the message, useful for driving custom experiences
parts*array of messagePartThe parts that form your message i.e. the content
alertmessageAlert objectDetails of the alert to be displayed on receipt of the message

from object

PropertyTypeDescription
profileId*stringThe profile Id the message is being sent from, if not set the profile Id from the access token is used
namestringThe name to display to the user

messagePart object

PropertyTypeDescription
data*stringString representationof the message part, for non text MIME types use base64
typestringThe MIME type (if applicable) of the part
namestringA name for the part
urlstringA URL associated with the message part
sizeintegerSize of the message part in bytes

messageAlert object

PropertyTypeDescription
titlestringTitle for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
bodystringBody for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
platformsmessageAlertPlatforms objectThe platform specific details for the alert. If specified, these are set verbatim and alert.title / alert.body values are ignored

messageAlertPlatforms

PropertyTypeDescription
apnsmessageAlertApns objectThe APNS native channel push message specific details
fcmmessageAlertFcm objectThe FCM native channel push message specific details

messageAlertApns

PropertyTypeDescription
badgeintegerThe value to display on the application badge
soundobjectThe soundfile to play on the device when the notification arrived
alertstringThe alert to display on the device when the notification arrives
payloadobjectThe payload to send to the device

messageAlertFcm

PropertyTypeDescription
collapse_keyobjectThe collapse key to send to FCM
dataobjectThe payload to send to the device
notificationmessageAlertFcmNotification objectDetails of the notification to display

messageAlertFcmNotification

PropertyTypeDescription
titlestringThe title to display
bodystringThe body to display
iconstringThe icon to display

Examples of sends using custom bodies are:

{
  "body": "App Messaging send from the Omnichannel API",
  "to": {
    "profileId": "[email protected]"
  },
  "conversationId": "[email protected]:Acme Support",
  "customBody": {
    "appMessaging": {
      "from": "Acme Corp",
      "alert": {
        "title": "Acme Support Update",
        "body": "You have a new message on your support ticket, click here to read it"
      },
      "parts": [
        {
          "type": "text/plain",
          "data": "Your item has arrived and your account has been credited $50.00"
        }
      ]
    }
  },
  "rules": [
    "appMessaging"
  ]
}

🚧

Cannot use a customBody and channelOptions together

It's not possible to define a customBody and channelOptions together in the same request as we won't know which settings to use, so either use the universal send with channelOptions or define everything using a customBody

Receipts and Inbounds

To receive feedback or inbound messages from App Messaging sends please see the following:

Inbound Messages

Allows you to receive App Messaging messages sent. Messages are delivered to a URL of your choosing using the webhook system. See the Inbound event in the Message Events section for more details.

Receipts

If you need to to know the status of messages you've sent using one of our Omnichannel API, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts:

  • Sent
  • Delivered
  • Read
  • Failed