Talk(聊天)

一个会话,落在一台机器上,经网络到达。

本页讲创建会话、谁能加入、SDK,以及连接断掉时会发生什么。

01

创建会话

创建一个会话
curl -X POST https://dash.yunzheng.space/api/v1/talk/rooms \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support","kind":"room"}'
字段含义
kindroom 按 retention_days 保留历史;live 只在内存留最近几百条,不落盘。
city落在哪座城市。套餐功能;不填则由余量最多的城市接收。历史也在那里,所以不会迁移。
max_peers、max_kbps、retention_days本会话的上限,不超过套餐允许值。超过会被拒绝,而不是被悄悄下调。
public_joinfalse 表示链接不再应答,只有你后端签发的令牌能进。

应答里有 key(链接)与 join_url(托管页)。用 PUT /talk/rooms/{id}/passcode 设口令;存的是哈希,读不回来。

02

SDK

从你的页面加入
<script src="https://talk.yunzheng.space/v1.js"></script>
<script>
  var chat = OrbitTalk.join({
    room: "<room key>",
    label: "Ada",
    passcode: "",
    onMessage: function (m) { console.log(m.seq, m.label, m.body); },
    onState: function (s, d) { if (s === "open") console.log("in, " + d.members + " here"); },
    onPresence: function (p) { console.log(p.members + " here"); },
    onError: function (e) { console.error(e.code, e.message); }
  });
  chat.send("Hello");
  // later: chat.leave();
</script>

send 立即返回一个 id,消息在连接允许时发出;连接断开时它在发件箱里等待,下次连上再发。你的应用不必自己写这个缓冲。

如果由你的后端决定谁能进——你的用户、用你给的名字——就关掉 public_join,在你的服务器上用 POST /talk/rooms/{id}/join 签发令牌(peer_id 填你的用户 id,label 填显示名),再通过 fetchJoin 交给 SDK。每次重连 SDK 都会再调一次,因为令牌只有两分钟有效。

后端门
OrbitTalk.join({
  fetchJoin: function () {
    // your server calls POST /talk/rooms/{id}/join with the caller's own id and name
    return fetch("/my-api/chat-token", { method: "POST", credentials: "same-origin" })
      .then(function (r) { return r.json(); });
  },
  onMessage: function (m) { /* m.peer is YOUR user id; m.label is the name you gave */ }
});
关掉链接访问后,房间密钥本身打不开任何东西:泄露的链接对谁都没用,房间里的每个席位都是你的服务器签发的。
03

读取会话记录

消息存在承载该会话的那台机器上,不会被复制到控制面。你的账号可以用 GET /talk/rooms/{id}/history 一页一页读回来,凭的是你的 API 密钥——所以这个调用应当放在你的服务器上,和签发加入令牌的那段代码在一起。

一页一页读一个会话
var page = await OrbitTalk.history({ room: 12, key: process.env.ORBIT_TOKEN });
page.messages.forEach(function (m) { console.log(m.seq, m.at, m.label, m.body); });

// Walk forward: pass the page's "next" back as the cursor until it comes back null.
while (page.next != null) {
  page = await OrbitTalk.history({ room: 12, key: process.env.ORBIT_TOKEN, cursor: page.next });
}
字段含义
cursor读这个序号之后的内容。第一次不填,之后把上一页的 next 传回来。
limit每页条数,1 到 500。默认 200——一屏的量,而不是全部。
next下一页的游标;如果已经读完则为 null。不满一页就说明没有更多了,所以它不会带游标。
messages[].peer发送者。走后端门时这就是你自己的用户 id——正因如此,一年后再看这段记录才还有意义。
每一次读取都会写进你账号的审计日志:哪个会话、游标、每页多少条、返回了多少条。直播聊天不落盘,所以它返回空页并附一句说明。
04

连接断掉时

每条消息都带会话分配的序号,SDK 记住它看到的最后一个。重连时只请求之后的内容,所以不重复、不遗漏。你发出的每条消息也带自己的 id,重置后重发会得到第一份已有的序号,而不会被存两次。

已过期的历史会被明确报告为缺口,而不是静默跳过:重连后的第一帧会说明还能提供的最早序号。
05

计量什么

限额含义
会话数可以拥有多少个
并发连接所有会话加起来同时在线的人数
每月消息数每条只计一次,无论客户端重发多少次
每月流量进出字节
历史天数会话的上限;直播聊天不保留
继续

相关文档

开始使用

Orbit 账户的组织方式、控制台各处的功能,以及从登录到让我们的网络开始应答一个域名的最短路径。

DNS 托管

建区、把注册商的 NS 指向我们、管理记录。含加权应答、带健康检查的记录、顶点 ALIAS 与区文件导入。

接入主机名

整域委派、单主机名委派,或加一条 CNAME 而完全不动现有 DNS。三者各自的代价与适用场景。

← 全部文档