Custom Channels

Channel Identifier

In the API custom channels can be referenced using their custom channel ids. To find your custom channels id simply go to the Channels page and click the Id button on the custom channels section (highlighted in green below).

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

Sending messages

Sending custom channel messages is simple using the Comapi Enterprise Communications API; simply ensure that in your rules or ruleSet you include the custom channel id, and follow the guidance below:

Addressing 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. For more information on profile Ids see the The One API Overview.

Title and Body

The title and body fields of the request will be 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 please ensure you escape it to create a string.

If specified this will be used instead of your defined body template for the custom channel, but you must still provide a to section identifier, we suggest 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 with Comapi, but you will be responsible in creating the simple adaptor layer between the 3rd party systems feedback mechanisms and Comapi.

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

Comapi provides 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 via our webhooks to your integrations. The web methods are:

Receipts

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

📘

Where can I find the messageId?

Hopefully the 3rd party channel you are integrating will allow meta data or a message reference to be added to the request. If so you can use the {{messageId}} token when setting up the custom channels body template to map the Comapi message id in. This will them often be echoed on any inbound data.

See our Custom Channels section for more info.

Inbound Messages

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

You will need to 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 is available for display or processing later.