BIRD Realtime

为您的应用打造的 Realtime API。订阅、发布、扩展。

配置时间：

实时聊天、在线状态、应用内通知和实时仪表盘，无需自行运维 WebSocket 基础设施。

app.ts

connected

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: APP_KEY,
  region: "us1",
});

const channel = bird.subscribe("orders-42");

channel.bind("order-shipped", (data) => {
  render(data);
});

app.ts

connected

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: APP_KEY,
  region: "us1",
});

const channel = bird.subscribe("orders-42");

channel.bind("order-shipped", (data) => {
  render(data);
});

从 npm install 到首个事件仅需 5 分钟

用您已经在使用的语言发布您的第一个事件。

提供 Node、Python 和 Go 的服务端 SDK，用于订阅端的浏览器客户端，以及纯 HTTP 方式——当您不想引入额外依赖时。频道无需预先配置：一旦有订阅者，它即刻存在。

const result = await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order.updated",
  channels: ["orders", "presence-lobby"],
  data: { order_id: "ord_123", status: "shipped" },
});
console.log(result.data?.length); // one entry per channel

使用 Realtime 可以构建什么

为产品的每个角落带来实时更新——从聊天和仪表盘到物流追踪和游戏，全部通过一个简洁的 API 实现。

01
实时比分和赛果
比赛更新、投票结果、选举之夜：一次发布调用即可将最新数据同时推送到每个订阅屏幕。
02
应用内聊天
每个聊天室一个频道，在线状态显示谁在线，客户端事件实现输入指示器——无需服务器往返。
03
在线协作
客户端事件通过频道在用户之间传递光标位置、选区和协同编辑信号，无需经过后端中转。
04
多人游戏
在线状态填充大厅，客户端事件传递操作指令，每场比赛一个频道，确保每位玩家实时掌握游戏状态。
05
实时图表和仪表盘
指标变化时即时发布。缓存频道为每位后加入者提供当前值，图表永远不会空白渲染。
06
在线状态指示器
在线状态频道在成员加入和离开时进行追踪；Webhook 保持您后端的名单同步。
07
实时位置追踪
客户地图上的快递员、分享路线的好友、调度屏幕上的车队：发布坐标，每位观察者实时跟踪，最后已知位置为后加入者缓存。
08
订单和配送状态
每个订单一个缓存频道保存当前状态，订阅即等同于初始状态获取。
09
拍卖和竞价
每次出价同时出现在每位竞拍者的屏幕上，缓存频道为中途加入者提供当前最高出价。
10
用户级通知推送
每位用户一个私有频道，由您的后端签名订阅，确保只有正确的客户端可以监听。

为什么选择 Realtime

实时体验是您扩展时最先出问题的部分。我们已经运营了十多年。

阅读文档

连接状态、在线状态、消息扇出、重连退避，以及吸收流量峰值的能力——这些是实时功能中容易原型化但难以运维的部分。Realtime 作为 Bird API 内的托管服务运行，因此实时频道与您已用于邮件和 SMS 的认证、可观测性和 Webhook 共享同一套体系。

presence.ts

18 members

const room = bird.subscribe("presence-room-42");

room.bind("bird:subscription_succeeded", () => {
  const members = [...room.members.values()];
  render({ me: room.myId, members });
});

room.bind("bird:member_added", (member) => {
  addToRoster(member.member_id);
});

room.bind("bird:member_removed", (member) => {
  removeFromRoster(member.member_id);
});

每一次状态变更都是一个 Webhook。

客户端随时连接和断开，无需触及您的后端。以下是后端感知方式：当第一个订阅者到达时启动高开销任务，当最后一个离开时停止，并维护您自己对房间成员的视图。

POST /webhooks/bird

signed

{
  "type": "realtime.member_added",
  "timestamp": "2026-05-19T15:42:01.221Z",
  "data": {
    "channel": "presence-room-42",
    "member_id": "usr_4hQ2m"
  }
}

realtime.channel_occupied首个订阅者加入了一个此前为空的通道。
realtime.channel_vacated最后一个订阅者已离开；通道现在为空。
realtime.member_added一个成员加入了在线状态通道。
realtime.member_removed一个成员离开了在线状态通道。
realtime.connection_count频道的连接数发生了变化。

集成了邮件，就等于集成了 Realtime。

相同的认证、相同的幂等契约、相同的错误信封、相同的 webhook 结构。唯一的区别在于传输方式：长连接 WebSocket 替代一次性 REST 发送。

Realtime。

realtime

await bird.realtime.members.send(APP_ID, "usr_4hQ2m", {
  event: "order-shipped",
  data:  { status: "shipped" },
});

无论用户在哪里连接，都能触达——同时覆盖每个标签页和设备。无需指定频道，无需追踪连接。

SMS。

sms

await bird.sms.send({
  from:     "Bird",
  to:       "+15005550006",
  text:     `Your order has shipped.`,
  category: "transactional",
});

同样的调用，只是换了一个频道。适用于需要将更新发送到手机而非已连接客户端的场景。