A8Chat Bot Task API
This is used to start a botpress flow in a messaging channel for the given user.
Each request from A8Flow to start a conversation with the given user is referred by the name "bot task" here.
The request should specify the user details with whom the chat conversation must be started by the bot. With this, the user must be able to be identified even if he is offline. Botpress flows can be built to handle these tasks. The request must have this flow name. The task will start the flow to the user in the specified messaging channel with the user details.
Given below are details of the APIs for creating and monitoring the tasks. Each request must have the API key in the authorization header.
Create or Start A Task
Request URL: https://livechat-testing.autonom8.com/
Request Method: POST
Request Header: Authorization: Bearer(API KEY)
Request JSON Body:
| KEY | TYPE | DESCRIPTION | EXAMPLE/REMARKS |
|---|---|---|---|
| webhook | string | The webhook which should be called by the bot/agent to update details about the task | http://hdfc.autonom8.com/task/ |
| user | object | Details about the user to which the bot must start the conversation with | See user object payload |
| tag | string | Easily readable name or identifier which can be used to group the tasks sent to a number of users | hdfcSurvey |
| channel | string | The messaging or conversational platform of the user. Channels supported now: whatsapp, facebook, twitter, sms, and rest | |
| botHandle | string | The name or identifier of the bot which should start the conversation | edgebot |
| bpFlowToTrigger | string | The name of the flow in botpress that this conversation should start with | survery |
| context | object | Custom data which should be passed to the flow | {"employee": "", "startDate": ""} This is an optional field. |
User Object Payload:
| KEY | TYPE | DESCRIPTION | EXAMPLE/REMARKS |
|---|---|---|---|
| userId | string | The user identifier to which the chat is initiated. In case of whatsapp channel, this could be mobile number. For facebook it is page specific user Id or PSID. | 919876543210 |
| username | string | Name of the user | Username(This is an optional field) |
Response JSON Body: The request will return a task ID which can be used to stay updated with the changes.
Sample Response: { "taskId" : "5f16c55e0340eb3554fc059b" }
Get Task Details
Request URL: https://livechat-testing.autonom8.com/
Request Method: GET
Request Header: Authorization: Bearer(API key)
Response JSON Body:
| KEY | TYPE | DESCRIPTION | EXAMPLE/REMARKS |
|---|---|---|---|
| webhook | string | The webhook which should be called by the bot/agent to update details about the task | http://hdfc.autonom8.com/task/(taskID) |
| id | string | The task identifier | 5f16c55e0340eb3554fc059b |
| tag | string | Easily readable name or identifier which can be used to group the tasks sent to a number of users | hdfcSurvey |
| clientId | string | The user identifier used in A8Chat | whatsapp_919876543210_A8Chat_edgebot |
| botHandle | string | The name or identifier of the bot which handles the conversation | edgebot |
| flowToTrigger | string | The name of the flow in botpress that this conversation started with | survey |
| orgId | string | Identifier of the organization handling the task | |
| status | string | Current status of the task | It has three states like new, inprogress(bot is handling the task), and done(task is completed). |
| context | object | Custom data that was passed to the flow | {"employee": "", "startDate": ""} Any custom data can be passed as an object. |
| result | object | End payload that is sent to the requester via webhook. This is stored only when the task is completed (done state) | {"rate" : "Good","reason" : "It was fast"}. Any custom data that the bot sends back as the response of the whole task. |
Get Task Details using Tag Name
Request URL: https://livechat-testing.autonom8.com/
Query Parameter: tag=[tag name]
Request Method: GET
Request Header: Authorization: Bearer(API key)
Response: Array of tasks with the given tag name in the org.
Botpress Events to Update/End Task
Update Task
The bot can update values to the requester by calling the updateTask event. This event gets the current event states and the payload to update. With the event state values, the payload is sent to the webhook of the requester.
bp.events.updateTask(event, value) event : Incoming event value : Payload that is to be sent to the requester ( A custom object) Sample usage of the updateTask event in a botpress action.
function action(bp: typeof sdk, event: sdk.10.IncomingEvent, args: any, { user, temp, session } = event.state)
{
/** Your code starts below */
/**
* updateSurveyResults
* @title update survery results
* @category A8chat
* @author Autonom8
*/
const updateSurveyResults = async () => {
let value = {}
if (temp.rate != '') {
value['rate'] = temp.rate
}
if (temp.reason != '') {
value['reason'] = temp.reason
}
if (temp.toadd I= '') {
value['toAdd'] = temp.toAdd
}
await bp.events.updateTask(event, value)
}
return updateSurveyResults()
/** Your code ends here */
}
End Task
After completing the task, the bot can send the values to the requester by calling the endTask event. This event gets the current event states and the payload to send to the requester. With the event state values, the payload is sent to the webhook of the requester and the task is moved to done state.
bp.events.endTask(event, value) event : Incoming event value : Payload that is to be sent to the requester ( A custom object)
Sample usage of the endTask event in a botpress action
function action(bp: typeof sdk, event: sdk.10.IncomingEvent, args: any, { user, temp, session } = event.state)
{
/** Your code starts below */
/**
* endSurvey
* @title End survey
* @category A8chat
* @author Autonom8
*/
const updateSurveyResults = async () => {
let value = {
rate = temp.rate,
reason: temp.reason,
toAdd: temp.toAdd
}
await bp.events.endTask(event, value)
}
return updateSurveyResults()
/** Your code ends here */
}