Channel identifier

In the API this channel can be referenced using: appMessaging.

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

Send messages

To send in-app messages using the Enterprise Communications API you must ensure that in your rules or ruleSet you include the appMessaging channel.

Address your messages

To target who an app messaging message is delivered to, include a profileId in the to section of the request.

Conversations

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

{
  "body": "App Messaging send from Comapi",
  "to": {
    "profileId": "dave@acme.com"
  },
  "rules": [
    "appMessaging"
  ]
}

{
  "body": "App Messaging send from Comapi",
  "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}"
    }
  ]
}

Send messages compatible with Chat

If you would like to send messages using the Enterprise Communications API into the web widget or chat SDK, this requires specific sender profile IDs and conversation IDs to work.

Chat compatible conversation ID

The conversation ID must be structured as follows:

{Team name}_{Profile Id}

The team name is the Chat team name you want to send from, for example, Customer Services, with any spaces replaced by , so for_Customer Services it would be Customer_Services.

The profile ID is the user’s 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 have only 2 participants; the chat team and the end customer. To ensure that messages you send through the Enterprise Communications API are seen as sent from a Chat team you must specify the optional channelOptions section specifying that the message is from the correct profile ID for the chat team you are sending on behalf of.

The profileId must be structured as follows:

TEAM\{Team name}

The team name is the Chat team name you want to send from, for example, Customer Services, with any spaces replaced by , so for_Customer Services it would be Customer_Services:

TEAM\Customer_Services

Example of a Chat compatible send:

{
  "body": "Test from Comapi",
  "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 channel’s most common options.

To use the channel options, create an 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 Comapi Enterprise Communications 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 metadata you want to send with the message, useful for driving custom experiences.
`parts`*	array of messagePart	The parts that form your message; 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 representation of 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. This is ignored if any details are set in platforms.
`body`	string	Body for the notification to send to all platforms. 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 sound file 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:

{
  "body": "App Messaging send from Comapi",
  "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"
  ]
}

🚧
customBody and channelOptions
It's not possible to define a customBody and channelOptions together in a single 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

Inbound messages

Allows you to receive App Messaging messages sent. Messages are delivered to a URL of your choosing using the webhook system.

Receipts

If you need to to know the status of messages you've sent using one of our Enterprise Communications APIs, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system.

You can receive the following types of receipts:

Sent
Delivered
Read
Failed