跳至正文
OmniMessage

消息类型

九种消息类型，一种请求正文

发送请求指定渠道、接收方和类型，内容位于与类型同名的键下。本页展示每种类型、生成它的请求正文以及支持它的渠道。

打开 API 参考比较各渠道

支持矩阵

各渠道接受的消息类型

渠道通过 capabilities 报告其接受的类型。发送渠道不支持的类型会返回 400 unsupported_message_type，且不会扣费。

各渠道类型对消息类型的支持情况
类型WhatsAppSMSSMS OTPTelegramMessengerInstagramTikTok
文本text支持支持支持支持支持支持支持
附件attachments支持支持不支持支持支持支持支持
模板template支持不支持不支持不支持不支持不支持不支持
回复按钮button支持不支持不支持支持支持支持支持
列表list支持不支持不支持不支持不支持不支持不支持
URL 按钮cta_url支持不支持不支持不支持不支持不支持不支持
位置location支持不支持不支持支持不支持不支持不支持
联系人contacts支持不支持不支持支持不支持不支持不支持
投票poll不支持不支持不支持支持不支持不支持不支持
type: "text"

文本

纯文本，所有渠道类型均可接受。设置 preview_url 可让渠道显示链接预览。

body：1 至 4,096 个字符。

  • WhatsApp Business
  • SMS
  • SMS OTP
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "您的订单 #1042 已发货。物流跟踪：https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}
type: "attachments"

附件

每条消息一个媒体项，通过 https URL 引用：图片、视频、文档、音频、语音或贴纸，可附带说明文字。

有且仅有一项。caption：最多 1,024 个字符。

  • WhatsApp Business
  • SMS
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "attachments",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/receipts/1042.jpg",
      "caption": "这是订单 #1042 的收据。"
    }
  ]
}
type: "template"

模板

带变量的已获批准的 WhatsApp 模板。在 24 小时客户服务窗口之外，WhatsApp 只接受模板消息。

name 和 language 必须与渠道的某个已获批准的模板一致。

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "template",
  "template": {
    "name": "order_out_for_delivery",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "李娜"
          },
          {
            "type": "text",
            "text": "#1042"
          },
          {
            "type": "text",
            "text": "18:00"
          }
        ]
      }
    ]
  }
}
type: "button"

回复按钮

带最多三个快捷回复的消息。被点按的按钮 ID 会通过 message.received 事件回传到您的 Webhook。

1 至 3 个按钮。title：最多 20 个字符。

  • WhatsApp Business
  • Telegram
  • Messenger
  • Instagram
  • TikTok
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "button",
  "button": {
    "body": {
      "text": "您已预订今晚 19:30 的两人桌。您还能按时到吗？"
    },
    "action": {
      "buttons": [
        {
          "reply": {
            "id": "confirm",
            "title": "确认"
          }
        },
        {
          "reply": {
            "id": "reschedule",
            "title": "改期"
          }
        },
        {
          "reply": {
            "id": "cancel",
            "title": "取消预订"
          }
        }
      ]
    }
  }
}
type: "list"

列表

通过单个按钮打开的菜单，其中的行按带标题的分组排列。

action.button：最多 20 个字符。

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "list",
  "list": {
    "body": {
      "text": "今天需要哪个团队为您服务？"
    },
    "action": {
      "button": "选择团队",
      "sections": [
        {
          "title": "团队",
          "rows": [
            {
              "id": "orders",
              "title": "订单",
              "description": "配送、退货和退款"
            },
            {
              "id": "billing",
              "title": "账单",
              "description": "发票和付款方式"
            },
            {
              "id": "technical",
              "title": "技术支持",
              "description": "设置和故障排查"
            }
          ]
        }
      ]
    }
  }
}
type: "cta_url"

URL 按钮

带一个可打开 URL 的按钮的消息，适用于物流跟踪页面、付款和登录链接。

每条消息一个按钮。

  • WhatsApp Business
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "cta_url",
  "cta_url": {
    "body": {
      "text": "您的包裹正在路上。点击实时跟踪。"
    },
    "action": {
      "parameters": {
        "display_text": "跟踪订单",
        "url": "https://example.com/t/1042"
      }
    }
  }
}
type: "location"

位置

带名称和地址的位置标记，可在接收方的地图应用中打开。

latitude 和 longitude 为十进制度数。

  • WhatsApp Business
  • Telegram
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "location",
  "location": {
    "latitude": 25.2048,
    "longitude": 55.2708,
    "name": "自提点",
    "address": "迪拜谢赫扎耶德路"
  }
}
type: "contacts"

联系人

一张或多张联系人名片。数组会原样转发给渠道，因此使用服务商自己的联系人格式。

示例展示的是 WhatsApp 联系人格式。

  • WhatsApp Business
  • Telegram
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "客服中心",
        "first_name": "客服"
      },
      "phones": [
        {
          "phone": "+971800123456",
          "type": "WORK"
        }
      ]
    }
  ]
}
type: "poll"

投票

Telegram 原生投票，包含一个问题和一组选项。

仅限 Telegram。

  • Telegram
POST /v1/messages
{
  "channel": "ch_4Tn8rW2yK6dF9sA1mQ5v",
  "to": "584201337",
  "type": "poll",
  "poll": {
    "question": "您希望我们什么时候配送订单？",
    "options": [
      "上午，09:00 至 12:00",
      "下午，12:00 至 17:00",
      "晚上，17:00 至 21:00"
    ]
  }
}

在沙盒中试用每一种类型

每个账户的每种渠道类型都有一个沙盒渠道。使用测试密钥发送它支持的任意类型，不会实际送达，也不会计费。

获取 API 密钥阅读文档