WhatsApp On-Premise 消息类型指南 | WOZTELL

WhatsApp 消息类型

以下是可以通过 WhatsApp On-Premise 发送的消息类型列表:

文本

WhatsApp 文本消息
WhatsApp 文本消息
{
"type": "TEXT",
"text": "你好,世界!",
}
复制
属性 说明 是否必需
type TEXT
text 字符串;最多 2000 个字符


图片

WhatsApp 图片
WhatsApp 图片
WhatsApp 图片
WhatsApp 图片
{
"type": "IMAGE",
"text": "我是 Sanuker!",
"attachment_id": "289832336612941",
}
复制
属性 说明 是否必需
type IMAGE
text 字符串;图像的说明文字
attachment_id 图像的媒体 ID 是(或 url)
url 图像的 URL 是(或 attachment_id)
Idea
提示
  • 图像必须是有效的图像文件格式:.jpeg.png
  • 图像必须为 8 位RGBRGBA
  • 最大文件大小为 5MB


音频

WhatsApp 音频消息
WhatsApp 音频消息
{
"type": "AUDIO",
"attachment_id": "668795277867495"
}
复制
属性 说明 是否必需
type AUDIO
attachment_id 音频的媒体 ID 是(或 url)
url 音频的 URL 是(或 attachment_id)
Idea
提示
  • 音频必须为有效的音频文件格式,包括 .aac.mp4.mpeg.amr.ogg(仅支持 opus 编解码器,基本的 ogg 不支持)
  • 最大文件大小为 16MB


视频

WhatsApp 视频
WhatsApp 视频
WhatsApp 视频
WhatsApp 视频
{
"type": "VIDEO",
"attachment_id": "496729438556614",
"text": "文本"
}
复制
属性 说明 是否必需
type VIDEO
text 字符串;视频的说明文字
attachment_id 视频的媒体 ID 是(或 url)
url 视频的 URL 是(或 attachment_id)
Idea
提示
  • 视频必须是有效的视频文件格式,包括 .mp4.3gp
  • 最大文件大小为 16MB
  • 仅支持 H.264 视频编解码器和 AAC 音频编解码器
  • 支持带有单一音频流或无音频流的视频


贴纸

WhatsApp 贴纸
WhatsApp 贴纸
{
"type": "STICKER",
"attachment_id": "1030335650902052"
}
复制
属性 说明 是否必需
type VIDEO
url 贴纸的 URL 是(或 attachment_id)
attachment_id 贴纸的媒体 ID 是(或 url)
Idea
提示
  • 图像格式必须为 .webp,尺寸为 512x512 像素
  • 静态贴纸的最大文件大小为:100KB
  • 动态图贴纸的最大文件大小为:500KB


文件

WhatsApp 文件
WhatsApp 文件
WhatsApp 文件
WhatsApp 文件
{
"type": "FILE",
"filename": "文本",
"attachment_id": "496729438556614"
}
复制
属性 说明 是否必需
type FILE
filename 字符串;文件的预览名称
url 文件的 URL 是(或 attachment_id)
attachment_id 文件的媒体 ID 是(或 url)
Idea
提示
  • 文件必须为有效格式,包括 plainpdfvnd.ms-powerpointmswordvnd.ms-excelvnd.openxmlformats-officedocument.wordprocessingml.documentvnd.openxmlformats-officedocument.presentationml.presentationvnd.openxmlformats-officedocument.spreadsheetml.sheet
  • 最大文件大小为 100MB


位置

WhatsApp 位置
WhatsApp 位置
{
"type": "LOCATION",
"location": { "name": "ABC 公司", "address": "彩虹路101号,DFG大厦1楼C室", "lat": "22.31586918460027", "long": "114.20883121469535" }}
复制
属性 说明 是否必需
type LOCATION
name 字符串;位置名称
address 字符串;位置地址
lat 纬度
long 经度


联系人

{
"type": "CONTACTS",
"contacts": [...]
}
复制
属性 说明 是否必需
name 字符串;联系人姓名
address 字符串;联系人地址
birthday 字符串;日期
emails 字符串;电子邮件地址
org 字符串;公司名称
phones 字符串;电话号码
urls 字符串;网址
Idea
提示
  • 你可以发送一个或多个联系人卡片。
  • 每个联系人卡片都必须包含 name 字段。
  • 你可以添加以下字段:addressbirthdayemailsorgphonesurls


回应

WhatsApp 回应
                    
                        {
"type": "REACTION",
"message_id": "wamid.HBgLODUyNTQwNjM1OTgVAgASGBQzRUIwOTVERkZCRDIwODg5REQwMAA=",
"emoji": "😊"
}
复制
属性 说明 是否必需?
type REACTION
message_id 用于标识要回应的消息的 ID
emoji 用作回应的表情符号;可以是表情符号本身或转义的 Unicode(例如 \uD83D\uDE0A)
Idea
提示

可以从日志中的消息事件或使用 ApiScope.chatOpen API 中获取上一条消息的消息 ID。

例如:

                                    
                                        query chat {
apiViewer{
conversationHistory (first: 10, platform: "whatsapp-cloud", memberId: "999abe6524f9db0009963008") {
edges{
node{
memberId
messageEvent
}
}
}
}
}
复制


互动消息

互动消息允许用户通过点击按钮快速回应。用户在列表或按钮消息中一次只能选择一个选项,但他们可以返回并重新打开先前的消息。

列表消息

列表消息 - 1
列表消息 - 1
列表消息 - 2
列表消息 - 2
                    
{
"type": "WHATSAPP_LIST",
"header": {
"type": "text",
"text": "你好 👋🏻"
},
"body": {
"text": "Sanuker 提供聊天机器人解决方案。"
},
"footer": {
"text": "Facebook 与 WhatsApp 官方合作伙伴"
},
"action": {
"button": "菜单",
"sections": [
{
"title": "部分标题",
"rows": [
{
"payload": "GREETINGS",
"title": "主菜单",
"description": "你好!"
},
{
"payload": "ABOUT_SANUKER",
"title": "关于 Sanuker",
"description": "你是谁?"
}
]
}
]
}
}
复制
属性 说明 是否必需?
Header 列表消息的标题,仅允许使用 text
Body 消息主体内容(最多 1024 个字符)
Footer 页脚内容(最多 60 个字符)
Action 在 action 内必须嵌套:
- 一个包含按钮内容的 button 字段
- 至少一个 section 对象(最多 10 个)
在每个 section 中,必须添加至少一个 rows 对象

action 对象

属性 说明 是否必需?
button 按钮内容。不能是空字符串,且在消息中必须唯一(最多 20 个字符)
sections section 对象数组。最少 1 个,最多 10 个

section 对象

属性 说明 是否必需?
title 部分标题 是(当消息包含多个 section 时)
rows 包含一个选项列表。每个行项必须有标题和 ID。你可以添加描述(可选)

回复按钮

回复按钮
                    
                        {
"type": "WHATSAPP_REPLY_BUTTONS",
"header": {
"type": "image",
"image": { "id": "2e5a7aad-e8c7-43ba-ad5e-b298bb32f8af" }
},
"body": {
"text": "Sanuker 提供聊天机器人解决方案。"
},
"footer": {
"text": "Facebook 与 WhatsApp 官方合作伙伴"
},
"action": {
"buttons": [
{ "type": "reply", "reply": { "payload": "GREETINGS", "title": "主菜单" } },
{ "type": "reply", "reply": { "payload": "ABOUT_SANUKER", "title": "关于 Sanuker" } }
]
}
}
复制
属性 说明 是否必需
Header 列表消息的标题;可以为文本或媒体类型:“图片”、“视频”、“文档”
Body 消息主体内容(最多 1024 个字符)
Footer 页脚内容(最多 60 个字符)
Action 必须添加至少一个按钮,并包含类型和标题。最多不超过 3 个按钮

action 对象

属性 说明 是否必需?
buttons 一个按钮可以包含以下参数:
type:仅支持类型为 reply(用于回复按钮消息)
title:按钮标题,不能为空字符串且在消息中必须唯一(最多 20 个字符)


单一商品消息

                    
                        {
"type": "PRODUCT",
"action": {
"type": "single",
"catalog_id": "1134377510532066",
"product_retailer_id": "03-Pack"
},
"body": {
"text": "查看我们的今日推荐包包"
}
}
复制
属性 说明 是否必需
body 消息主体内容(最多 1024 个字符)
footer 页脚内容(最多 60 个字符)
action 必须包含:
- 必须设置为 single,用于单一商品消息;
- catalogId:用于此消息的目录 ID。可在 Commerce Manager 中获取;
- productId:商品的唯一标识符(内容 ID)

多商品消息

Idea
提示

多商品消息最多只能包含 30 个商品。

                    
                        {
                          "type": "PRODUCT",
                          "header": {
                            "type": "text",
                            "text": "秋季新品"
                          },
                          "action": {
                            "type": "multi",
                            "catalog_id": "1134377510532066",
                            "sections": [
                              {
                                "title": "城市精选",
                                "product_items": ["01-Pack", "02-Bag"]
                              },
                              {
                                "title": "登山必备",
                                "product_items": ["03-Pack"]
                              }
                            ]
                          },
                          "body": {
                            "text": "点击查看我们的秋季新品"
                          }
                        }
                    
                
复制
属性 说明 是否必需
header type 必须为 text。包含你想要显示的文本内容对象
body 消息主体内容(最多 1024 个字符)
footer 页脚内容(最多 60 个字符)
action 必须包含:
- type:必须为 multi,用于多商品消息;
- catalogId:你希望使用的商品目录 ID,可通过 Commerce Manager 获取;
- sections:一个包含多个 section 对象的数组。必须至少包含一个 section

sections 字段:

属性 说明 是否必需
title 每个 section 的标题
product_items product_retailer_id:每个商品的唯一标识符(内容 ID)


WhatsApp 消息模板

WhatsApp 模板消息
                    
                        {
                          "type": "TEMPLATE",
                          "components": [
                            {
                              "parameters": [
                                {
                                  "image": {
                                    "id": "57ec1287-6915-4a44-8dc9-9caa620385e1"
                                  },
                                  "type": "image"
                                }
                              ],
                              "type": "header"
                            },
                            {
                              "type": "button",
                              "sub_type": "quick_reply",
                              "index": "0",
                              "parameters": [
                                {
                                  "type": "payload",
                                  "payload": "联系 Sanuker"
                                }
                              ]
                            },
                            {
                              "type": "button",
                              "sub_type": "quick_reply",
                              "index": "1",
                              "parameters": [
                                {
                                  "type": "payload",
                                  "payload": "GREETINGS"
                                }
                              ]
                            },
                            {
                              "type": "button",
                              "sub_type": "quick_reply",
                              "index": "2",
                              "parameters": [
                                {
                                  "type": "payload",
                                  "payload": "ABOUT_SANUKER"
                                }
                              ]
                            }
                          ],
                          "languagePolicy": "deterministic",
                          "languageCode": "en",
                          "namespace": "bc3ac5dd_6dfd_2345_d5f7_123456789bf",
                          "elementName": "multiple_button_test_1",
                          "accountId": "1234567890"
                        }
                    
                
复制

模板详情

属性 说明 是否必需?
Name 只能包含小写字母数字字符和下划线(_);不允许其他字符或空格
Category 选择模板的正确分类;查看 支持的分类列表
Language 选择模板的正确语言;所有翻译将使用相同模板名称;你将在发送模板时指定语言字段; 查看 支持的语言列表
Content 模板消息的内容;支持使用 {{1}} 格式的参数占位符
Header 消息模板的标题;可以是文本或媒体类型:“Image”、“Video”、“Document”
Body 消息模板的主体(字符限制:1024)
Footer 消息模板的文本页脚
Buttons 模板消息的按钮;可以是行动呼吁或快速回复;最多支持 3 个按钮

最大字符限制

属性 字符限制
Body(无标题/页脚) 最多 1024 个字符
Body(含标题/页脚) 最多 160 个字符
Header 60 个字符
Footer 60 个字符

请注意,在 WhatsApp 消息模板中,字符限制不适用于 变量

设置流程

  1. 打开“响应构建器”并选择响应类型“WhatsApp 消息模板”。
创建 WhatsApp 消息模板响应
  1. 选择已有的“消息模板”。请确保你已完成 消息模板提交 流程,以查看你现有的模板。

  2. 语言策略 设置为 Deterministic(确定性)

  3. 选择你消息模板的 语言

  1. 请查看以下可选设置:
  • 如果你的 消息模板 包含 快速回复 按钮,则添加负载。
为 WhatsApp 消息模板添加 Payload 按钮
  • 如果 Header 使用多媒体(如图片或视频),请添加 媒体 IDurl
为 WhatsApp 消息模板添加媒体


引用回复

你可以将消息作为对对话中先前消息的回复进行发送。先前的消息将在上下文气泡中被引用,并与回复消息一同显示。

在向 WhatsApp 用户发送任何消息时,你需要添加属性 reply_to,并通过 Message ID 指定上下文消息。


{
  "type": "TEXT",
  "text": "你好!近来如何?",
  "reply_to": "wamid.HBgLODUyNTQwNjM1OTgVAgASGBQzRUIwQjBGOTBBREU1QTgzQkRFQwA="
}

                
复制
属性 说明 是否必需
reply_to 要回复的消息的 Message ID
Idea
提示
  • 仅限 30 天以内的消息可以在上下文气泡中被引用。否则,消息将作为普通消息发送。
  • 如果回复的消息是模板消息,则收件人不会看到上下文气泡。
  • 如果收件人使用的是 KaiOS,当回复的是图片、视频、音频或语音时,将无法看到上下文气泡。
  • 可通过日志中的消息事件或在 Open API 中使用 ApiScope.chat 获取前一条消息的 message ID。

例如:


query chat {
    apiViewer {
        conversationHistory (first: 10, platform: "whatsapp-cloud", memberId: "999abe6524f9db0009963008") {
            edges {
                node {
                    memberId
                    messageEvent
                }
            }
        }
    }
}

                                
复制