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.

If your browser cannot download the JSON files after clicking the URL...

Please right click and "Inspect" to open the developer tools. Select "Source" and right click to download the source file by "Save as..."

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 Type	Query parameter name
API Key	accessToken

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.

Generate Template in `JSON`

WOZTELL allows you to create and manage message template in the platform. When you are sending responses with Bot API, there is a convenient way to obtain the content of a template in JSON.

Under "Resources", select "Responses".

Select "+ New Response".

Expand the tab. Select "Add Platform" and select "WhatsApp Cloud". This will allow you to apply message types specific to WhatsApp Cloud.

Select "Message template" from the message types.

Select the relevant "Integration" and click on "Update Message Template".

Choose the "Message Template" you would like to use. Then, select the relevant "Language Policy" and "Language".

Fill in the required components in the template, for instance, images and parameters. Click "Confirm" to exit this window.

In the response, switch to "Advanced" to obtain the content of the template in JSON.

Request

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

Query Parameters:

Query Parameter	Required	Type	Description
accessToken	Yes	apiKey	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

Request Body Schema: application/json

Field	Required	Type	Description
channelId	Yes	String	Channel ID in WOZTELL
memberId	No	String	`Either memberId, recipientId` Member ID in WOZTELL
recipientId	No	String	`Either memberId, recipientId` Recipient ID in integration. E.g. PSID on Facebook, phone number on WhatsApp, etc (Not guaranteed, please consult integration creator if required)
response	Yes	array	The 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

WhatsApp
Facebook

{
  "channelId": "5fe729b3094223123123",
  "recipientId": "85291239123",
  "response": [
    {
      "type": "TEMPLATE",
      "elementName": "testing",
      "languageCode": "zh_CN",
      "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"
            }
          ]
        }
      ]
    }
  ]
}

{
  "channelId": "5ece50e72efaabd58ef55027",
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "response": [
    {
      "type": "TEXT",
      "text": "Hello World"
    },
    {
      "type": "IMAGE",
      "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
    }
  ]
}

Response

Status Code	Description
200	This 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

Object	Type	Description
ok	Int	Value: `1`, status that indicate this request is successfully made or not
member	String	WOZTELL Member ID
sendResult	Object	Send result object
sendResult.ok	Int	Integration server succeed receive response
sendResult.member	String	WOZTELL 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 Code	Description
500	This request will returns HTTPS code 500 if encounter error before the bot execution.

Response Body Schema: application/json

Object	Type	Description
ok	Int	Always 0, indicate Bot found error before sending out response to integration server
err_code	String	Error code in WOZTELL
error	String	Error message

Sample Response

Status Code: 200
Content type: application/json

Success
Failure

{
  "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"
      }
    ]
  }
}

{
"ok": 0,
"err_code": 100,
"err": "Phone Number Invalid."
}

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 Parameter	Requried	Type	Description
accessToken	Yes	apiKey	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

Request Body Schema: application/json

Field	Required	Type	Description
channelId	Yes	String	Channel ID in WOZTELL
memberId	No	String	`Either memberId, recipientId` Member ID in WOZTELL
recipientId	No	String	`Either memberId, recipientId` Recipient ID in integration. E.g. PSID on Facebook, phone number on WhatsApp, etc (Not guaranteed, please consult integration creator if required)
redirect	Yes	Object	The target node you wish to redirect to.
redirect.tree	Yes	String	Target tree you wish to redirect to.
redirect.nodeCompositeId	Yes	String	Target node you wish to redirect to.
redirect.runPreAction	No	Boolean	Redirect execute pre-action; can be set as `true` or `false`
redirect.sendResponse	No	Boolean	Redirect send response; can be set as `true` or `false`
redirect.runPostAction	No	Boolean	Redirect execute post-action; can be set as `true` or `false`
meta	No	Object	`Optional` 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": true,
    "runPostAction": true
  },
  "meta": {
    "name": "Sanuker",
    "orderId": "5ecf6be76fcfda6b139d802c"
  }
}

Response

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

Response Body Schema: application/json

Object	Type	Description
ok	Int	Always 1, indicate Bot executed send response command
member	String	WOZTELL Member ID
sendResult	Object	Send result
sendResult.ok	Int	Integration server succeed receive response
sendResult.member	String	WOZTELL 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 Code	Description
500	This request will returns HTTPS code 500 if encounter error before the bot execution.

Object	Type	Description
ok	Int	Always 0, indicate Bot found error before sending out response to integration server
err_code	Int	Error code in WOZTELL
error	String	Error 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.

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

Authentication​

accessToken​

tip

Send Responses​

Generate Template in JSON​

Request​

Response​

Redirect Member to Node​

Meta object​

Request​

Response​

Error Codes​

Authentication

accessToken

Send Responses

Generate Template in `JSON`

Request

Response

Redirect Member to Node

Meta object

Request

Response

Error Codes