Is this article helpful?

We love to hear from you!

Table of Contents

Custom Channel Quick Start

JQ Lee Updated by JQ Lee

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

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

Important: Make sure that you implement the Outgoing Message code on the /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
};

Tip: We also provide you with an example of a custom channel you can try to deploy on your server. Please have a look at 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.

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.

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

Feeling stuck? Do not fear.

Need assistance? Contact us for support. Help is here!

Custom Channel Overview

Can't find what you're looking for?

Talk to an expert here!

Contact Us
Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)