Channel identifier

In the API, custom channels can be referenced using their custom channel IDs.

To find your custom channel’s ID

1. Log in to the portal.
2. Go to the Channels > Configure.
3. Select Id for the custom channel you want to use.
   
   
   

This identifier can be used in the rules array and customBody sections of your API request.

Send messages

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

Address your messages

To target who a custom channel message is delivered to, ensure you include either the field referred to in the custom channels Id field name property or a profileId with this information in the to section of the request.

Title and body

The title and body fields of the request are used to create the custom channel request, so ensure you specify these.

{
  "body": "A message via custom channels",
  "title": "A email from Comapi",
  "to": {
    "email": "[email protected]"
  },
  "rules": [
    "custom_email"
  ]
}

Channel options

The channel options section is not used with custom channels.

Custom body

You can specify a custom body for a custom channel by adding a property to the customBody section with the same name as your custom channel id. The value must be a string, so if passing JSON you must ensure you escape it to create a string.

If specified, this is used instead of your defined body template for the custom channel, but you must still provide a to section identifier. We advise you provide a profileId, which is simply your unique identifier for your user.

{
  "to": {
    "profileId": "[email protected]"
  },
  "customBody": {
	"custom_email": "{  \"personalizations\": [    {      \"to\": [        {          \"email\": \"[email protected]\"        }      ]    }  ],  \"from\": {    \"email\": \"[email protected]\"  },  \"subject\": \"Custom bodies with custom channels\",  \"content\": [    {      \"type\": \"text\/html\",      \"value\": \"Hi from Comapi\"    }  ]}"
  },
  "rules": [
    "custom_email"
  ]
}

Receipts and inbounds

You can create two-way custom channel integrations through our API, but you must be responsible for creating the simple adaptor layer between the 3rd party system’s feedback mechanisms and our platform.

Your adaption layer needs to receive the data from the 3rd party system however they specify, such as a web page, and then call on to us to record the data.

We provide two web methods to allow receipts and inbound messages to be recorded in the system, so analytics can be recorded and receipts and inbound messages sent using our webhooks to your integrations. The web methods are:

Receipts

To record receipt values for a custom channel for a message you must call the Messages web services status update method with the messageId and status.

📘

Find the messageId

Hopefully the 3rd party channel you are integrating allows metadata or a message reference to be added to the request. If so, you can use the {{messageId}} token when setting up the custom channel’s body template to map the message ID in. This is then often echoed on any inbound data.

Inbound messages

To record inbound messages from your 3rd party channel you need to call the Messages services inbound method.

You must populate the from and to objects with the identifiers used by the channel, and if possible provide a text only version of the message in the body property. The channel Data object is used to record the raw unaltered body provided by the channel, so it‘ i’s available for display or processing later.