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": "dave@acme.com"
  },
  "rules": [
    "appMessaging"
  ]
}

{
  "body": "App Messaging send from the Omnichannel API",
  "to": {
    "profileId": "dave@acme.com"
  },
  "conversationId": "Customer_Services_dave@acme.com",
  "rules": [
    "appMessaging"
  ]
}

{
  "to": {
    "profileId": "dave@acme.com"
  },
  "channelOptions": {
    "appMessaging": {
      "from": {
        "profileId": "Acme-Support",
        "name": "Support"
      }
    }
  },
  "conversationId": "dave@acme.com: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 dave@acme.com would be:

Customer_Services_dave@acme.com

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:

Property	Type	Description
from	from* object	The profile Id the message is being sent from, if not set the profile Id from the access token is used

from object

Property	Type	Description
`profileId`*	string	The profile Id the message is being sent from, if not set the profile Id from the access token is used
`name`	string	The name to display to the user

{
  "body": "How can we help you today?",
  "to": {
    "profileId": "dave@acme.com"
  },
  "channelOptions": {
    "appMessaging": {
      "from": 
      {
      	"profileId": "Acme-Support",
      	"name": "Support"
      }
    }
  },
  "conversationId": "dave@acme.com: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:

Property	Type	Description
`from`	from* object	Who the message is being sent from
`metadata`	object	Any JSON meta data you want to send with the message, useful for driving custom experiences
`parts`*	array of messagePart	The parts that form your message i.e. the content
`alert`	messageAlert* object	Details of the alert to be displayed on receipt of the message

from object

Property	Type	Description
`profileId`*	string	The profile Id the message is being sent from, if not set the profile Id from the access token is used
`name`	string	The name to display to the user

messagePart object

Property	Type	Description
`data`*	string	String representationof the message part, for non text MIME types use base64
`type`	string	The MIME type (if applicable) of the part
`name`	string	A name for the part
`url`	string	A URL associated with the message part
`size`	integer	Size of the message part in bytes

messageAlert object

Property	Type	Description
`title`	string	Title for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
`body`	string	Body for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
platforms	messageAlertPlatforms* object	The platform specific details for the alert. If specified, these are set verbatim and alert.title / alert.body values are ignored

messageAlertPlatforms

Property	Type	Description
`apns`	messageAlertApns* object	The APNS native channel push message specific details
`fcm`	messageAlertFcm* object	The FCM native channel push message specific details

messageAlertApns

Property	Type	Description
`badge`	integer	The value to display on the application badge
`sound`	object	The soundfile to play on the device when the notification arrived
`alert`	string	The alert to display on the device when the notification arrives
`payload`	object	The payload to send to the device

messageAlertFcm

Property	Type	Description
`collapse_key`	object	The collapse key to send to FCM
`data`	object	The payload to send to the device
`notification`	messageAlertFcmNotification* object	Details of the notification to display

messageAlertFcmNotification

Property	Type	Description
`title`	string	The title to display
`body`	string	The body to display
`icon`	string	The icon to display

Examples of sends using custom bodies are:

{
  "body": "App Messaging send from the Omnichannel API",
  "to": {
    "profileId": "dave@acme.com"
  },
  "conversationId": "dave@acme.com: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