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 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": "[email protected]"
  },
  "rules": [
    "appMessaging"
  ]
}

{
  "body": "App Messaging send from the Omnichannel API",
  "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 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 [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 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:

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

from object

messagePart object

messageAlert object

messageAlertPlatforms

messageAlertApns

messageAlertFcm

messageAlertFcmNotification

Examples of sends using custom bodies are:

{
  "body": "App Messaging send from the Omnichannel API",
  "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 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