Custom Channel

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 the API documentation of messaging service provider for reference).
2. Your custom integration server will receive the message and will post it to respond.io (in respond.io format).
3. respond.io 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, respond.io will call your custom integration server with the message payload (in respond.io 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 the 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. Tip, 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. On the respond.io platform, go to 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.
      1. Sample format: +60177872890
   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.respond.io/custom/channel/webhook/

Step 2: Pass Messages to respond.io

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

The following code will be calling the webhook on the respond.io 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": "+60177872890",
  "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": "john@respond.io",
    "phone": "+60177872890",
    "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": "+60177872890",
  "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": "john@respond.io",
    "phone": "+60177872890",
    "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": "+60177872890",
  "events": [
    {
      "type": "message_status",
      "mId": "xcvzzxcxczxczxc",
      "timestamp": 2132131321000,
      "status": {
        "value": "sent|delivered|read|failed",
        "message": "Error: Sending failed due to invalid token"
      }
  ]
}'

Response - Success (HTTP status → 200)

"OK"

Step 3: Handle Outgoing Messages from respond.io

respond.io will be calling the following endpoint <API Base URL>/message

Here is the cURL example of respond.io 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": "+60177872890",
	"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
};

Messages Type

Sample for Text

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

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

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

Sample for Quick Reply

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

Error Codes

Error (HTTP Status → 4xx)

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

Broadcast Capabilities

It is possible to send broadcast messages through a custom channel connected to respond.io, but certain conditions may cause the messages to fail to send.

With custom channels, it is not possible to detect whether a messaging window is open or closed. It is also not possible to send tagged or template messages.

Troubleshoot