JivoChat Chat API 详解：全渠道客服消息接口使用指南

Chat API 让你能够处理来自任意渠道的客户请求，无论是移动应用、桌面应用，还是网站上完全自定义的聊天窗口。客服在 JivoChat 应用中接收这些会话的方式与其他渠道完全相同。

此集成使用 Webhooks 机制。JivoChat 提供一个端点用于接收渠道状态和传输客户消息；而在被集成系统一侧，也需要有一个端点用于将客服的回复传输给客户。

JivoChat 端点包含一个随机字符串以防止暴力破解攻击，同时还包含渠道标识符 JIVO_PUBLIC_ID。

要生成你专属的 JivoChat 端点，请登录 JivoChat 网页应用 或我们的某个桌面应用，然后前往 管理（Manage） -> 添加渠道（Add Channels） -> Chat API。

点击连接 Chat API（Connect chat API）。

输入渠道名称、你的 webhook 服务器 URL，选择是否启用分块传输编码（chunked encoding）选项，选择哪些客服将负责接收你所创建渠道的会话，完成后点击添加渠道（Add channel）。

现在你专属的 JivoChat 端点 URL 已生成，可以使用了。

完成！接下来你只需查看我们下方的其余说明，了解如何使用生成的端点即可。

总体工作原理

集成的主要工作流程

title JivoSite-Webhooks Channel

Customer API->JivoSite: Channel Status HTTP GET
JivoSite->Customer API: Online (1)
Customer API->User: Show custom chat window
User->Customer API: Type User Message
Customer API->JivoSite: User Message HTTP POST
JivoSite->Agent: User Message
Agent->JivoSite: Agent Message
JivoSite->Customer API: Agent Message HTTP POST
Customer API->User: Draw Agent Message

协议说明

Customer API->JivoSite: 聊天状态

GET https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID/status

标准响应为 200 OK，响应体为一个整数： 0 - 聊天不可用。客服离线，或聊天窗口已从网站上移除 1 - 聊天可用。客服在线

如果 JivoSite 中不存在 JIVO_PUBLIC_ID 对应的渠道，服务器将返回状态为 404 的 HTTP 响应。

如果响应异常，建议立即通知我们。

Customer API->JivoSite: 用户消息

POST https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID
{
"sender" :
{
"id"  : "12345",
"name" : "John Doe",
"photo" : "https://example.com/photo.jpg",
"url"  : "https://ya.ru/simple/page.html",
"phone" : "12345678901",
"email" : "john@doe.сom",
"invite" : "Hello! Can I help you?"
},
"message" :
{
"type" : "text",
"id"  : "customer_message_id",
"text" : "User Message Text"
}
}

sender.id（必填，字符串或整数）客户在 Customer API 中的标识符。如果该字段为空或缺失，消息将不会被传输。

sender.name, phone, email（可选字段，字符串）如果 JivoSite 收到这些字段，会将收到的信息展示给客服。如果没有收到，会话中客户的信息将显示为“匿名（Anonymous）”。这些值可以在会话过程中更新。

sender.photo（可选）客户头像图片链接。链接应以 “http: //” 或 “https: //” 开头。推荐图片尺寸为 128 * 128 px，格式为 png | jpg | gif。应用程序会尝试显示这些图片，但不保证显示效果完全正确。

sender.invite（可选）邀请文本。其功能类似于聊天窗口中“以客服身份发送邀请”（触发器动作）的功能。邀请的展示逻辑由 Customer API 一侧的会话实现，而邀请文本可以发送到 sender.invite 字段，客服将能看到它并了解客户是在什么背景下发起咨询的。

message.id（消息标识符）消息在 Customer API 中的标识符。除日志外，它不会在任何地方显示。它将在下一版本中用于送达/已读通知。

message.type（必填）常量 “text”。暂不支持其他消息类型，但未来将会支持。

message.text（type == text 时必填）客户消息字符串，最多 1000 个字符。如果超过 1000 个字符，我们将截断该消息。

标准响应为 200 OK。如果响应代码不是 200，建议立即通知我们。

如果 JivoSite 中不存在 JIVO_PUBLIC_ID 对应的渠道，服务器将返回状态为 404 的 HTTP 响应。

JivoSite->Customer API: 客服消息

POST <Customer API HTTPS-endpoint URL>/JIVO_PUBLIC_ID

{
"sender" : {
"name" : "Agent Name",
"photo" : "Agent Photo URL"
},
"recipient" : {
"id" : "12345"
},
"message" : {
"type" : "text",
"id"  : "jivo_message_id",
"text" : "Agent Message Text"
}
}

sender.name（客服姓名）发送该消息的客服姓名。

sender.photo（图片链接）客服头像。

recipient.id（客户标识符）客户在 Customer API 中的标识符。我们会从收到的消息中获取该值，并将其原样传回。

message.id（消息标识符）消息在 JivoSite 中的标识符。将来会用于送达/已读通知。

标准响应为 200 OK。

响应体为 JSON 格式：

{
"result" : "ok"
}

或

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

错误信息将显示在 JivoSite 的会话中，供客服查看。根据错误代码的不同，它也可能不显示。

消息输入状态通知

要通知消息输入状态，可使用带有类型标识的消息： type: “typein” - 开始输入消息。 type: “typeout” - 结束输入消息。 该类型消息中的其他字段将被忽略。

此机制在两个方向上的工作方式完全相同：从 JivoSite 到 Customer API，以及从 Customer API 到 JivoSite。

多媒体消息

多媒体消息的传输方式与文本消息相同，但它们具有特殊的 type 值和附加字段。下方列出了每种受支持的媒体类型所需的字段构成及 type 字段的值。

type 字段值	必填的附加字段	类型
video	file, file_name, file_size	视频
audio	file, file_name, file_size	音频
voice	file, file_name, file_size	语音消息
photo	file, file_name, file_size	图片
sticker	file, file_name, file_size	贴纸
document	file, file_name, file_size	文件（文件链接）
location	latitude, longitude	地理位置

多媒体消息的可选字段如下：

多媒体消息字段	说明
string file	http(s) 文件 url
string thumb	http(s) 缩略图 url（w320px）
string emoji	可用 unicode 字符替代媒体内容
number file_size	文件大小（字节），正整数
string file_name	用户自定义文件名
number duration	时长（秒），正整数
number width	宽度（像素），正整数
number height	高度（像素），正整数
string text	文本消息或评论
string performer	作者（作曲者、表演者等）
string title	标题
number latitude	纬度（实数）
number longitude	经度（实数）

消息重发

事件以 http(s) 请求的形式发送到 Customer API 服务器，每 3 秒发送一次，共发送 3 次，直到收到有效的成功响应为止。这给了服务器 6 秒的时间来更新软件，这在大多数情况下已经足够。如果服务器不可用，将在 9 秒后返回错误事件。这些默认设置可以让你快速收到发送方的响应。如果发生超时或 Customer API 错误，客服将在会话中看到一条错误消息。

Chunked 请求

JivoSite 向 Customer API 发送请求时，既可以包含 Content-Length 字段，也可以使用 Chunked 编码。