WOZTELL 公共 API 集成指南 | 收件箱文档

公共 API

介绍

公共集成 API 允许你无需操作平台界面即可执行某些 Inbox 集成操作。借助集成 API，你还可以通过聊天机器人逻辑控制 Inbox 集成。

API 端点

请使用以下公共集成 API 的端点 URL：
https://api.inbox.woztell.sanuker.com/v1.0/

身份验证

要对集成 API 进行身份验证，需要使用该集成所需的 Payload 和 SignedContext。

  • Payload: {"appIntegration":"appIntegrationId","app":"appId"}
  • SignedContext: (signature).{{base64(JSON.stringify(payload))}}
  1. 通过调用 installedIntegrations 查询 Inbox 集成相关信息，使用 开放 API。

请求：


query {

  apiViewer {

    installedIntegrations {

      appId

      _id

      signature

      integrationId

    }

  }

}
复制

响应：

{
    "data": {
        "apiViewer": {
            "installedIntegrations": [
                {
                    "appId": "62062c0b717195320192b18f7",
                    "_id": "6420fig28e65b466d4607ea2",
                    "signature": "mKq60mpKn/YzaP5123tWU+AWX65LqT6BHkBIfq9d3os=",
                    "integrationId": "inbox"
                }
            ]
        }
    }
}
复制

  1. 使用以下格式创建 Payload：

    {"appIntegration":"appIntegrationId","app":"appId"}

Payload 示例：

{"appIntegration":"6420fig28e65b466d4607ea2","app":"62062c0b717195320192b18f7"}
复制

  1. 将 Payload 编码为 Base64 格式。

  2. 将编码后的 Payload 与 Signature 组合，生成以下格式的 SignedContext：

    (signature).{{base64(JSON.stringify(payload))}}

SignedContext 示例

mKq60mpKn/YzaP5123tWU+AWX65LqT6BHkBIfq9d3os.eyJhcHBJbnRlZ3JhdGlvbiI6IjY0MjBmaWcyOGU2NWI0NjZkNDYwN2VhMiIsImFwcCI6IjYyMDYyYzBiNzE3MTk1MzIwMTkyYjE4ZjcifQ==
复制

  1. 将其添加到请求头中，分别作为 X-Woztell-Payload 和 X-Woztell-SignedContext。


GET /list-threads

此 API 用于获取对话线程列表。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数

名称类型说明必填
channelIdstring按渠道筛选线程否
folderIdstring按文件夹筛选线程否
memberIdstring按成员筛选线程否
externalIdstring使用 ExternalId 按成员筛选线程否
threadIdstring按线程 ID 筛选否
userIdstring按分配用户筛选线程否
limitinteger控制返回线程数量 （默认值：10）否
afterstring用于获取下一批线程，可从响应中的 paging.cursors 中获取否
beforestring用于获取下一批线程，可从响应中的 paging.cursors 中获取 否

请求：
curl --location --request GET 'https://api.inbox.woztell.sanuker.com/v1.0/api/list-threads?folderId=main&limit=10'
复制

响应：



{
  "ok": 1,
  "data": [
    {
      "channelId": "string",
      "memberId": "string",
      "externalId": "string",
      "userId": "string",
      "threadId": "T0000027",
      "title": "Test User",
      "folder": "main"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjU5N2I1MDZkOTcyYTMzNzU3ZTM3ZDgz",
      "before": "NjRhZTE5Yjg3MzQ0YjA1YzM2ZmMyOWQw"
    },
    "hasPrevious": true,
    "hasNext": true
  }
}
复制

GET /list-users

此 API 用于获取 Inbox 用户列表。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数


名称类型说明必填
channelIdstring按渠道筛选用户（如代理角色、名称、邮箱和头像来自渠道设置)否
folderIdstring按具有访问权限的文件夹筛选用户否
userIdstring按用户的 Woztell ID 筛选用户否
memberIdstring按成员筛选用户否
externalIdstring使用 ExternalId 按成员筛选用户否
threadIdstring按线程 ID 筛选用户否
limitinteger控制返回用户数量（默认值：10）否
afterstring 用于获取下一批用户，可从响应中的 paging.cursors 获取否
beforestring用于获取上一批用户，可从响应中的 paging.cursors 获取否

请求：

curl --location --request GET 'https://api.inbox.woztell.sanuker.com/v1.0/api/list-users?folderId=main&userId=632a6743a63fdf590c994a77&channelId=6486be9adfc4ee3ff9d39348'

复制

响应：



{
  "ok": 1,
  "data": [
    {
      "userId": "6474449cdfc4ee3646d392bf",
      "role": "ADMIN",
      "agentRole": "MANAGER",
      "channel": "6474449cdfc4ee3646d392bd",
      "name": "Test User",
      "email": "test_user@email.com",
      "icon": "string"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjU5N2I1MDZkOTcyYTMzNzU3ZTM3ZDgz",
      "before": "NjRhZTE5Yjg3MzQ0YjA1YzM2ZmMyOWQw"
    },
    "hasPrevious": true,
    "hasNext": true
  }
}
复制

POST /update-thread-folder

此 API 用于将线程分配到特定文件夹。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数：

名称 类型 说明 必填
memberId string 成员 ID 是
folderId string 文件夹 ID 是

端点：

https://api.inbox.woztell.sanuker.com/v1.0/update-thread-folder
复制

请求：

{
    "memberId": "920o80371234550009a01abd",
    "folderId": "test-folder"
}
复制

响应：

{
    "ok": 1,
    "thread": {
        "_id": "640a123opp71ee2b943ed283",
        "wAppId": "90283b9b71780112208b18f7",
        "wChannelId": "621f29ae4e11986de280e29d",
        "wMemberId": "630d8962168350009a01acd",
        "_version": 2,
        "createdAt": 1678377627235,
        "etag": "d-bkiiEXyVO8CtQ9cHw/5zjO581rM",
        "externalId": "8521234567",
        "folder": "test-folder",
        "lastChatAt": 1682454661289,
        "lastMessage": "[Bot] Hello there!",
        "threadId": "T0000999",
        "title": "John Lee",
        "updatedAt": 1682661372214,
        "lastReadAt": 1682487947711,
        "unreadCount": 0
    }
}
复制

POST /update-thread-agent

此 API 用于为线程添加或移除指定负责人。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数：

名称 类型 说明 必填
memberId string 成员 ID 是
userId string 团队成员的用户 ID 是


备注
团队成员的用户 ID 可从 Open API 的团队成员处获取。
添加负责人：

query {
    apiViewer{
        app {
            _id
            teamMembers{
                user{
                    _id
                    email{
                        email
                    }
                }
            }
        }
    }
} 


端点：

要求：

添加受让人

{
    "memberId": "64744e15bdcca70008a4358f",
    "userId": "632a6743a63fdf590c994a77"
}

移除受让人
{
    "memberId": "64744e15bdcca70008a4358f",
    "userId": null
}

回复：
{
    "ok": 1,
    "thread": {
        "_id": "66892602f94ff12ece18f325",
        "wAppId": "62062b9b71780332208b18f7",
        "wChannelId": "636ccf9ff3cfa1164f3e1d1d",
        "wMemberId": "636cd3d81daca40008296f08",
        "_version": 2,
        "createdAt": 1685530114217,
        "etag": "d-NHYurKhPB+vkbZKV87SrRXRvl+0",
        "externalId": "85254063598",
        "folder": "main",
        "lastChatAt": 1705381701000,
        "lastMessage": "image_test",
        "threadId": "T0000035",
        "title": "Decco Ip",
        "updatedAt": 1705487316616,
        "lastReadAt": 1705461548278,
        "unreadCount": 0,
        "wUserId": "5c0e33c7502129b7ac9e143f"
    }
}


POST /update-thread-title

此 API 用于更新对话线程的标题。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数：

名称 类型 说明 必填
memberId string 属于线程的成员 ID 可选（与 threadId 二选一）
threadId string 线程 ID 可选（与 memberId 二选一）
title string 新的线程标题 是

端点：

https://api.inbox.woztell.sanuker.com/v1.0/update-thread-title
复制

请求


{
  "ok": 1,
  "thread": {
    "_id": "6475559cdfc4ee3646d392bb",
    "_version": 2,
    "etag": "d-x9crPvAd751WYspgcj0cBtisySE",
    "wAppId": "6475559cdfc4ee3646d392bb",
    "wChannelId": "6474449cdfc4ee3646d392bd",
    "wMemberId": "6474449cdfc4ee3646d392be",
    "externalId": "5466281980129353",
    "wUserId": "6474449cdfc4ee3646d392bf",
    "threadId": "T0000027",
    "createdAt": 1686541076488,
    "updatedAt": 1686541076488,
    "lastReadAt": 1686541076488,
    "lastChatAt": 1686541076488,
    "unreadCount": 0,
    "title": "John (Key Client)",
    "folder": "main"
  }
}
复制

POST /internal-message

此 API 用于在线程中发送一条内部消息。

身份验证

要进行身份验证，请按照此指南操作，在请求头中填写 X-Woztell-Payload 和 X-Woztell-SignedContext。

参数：

名称 类型 说明 必填
threadId string 线程 ID（用于识别消息所属会话） 必填（threadId 或 memberId 二选一）
memberId string 成员 ID 必填（threadId 或 memberId 二选一）
message string 要发送的内部消息内容 是

端点

https://api.inbox.woztell.sanuker.com/v1.0/internal-message
复制

请求

{
    "threadId": "T0000001",
    // or "memberId": "6475559cdfc4ee3646d392bb",
    "message": "Test Internal Message"
}
复制

响应

{
    "ok": 1,
    "message": "Test Internal Message",
    "memberId": "6475559cdfc4ee3646d392bb",
    "threadId": "T0000001"
}
复制

最后更新于 2024 年 3 月 18 日