Custom Channel

Integrate third-party messaging app into YesHello dashboard

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

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 API documentation of messaging service provider for reference).

  2. Your custom integration server will receive the message and will post it to YesHello (in YesHello format).

  3. YesHello 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, YesHello will call your custom integration server with the message payload (in YesHello 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 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. 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. In YesHello platform, go to the 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.

      Sample format: +60177872111

    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.yeshello.chat/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 YesHello

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

The following code will be calling the webhook on the YesHello 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": "john@respond.io",
    "phone": "+60177872890",
    "language": "en"
  }
}'

Fields

FieldDescriptionValidation

channelId

Unique Channel ID

Required. Unique field. Is generated by YesHello

contactId

Unique Contact ID

Required. Unique YesHello 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(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

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 YesHello

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

Fields

FieldDescriptionValidation

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

type

Message type

Required. text

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

type

Message type

Required. location

latitude

Coordinates

Required. Latitude (Β±90Β°) within valid ranges

longitude

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

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!

Last updated