Custom Channel

Integrate third-party messaging app into Alexa360

This feature is currently in Beta.

Custom Channel is only available to Business Plan and above only. Please upgrade or subscribe to a Business or Enterprise if you wish to use this feature!

Tips: We also provide you with an example of custom channel you can try to deploy it on your server.

How it works

Receiving a Message:

To receive a message via a Custom Channel, the following steps need to be followed:

1 .When a contact attempts to send a message, the messaging service provider will call your custom integration server with the message payload (please review API documentation of messaging service provider for reference).

2. Your custom integration server will receive the message and will post it to Alexa360 (in Alexa360 format).

Alexa360 will receive the post request, save the message and display it on the messaging module.

Sending a Message:

To send a message via a Custom Channel, the following steps need to be followed:

1. When a User/Workflow/Broadcast will attempt to send a message, Alexa360 will call your custom integration server with the message payload (in Alexa360 format).

2. Your custom integration server will receive the message and will post it to the messaging service provider in the format that they require (please review API documentation of messaging service provider for reference).

3. The messaging service provider will receive the Webhook and confirm if the message has been delivered successfully. Tips, if the message is not delivered successfully, you can try adding a retry mechanism in your custom integration server.

Configuration

Step 1: Create a channel

1. In Alexa360 platform, go to the Settings > Channels and click on ADD CHANNEL button

2. Select Custom Channel

3.Enter the API Base URL

4. Select the ID type for the channel and click NEXT. This ID is for the purpose of user identification and will be used to communicate with your custom integration server. There are two types of IDs available:

1. Phone Number: Use this if the messaging service provider recognizes contacts based on their Phone Number.

Sample format: [phone]

2. Custom ID: Use this if the messaging service provider recognizes contacts based on a custom-generated ID.

1. The maximum character length is 50

2. A-Z, a-z, 0-9, _ , =, + , / and @ are allowed.

5. The following dialog will provide the Channel ID, API Token, and Webhook URL e.g.

1. Channel ID: gfd8g7fd89dgfd

2. API Token: aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd

3. Webhook URL: https://app.alexa360.io/custom/channel/webhook/

Tips: Using Phone Number ID type allows you to initiate a conversation and send the first message to a contact.

Step 2: Pass Messages to Alexa360

Webhook URL is used to POST the Messages, Messaging Echoes and Messaging Receipts to the Alexa360 platform.

The following code will be calling the webhook on the Alexa360 platform and will be creating the contact (if it does not exist) and saving the message against the contact.

Sample for Messages

curl -X POST \
  https://app.respond.io/custom/channel/webhook/ \
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "channelId": "gfd8g7fd89dgfd",
  "contactId": "[phone]",
  "events": [
    {
      "type": "message",
      "mId": "xcvzzxcxczxczxc",
      "timestamp": 2132131321000,
      "message": {
        "type": "text",
        "text": "Hello World"
      }
    }
  ],
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",
    "countryCode": "MY",
    "email": "[e-mail]",
    "phone": "[phone]",
    "language": "en"
  }
}'

Sample for Messaging Echoes

curl -X POST \
  https://app.respond.io/custom/channel/webhook/ \
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "channelId": "gfd8g7fd89dgfd",
  "contactId": "[phone]",
  "events": [
    {
      "type": "message_echo",
      "mId": "xcvzzxcxczxczxc",
      "timestamp": 2132131321000,
      "message": {
        "type": "text",
        "text": "Hello World"
      }
    }
  ],
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "profilePic": "<https://static.independent.co.uk/s3fs-public/thumbnails/image/2015/07/08/14/pic.jpg>",
    "countryCode": "MY",
    "email": "[e-mail]",
    "phone": "[phone]",
    "language": "en"
  }
}'

Sample for Messaging Receipts

curl -X POST \
  https://app.respond.io/custom/channel/webhook/ \
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "channelId": "gfd8g7fd89dgfd",
  "contactId": "[phone]",
  "events": [
    {
      "type": "message_status",
      "mId": "xcvzzxcxczxczxc",
      "timestamp": 2132131321000,
      "status": {
        "value": "sent|delivered|read|failed",
        "message": "Error: Sending failed due to invalid token"
      }
  ]
}'

Fields

Field	Description	Validation
channelId	Unique Channel ID	Required. Unique field. Is generated by Alexa360​
contactId	Unique Contact ID	Required. Unique Alexa360 contact id. Max 50 char
events.type	Event type	Required. Available type: message, message_echo, and message_status
events.mId	Message ID	Required. Unique message ID. Max 50 char
events.timestamp	UNIX Epoch Time(milliseconds)	Required. Time of the event that triggered the callback
events.message.type	Message type	Required. Available message types: text, attachment, location and quick_reply. Refer Message Type section for other message type samples.
events.message.text	Message text	Required. Max length 7,000 characters
events.status.value	Text	Required if event.type is message_status. Available status values: sent, delivered, read, and failed
events.status.message	Text	Required if events.status.value is failed.
contact.firstName	First name	Optional. Max 50 characters
contact.lastName	Last name	Optional. Max 50 characters
contact.profilePic	Profile pic URL	Optional. Avatar size should be no more than 100 kb. Recommended 720x720
contact.locale	Locale Code	Optional. Refer here for the list of values.
contact.countryCode	Country Code	Optional. 2 letters country code - ISO ALPHA-2 Code
contact.timezone	Time zone	Optional. (min: -24) (max: 24)
contact.email	Email address	Optional. Max 50 characters
contact.phone	Phone number	Optional. Max 18 characters
contact.language	Language	Optional. ISO 639-1

Response - Success (HTTP status → 200)

"OK"

Step 3: Handle Outgoing Messages from Alexa360

Alexa360 will be calling the following endpoint <API Base URL>/message

Important: Make sure that you implement Outgoing Message code on the /message route in your web server

Here is the cURL example of Alexa360 calling the endpoint

curl -X POST \
  <API Base URL>/message \
  -H 'authorization: Bearer aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
	"channelId": "gfd8g7fd89dgfd",
	"contactId": "[phone]",
	"message": {
		"type": "text",
		"text": "Hello World"
	}
}'

Response - Success (HTTP status → 200)

{
    "mId": "1640141607842"
}

Authentication has to be done on the endpoint before passing the message to the Messaging Service Provider. Here is an express middleware example

const {validationResult} = require('express-validator');

const validateToken = (req, res, next) => {
    const apiToken = <<API Token>>
    const bearerToken = req.headers.authorization;

    if (!bearerToken)
        return res.send(401)

    const token = bearerToken.substring(7, bearerToken.length);

    if (apiToken !== token) {
        return res.send(401)
    }
    next();
};

module.exports = {
    validateToken
};

Tips: We also provide you with an example of custom channel you can try to deploy it on your server.

Messages Type

Sample for Text

{
  "type": "text",
  "text": "Welcome to respond.io",
}

Fields

Field	Description	Validation
type	Message type	Required. text
text	Message text	Required. Max length 7,000 characters

Sample for Media File

{
  "type": "attachment",
  "attachment": {
    "type": "image|video|audio|file",
    "url": "https://abc/japan.png",
    "mimeType": "image/png",
    "fileName":"company logo.png",
    "description": "latest company logo"
  }
}

Field	Description	Validation
type	Message type	Required. attachment.
attachment.type	Attachment type	Required.Available attachment types: image, video, audio and file
attachment.url	URL	Required. Max 2,000 characters. Make sure it’s a public link so users or contacts able to see the content
attachment.mimeType	Mime type of the attachment	Optional
attachment.fileName	File name	Optional. File name should include extension. Max 256 characters (including file extension). Sending a file without extension or with the wrong extension might cause the contact or user to be unable to open the file
attachment.description	File description	Optional. Max 256 characters. Only applicable for attachment.type = image

Please make sure that the URL provided for the attachment is not downloaded forcibly by the browser (i.e. the Content-Disposition header in the HTTP response should be the default value which is inline)

Sample for location

{
  "type": "location",
  "latitude": 0.123456,
  "longitude": -0.1234,
  "address": "Sky Suites, Jalan P. Ramlee, Kuala Lumpur, 50250 Kuala Lumpur, Wilayah Persekutuan Kuala Lumpur"
}

Field	Description	Validation
type	Message type	Required. location
latitude	Coordinates	Required. Latitude (±90°) within valid ranges
longitude	Coordinates	Required. Longitude (±180°) within valid ranges
address	Location Address	Optional. Max 256 characters

Sample for Quick Reply

{
  "type": "quick_reply",
  "title": "Select your preferred language",  
  "replies": [
    "Malay",
    "English"
  ]
}

Field	Description	Validation
type	Message type	Required. quick_reply
title	Quick reply title	Required. Max 256 characters
replies	Reply text	Required. Max 10 replies with max 256 characters for each reply

Error Codes

Error (HTTP Status → 4xx)

{
    "error": {
        "message": "Error message"
    }
}

{

"error": {

"message": "Error message"

}

}

Troubleshoot

This feature is currently in Beta.