Connect to Custom Platform
Introduction
Stella allows you to integrate with a custom platform and custom livechat system. The clients and agents can stay on their own platform, and talk to each other indirectly in livechat.
Inlet: The platform where clients, customers or users can interact with the chatbot. Optionally the client can enter livechat with the outlet platform.
Outlet: The platform where agents, customer service team or admins can answer client’s livechat request. There may be minimal chatbot interaction in the form of commands.
For the custom platform, users need to host the web chat service themselves and build their own UI.
How does it work?
When a client from the inlet platform requests a livechat, we will send a livechat request to the Livechat API. The custom livechat system should handle the livechat request (such as creating a new ticket, delivering the ticket to a specific group, assigning an agent to the ticket, or other procedure that fits the system).
To see how you can request livechat in Stella, please refer to the sample code below:
return new Promise(async (resolve) => {
try {
const result = await this.createAssignment({
member: this.member,
assignmentDetails: {
summary: "summary",
groupName: "groupName",
},
createGroup: {},
history: true,
label: "Label",
meta: {}
})
console.log("Create Assignment result", result)
this.member.botMeta.liveChat = true;
this.member.group = result.groupId;
this.member.createAssignmentSuccess = true;
console.log("Create Assignment - Successfully created assignment");
} catch (err) {
console.log("Create Assignment - Fail to create assignment" + err);
this.member.createAssignmentSuccess = false;
}
resolve({ member: this.member })
})
The livechat system should send any admin replies to Stella via Webhook API, with the sendToInlet field. We will then relay the replies to the client in inlet platform.
On the other hand, when a client sends messages to the inlet bot, we will relay the messages to the outlet platform through the Relay API.
If the admin is triggering the chatbot flow, usually by typing commands, a request should be sent to the Webhook API with the sendToBot field. We will send any chatbot responses to the Send API.
Webhook API
Webhook API is the entry point of chatbot service of Sanuker. The custom platform should send a request to the Webhook API when the user type messages, click buttons, or interact with the bot in other ways. The custom platform should specify whether to send the event to bot logic, or to relay the message to the corresponding user in their inlet platform.
Documentation of requesting webhook API will be listed below:
API Endpoint
| Method | Path |
|---|---|
| POST | https://bot.stellabot.com/v2.4/customWebhook |
Query Params
| Key | Value |
|---|---|
| accessToken | To be provided |
| c | Channel ID (can be found in Channels page) |
| a | Organisation ID (can be found in Settings page) |
Header
| Key | Value |
|---|---|
| Content-type | application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
| profile | Object | Yes | User profile |
| externalId | String | Yes | Unique ID for user in custom platform |
| sendToBot | Object | No | Pass the message event to chatbot flow |
| sendToInlet | Object | No | Relay the message from admin to user |
sendToBot
| Field | Type | Required | Description |
|---|---|---|---|
| messageEvent | Object | Yes | Message Object |
messageEvent
| Field | Type | Required | Description |
|---|---|---|---|
| from | String | Yes | Unique ID for user in custom platform |
| to | String | No | Unique ID for conversation |
| type | String | Yes | eg. “PAYLOAD”, “TEXT” |
| data | Object | Yes | Message Object (Example fields are listed below. Additional fields can be added as needed.) |
| timestamp | Number | Yes | Timestamp in ms |
data
| Field | Type | Required | Description |
|---|---|---|---|
| text | String | No | Text of the message |
| payload | String | No | Payload of the button |
sendToInlet
| Field | Type | Required | Description |
|---|---|---|---|
| response | Object | Yes | Response Object |
| memberId | String | Yes | Unique ID for inlet user ( member._id from Livechat API) |
Response
| Code | Description |
|---|---|
| 200 | A successful bot flow or the message is successfully relayed to inlet user |
| 500 | An error is encountered, with the Error object in body |
Livechat API
Prepare API for Stella to send livechat request from inlet user. The API path will be saved in channel.info.livechatApi. When a user triggers the livechat event, we will send the following body as JSON to the Livechat API (only important fields are listed below):
body
| Field | Type | Description |
|---|---|---|
| member | Object | Member object of the user requesting livechat |
| assignmentDetails | Object | Details of the livechat |
| chatHistoryURL | String | (Optional) Link for the chat history of the user |
| meta | Object | (Optional) Meta data of the livechat request |
member
| Field | Type | Description |
|---|---|---|
| _id | String | Unique ID for user on Stella |
| profile | Object | User profile |
| meta | Object | Meta data of the user |
| botMeta | Object | Bot-related meta data of the user |
assignmentDetails
| Field | Type | Description |
|---|---|---|
| summary | String | (Optional) A summary of the livechat request that can be sent to the agent |
| groupName | String | (Optional) A name that the outlet system will use to create the conversation group for admin |
Response
| Code | Description |
|---|---|
| 200 | Live chat request is successfully processed |
| >= 400 | Encounter error when processing the live chat request |
Relay API
Prepare API for Stella to relay client message to the corresponding livechat conversation. The API path will be saved in channel.info.relayResponseApi. When an inlet user send messages after triggering livechat, we will send the following body as JSON to the Relay API (only important fields are listed below):
body
| Field | Type | Description |
|---|---|---|
| response | Object | Response object |
| member | Object | Member object of the inlet user |
| channel | Object | Channel object of the outlet channel that the message is relaying to |
For Response Object, you can refer to the message types.
member
| Field | Type | Description |
|---|---|---|
| _id | String | Unique ID for user on Stella |
| profile | Object | User profile |
| meta | Object | Meta data of the user |
| botMeta | Object | Bot-related meta data of the user |
botMeta
| Field | Type | Description |
|---|---|---|
| tempData | Object | Temporary meta data of the user |
channel
| Field | Type | Description |
|---|---|---|
| info | Object | Information of the channel |
Response
| Code | Description |
|---|---|
| 200 | Message is successfully relayed to the live chat |
| >= 400 | Encounter error when sending the message to the live chat |
For the error case, Stella will send the original message to the live chat tree of the channel, with the field relayMessageError containing the messages that cannot be sent to live chat. A Global node, with a trigger with condition this.messageEvent.relayMessageError, should be added to the live chat tree to capture this error. Any necessary actions or responses can be implemented in the nodes in the live chat tree to handle the error if needed.
Send API
Prepare API for Stella to send response to a specific user or conversation. If the conversationId is provided, the response should be sent to the conversation, otherwise the response should be sent to the member. The API path will be saved in channel.info.sendResponseApi. We will send the following body as JSON to the Send API (only important fields are listed below):
body
| Field | Type | Description |
|---|---|---|
| response | Object | Response object |
| member | Object | Member object that the response is sent to |
| channel | Object | Channel object |
| conversationId | String | (Optional) Unique ID for conversation that the response is sent to (same as messageEvent.to in Webhook API) |
For Response Object, you can refer to the message types.
member
| Field | Type | Description |
|---|---|---|
| externalId | String | Unique ID for user in custom platform (same as messageEvent.from in Webhook API) |
| profile | Object | User profile |
| meta | Object | Meta data of the user |
| botMeta | Object | Bot-related meta data of the user |
channel
| Field | Type | Description |
|---|---|---|
| info | Object | Information of the channel |
Response
| Code | Description |
|---|---|
| 200 | Message is successfully relayed to the live chat |
| >= 400 | Encounter error when sending the message to the live chat |
Connect to Custom Channel
- In "Channels", create a new channel.
- In "Platform", select "Custom" as the deployment platform.
- Then, "Custom Info" will be displayed below.
- Enter the endpoint URLs in "Custom Info".
