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 Comapi Enterprise Communications 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 The One 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 Comapi",
  "to": {
    "profileId": "[email protected]"
  },
  "rules": [
    "appMessaging"
  ]
}
{
  "body": "App Messaging send from Comapi",
  "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 Comapi's Chat tool

If you would like to send messages using the Enterprise Communications 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 Comapi 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 Comapi 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 Enterprise Communications 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 Comapi 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 Comapi Chat compatible send using the Enterprise Communications API:

{
  "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 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 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:

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 Comapi",
  "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 Comapi doesn'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:

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

If you need to to know the status of messages you've sent using one of our Enterprise Communications API, you can request that delivery receipts are forwarded to a URL of your choosing using Comapi's 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

πŸ‘

Check out our quick starts...

Check out our quick starts for simple code examples of how to send with the "One" API