Table of Contents
Custom Channel Quick Start
Configuration
Step 1: Create a channel
- On the respond.io platform, go to Settings > Channels and click on ADD CHANNEL button.
- Select Custom Channel.
- Enter the API Base URL.
- 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:
- Phone Number: Use this if the messaging service provider recognizes contacts based on their Phone Number.
- Sample format:
+60177872890
- Sample format:
- Custom ID: Use this if the messaging service provider recognizes contacts based on a custom-generated ID.
- The maximum character length is 50.
A-Z,a-z,0-9,_,=,+,/and@are allowed.
- Phone Number: Use this if the messaging service provider recognizes contacts based on their Phone Number.
- The following dialog will provide the Channel ID, API Token, and Webhook URL e.g.
- Channel ID:
gfd8g7fd89dgfd - API Token:
aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd - Webhook URL:
https://app.respond.io/custom/channel/webhook/
- Channel ID:
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"
}
]
}'
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"
Step 3: Handle Outgoing Messages from respond.io
respond.io will be calling the following endpoint <API Base URL>/message
/message route in 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": "+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",
}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. |
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. |
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"
}
}
