聊天对话API
⚠️自2022年1月1日起，聊天对话API处于维护模式，将不会接收新功能。Bug和安全修复将在需要时继续进行。消息客户可以参考机器人的阳光对话作为替代选择。
聊天对话API让您的应用程序充当Zendesk聊天代理，并与使用Zendesk Web Widget或Zendesk亚博聊天Widget的客户进行交互。API是一个GraphQL API这是Zendesk的第一个。亚博
除了Web部件而且聊天窗口小部件，该API与移动聊天SDK提供的聊天功能一起工作安卓而且iOS，以及Web SDK．
对话API可用于Zendesk聊天企业或高级(遗留)计划。亚博
文档
有关使用对话API的实践教程，请参见从对话API开始在开发帮助中心。
会话API的参考文档可在以下站点获得https://亚博zendesk.github.io/conversations-api/．
对话API是Zendesk发布的第一个GraphQL API。亚博这些文档托管在一个单独的站点上，以利用GraphQL模式。使用GraphQL的一个好处是可以直接从GraphQL模式生成高质量的API文档。
亚博Zendesk正在developer.zendesk.com上研究生成和发布GraphQL文档的解决方案。
请参阅以下资源以了解更多关于Grap亚博电脑端hQL的信息:
- GraphQL简介在graphql.org网站上
- 如何使用GraphQL网站
- GraphQL规范网站
- awesome-graphqlGithub上
API的路径
对话API使用以下路径之一:
WebSocket
wss: / / chat-api.zopim.com/stream/0.1/graphql/ {session_id}: {client_id}
HTTP
文章https://chat-api.zopim.com/graphql/request
使用HTTP进行身份验证。通过WebSocket连接进行所有其他请求。
聊天REST API不受为对话API引入新路径的影响。
身份验证
对话API使用OAuth2进行身份验证。要生成OAuth访问令牌，请参见OAuth身份验证在Chat REST API文档中。将令牌的范围设置为读，写,闲谈，聊天．
使用令牌启动带有对话API的代理会话。看到启动代理会话在入门指南中。
管理WebSocket
为了优化WebSocket连接的可靠性，请遵循以下最佳实践。
- 定期发送ping以防止由于空闲连接而断开连接。
｛“团体”：“萍”，“有效载荷”：“< any_payload >”｝
如果ping成功，您应该收到给定有效负载的回显。
｛“团体”：“乒乓球”，“有效载荷”：“< any_payload >”｝
- 如果WebSocket连接异常断开(例如，在没有停止会话的情况下断开)
stopAgentSession突变)，建议立即重新连接到同一个经过身份验证的WebSocket URL，以便能够恢复会话，而不需要再次设置。如果会话无法恢复，则需要通过执行命令重新设置会话startAgentSession请求，更新代理状态，并重新设置订阅。
结构化信息
您可以使用对话API向访问者发送结构化消息。与传统的纯文本消息相比，结构化消息提供了更丰富的聊天体验，包括快速回复建议、模板和交互式按钮。有关更多信息，请参见在Zendesk聊天中使用结构化消息亚博在聊天帮助中心。
分页
对话API使用Relay连接模型来提供对结果集进行切片和分页的标准机制。看到继电器游标连接规范更多信息请访问Facebook Github网站。
速度限制
对话API是有速率限制的。
| 描述 | 限制 |
|---|---|
| 请求 | 每秒100个请求。请求可以是GraphQL查询，突变(除了startAgentSession)，订阅，或“停止订阅” |
startAgentSession请求 |
每秒1个请求或每小时50个请求(以先到达者为准) |
| 已公布订阅数据 | 每秒5万个订阅数据 |
对话API也受到以下因素的限制:
| 描述 | 限制 |
|---|---|
| 最大查询深度 | GraphQL查询的最大深度为11 |
| 最大并发订阅数 | 一个代理会话一次最多只能有10个GraphQL订阅 |
由于GraphQL的特性，速率限制不同于传统的REST API速率限制。一个GraphQL请求可以替代多个REST请求。
目前没有检索速率限制状态的端点。如有需要，请自行记录使用情况。
费率限制可能会有所更改。
限制
对话API有以下限制:
常见问题解答
如果你有任何问题，请到聊天对话API社区．如果之前没有人问过，请随时提出问题。
更新日志
2020年9月9日
- 添加
msg_id参数sendMessage突变。 - 添加
msg_id字段消息类型。
2020年4月7日
- 暴露
raw_id领域的游客，VisitorChannel，代理而且部门类型。
2020年4月1日
- 中增加了对基于字符串的请求id的支持Websocket请求/响应有效负载．
2019年7月2日
- 添加
graphQLSubscriptions查询
6月6日
- 添加
current_ip字段游客类型。 - 添加
知识产权字段VisitorChannel类型。
2月27日
- 增加了对结构化消息的支持，包括
sendQuickReplies，sendButtonTemplate，sendPanelTemplate，sendPanelTemplateCarousel,sendListTemplate突变。有关更多信息，请参见在Zendesk聊天中使用结构化消息亚博在聊天帮助中心。
2019年2月12日
- 添加
external_id字段游客类型。
2019年1月7日
- 增加了对新的部门状态的支持。
DEPARTMENT_STATUS现在包括在线，离线和离开。
2018年11月28日
- 添加
代理查询
8月24日
- 修正了一个问题，不允许标签与特殊字符
addTags突变。API现在只允许在标记中使用字母数字字符、连字符(-)和下划线(_)。
法律声明
您对API的使用和访问明确以您遵守我们的政策、限制和与API相关的其他规定为条件API限制及责任，我们的改变政策，以及我们提供给您的其他文件。你亦必须遵守亚博Zendesk主订阅协议和亚博Zendesk隐私政策，在所有API的使用中。如果Z亚博endesk认为您已经或试图违反任何条款、条件或这些政策或协议的精神，您访问和使用API的权利可能会被暂时或永久撤销。