Links

Custom Channel

Integrate third-party messaging app into respon.io
This feature is currently in Beta. If you encounter any issues, please contact us here!
Custom Channel is only available to Enterprise Plans only. Please upgrade or subscribe to an Enterprise Plan 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. Please have a look at our GitHub project here.
custom channel flow image

How it works

Receiving a Message:

To receive a message via a Custom Channel, the following steps need to be followed:
  1. 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. 2.
    Your custom integration server will receive the message and will post it to respond.io (in respond.io format).
  3. 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. 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. 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. 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. 1.
    In respond.io platform, go to the Settings > Channels and click on ADD CHANNEL button
  2. 2.
    Select Custom Channel
  3. 3.
    Enter the API Base URL
  4. 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. 1.
      Phone Number: Use this if the messaging service provider recognizes contacts based on their Phone Number.
      Sample format: +60177872890
    2. 2.
      Custom ID: Use this if the messaging service provider recognizes contacts based on a custom-generated ID.
      1. 1.
        The maximum character length is 50
      2. 2.
        A-Z, a-z, 0-9, _ , =, + , / and @ are allowed.
  5. 5.
    The following dialog will provide the Channel ID, API Token, and Webhook URL e.g.
    1. 1.
      Channel ID: gfd8g7fd89dgfd
    2. 2.
      API Token: aaaxczsadzxcasdacxzcasdaaaxczsadzxcasdacxzcasd
    3. 3.
      Webhook URL: https://app.respond.io/custom/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 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.
curl -X POST \
**<https://app.respond.io/custom/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": "[email protected]",
"phone": "+60177872890",
"language": "en"
}
}'
Fields
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 char
events.type
Event type
Required. message
events.mId
Message ID
Required. Unique message ID. Max 50 char
events.timestamp
UNIX Epoch Time(millieseconds)
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
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 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
};
Tips: We also provide you with an example of custom channel you can try to deploy it on your server. Please have a look at our GitHub project here.

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
Descrtiption
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

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

Troubleshoot

This feature is currently in Beta. If you encounter any issues, please contact us here!