发送消息

请求方式

POST /whatsapp/messages HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段类型注释
X-API-Keystring必填，API 密钥

通用请求参数

字段类型注释
tostring是，接收方电话号码
typestring是，消息类型
phone_number_idstring是，发送方电话号码 ID

文本消息 (text)

{
  “to”: “+15551234567”,
  “type”: “text”,
  “phone_number_id”: “1906385232743451”,
  “text”: {“body”: “Hello, this is a test message!”, “preview_url”: false}
}

字段类型注释
text.bodystring是，消息正文
text.preview_urlbool否，是否预览 URL，默认 false

图片消息 (image)

{
  “to”: “+15551234567”,
  “type”: “image”,
  “phone_number_id”: “1906385232743451”,
  “image”: {“link”: “https://example.com/image.jpg”, “caption”: “Check out this image”}
}

字段类型注释
image.linkstring是，图片链接
image.captionstring否，图片说明

模板消息 (template)

{
“to”: “+15551234567”,
“type”: “template”,
“phone_number_id”: “1906385232743451”,
“template”: {
“name”: “order_confirmation”,
“language”: { “code”: “en_US”, “policy”: “deterministic” },
“components”: [
{
“type”: “header”,
“parameters”: [ { “type”: “text”, “text”: “Order #1234” } ]
},
{
“type”: “body”,
“parameters”: [
{ “type”: “text”, “text”: “John” },
{ “type”: “currency”, “currency”: { “fallback_code”: “USD”, “amount”: “25.00” } }
]
},
{
“type”: “button”,
“sub_type”: “url”,
“index”: “0”,
“parameters”: [ { “type”: “text”, “text”: “track123” } ]
}
]
}
}

字段类型注释
template.namestring是，已审核通过的模板名称
template.language.codestring是，语言代码（如 en_US、zh_CN）
template.language.policystring否，回退策略，固定 deterministic
template.componentsarray否，模板参数组件数组
components[].typestring是，组件类型：header / body / button / footer / media
components[].sub_typestring否，button 组件子类型：url / quick_reply
components[].indexstring否，button 组件的序号（从 “0” 开始）
components[].parameters[].typestring是，参数类型：text / image / document / video / audio / currency / datetime / button
components[].parameters[].textstring否，type=text 时的文本值
components[].parameters[].currencyobject否，type=currency 时，含 fallback_code / amount / code 等
components[].parameters[].datetimeobject否，type=datetime 时，含 fallback_value / component 等

视频消息（video）

{
“to”: “+15551234567”,
“type”: “video”,
“phone_number_id”: “1906385232743451”,
“video”: { “link”: “https://example.com/video.mp4“, “caption”: “Check out this video” }
}

字段类型注释
video.linkstring否，视频链接 URL（与 video.id 二选一）
video.idstring否，已上传媒体的 ID（与 video.link 二选一）
video.captionstring否，视频说明文字

音频消息（audio）

{
“to”: “+15551234567”,
“type”: “audio”,
“phone_number_id”: “1906385232743451”,
“audio”: { “link”: “https://example.com/audio.mp3” }
}

字段类型注释
audio.linkstring否，音频链接 URL（与 audio.id 二选一）
audio.idstring否，已上传媒体的 ID（与 audio.link 二选一）

文档消息（document）

{
“to”: “+15551234567”,
“type”: “document”,
“phone_number_id”: “1906385232743451”,
“document”: {
“link”: “https:file.pdf”,
“filename”: “invoice-2026.pdf”,
“caption”: “Your monthly invoice”
}
}

字段类型注释
document.linkstring否，文档链接 URL（与 document.id 二选一）
document.idstring否，已上传媒体的 ID（与 document.link 二选一）
document.filenamestring否，文件名（建议带上扩展名）
document.captionstring否，文档说明文字

贴纸消息（sticker）

{
“to”: “+15551234567”,
“type”: “sticker”,
“phone_number_id”: “1906385232743451”,
“sticker”: { “link”: “https://example.com/sticker.webp” }
}

字段类型注释
sticker.linkstring否，贴纸链接 URL（与 sticker.id 二选一，需为 animated/static 贴纸格式）
sticker.idstring否，已上传贴纸的媒体 ID（与 sticker.link 二选一）

位置消息（location）

{
“to”: “+15551234567”,
“type”: “location”,
“phone_number_id”: “1906385232743451”,
“location”: {
“longitude”: -122.425559,
“latitude”: 37.774797,
“name”: “Meta HQ”,
“address”: “1 Hacker Way, Menlo Park, CA 94025”
}
}

字段类型注释
location.longitudenumber是，经度
location.latitudenumber是，纬度
location.namestring否，地点名称
location.addressstring否，详细地址

联系人消息（contacts）

{
“to”: “+15551234567”,
“type”: “contacts”,
“phone_number_id”: “1906385232743451”,
“contacts”: [
{
“name”: {
“formatted_name”: “John Smith”,
“first_name”: “John”,
“last_name”: “Smith”
},
“birthday”: “1990-01-01”,
“phones”: [
{ “phone”: “+15551234567”, “type”: “CELL”, “wa_id”: “15551234567” }
]
}
]
}

字段类型注释
contacts[].name.formatted_namestring是，联系人全名
contacts[].name.first_namestring否，名
contacts[].name.last_namestring否，姓
contacts[].birthdaystring否，生日，格式 YYYY-MM-DD
contacts[].phones[].phonestring否，电话号码（带 + 的国际格式）
contacts[].phones[].typestring否，号码类型：CELL / MAIN / IPHONE / HOME / WORK
contacts[].phones[].wa_idstring否，该号码对应的 WhatsApp ID

互动消息（interactive）

1）按钮（button）

{
“to”: “+15551234567”,
“type”: “interactive”,
“phone_number_id”: “1906385232743451”,
“interactive”: {
“type”: “button”,
“body”: { “text”: “Please choose an option” },
“footer”: { “text”: “Powered by PandaGPT” },
“action”: {
“buttons”: [
{ “type”: “reply”, “reply”: { “id”: “btn_yes”, “title”: “Yes” } },
{ “type”: “reply”, “reply”: { “id”: “btn_no”, “title”: “No” } }
]
}
}
}

字段类型注释
interactive.typestring是，固定 button
interactive.headerobject否，标题区，header.type: text/image/video/document
interactive.header.textstring否，header.type=text 时的标题文本
interactive.body.textstring是，正文文本
interactive.footer.textstring否，页脚文本
interactive.action.buttons[].typestring是，固定 reply
interactive.action.buttons[].reply.idstring是，按钮回传 ID
interactive.action.buttons[].reply.titlestring是，按钮显示文案

button 类型最多 3 个按钮，title 长度有限制。

2）列表（list）

{
“to”: “+15551234567”,
“type”: “interactive”,
“phone_number_id”: “1906385232743451”,
“interactive”: {
“type”: “list”,
“header”: { “type”: “text”, “text”: “Menu” },
“body”: { “text”: “Pick one item” },
“footer”: { “text”: “Tap to browse” },
“action”: {
“button”: “View options”,
“sections”: [
{
“title”: “Section 1”,
“rows”: [
{ “id”: “row_1”, “title”: “Item A”, “description”: “Desc A” },
{ “id”: “row_2”, “title”: “Item B” }
]
}
]
}
}
}

字段类型注释
interactive.typestring是，固定 list
interactive.body.textstring是，正文文本
interactive.action.buttonstring是，列表触发按钮文案
interactive.action.sections[].titlestring否，分组标题
interactive.action.sections[].rows[].idstring是，行回传 ID
interactive.action.sections[].rows[].titlestring是，行标题
interactive.action.sections[].rows[].descriptionstring否，行描述

3）商品目录（product / product_list / catalog_message）

{
“to”: “+15551234567”,
“type”: “interactive”,
“phone_number_id”: “1906385232743451”,
“interactive”: {
“type”: “product”,
“body”: { “text”: “Featured product” },
“action”: { “catalog_id”: “999888777666555”, “product_retailer_id”: “item-001” }
}
}

字段类型注释
interactive.typestring是，product / product_list / catalog_message 之一
interactive.action.catalog_idstring条件必填，product / product_list 所需商品目录 ID
interactive.action.product_retailer_idstring条件必填，product 类型的单品零售 ID
interactive.action.sectionsarray条件必填，product_list 的商品分组（含 product_retailer_id）
interactive.action.product_retailer_id (catalog_message)string条件必填，catalog_message 使用的零售商品 ID

4）Flow / 订单（flow / order_details / order_status）

{
“to”: “+15551234567”,
“type”: “interactive”,
“phone_number_id”: “1906385232743451”,
“interactive”: {
“type”: “flow”,
“body”: { “text”: “Complete your booking” },
“action”: {
“mode”: “published”,
“flow_message_version”: “3”,
“flow_token”: “a-token”,
“flow_id”: “FLOW_ID”,
“flow_cta”: “Open”
}
}
}

字段类型注释
interactive.typestring是，flow / order_details / order_status 之一
interactive.action.modestringflow 必填，published 或 draft
interactive.action.flow_message_versionstringflow 必填，Flow 消息版本
interactive.action.flow_tokenstringflow 必填，鉴权 token
interactive.action.flow_idstringflow 必填，Flow ID
interactive.action.flow_ctastringflow 必填，按钮文案
interactive.action.typestringorder_details / order_status 必填，订单动作类型

回应消息（reaction）

{
“to”: “+15551234567”,
“type”: “reaction”,
“phone_number_id”: “1906385232743451”,
“reaction”: { “message_id”: “wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQ…”, “emoji”: “👍” }
}

字段类型注释
reaction.message_idstring是，要回应的那条消息的 ID
reaction.emojistring否，表情符号；不传则移除已有回应