JivoChat Bot API 使用教程

我们的 Bot API 允许你将机器人平台连接到 JivoChat 中的任何对话：网站聊天、即时通讯和社交网络。添加机器人后，所有对话都会先发送到机器人提供商进行处理。

如果你在任何平台上拥有自己的机器人并希望将其连接到我们，请给我们发送邮件以生成你的提供商 ID。

数据交换

数据交换的发起方是 JivoChat，发生在收到客户发来的消息时。事件通过 webhook 机制与机器人提供商进行交换。所有来自 JivoChat 的事件都会发送到提供商的端点，作为响应，提供商会将事件发送到 JivoChat 的端点。

JivoChat 与机器人提供商之间往来的所有事件均以 HTTPS 请求方式发送，使用 POST 方法和 application/JSON 格式。请求超时时间为 3 秒，重试次数为 2 次，直到收到正常的成功响应，否则客户将被转接给人工客服。这为服务器上的软件更新提供了 9 秒的时间，在大多数情况下已经足够。

机器人提供商的端点 URL 由其自行决定。JivoChat 的端点配置如下：bot.jivosite.com/webhooks/{provider_id}，其中 provider_id 是唯一的提供商标识符，为每个提供商单独颁发。

响应代码

下表列出了 JivoChat 和机器人提供商可能返回的响应代码。

响应代码	描述
200 OK	成功的正常响应
400 Bad Request	请求格式无效。你需要检查请求字段是否符合 API 格式
401 Unauthorized	授权错误
403 Forbidden	访问被拒绝
404 Not Found	端点格式错误
405 Method Not Allowed	不支持此方法或事件
429 Too Many Request	超出单位时间内的请求次数限制
500 Internal Server Error	请求处理错误
502 Bad Gateway	服务器过载
503 Service Unavailable	服务器不可用
504 Gateway Timeout	请求执行失败

在发生异常情况时，建议在响应体中按以下格式传递错误信息：

{
  "error" :
    {
      "code": "<error code>",
      "message": "<human-readable error message>"
    }
}

错误代码

代码	描述
invalid_client	令牌客户端认证错误。随 HTTP 代码 401 Unauthorized 一起返回
unauthorized_client	通过 Authorization 请求头授权失败
invalid_request	请求缺少必填参数、使用了不支持的参数值、包含重复参数、包含多组凭据，或存在其他请求错误

身份验证

访问 API 的机器人提供商客户端的身份验证通过令牌进行，该令牌由机器人提供商生成。客户端从机器人提供商处获取令牌，并将其填入 JivoChat 中已连接的机器人渠道的设置中。JivoChat 与机器人提供商之间的所有请求均使用此令牌，令牌会传递到请求 URL 中。格式：

POST https://{bot_endpoint}/token
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/{provider_id}/{token}
Content-Type: application/json

...

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

事件类型

消息类型	方向	描述
CLIENT_MESSAGE	JivoChat API → Bot-Provider	新客户消息事件，机器人提供商需要为其提供回复选项
BOT_MESSAGE	Bot-Provider → JivoChat API	机器人对客户消息的回复
INVITE_AGENT	Bot-Provider → JivoChat API	当机器人没有可用的回复选项时，将对话转接给人工客服
AGENT_JOINED	JivoChat API → Bot-Provider	人工客服在机器人提供商或客户的发起下加入对话
AGENT_UNAVAILABLE	JivoChat API → Bot-Provider	用于通知当前应用中没有可接入对话的可用客服

CHAT_CLOSED	JivoChat API → Bot-ProvideR	对话关闭时触发的事件

CLIENT_MESSAGE

*场景：*机器人服务方已连接到通信渠道 -> 客户发送消息 -> JivoChat 将消息代理给机器人提供商 -> 消息被处理并根据场景返回响应。

事件参数

名称	类型	描述
id	String	唯一事件标识符，用于日志记录和调试
client_id	String	向 JivoChat 客户的某个渠道发送消息的用户的标识符。在客户账户内唯一
chat_id	String	进行用户与人工客服对话的聊天标识符。在客户账户内唯一
message	Message	客户消息

示例

{
  event: "CLIENT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123",
  message: {
    type: "TEXT",
    text: "Hello! How much is the delivery?",
    timestamp: 1583910736
  }
}

BOT_MESSAGE

*场景：*客户发送消息 -> JivoChat 将消息代理给机器人提供商 -> 消息被处理 -> 机器人回复准备好的消息 -> 消息发送给客户。

事件参数

名称	类型	描述
id	String	唯一事件标识符，用于日志记录和调试
chat_id	String	进行用户与人工客服对话的聊天标识符。在客户账户内唯一
message	Message	来自机器人的消息

示例

{
  event: "BOT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  message: {
    type: "BUTTONS",
      title: "Are you interested in delivery within the New York area?",
      text: "Are you interested in delivery within the New York area? Yes / No"
      timestamp: 1583910736,
      buttons: [
        {
          text: "Yes",
        }, {
          text: "No"
        }
      ]
  }
}

INVITE_AGENT

*场景：*客户发送消息 -> JivoChat 将消息代理给机器人提供商 -> 消息被处理 -> 机器人没有准备好的回复 -> 对话转接给人工客服。

事件参数

名称	类型	描述
id	String	唯一事件标识符，用于日志记录和调试
client_id	String	向 JivoChat 客户的某个渠道发送消息的用户的标识符。在客户账户内唯一
chat_id	String	进行用户与人工客服对话的聊天标识符。在客户账户内唯一

示例

{
  event: "INVITE_AGENT",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_JOINED

*场景：*客户发送消息 -> JivoChat 将消息代理给机器人提供商 -> 消息被处理 -> 机器人没有准备好的回复 -> 对话转接给人工客服 -> 人工客服加入对话。

事件参数

名称	类型	描述
id	String	唯一事件标识符，用于日志记录和调试
client_id	String	向 JivoChat 客户的某个渠道发送消息的用户的标识符。在客户账户内唯一
chat_id	String	进行用户与人工客服对话的聊天标识符。在客户账户内唯一

示例

{
  event: "AGENT_JOINED",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_UNAVAILABLE

*场景：*机器人提供商将对话转接给人工客服，但应用中没有可用的客服，此时机器人根据预设的对话流程发送消息，请用户留下联系方式。

事件参数

名称	类型	描述
id	String	唯一事件标识符，用于日志记录和调试
chat_id	String	进行用户与人工客服对话的聊天标识符。在客户账户内唯一
client_id	String	向 JivoChat 客户的某个渠道发送消息的用户的标识符。在客户账户内唯一

示例

{
  event: "AGENT_UNAVAILABLE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  chat_id: "213123",
  client_id: "213123"
}

消息类型

消息类型	描述
TEXT	普通文本消息
MARKDOWN	Markdown 格式的文本消息
BUTTONS	回复选项按钮

TEXT

消息参数

名称	类型	描述
text	String	消息文本
timestamp	String	消息创建时间戳，unix time

示例

{
  type: "TEXT",
  text: "Hello! What is your weekend routine?",
  timestamp: 1583910736
}

MARKDOWN

消息参数

名称	类型	描述
content	String	Markdown 格式的消息。第一版支持：链接、粗体、斜体
text	String	面向不支持此消息类型的通信渠道的文本回退内容，否则消息将无法发送给客户
timestamp	String	消息创建时间戳，unix time

示例

{
  type: "MARKDOWN",
  content: "To disable **PUSH notifications**, please follow the steps described in our [instructions](https://site.com/page_url)",
  text: "To disable PUSH notifications, please follow the steps described in our instructions https://site.com/page_url",
  timestamp: 1583910736
}

BUTTONS

消息参数

名称	类型	描述
buttons	Array	一组带有预设回复的按钮。最多 3 个按钮
title	String	按钮的文本标题
text	String	面向不支持此消息类型的通信渠道的文本回退内容，否则消息将无法发送给客户
button.text	String	预设回复的文本
timestamp	String	消息创建时间戳，unix time

示例

{
  type: "BUTTONS",
  title: "Could you please specify the desired delivery service?"
  text: "Could you please specify the desired delivery service? PEC and Boxberry are available",
  buttons: [
    {
      text: "PEC"
    },
    {
      text: "Boxberry"
    }
  ],
  timestamp: 1583910736
}

上一页
JivoChat CRM API 集成开发指南下一页
JivoChat Chat API 详解：全渠道客服消息接口使用指南