Woztell 机器人 API 文档 - 参考与错误代码

BotAPI 机器人接口

Bot API 基于 REST构建。您可以通过标准的HTTP请求调用我们的API，并将您的api密钥放置在查询参数中。然后，WOZTELL将返回JSON编码的响应，其中包含相应的数据，您可以根据这些数据确定相关操作是否已完成。

在开始之前，您可以首先下载BotAPI Postman集合 和 环境 文件（以 JSON 格式）

如果您的浏览器在点击URL后无法下载JSON文件...
请右键点击并选择“检查”以打开开发者工具。选择“源代码”，然后右键点击以“另存为...”下载源文件。

认证​​

accessToken​

access token应该作为 查询参数 放置为 accessToken 在请求中。可以按照这个 指南生成access token。

每个API可能有不同的权限范围，选择任何一个权限范围即可调用API。

安全方案类型 查询参数名
API密钥 accessToken
想法
提示

另外，Access Token 也可以放在授权头中，作为 Bearer Token。


发送响应​

代表您的聊天机器人向WOZTELL中的特定成员发送响应。

在 JSON 中生成模板​

WOZTELL允许您在平台中创建和管理消息模板。当您使用 Bot API 发送响应时，可以方便地以 JSON 格式获取模板的内容。

  1. 在“资源”下，选择“响应”。
  1. 选择“+ 新响应”。
  1. 展开选项卡。选择“添加平台”并选择“WhatsApp Cloud”。这将允许您应用特定于WhatsApp Cloud的消息类型。
  1. 从消息类型中选择“消息模板”。
  1. 选择相关的“集成”，然后点击“更新消息模板”。
  1. 选择您想要使用的“消息模板”。然后，选择相关的“语言政策”和“语言”。
  1. 填写模板中所需的组件，例如图片和参数。点击“确认”退出此窗口。
  1. 在响应中，切换到“高级”以获取模板内容的 JSON。

请求​

授权: accessToken(bot:sendResponses, bot:admin)

查询参数：

查询参数 是否必填 类型 描述
accessToken 是 apiKey accessToken应该作为查询参数accessToken放在请求中。可以根据此 指南生成。每个API可能有不同的权限范围，选择其中一个权限范围即可调用API

请求体模式： application/json

字段 是否必填 类型 描述
channelId 是 字符串 WOZTELL中的频道ID
memberId 否 字符串 可以使用memberId或recipientId
WOZTELL中的成员ID
recipientId 否 字符串 可以使用memberId或recipientId
集成中的接收者ID。例如，Facebook上的PSID，WhatsApp上的电话号码等（无法保证，必要时请咨询集成创建者）
response 是 数组 您希望作为响应发送的数据。您可以通过参考集成文档或从Bot构建器中复制来构建响应对象。


示例请求：
  • 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"
            }
          ]
        }
      ]
}
  ]
}
复制

响应

状态码 描述
200 如果机器人开始执行，则此请求将返回HTTPS代码200。

响应体模式： application/json

对象 类型 描述
ok Int 值： 1，表示请求是否成功执行
member String WOZTELL成员ID
sendResult 对象 发送结果对象
sendResult.ok Int 集成服务器成功接收到响应
sendResult.member String WOZTELL成员ID
sendResult.result 对象 集成服务器发送的结果数组，应包含 ok、 messageEvent、 error (可选)字段，用于显示每个响应的结果
状态码 描述
500 如果在机器人执行之前遇到错误，此请求将返回 HTTPS 代码 500。

响应主体架构: application/json

对象 类型 描述
ok 整数 始终为 0，表示在向集成服务器发送响应之前出现“未找到”错误
err_code 字符串 中的错误代码 in WOZTELL

示例响应

  • 状态码: 200
  • 内容: 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"
        }
      }
    ]
  }
}
复制
  • 状态码: 500
  • 内容: application/json
{
  "ok": 0,
  "err_code": 108,
  "err": "缺少channelId参数。"
}
复制

将成员重定向到节点​

将成员重定向到树中的特定节点并执行节点的所有或部分组件。这对于对成员执行复杂操作并将所有机器人逻辑保留在树中，而不是硬编码在API中，非常有用。

如果未提供memberId，系统将使用提供的recipientId查找成员。

Meta对象​

要在变换响应或目标节点的操作中使用传递的meta对象，可以使用以下代码访问您的meta。

this.agendaMeta
复制

示例：

在变换响应或操作中访问
return new Promise((resolve, reject) => {
  // ...
  const name = this.agendaMeta.name // "Sanuker"
  const orderId = this.agendaMeta.orderId // "5ecf6be76fcfda6b139d802c"
  // ...
})
复制

请求​

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

授权: accessToken(bot:redirectMemberToNode, bot:admin, api:admin)

查询参数：

查询参数 是否必填 类型 描述
accessToken 是 apiKey accessToken应该作为查询参数accessToken放在请求中。可以根据此 指南生成。每个API可能有不同的权限范围，选择其中一个权限范围即可调用API

请求体模式： application/json

字段 是否必填 类型 描述
channelId 是 字符串 WOZTELL中的频道ID
memberId 否 字符串 memberId或recipientId
WOZTELL中的成员ID
recipientId 否 字符串 memberId或recipientId
集成中的接收者ID。例如：Facebook上的PSID，WhatsApp上的电话号码等（无法保证，请咨询集成创建者是否需要）
redirect 是 对象 您希望重定向到的目标节点。
redirect.tree 是 字符串 您希望重定向到的目标树。
redirect.nodeCompositeId 是 字符串 您希望重定向到的目标节点。
redirect.runPreAction
是
字符串
重定向执行预操作；可设置为 true 或 false
redirect.sendResponse
是
布尔值
重定向发送响应；可设置为 true 或 false
redirect.runPostAction
是
布尔值
重定向执行后操作；可设置为 true 或 false
meta
是
对象
可选
提供给节点的元对象。
可以通过 this.agendaMeta 在目标节点中访问元对象。错误代码

示例请求

内容类型： application/json

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

响应​

状态码 描述
200 如果机器人开始执行，则此请求将返回HTTPS代码200。

响应体模式： application/json

对象 类型 描述
ok Int 始终为1，表示机器人已执行发送响应命令
member 字符串 WOZTELL成员ID
sendResult 对象 发送结果
sendResult.ok Int 集成服务器成功接收到响应
sendResult.member 字符串 WOZTELL成员ID
sendResult.result [对象] 集成服务器返回的发送结果数组，应该包含 ok、 messageEvent、 error (可选)字段，用于显示每个响应的结果


状态码 描述
500 如果在机器人执行之前遇到错误，此请求将返回HTTPS代码500。
对象 类型 描述
ok Int 始终为0，表示机器人在发送响应到集成服务器之前遇到错误
err_code Int WOZTELL中的错误代码
error 字符串 错误信息


响应示例

  • 状态码：200
  • 内容: 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"
        }
      }
    ]
  }
}
复制
  • 状态码: 500
  • 内容: application/json
{
  "ok": 0,
  "err_code": 108,
  "err": "channelId is required."
}
复制


当发生错误时，WOZTELL会将相应的错误代码返回给请求方。
代码 描述
100 提供的电话号码无效。电话号码不存在或没有关联的WhatsApp账户
104 Facebook PSID无效或访问令牌所处的指定频道无效
108 缺少参数
112 找不到具有相应channelId的频道
113 WhatsApp服务器错误
最后更新于