在移动应用中使用

可以。组件是普通 HTTP API 上的一个瘦客户端，那个 API 里没有任何东西假设了浏览器——没有 cookie、没有重定向、JSON 进 JSON 出。iOS 或 Android 应用访问的是同一个代理，同一个套餐，同一份配额。没有单独的移动产品要买，也没有 SDK 要装。

会变的是应用怎么证明它是谁，这点在你发布一个别人能解包的二进制之前，值得做对。

两条路，以及你要哪条

如果你的应用已经有后端，就用它。 你的服务器持有站点密钥，签发短时效签名 token；应用向你的服务器要一个，再把它发给我们。密钥永远不会打包进应用，token 几分钟就过期，哪些用户能开对话由你决定。有得选的话，走这条路。

如果应用没有后端，它可以改用公开站点密钥——就是网站组件用的那把。明白这意味着什么：密钥可以从任何应用二进制里提取出来，而且和网站不同，这里没有域名可以核对。你得故意打开它，在控制台里，站点 Setup 标签页上的 Also used from a mobile app。在那之前，没有浏览器来源的请求会被拒绝。

这种情况下，紧接着勾选它下面的 Require each app install to register。你的应用首次运行时调用一次 /v1/install，保存返回的 id，之后每个请求都带上它。请求按已注册的安装限速，所以提取出来的密钥不会让一个调用方无限制地消耗机器人共享的配额。代价是每个安装多一次调用。

请求顺序

Base URL 是 https://kavilo.cloud。每个请求都把凭证放在请求头里——要么 Authorization: Bearer <token>，要么 X-Kavilo-Key: kw_pub_…。

• POST /v1/install — 只在勾了上面那个设置时，首次运行调用一次。保存它返回的 installId，之后作为 X-Kavilo-Install 发送。
• POST /v1/session — 打开或恢复。发送 {"conversationId": "…"}，首次为空。返回要保存的 id、问候语、游标，以及到目前为止的历史。
• POST /v1/message — 发送一轮。立即返回 202；回复从你正在读的那条通道到达。
• POST /v1/poll — 接收回复的两种方式之一。发送你的游标，拿到所有新内容。最多等 25 秒，拿不到才返回空，所以循环调用是长轮询，不是忙等。
• GET /v1/stream — 轮询的替代方案：以服务器推送事件的形式接收相同的帧。
• POST /v1/end — 访客结束。发送对话记录，关闭对话。

轮询和流式读的是同一份缓冲、同一个游标，所以可以在对话中途切换而不丢东西。手机上轮询通常更容易：网络切换时无需特殊处理就能撑过去，而且用户阅读期间它不会占着一个 socket 不放。

读取回复

每个帧有 seq、kind，通常还有 text。每收到一个 token 帧就追加上去。这一轮到 final 结束，它带着完整答案——以它为准，替换你累积的内容，这样重连不会让你把回复显示两遍。一轮也可能以 error 结束。只有这两种结束方式；没有单独的 “done” 帧要等。

一条消息不一定只有一条回复。访客在代理还在回答时又发了第二条，会并入同一轮。一个应用如果死等“每条消息一条回复”，迟早会挂住；一直读到 final 为止。

应用切到后台

对话静默十五分钟会被关闭，对话记录随之发出——这和网页上的规则一样，网页上访客关掉标签页和起身泡茶看起来完全一样。手机休眠很容易越过这条线。

所以回到前台时，用你存下的 id 再调一次 /v1/session。如果对话还开着就继续；如果被关了就拿到一个全新的。无论哪种情况，响应都会给你历史，让你重新绘制屏幕。把这个调用当作屏幕加载的方式，而不是错误处理。

还没有的

附件。聊天 API 没有上传端点，应用和网页都没有，所以访客没法发一张坏掉零件的照片。如果这正是你的应用要解决的，告诉我们——有人真的需要时，它会排到前面。

从这里开始

向我们索要参考客户端，我们会把完整顺序用 Swift 和 Kotlin 发给你——各约一百行，短到值得读一遍而不是盲信。发邮件到 hello@kavilo.cloud，说明你在哪个平台。