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

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 [email protected] would be:

[email protected]

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:

from object.

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

from object

messagePart object

messageAlert object

messageAlertPlatforms

messageAlertApns

messageAlertFcm

messageAlertFcmNotification

Examples of sends using custom bodies:

{
  "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"
  ]
}

🚧

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