The app integration can receive inbound messages from an user, which will be sent to the bot to be processed asynchronously. The bot will process the user messages and create a response.
The response will be provided to the messaging.performSend operation from which you can send it back to the user using the external messaging service APIs. See Sending.
The method messaging.performReceive will be called with 2 arguments. The first argument is the sdk object and the second argument is the bundle object.
const performReceive = (sdk, bundle) => {
return [evt1, evt2]
}The bundle.request field contains the webhook request sent from the external messaging service. It contains the following fields:
| Field | Description |
|---|---|
request.content | The body of the request. If the content type of the request was set to application/json it will be transformed into an object; otherwise it will be a plain string. |
request.method | The HTTP method of the request. |
request.query | The parsed query string of the request. |
request.headers | The parsed headers of the request. |
Your app's logic must process this request and return an array of messages or actions to be handled by the bot. The returned array can be empty if no processing is needed by the bot.
The follow section details the format that needs to be followed when returning a messages array to Chatlayer:
| Field | Description | Type | Required |
|---|---|---|---|
user | Define user properties | User Properties | Yes |
actor | Define from who the message is coming User Properties | Yes | |
type | Type of the message payload | message/action | Yes |
message | Message data. Only required when type is message | Messages | No |
action | Action data. Only required when type is action | Actions | No |
timestamp | Timestamp the message was generated in number of milliseconds elapsed since January 1, 1970 00:00:00 UTC. If not provided, the time at which the message was received will be used | number | Yes |
| Field | Description | Type | Required |
|---|---|---|---|
id | User id used to differentiate from other conversations | string | Yes |
firstName | First name of the user | string | No |
lastName | Last name of the user | string | No |
preferredLanguage | Preferred language for the conversation | string | No |
| Field | Description | Type | Required |
|---|---|---|---|
type | Type of entity the message is coming from | "user" | Yes |
// a text message
const message = {
user: {
id: "user_id",
firstName: "John",
lastName: "Doe",
preferedLanguage: "en"
},
actor: {
type: "user"
},
type: "message",
message: {
messageType: "text",
text: "Hi from user",
},
timestamp: 1646415058102
}
return [message]In the following schemas we will only describe the actual message format and omit the user data, actor, timestamp, and other fields.
| Field | Description | Type | Required |
|---|---|---|---|
messageType | Type of the message | "text" | Yes |
text | Text contained in the message | string | Yes |
{
"message": {
"messageType": "text",
"text": "Hey bot, how are you doing?"
}
}Postback is used when a user clicks on a button or some other response trigger. The payload provided is usually base64 encoded data.
{
"message": {
"messageType": "postback_v2",
"payload": "jkhasiopwqnm12ikonhbio",
"title": "Button title"
}
}Upload can be used when the user sends an uploaded file in the bot.
{
"message": {
"messageType": "upload",
"url": [
"https://upload.com/image1",
"https://upload.com/image2"
]
}
}Besides the messaging capabilities, we can also trigger certain actions by returning an action object.
The value of action.data.handover.to can be bot or agent:
| Value | Description |
|---|---|
bot | Onload the conversation to the bot again. |
agent | Offload the conversation to the agent (the bot will not reply anymore after this). |
{
"type": "action",
"action": {
"type": "conversation_handover",
"data": {
"handover": {
"to": "bot"
}
}
},
"timestamp": 1646415058102,
"actor": {
"type": "user"
},
"user": {
"id": "user_id"
}
}Each conversation has session data that can be read in the bot. You can add session data to the conversation by specifying a session object. The names you give to your object keys are only for your organization and do not matter to Chatlayer.
const message = {
user: {
id: "user_id",
},
actor: {
type: "user"
},
type: "message",
message: {
messageType: "text",
text: "Hi from user",
},
session: {
myKey: {
foo: "bar"
}
},
timestamp: 1646415058102
}