分类： 电话

获取媒体

请求方式

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

请求头

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

请求参数

字段类型注释
media_idstring是，素材id
phone_number_idstring是，关联手机号phone_number_id

返回的结果:

文件流

Webhook 参考文档

转发WhatsApp Business 开放平台发送过来的信息，数据结构不做变动

数据：

account_alerts 参考文档：account_alerts Webhook 参考文档 | 开发者文档 (facebook.com)

account_review_update参考文档：account_review_update Webhook 参考文档 | 开发者文档 (facebook.com)

account_update参考文档：account_update Webhook 参考文档 | 开发者文档 (facebook.com)

business_capability_update参考文档：business_capability_update Webhook 参考文档 | 开发者文档 (facebook.com)

history（历史记录）参考文档：history（历史记录）Webhook 参考文档 | 开发者文档 (facebook.com)

message_template_components_update参考文档：message_template_components_update Webhook 参考文档 | 开发者文档 (facebook.com)

message_template_quality_update参考文档：message_template_quality_update Webhook 参考文档 | 开发者文档 (facebook.com)

message_template_status_update参考文档：message_template_status_update Webhook 参考文档 | 开发者文档 (facebook.com)

消息 参考文档：消息 Webhook 参考文档 | 开发者文档 (facebook.com)

partner_solutions 参考文档：partner_solutions Webhook 参考文档 | 开发者文档 (facebook.com)

payment_configuration_update 参考文档：payment_configuration_update Webhook 参考文档 | 开发者文档 (facebook.com)

phone_number_name_update 参考文档：phone_number_name_update Webhook 参考文档 | 开发者文档 (facebook.com)

phone_number_quality_update 参考文档：phone_number_quality_update Webhook 参考文档 | 开发者文档 (facebook.com)

安全 参考文档：安全 Webhook 参考文档 | 开发者文档 (facebook.com)

smb_app_state_sync 参考文档：smb_app_state_sync Webhook 参考文档 | 开发者文档 (facebook.com)

smb_message_echoes 参考文档：smb_message_echoes Webhook 参考文档 | 开发者文档 (facebook.com)

template_category_update 参考文档：template_category_update Webhook 参考文档 | 开发者文档 (facebook.com)

user_preferences  参考文档：user_preferences Webhook 参考文档 | 开发者文档 (facebook.com)

上传文件（获取句柄）

请求方式

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

请求头

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

请求参数

{
  “waba_id”: “1083606018111111”,
  “file_type”: “image/jpeg”,
  “file”: “文件流”,
  “filename”: “文件名称”
}

字段类型注释
waba_idstring是，WABA账户ID
file_typestring否，MIME类型 (可选，如 image/jpeg, video/mp4, audio/mpeg, application/pdf)
filefile是，multipart/form-data，file 字段上传附件
filenamestring否，文件名

返回的结果

{

    “code”: 1,

    “data”: {

        “handle”: “4:MTIzMTIzMjE=:aW1hZ2UvcG5n:ARbZiIePV5AwoQsa1bD7GD47CUCMBdI2koNNbCCk1Z9z22tSoQOJl-qrzWfxt7r90K8C9FAiv-3HuPOqUR-hnAAW9jtj14rVGx31yeyvIFaepg:e:1789119311:708496041332449:61590501153676:ARazgi2rvF7LYOHPcJE”

    },

    “msg”: “OK”

}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据
-handlestring媒体素材句柄

上传附件

请求方式

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

请求头

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

请求参数

{
  “phone_number_id”: “1083606018111111”,
  “media_type”: “image/jpeg”,
  “file”: “文件流”,
  “url”: “文件地址”
}

字段类型注释
phone_number_idstring是，WABA 手机号id
media_typestring否，MIME类型 (可选，如 image/jpeg, video/mp4, audio/mpeg, application/pdf)
filefile否，multipart/form-data，file 字段上传附件
urlstring否，附件URL (URL方式必填)

返回的结果

{

    “code”: 1,

    “data”: {

        “media_id”: “1543107790406532”

    },

    “msg”: “OK”

}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据
-media_idstring素材id

发送消息

请求方式

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否，表情符号；不传则移除已有回应

删除模板

请求方式

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

请求头

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

请求参数

{“waba_id”: “918802267845274”, “hsm_id”: “960321963707594”}

或批量删除：

{“waba_id”: “918802267845274”, “hsm_ids”: [“960321963707594”, “1398810078762909”]}

字段类型注释
waba_idstring是，WABA 账户 ID
template_namestring三选一，模板名称
hsm_idstring三选一，模板 ID
hsm_idsarray三选一，模板 ID 列表，最多 100 个

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据

修改模板

请求方式

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

请求头

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

请求参数

字段类型注释
template_idstring是，模板 ID
namestring否，模板名称
categorystring否，模板分类
languagestring否，语言代码
componentsarray否，模板组件列表
allow_category_changebool否，是否允许分类变更

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据

创建模板

请求方式

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

请求头

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

请求参数

字段类型注释
waba_idstring是，WABA 账户 ID
namestring是，模板名称（小写字母、数字、下划线）
categorystring是，模板分类：MARKETING / UTILITY / AUTHENTICATION
languagestring是，语言代码 规范：支持的语言 | 开发者文档 (facebook.com)
componentsarray是，模板组件列表
allow_category_changebool否，是否允许分类变更

components 组件结构

[
  {“type”: “HEADER”, “format”: “TEXT”, “text”: “标题文本”, “example”: {“header_text”: [“示例”]}},
  {“type”: “BODY”, “text”: “正文内容，支持 {{1}} 变量”, “example”: {“body_text”: [[“变量1”, “变量2”]]}},
  {“type”: “FOOTER”, “text”: “页脚文本”},
  {“type”: “BUTTONS”, “buttons”: [
    {“type”: “QUICK_REPLY”, “text”: “按钮文字”},
    {“type”: “URL”, “text”: “访问网站”, “url”: “https://example.com”},
    {“type”: “PHONE_NUMBER”, “text”: “拨打电话”, “phone_number”: “+15551234567”}
  ]}
]

组件类型说明： – HEADER – 头部（TEXT / IMAGE / VIDEO / DOCUMENT） – BODY – 正文（必填） – FOOTER – 页脚 – BUTTONS – 按钮组（QUICK_REPLY / URL / PHONE_NUMBER）

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据

获取模板列表

请求方式

GET /whatsapp/templates HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

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

请求参数

字段类型注释
waba_idstring是，WABA 账户 ID
template_idstring否，模板 ID
pageint否，页码，默认 1
limitint否，每页条数，默认 10
fieldsstring否，指定返回字段

可用 fields 字段：id, name, status, category, language, parameter_format, components, previous_category, sub_category, message_send_ttl_seconds, is_primary_device_delivery_only, is_sms_fallback_enabled, quality_score, health_status, source, rejected_reason, library_template_name, bid_spec, correct_category, cta_url_link_tracking_opted_out, degrees_of_freedom_spec, display_format, last_updated_time

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {
    “data”: {
      “0”: {
        “id”: “960321963707594”,
        “name”: “subsidy”,
        “status”: “APPROVED”,
        “category”: “MARKETING”,
        “language”: “zh_CN”,
        “parameter_format”: “NAMED”,
        “message_send_ttl_seconds”: 86400,
        “is_primary_device_delivery_only”: false,
        “quality_score”: {“score”: “UNKNOWN”, “date”: 1784204376},
        “source”: “manual”,
        “components”: {
          “0”: {“type”: “HEADER”, “format”: “IMAGE”, “example”: {“header_handle”: [“https://…”]}},
          “1”: {“type”: “BODY”, “text”: “【河北省卫健委】您的{{subsidy_name}}已成功发送…”}
        }
      }
    },
    “total”: 7,
    “per_page”: 10,
    “current_page”: 1
  }
}

字段类型注释
idstring模板 ID
namestring模板名称
statusstring模板状态
categorystring模板分类
languagestring语言
parameter_formatstring参数格式
message_send_ttl_secondsint消息发送有效期（秒）
is_primary_device_delivery_onlybool是否仅主设备投递
quality_scoreobject质量评分
sourcestring来源
componentsarray模板组件列表
totalint总记录数
per_pageint每页条数
current_pageint当前页码

请求验证码

请求方式

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

请求头

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

请求参数

{
  “phone_number_id”: “1906385232743451”,
  “code_method”: “SMS”,
  “language”: “en_US”
}

字段类型注释
phone_number_idstring是，电话号码 ID
code_methodstring否，验证码方式，默认 SMS，可选 SMS 或 VOICE
languagestring否，语言，默认 en_US

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段类型注释
codeint状态码
msgstring提示信息
dataobject返回数据