Custom Channel Quick Start

This integration allows your team to chat with your customers over any messaging Channel via a custom implementation.

Connecting a Custom Channel

Step 1: Go to Settings > Channels

Step 2: Click Add Channel > Custom Channel > Connect

Step 3: Enter the destination Webhook URL where outgoing messages will be sent.

Step 4: Select the ID type for the Channel > click Next

ID types are used for user identification and are 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: [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.

Step 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/Using a Phone Number ID type allows you to initiate a conversation and send the first message to a Contact.

Pass Messages to respond.io

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

The provided code will trigger the webhook on respond.io, creating a Contact if necessary and saving the message under that 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"
      }
  ]
}'

Field	Description	Validation
channelId	Unique Channel ID	Required. Unique field. Is generated by respond.io.
contactId	Unique Contact ID	Required. Unique respond.io contact id. Max 50 characters.
events.type	Event Type	Required. Available type: message, message_echo, and message_status.
events.mld	Message ID	Required. Unique message ID. Max 50 characters.
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"

Handle Outgoing Messages from respond.io

respond.io will call the endpoint <API Base URL>/message

Ensure you apply the Outgoing Message code on the /message route of your web server.

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": "[phone]",
	"message": {
		"type": "text",
		"text": "Hello World"
	}
}'

Response - Success (HTTP status → 200)

{
	"mId": "1640141607842"
}

Authentication needs to happen at the endpoint before sending the message to the Messaging Service Provider.

Here's an example of using an express middleware for this purpose:

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

We've included an example of a Custom Channel you can test on your server. Check out our GitHub project here.

Messages Type

Sample for Text

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

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 are able to see the content.
attachment.mimeType	Mime Type of the Attachment	Optional
attachment.fileName	File Name	Optional. The File name should include an extension. Max 256 characters (including file extension). Sending a file without an 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.

Ensure that the attachment URL isn't forcibly downloaded by the browser. The HTTP response's Content-Disposition header should have 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.
longtitude	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"
	}
}

Channel Configuration

Step 1: Click Settings > Channels

Step 2: Locate the Custom Channel > click Manage

Step 3: In the Custom Channel Configuration page you will see the following configurations:

• Channel Icon - Upload an image that serves as the icon for your Custom Channel.

• Channel Name - The Channel Name can be changed and is used internally to identify the Channel.

• Webhook URL for Outgoing message — The webhook URL for outgoing messages to this Channel.

• Webhook URL for Incoming message — The webhook URL for incoming messages to this Channel.

• ID Type — These are used for user identification and are used to communicate with your custom integration server.

• Channel ID — Unique Channel ID to identify your Custom Channel.

• API Token — A unique identifier used to authenticate a user to access an API.

Step 4: Click Save Changes to update the Custom Channel configuration.

FAQ and Troubleshooting

Can I connect chats from other platforms using a Custom Channel?

Yes, you can. Here are three steps to follow:

1. In respond.io, input the destination webhook URL from the other platform into the Webhook URL for Incoming message field.

2. In the other platform, set up a webhook URL pointing to respond.io, allowing Contacts to send messages back to you.

3. You'll require a Custom Integration Server to interpret APIs from both respond.io and the other platform, enabling message exchange between them.

Make sure to confirm with the other platform that the first two steps are feasible.