消息网关 API
一个 API，接入所有消息渠道
通过同一个 REST 端点发送 WhatsApp Business、SMS、Telegram、Messenger、Instagram 和 TikTok 消息。预付费，按出站消息计费，提供投递 Webhook 和测试模式。
- 低至
- $0.0003
- 每条出站消息
- 注册即送
- 100
- 条免费消息
- 最低承诺
- 无
- 预付费，无需签约
curl https://api.omnimessage.co/v1/messages \
-H "Authorization: Bearer om_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-shipped" \
-d '{
"channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
"to": "+971501234567",
"type": "text",
"text": { "body": "Your order #1042 has shipped." },
"reference": "order-1042"
}'{
"id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
"object": "message",
"mode": "live",
"channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
"channel_type": "whatsapp",
"direction": "outbound",
"to": "+971501234567",
"from": "+971800123456",
"type": "text",
"content": {
"text": { "body": "Your order #1042 has shipped." }
},
"status": "queued",
"error": null,
"reference": "order-1042",
"metadata": {},
"billing": {
"source": "wallet",
"amount_micros": 1000,
"package_grant_id": null,
"refunded": false
},
"created_at": "2026-10-05T09:30:00.000Z",
"sent_at": null,
"delivered_at": null,
"read_at": null,
"failed_at": null
}渠道
七种渠道类型，一种请求结构
连接您已有的发送方。每个发送方都会成为一个渠道 ID，您将其传给同一个端点，各渠道回报的状态也完全一致。
- $0.001WhatsApp Business在您自己的 Cloud API 号码上发送模板、交互式消息和媒体。文本 · 附件 · 模板 · 回复按钮 · 列表 · URL 按钮 · 位置 · 联系人
- $0.0005SMS从您自己的 Twilio 号码发送文本和媒体消息。文本 · 附件
- $0.0005SMS OTP专用于一次性验证码的纯文本通道。文本
- $0.0003Telegram带按钮、投票、位置和媒体的机器人消息。文本 · 附件 · 回复按钮 · 位置 · 联系人 · 投票
- $0.0005Messenger与向您的 Facebook Page 发消息的用户对话。文本 · 附件 · 回复按钮
- $0.0005InstagramInstagram 专业账号的私信。文本 · 附件 · 回复按钮
- $0.0005TikTokTikTok 企业账号的私信。文本 · 附件 · 回复按钮
- 自带渠道您的号码和机器人始终归您所有查看各渠道所需条件
工作原理
从注册到消息送达，只需四步
无需销售沟通，也没有最低消费承诺。注册账户一分钟后，您就可以在测试模式下发起第一次 API 调用。
- 第 01 步
注册账户
注册、验证邮箱，然后在控制台中创建 API 密钥。测试密钥立即可用，无需先连接任何渠道。
- 第 02 步
连接渠道
在控制台中使用 Facebook 或 TikTok 登录，即可连接 WhatsApp 号码、Page 或企业账号。Telegram 机器人或 Twilio 号码可凭其凭据在控制台中添加，也可以通过
POST /v1/channels添加。 - 第 03 步
通过同一个端点发送
POST /v1/messages接受一个渠道 ID、一个接收方和一个带类型的内容对象。所有渠道的请求结构完全相同。 - 第 04 步
跟踪每一次投递
带签名的 Webhook 会报告已发送、已送达、已读和失败状态。同样的历史记录也可以在控制台和
GET /v1/messages中查看。
消息类型
所发即所见
每条消息都有一个类型，以及位于该类型同名键下的内容对象。任选一种，即可对照查看请求正文及其生成的消息。
{
"channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
"to": "+971501234567",
"type": "text",
"text": {
"body": "您的订单 #1042 已发货。物流跟踪：https://example.com/t/1042",
"preview_url": true
},
"reference": "order-1042"
}纯文本，所有渠道类型均可接受。设置 preview_url 可让渠道显示链接预览。
渠道WhatsApp Business、SMS、SMS OTP、Telegram、Messenger、Instagram和TikTok
控制台
代码之外的事，交给控制台
创建密钥、连接渠道、搜索消息日志、重放 Webhook 投递以及管理计费。控制台显示的一切，同样可以通过 API 获取。
价格
按条付费，或批量购买消息
为预付费钱包充值（$10 起），按各渠道的单条价格付费；也可以购买消息点数套餐，用于价格最高的渠道上的大批量发送。
按量付费
| 渠道 | 每条消息 |
|---|---|
| WhatsApp Business | $0.001 |
| Telegram | $0.0003 |
| SMS | $0.0005 |
| SMS OTP | $0.0005 |
| Messenger | $0.0005 |
| $0.0005 | |
| TikTok | $0.0005 |
价格包含的内容
- 计费被 API 受理的出站消息，在受理的那一刻计费。
- 免费入站消息、测试模式消息、Webhook 和控制台。
- 退还任何最终失败的消息，费用都会退回其来源的套餐或钱包。
- 另计Meta、运营商或其他服务商针对渠道本身收取的费用。
开发者体验
一次集成，长期省心
带签名的 Webhook、安全的重试、行为与生产环境一致的沙盒，以及可供程序分支处理的错误。
可校验的 Webhook
每次投递都基于时间戳和原始正文使用 HMAC-SHA256 签名，签名位于 OmniMessage-Signature 标头中。请在 10 秒内返回任意 2xx 响应。投递失败后会按退避策略重试八次，间隔从 30 秒到 24 小时。
import { createHmac, timingSafeEqual } from 'node:crypto';
// header is "t=<unix seconds>,v1=<hex hmac-sha256>"
export function verifySignature(rawBody, header, secret) {
const parts = header.split(',').map((part) => part.split('='));
const { t, v1 = '' } = Object.fromEntries(parts);
const expected = createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const matches =
v1.length === expected.length &&
timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
return fresh && matches;
}{
"id": "evt_8Kd2pQ7wN4xB1zR6mT3c",
"object": "event",
"type": "message.delivered",
"mode": "live",
"created_at": "2026-10-05T09:30:02.900Z",
"data": {
"object": {
"id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
"object": "message",
"status": "delivered",
"reference": "order-1042",
"delivered_at": "2026-10-05T09:30:02.871Z"
}
}
}零成本的测试模式
测试密钥使用内置的沙盒渠道，因此无需连接任何渠道。接收方号码的末几位数字决定模拟结果，您的 Webhook 会像在生产环境中一样触发。
curl https://api.omnimessage.co/v1/messages \
-H "Authorization: Bearer om_test_..." \
-H "Content-Type: application/json" \
-d '{
"channel": "ch_test_whatsapp",
"to": "+971501230002",
"type": "text",
"text": { "body": "Hello from the sandbox" }
}'带类型和代码的错误
所有非 2xx 响应的正文结构相同：表示失败类别的 type、可供分支判断的稳定 code、出错的 param（如有），以及供支持团队排查的 request_id。
{
"error": {
"type": "billing_error",
"code": "insufficient_balance",
"message": "Not enough wallet balance or package credits.",
"request_id": "req_5Vn1cH8jL3qW6yD9sF2k",
"doc_url": "https://omnimessage.co/docs/errors#insufficient_balance"
}
}幂等的 POST 请求
发送
Idempotency-Key标头后，24 小时内的重试会返回已存储的响应并带有Idempotent-Replayed: true，不会重复发送或重复扣费。可预期的限制
POST /v1/messages每个密钥每秒 100 次请求，其他端点为 20 次。每个响应都带有RateLimit-Remaining，429 响应带有Retry-After。批量发送
POST /v1/messages/batch最多接受 100 条消息。每一项单独受理、拒绝和计费，207 响应按索引逐项报告结果。限定权限范围的密钥
只为每个密钥授予其所需的权限范围，例如
messages:write或billing:read，并通过 IP 白名单加以限制。
常见问题
集成之前
这里是简短的回答，详细内容请查阅开发文档。
我需要自己的 WhatsApp 号码、机器人或 SMS 号码吗？
需要。OmniMessage 是一个自带渠道的网关：您连接自己的 WhatsApp Cloud API 号码、Telegram 机器人、Twilio 号码或社交账号，并始终保有其所有权。渠道页面列出了每种类型所需的条件。
具体对哪些内容计费？
API 每受理一条出站消息计费一次：如果您有套餐点数，则扣 1 个点数；否则按该渠道类型的单条价格从钱包扣费。入站消息和测试模式消息免费，最终失败的消息会自动退还费用。
价格是否包含 Meta、运营商或服务商的费用？
不包含。网关费涵盖 API、投递跟踪、Webhook 和控制台。Meta、Twilio 或其他服务商针对渠道本身收取的费用，由您与该服务商直接结算。
如何在不发送真实消息的情况下进行测试？
使用以 om_test_ 开头的密钥。每个账户的每种类型都有一个沙盒渠道，例如 ch_test_whatsapp。不会实际送达，也不会计费，状态均为模拟：接收方以 0000 结尾时失败，以 0001 结尾时停留在已发送，以 0002 结尾时还会变为已读，其他情况约两秒内送达。
余额用完后会怎样？
API 会返回 402 insufficient_balance，且不会有任何消息进入队列，因此您绝不会事后欠费。您可以订阅 balance.low 事件，或开启自动充值，在钱包余额低于您设定的阈值时自动充值。
我需要 SDK 吗？
不需要。API 采用基于 HTTPS 的 JSON 和 Bearer 身份验证，任何 HTTP 客户端都可以使用。开发文档提供了 cURL、Node、Python 和 PHP 示例。