Skip to main content

BotAPI

Bot API is built around REST. You can call our APIs through standard HTTP request with your api key placed in the query parameter. In turn, WOZTELL will return JSON-encoded response, with corresponding data that can determine wether related operations are completed.

Before getting started, you can first download the BotAPI Postman Collection and Environment in JSON format.

Authentication

accessToken

The access token should be placed as a query parameter as accessToken in the request. The access token can be generated following this guide.

Each API may have different scope, picking any one scope is enough for calling the API.

Security Scheme TypeQuery parameter name
API KeyaccessToken
tip

Alternatively, the Access Token can also be put in the authorization header as Bearer Token.


Send Responses

To send responses on behalf of your chatbot to a specific member in WOZTELL.

Request

Authorizations: accessToken(bot:sendResponses, bot:admin)

Query Parameters:

Query ParameterRequiredTypeDescription
accessTokenYesapiKeyThe access token should be placed as a query parameter as accessToken in the request. The access token can be generated following this guide. Each API may have different scope, picking any one scope is enough for calling the API

Request Body Schema: application/json

FieldRequiredTypeDescription
channelIdYesStringChannel ID in WOZTELL
memberIdNoStringEither memberId, recipientId
Member ID in WOZTELL
recipientIdNoStringEither memberId, recipientId
Recipient ID in integration. E.g. PSID on Facebook, phone number on WhatsApp, etc (Not guaranteed, please consult integration creator if required)
responseYesarrayThe data you wish to send as a response. You can construct the response object by referencing from integration documentations or copy from Bot builder.

Sample Request:

  • POST https://bot.api.woztell.com/sendResponses
  • Content Type: application/json
{
"channelId": "5fe729b3094223123123",
"recipientId": "85291239123",
"response": [
{
"type": "TEMPLATE",
"accountId": "617060612312312",
"namespace": "6c17f742_9f7f_4d8d_92ee_327cfvb356j",
"elementName": "testing",
"languageCode": "zh_CN",
"languagePolicy": "deterministic",
"components": [
{
"type": "header",
"parameters": [
{
"type": "video",
"video": {
"id": "caf8bc1a-fbc0-4dc3-9d08-434sdf6df"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "123"
}
]
}
]
}
]
}

Response

Status CodeDescription
200This request will returns HTTPS code 200 if the bot started execution. In the response body, a JSON String containing a "ok" flag with value 1 indicating execute success.

Response Body Schema: application/json

ObjectTypeDescription
okIntValue: 1, status that indicate this request is successfully made or not
memberStringWOZTELL Member ID
sendResultObjectSend result object
sendResult.okIntIntegration server succeed receive response
sendResult.memberStringWOZTELL Member ID
sendResult.resultObjectArray of send result from integration server, should have ok, messageEvent, error (Optional) fields for displaying result of each response

Status CodeDescription
500This request will returns HTTPS code 500 if encounter error before the bot execution.

Response Body Schema: application/json

ObjectTypeDescription
okIntAlways 0, indicate Bot found error before sending out response to integration server
err_codeStringError code in WOZTELL
errorStringError message

Sample Response

  • Status Code: 200
  • Content type: application/json
{
"ok": 1,
"member": "5ece50f3bf385b25c4e08db5",
"sendResult": {
"ok": 1,
"member": "5ece50f3bf385b25c4e08db5",
"result": [
{
"result": {
"messages": [
{
"id": "gBGGhSZphigfAglySd38a9T4jAE"
}
],
"meta": {
"api_status": "stable",
"version": "2.31.5"
}
},
"messageEvent": {
"from": 85291239123,
"to": 85232193219,
"data": {
"text": "Hello World"
},
"type": "TEXT",
"timestamp": 1611900841740,
"messageId": "gBGGhSZphigfAglySd38a9T4jAE"
},
"chatId": "5ece50f3bfa915g5c4e08db5"
},
{
"result": {
"messages": [
{
"id": "gBGGhSZafi5th8lySd38a9T4jAE"
}
],
"meta": {
"api_status": "stable",
"version": "2.31.5"
}
},
"messageEvent": {
"from": 85291239123,
"to": 85232193219,
"data": {
"url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
},
"type": "IMAGE",
"timestamp": 1611900841740,
"messageId": "gBGGhSZafi5th8lySd38a9T4jAE"
},
"chatId": "5ece50f3bfa915g5c4e08db6"
}
]
}
}
  • Status Code: 500
  • Content type: application/json
{
"ok": 0,
"err": "User is not authorized."
}

Redirect Member to Node

Redirecting a member to a specific node in tree and executing all or partial components of the node. This is useful for performing complex operations on a member and keeping all the bot logic in the tree instead of hard-coding in an api.

If memberId is not provided, the system would search for a member with the provided recipientId.

Meta object

To use the API passed meta object in transform response or actions of targeted node, use the following code to access your meta.

this.agendaMeta

Example:

To access in transform response or actions
return new Promise((resolve, reject) => {
// ...
const name = this.agendaMeta.name // "Sanuker"
const orderId = this.agendaMeta.orderId // "5ecf6be76fcfda6b139d802c"
// ...
})

Request

POST https://bot.api.woztell.com/redirectMemberToNode

Authorizations: accessToken(bot:redirectMemberToNode, bot:admin, api:admin)

Query Parameters:

Query ParameterRequriedTypeDescription
accessTokenYesapiKeyThe access token should be placed as a query parameter as accessToken in the request. The access token can be generated following this guide. Each API may have different scope, picking any one scope is enough for calling the API

Request Body Schema: application/json

FieldRequiredTypeDescription
channelIdYesStringChannel ID in WOZTELL
memberIdNoStringEither memberId, recipientId
Member ID in WOZTELL
recipientIdNoStringEither memberId, recipientId
Recipient ID in integration. E.g. PSID on Facebook, phone number on WhatsApp, etc (Not guaranteed, please consult integration creator if required)
redirectYesObjectThe target node you wish to redirect to.
redirect.treeYesStringTarget tree you wish to redirect to.
redirect.nodeCompositeIdYesStringTarget node you wish to redirect to.
redirect.runPreActionNoBooleanRedirect execute pre-action.
redirect.sendResponseNoBooleanRedirect send response.
redirect.runPostActionNoBooleanRedirect execute post-action.
metaNoObjectOptional
Meta object provided to the node.
Meta object can be accessed in target node via this.agendaMeta.

Sample Request

Content type: application/json

{
"channelId": "5ece50e72efaabd58ef55027",
"memberId": "5ece50f3bf385b25c4e08db5",
"recipientId": null,
"redirect": {
"tree": "5ecf6cfba3b6643c33a64079",
"nodeCompositeId": "j4Bivxm0GWhnNV1m",
"runPreAction": true,
"sendResponse": null,
"runPostAction": false
},
"meta": {
"name": "Sanuker",
"orderId": "5ecf6be76fcfda6b139d802c"
}
}

Response

Status CodeDescription
200This request will returns HTTPS code 200 if the bot started execution.

Response Body Schema: application/json

ObjectTypeDescription
okIntAlways 1, indicate Bot executed send response command
memberStringWOZTELL Member ID
sendResultObjectSend result
sendResult.okIntIntegration server succeed receive response
sendResult.memberStringWOZTELL Member ID
sendResult.result[Object]Array of send result from integration server, should have ok, messageEvent, error (Optional) fields for displaying result of each response

Status CodeDescription
500This request will returns HTTPS code 500 if encounter error before the bot execution.
ObjectTypeDescription
okIntAlways 0, indicate Bot found error before sending out response to integration server
err_codeIntError code in WOZTELL
errorStringError message

Sample Response

  • Status Code: 200
  • Content: application/json
{
"ok": 1,
"member": "5ece50f3bf385b25c4e08db5",
"sendResult": {
"ok": 1,
"member": "5ece50f3bf385b25c4e08db5",
"result": [
{
"ok": 1,
"messageEvent": {
"from": 85291239123,
"to": 85232193219,
"data": {
"text": "Hello World"
},
"type": "TEXT",
"timestamp": 1611900841740,
"messageId": "gBGGhSZphigfAglySd38a9T4jAE"
}
},
{
"ok": 1,
"messageEvent": {
"from": 85291239123,
"to": 85232193219,
"data": {
"url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
},
"type": "IMAGE",
"timestamp": 1611900841740,
"messageId": "gBGGhSZafi5th8lySd38a9T4jAE"
}
}
]
}
}
  • Status Code: 500
  • Content: application/json
{
"ok": 0,
"err_code": 108,
"err": "channelId is required."
}

Error Codes

WOZTELL will return corresponding error codes to the request side when there is an error occurred.

CodeDescription
100Phone Number provided is invalid. Either the number does not exist or does not have a linked WhatsApp account
104Facebook PSID is invalid or the access token resides in the designated channel is invalid
108Parameter(s) is missing
112Channel with the corresponding channelId cannot be found
113WhatsApp server Error