# Custom Channel Quick Start #### 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: `+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.
**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.`IS-Messenger`/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 IS-Messenger** **Webhook URL** is used to post the **Messages**, **Messaging Echoes** and **Messaging Receipts** to the IS-Messenger platform. The provided code will trigger the webhook on IS-Messenger, creating a Contact if necessary and saving the message under that Contact. **Sample for Messages** ``` curl -X POST \ https://app.is-global.com/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": "", "countryCode": "MY", "email": "john@IS-Messenger", "phone": "+60177872890", "language": "en" } }' ``` **Sample for Messaging Echoes** ``` curl -X POST \ https://app.is-global.com/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": "", "countryCode": "MY", "email": "john@is-messenger.com", "phone": "+60177872890", "language": "en" } }' ``` **Sample for Messaging Receipts** ``` curl -X POST \ https://app.is-global.com/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 IS-Messenger. | | contactId | Unique Contact ID | Required. Unique IS-Messenger 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 IS-Messenger** IS-Messenger will call the endpoint `/message` Ensure you apply the **Outgoing Message** code on the `/message` route of your web server. Here is the cURL example of IS-Messenger calling the endpoint: ``` curl -X POST \ /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 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 = <> 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](https://chat.openai.com/link). **Messages Type** **Sample for Text** ``` { "type": "text", "text": "Welcome to IS-Messenger", } ``` | **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 IS-Messenger, 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 IS-Messenger, allowing Contacts to send messages back to you. 3. You'll require a **Custom Integration Server** to interpret APIs from both IS-Messenger and the other platform, enabling message exchange between them. Make sure to confirm with the other platform that the first two steps are feasible.