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:

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

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 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