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.

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.

1. Under "Resources", select "Responses".

2. Select "+ New Response".

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

4. Select "Message template" from the message types.

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

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

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

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

Request​

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

Query Parameters:

Request Body Schema: application/json

Sample Request:

• POST https://bot.api.woztell.com/sendResponses
• Content Type: application/json

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

Response​

Response Body Schema: application/json

Response Body Schema: application/json

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:

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:

Request Body Schema: application/json

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​

Response Body Schema: application/json

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.