Skip to content

WhatsApp API mt

Jump to bottom
zjc1750514326 edited this page Feb 27, 2025 · 47 revisions

发送消息

通过API发起WhatsApp号码消息发送服务

  • URL：https://api2.nxcloud.com/api/wa/mt
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fme2na3kdi3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 2 WhatsApp业务类型，取固定值“2”
action String 是 mt WhatsApp业务操作，取固定值“mt”
sign String 是 6e9506557d1f289501d333ee2c365826 API入参参数签名，签名算法

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
business_phone String 是 86158xxxx1795 消息发送方的WhatsApp号码，需要带国码。如86158xxxx1795
messaging_product String 是 whatsapp 发送消息的通道，应用于WhatsApp消息的发送时，值必须为“whatsapp”
recipient_type String 是 individual 消息接收方类型，应用于WhatsApp消息的发送时，值必须为“individual”
to String 是 86158xxxx1795 消息接收方的WhatsApp号码，需要带国码。如86158xxxx1795
type String 是 text 支持以下消息类型的发送：
1. text 文本
2. image 图片
3. video 视频
4. audio 音频
5. document 文档
6. location 位置
7. sticker 贴图表情
8. template 模板
9. interactive 互动消息
10. reacticon心情消息
cus_message_id String 否 wamid.HBgLODUyNTUzMTE3MDUVAgARGBI 自定义消息id，将会在提交消息成功
和消息状态回调里作为消息id返回，请保持全局唯一
dr_webhook String 否 https://test.com/webhook 消息状态回调会优先推送到该地址，
不填则推送到应用webhook上，webhook接口返回的http状态码必须为200
biz_opaque_callback_data String 否 有助于追踪的任意字符串。
例如，您可以在此字段中传递消息模板编号，以从您发送的第一条消息开始追踪客户体验历程。然后，您可以追踪不同消息模板类型的投资回报 (ROI)，以找出最有效的类型。
此字符串包含在 Webhooks 负载的 statuses 对象中，因此任何已在 WhatsApp Business 商业帐号中订阅 messages Webhooks 字段的应用均可获取此字符串。
此字段不会被处理，只会将其作为已发送/已送达/已读消息 Webhooks 的一部分返回。
api_type int 否 0 API类型 0表示Cloud API ，1表示MM Lite API.不填默认0

消息类型

  1. 文本消息参数：
参数名 类型 必选 示例值 说明
context JsonObject 否 参照请求示例 此对象包含您所回复的之前的消息ID
text JsonObject 否 参照请求示例 文本消息内容，type=text必填
  • context object参数：
参数名 类型 必选 示例值 说明
message_id String 是 - 消息ID
  • text object参数：
参数名 类型 必选 示例值 说明
body String 是 - 文本消息体，可以包含 URL 或者格式化标 识。 格式化标识说明如下： 加粗：需要加粗的文字，如 Your total is $10.50. 斜体：需要斜体的文字，如 Your total is $10.50. 划线：需要划线的文字，如 Your total is $10.50.
preview_url boolean 否 - 是否开启 URL 预览，设置为 true 为开启预 览，设置为 false 为关闭预览。URL 需是以http://或者https://开头，后续以域名表达 的链接地址信息（不识别以 IP 地址表达的 链接地址）。URL 预览是 WhatsApp 客户端 支持的消息呈现功能
  1. 图片消息参数：
参数名 类型 必选 示例值 说明
image JsonObject 否 参照请求示例 图片消息内容，type=image必填
  • image object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 图片的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 图片的存储ID，通过Media接口上传文件后获得。
caption String 否 - 图片描述,最大长度1024字符
  1. 视频消息参数：
参数名 类型 必选 示例值 说明
video JsonObject 否 参照请求示例 视频消息内容，type=video必填
  • video object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 视频文件的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 视频文件的存储ID，通过Media接口上传文件后获得。
caption String 否 - 视频描述,最大长度1024字符
  1. 音频消息参数：
参数名 类型 必选 示例值 说明
audio JsonObject 否 参照请求示例 音频消息内容，type=audio必填
  • audio object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 音频文件的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 音频文件的存储ID，通过Media接口上传文件后获得。
  1. 文档消息参数：
参数名 类型 必选 示例值 说明
document JsonObject 否 参照请求示例 文档消息内容，type=document必填
  • document object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 文档文件的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 文档文件的存储ID，通过Media接口上传文件后获得。
filename String 否 - 文档文件名称。
  1. 位置消息参数：
参数名 类型 必选 示例值 说明
location JsonObject 否 参照请求示例 位置消息内容，type=location必填
  • location object参数：
参数名 类型 必选 示例值 说明
longitude Double 是 - 经度信息。
latitude Double 是 - 维度信息。
name String 否 - 位置的名称。
address String 否 - 位置的详细地址信息。
  1. 贴图表情消息参数：
参数名 类型 必选 示例值 说明
sticker JsonObject 否 参照请求示例 贴图表情消息内容，type=sticker必填
  • sticker object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 贴图表情文件的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 贴图表情文件的存储ID，通过Media接口上传文件后获得。
  1. 模板消息参数：
参数名 类型 必选 示例值 说明
template JsonObject 否 参照请求示例 模板消息内容，type=template必填
  • template object参数：
参数名 类型 必选 示例值 说明
name String 是 - 模板名称。
language JsonObject 是 - 模板语言设置信息。
components array[component JsonObject] 否 - 模板内组件的变量、媒体参数设置信息序列，在组件内设置了变量，媒体参数情况下必填。
  • language object参数：
参数名 类型 必选 示例值 说明
code String 是 - 语言代码，参照支持的模板语言。
policy String 是 - 固定值为deterministic。
  • component object参数：
参数名 类型 必选 示例值 说明
type String 是 - 组件类型，可以是header，body，button, carousel
1）当type=header时，设置模板头部的变量信息；
2）当type=body时，设置模板内容的变量信息；
3）当type=button时，设置模板按钮的变量信息；
4）当type=carousel时，设置轮播模板卡片组件信息
sub_type String 否 - 所创建的按钮类型，type=button时必须，
可以是URL, QUICK_REPLY, FLOW,COPY_CODE。
type为其它类型时无该项。
index String 否 - 按钮的位置索引，仅type=button时为必须，仅type=button时为必须，按钮的序号,0 为起始值。
parameters array[parameter JsonObject] 否 - 组件参数列表。
cards array[card JsonObject] 否 - 当type=carousel时 必填.
  • card object参数：
参数名 类型 必选 示例值 说明
card_index int 是 - 轮播图卡片序号
components array[component JsonObject] 是 - 轮播图组件,且component的type取值为header，body，button.
  • parameter object参数：
参数名 类型 必选 示例值 说明
type String 是 - 其中：
1）当component object的 type=header时，可以为text，image，video，document；
2）当component object的 type=body时，取值为text；
3）当component object的 type=button且sub_type=URL时，取值为text；
4）当component object的 type=button且sub_type= QUICK_REPLY时，取值为payload;
4）当component object的 type=button且sub_type= COPY_CODE时，取值为coupon_code
text String 否 - 仅type= text时为必须，设置对应参数的文本内容。type为其它类型时无该项
payload String 否 - 仅type= payload时为必须，设置对应参数的负载内容，payload object定义参照视频消息。type为其它类型时无该项
image JsonObject 否 - 仅type= image时为必须，设置对应参数的图片内容，image object定义参照图片消息。type为其它类型时无该项
video JsonObject 否 - 仅type= video时为必须，设置对应参数的视频内容，video object定义参照视频消息。type为其它类型时无该项
document JsonObject 否 - 仅type= document时为必须，设置对应参数的文档内容，document object定义参照文档消息。type为其它类型时无该项
coupon_code String 否 - 仅type= coupon_code时为必须，设置对应参数的负载内容，coupon_code object定义COPY_CODE消息。type为其它类型时无该项
  1. 互动消息参数：
参数名 类型 必选 示例值 说明
interactive JsonObject 否 参照请求示例 模板消息内容，type=interactive必填
  • interactive object参数：
参数名 类型 必选 示例值 说明
type String 是 - 互动消息类型，可以是button（快速回复）list（列表）catalog_message（目录）product（商品）product_list（商品列表） cta_url (访问网址) flow
header JsonObject 否 - 头部；type=product_list必填
body JsonObject 否 - 主体
footer JsonObject 否 - 尾部
action JsonObject 是 - 行为
  • header object参数：
参数名 类型 必选 示例值 说明
type string 是 - 您希望使用的标题类型。支持的值：
text：用于列表消息、回复按钮和多商品消息。
text string 条件 - 标题的文本。格式允许使用表情符号，
最大长度：60个字符。如果type设置为text，则此字段为必填。
image object 条件 - image object只支持link
如果type设置为image，则此字段为必填。
video object 条件 - video object只支持link
如果type设置为video，则此字段为必填。
document object 条件 - document object只支持link
如果type设置为document，则此字段为必填。
  • body object参数：
参数名 类型 必选 示例值 说明
text String 是 - 文本
  • footer object参数：
参数名 类型 必选 示例值 说明
text String 是 - 文本
  • action object参数：
名称 类型 必须 描述
button string 是 用于列表消息。按钮内容。不能是空字符串，
并且必须在消息中唯一。支持表情符号。
最大长度：20个字符。
buttons array of JsonObjects 是 用于回复按钮。一个按钮对象可以包含以下参数：
type（唯一支持的类型是reply，用于回复按钮），
title（按钮标题。不能是空字符串，必须在消息中唯一。支持表情符号。最大长度：20个字符。）
id（按钮的唯一标识符。用户点击按钮时，此ID会在webhook中返回。最大长度：256个字符。）
catalog_id string 是 用于单个产品消息和多产品消息。
链接到您的WhatsApp Business账户的
Facebook目录的唯一标识符。
此ID可以通过Meta商务管理器检索。
product_retailer_id string 是 用于单个产品消息和多产品消息。
目录中产品的唯一标识符。
sections array of JsonObjects 是 用于列表消息和多产品消息。section对象的数组。
最少1个，最多10个。
mode string 可选 流程消息的可选项。流程的当前模式，
draft或published。默认：published。
flow_message_version string 是 流程消息所需。必须是3。
flow_token string 是 由业务生成的标识符，用作标识。
flow_id string 是 WhatsApp提供的流程的唯一标识符。
flow_cta string 是 CTA按钮上的文本，例如“Signup”。
最大长度：20个字符（不含表情符号）。
flow_action string 可选 流程消息的可选项。使用navigate预定义
消息的第一个屏幕。对于第一个屏幕由
您的端点提供的高级用例，使用data_exchange。
默认：navigate。
flow_action_payload JsonObject 可选 仅当flow_action是navigate时需要。
对象可以包含以下参数：
screen（必须。流程的第一个屏幕的id。），
data_object（可选。第一个屏幕的输入数据。必须是一个非空对象。）
  • section object参数：
名称 类型 必须 示例值 描述
product_items array of JsonObjects 是 - 用于多产品消息。对象数组，每个节最少1个产品，
整体最多30个产品。每个product对象包含以下字段：
product_retailer_id（字符串类型，必须，唯一标识目录中的产品。
要获取此ID，请转到Meta Commerce Manager，
选择您的账户和您想使用的商店，然后点击Catalog > Items，
找到您要提及的项目。项目ID显示在项目名称下方。）
rows array of JsonObjects 是 - 用于列表消息。包含多行的对象列表。
您可以在您的节中总共有10行。
每行必须有一个标题（最大长度：24个字符）
和一个ID（最大长度：200个字符）。
您可以添加描述（最大长度：72个字符），但这是可选的。
title string 条件 - 选项的标题。
如果消息有多个选项，则必须
最大长度：24个字符。
  1. reaction消息参数：
参数名 类型 必选 示例值 说明
reaction JsonObject 否 参照请求示例 心情消息内容，type=reaction必填
  • reaction object参数：
参数名 类型 必选 示例值 说明
message_id String 是 - 消息回复id,例如:wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYEkVCQkE4NjdGRUE5RDgyQzg0RAA=
emoji String 是 - 表情 例如:"❤️"

请求示例

文本消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "text",
    "text": {
        "body": "text-message-content",
        "preview_url": false
    }
}

引用消息请求示例

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "text",
    "context": {
        "message_id": "<meta_message_id>"
    },
    "text": {
        "body": "text-message-content",
        "preview_url": false
    }
}

图片消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "image",
    "image": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "caption":"image test"
    }
}

视频消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "video",
    "video": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "caption":"video test"
    }
}

音频消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "audio",
    "audio": {
        "id": "a51ca059-e12e-4838-b28b-d471773efb71"
    }
}

文档消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "document",
    "document": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac",
        "filename":"document-test"
    }
}

贴图表情消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "sticker",
    "sticker": {
        "id": "5867096a-a9be-4a56-94d6-89377623b4ac"
    }
}

位置消息请求示例

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "location",
    "location": {
        "latitude": "22.550802897696343",
        "longitude": "113.93844723701477",
        "name": "广东深圳",
        "address": "科兴科学园"
    }
}

模板消息请求示例

  • UTILITY 模板消息（通知类型）

body（application/json） 参数：

{
    "appkey": "xxxx",
    "business_phone": "1202xxxx388",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86188xxxxx977",
    "type": "template",
    "template": {
        "name": "wiz_id",
        "language": {
            "code": "id",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "David"
                    },
                    {
                        "type": "text",
                        "text": "hello world"
                    }
                ]
            }
        ]
    }
}
  • AUTHENTICATION 模板消息（复制验证码消息）

body（application/json） 参数：

{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "otp_test_02",
        "language": {
            "policy": "deterministic",
            "code": "zh_CN"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "123456"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                    {
                        "type": "text",
                        "text": "123456"
                    }
                ]
            }
        ]
    }
}
  • MARKETING 模板消息（营销消息快速回复）

body（application/json） 参数：

{
	"appkey": "aq4xxxfj",
	"business_phone": "120xxxx388",
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "86188xxxxx977",
	"type": "template",
	"template": {
		"name": "xy1029a",
		"language": {
			"code": "kk",
			"policy": "deterministic"
		},
		"components": [
			{
				"type": "body",
				"parameters": [
					{
						"type": "text",
						"text": "8:00"
					},
					{
						"type": "text",
						"text": "2023-01-01"
					}
				]
			},
			{
				"type": "button",
				"sub_type": "quick_reply",
				"index": "0",
				"parameters": [
					{
						"type": "payload",
						"payload": "text1"
					}
				]
			},
			{
				"type": "button",
				"sub_type": "quick_reply",
				"index": "1",
				"parameters": [
					{
						"type": "payload",
						"payload": "text2"
					}
				]
			}
		]
	}
}
  • MARKETING 模板消息（目录）

body（application/json） 参数：

{
	"appkey": "aq4xxxfj",
	"business_phone": "120xxxx388",
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "86188xxxxx977",
	"type": "template",
        "template": {
        "name": "xy_test_catalog01",
        "language": {
            "policy": "deterministic",
            "code": "zh_CN"
        },
         "components": [
            {
                "type": "button",
                "sub_type": "CATALOG",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "thumbnail_product_retailer_id": "jydq8qlspt"
                        }
                    }
                ]
            }
        ]
    }
}
  • MARKETING 模板消息（商品）

body（application/json） 参数：

{
    "appkey": "aq4xxxfj",
    "business_phone": "120xxxx388",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86188xxxxx977",
    "type": "template",
    "template": {
        "name": "mkt_test_glory",
        "language": {
            "policy": "deterministic",
            "code": "zh_CN"
        },
        "components": [
            {
                "type": "button",
                "sub_type": "mpm",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "thumbnail_product_retailer_id": "3qfw7ouze4",
                            "sections": [
                                {
                                    "title": "Premium Packages",
                                    "product_items": [
                                        {
                                            "product_retailer_id": "3qfw7ouze4"
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    }
}
  • MARKETING 模板消息（flow）

body（application/json） 参数：

{
	"appkey": "aq4xxxfj",
	"business_phone": "120xxxx388",
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "86188xxxxx977",
	"type": "template",
        "template": {
        "name": "test_flow_start",
        "language": {
            "policy": "deterministic",
            "code": "zh_CN"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "image",
                        "image": {
                            "id": "1398367154050711"
                        }
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "FLOW",
                "index": "0",
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "flow_token": "FLOW_TOKEN"
                        }
                    }
                ]
            }
        ]
    }
}

互动消息请求示例

  • 互动消息（列表）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "今天吃什么"
        },
        "body": {
            "text": "选一个你最喜欢的食物"
        },
        "footer": {
            "text": "nxcloud"
        },
        "action": {
            "button": "以下几种方便面你最喜欢哪种",
            "sections": [
                {
                    "title": "海鲜",
                    "rows": [
                        {
                            "id": "1",
                            "title": "海鲜面",
                            "description": "鲜虾鱼板面"
                        }
                    ]
                },
                {
                    "title": "牛肉",
                    "rows": [
                        {
                            "id": "2",
                            "title": "牛肉面",
                            "description": "红烧牛肉面"
                        }
                    ]
                },
                {
                    "title": "香菇",
                    "rows": [
                        {
                            "id": "3",
                            "title": "鸡",
                            "description": "香菇炖鸡面"
                        }
                    ]
                },
                {
                    "title": "扣肉",
                    "rows": [
                        {
                            "id": "4",
                            "title": "酸菜面",
                            "description": "梅菜扣肉面"
                        }
                    ]
                },
                {
                    "title": "红色清汤",
                    "rows": [
                        {
                            "id": "5",
                            "title": "番茄鸡蛋",
                            "description": "番茄牛肉面"
                        }
                    ]
                }
            ]
        }
    }
}
  • 互动消息（快速回复）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
        "type": "button",
        "body": {
            "text": "如果让你重来人生你会愿意吗？"
        },
        "action": {
            "buttons": [
                {
                    "type": "reply",
                    "reply": {
                        "id": "1",
                        "title": "愿意"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": "2",
                        "title": "不愿意"
                    }
                }
            ]
        }
    }
}
  • 互动消息（访问网址）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
        "type": "cta_url",
        "header": {
            "type": "image",
            "image": {
                "link": "https://www.nxcloud.com/img/kv_visual_01.a1d1602e.png"
            }
        },
        "body": {
            "text": " Drive international success for your business through our trusted industry leading partners. "
        },
        "footer": {
            "text": "nxcloud"
        },
        "action": {
            "name": "cta_url",
            "parameters": {
                "display_text": "NXCloud",
                "url": "https://www.nxcloud.com"
            }
        }
    }
}
  • 互动消息（目录）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
        "type": "catalog_message",
        "body": {
            "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
        },
        "action": {
            "name": "catalog_message",
            "parameters": {
                "thumbnail_product_retailer_id": "3qfw7ouze4"
            }
        }
    }
}
  • 互动消息（单商品）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
     "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "129002493482066",
       "product_retailer_id": "3qfw7ouze4"
     }
   }
}
  • 互动消息（多商品）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
    "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "header-content"
    },
    "body": {
      "text": "optional body text"
    },
    "footer": {
      "text": "optional footer text"
    },
    "action": {
      "catalog_id": "129002493482066",
      "product_retailer_id": "3qfw7ouze4",
      "sections": [
        {
          "title": "section-title",
          "product_items": [
            {
              "product_retailer_id": "3qfw7ouze4"
            },
            {
              "product_retailer_id": "cm2i4b15t7"
            }
          ]
        },
        {
          "title": "section-title",
          "product_items": [
            {
              "product_retailer_id": "3qfw7ouze4"
            }
          ]
        }
      ]
    }
  }
}
  • 互动消息（flow）
{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "interactive",
     "interactive": {
     "type": "flow",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "7524375840909375",
        "flow_cta": "提交!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "QUESTION_ONE",
          "data": {
            "demo": "5"
          }
        }
      }
    }
   }
}

心情消息请求示例

body（application/json） 参数：

{
    "appkey": "f54xxxtg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "reaction",
     "reaction": {
     "message_id": "<meta_message_id>",
     "emoji": "❤️"
   }
}

复制优惠码消息请求示例

body（application/json） 参数：

{
    "appkey": "8exxxyos",
    "business_phone": "852xxxx3867",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "simon_six",
        "language": {
            "code": "en_US",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "button",
                "sub_type": "COPY_CODE",
                "index": 4,
                "parameters": [
                    {
                        "type": "coupon_code",
                        "coupon_code": "123456"
                    }
                ]
            }
        ]
    }
}

轮播模板消息请求示例

body（application/json） 参数：

{
    "appkey": "8exxxyos",
    "business_phone": "852xxxx3867",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "carousel_template_media_cards_v1",
        "language": {
            "code": "en_US",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "AAAA"
                    },
                    {
                        "type": "text",
                        "text": "BBB"
                    },
                    {
                        "type": "text",
                        "text": "CCC"
                    }
                ]
            },
            {
                "type": "carousel",
                "cards": [
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "653936870328698"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-aloes"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "blue-elf"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 0
                    },
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "1118343899978698"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-crassulas"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "buddhas-temple"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 1
                    },
                    {
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "image": {
                                            "id": "608602548800223"
                                        }
                                    }
                                ]
                            },
                            {
                                "type": "button",
                                "index": 0,
                                "parameters": [
                                    {
                                        "type": "payload",
                                        "payload": "more-echeverias"
                                    }
                                ],
                                "sub_type": "quick_reply"
                            },
                            {
                                "type": "button",
                                "index": 1,
                                "parameters": [
                                    {
                                        "type": "text",
                                        "text": "black-prince"
                                    }
                                ],
                                "sub_type": "url"
                            }
                        ],
                        "card_index": 2
                    }
                ]
            }
        ]
    }
}

响应参数

参数名 类型 说明
code Integer 结果编码
data JsonObject 请求结果
message String 请求结果说明

发送成功

  • data object参数：
参数名 类型 说明
messaging_product String 通信通道类型
messages array[message JsonObject] 消息序列
  • message object参数：
参数名 类型 说明
id String 系统生成的唯一的ID

响应示例

成功示例

{
    "code": 0,
    "message": "Success",
    "data": {
        "messaging_product": "whatsapp",
        "messages": [
            {
                "id": "wamid.18857e85eff8438caea378a54f1e9220"
            }
        ]
    },
    "traceId": "409038383a8a4812a82ccd7e3a6f33b5"
}

失败示例

{
    "code": 9003,
    "message": "Customer APP does not exist / Status is unavailable",
    "traceId": "5598e59e500d4a77b0c298be3ad81644"
}

响应码说明

code message 解决办法
0 Success
-1 Failure 请联系技术人员排除问题
1000~100X Authentication failed 详情查看API鉴权部分
1100 Customer does not exist / Status is unavailable 账号状态异常，联系业务人员处理账号问题
1102 Insufficient balance 账号余额不足，请联系业务人员充值
9000 Request parameter error 参数缺失，请检查必须的参数
9001 System business error 系统业务错误，请联系技术人员排除问题
9002 Phone number error 非法号码，请检查号码正确性
9003 Customer APP does not exist / Status is unavailable 应用状态异常（不存在/禁用），联系业务人员处理云平台应用创建/禁用问题
9004 Customer APP does not have quotation 应用没有对应国家报价，联系业务人员处理应用报价问题
10003 WhatsApp business phone is not bind app 该whatsapp号码未绑定应用，请联系业务人员处理应用和手机号绑定操作
10005 WhatsApp Template does not exist or low quality WhatsApp 模板不存在或者质量低

模板语言

语言 代码   语言 代码   语言 代码
Afrikaans af   Greek el   Portuguese (BR) pt_BR
Albanian sq   Gujarati gu   Portuguese (POR) pt_PT
Arabic ar   Hebrew he   Punjabi pa
Azerbaijani az   Hindi hi   Romanian ro
Bengali bn   Hungarian hu   Russian ru
Bulgarian bg   Indonesian id   Serbian sr
Catalan ca   Irish ga   Slovak sk
Chinese (CHN) zh_CN   Italian it   Slovenian sl
Chinese (HKG) zh_HK   Japanese ja   Spanish es
Chinese (TAI) zh_TW   Kannada kn   Spanish (ARG) es_AR
Croatian hr   Kazakh kk   Spanish (SPA) es_ES
Czech cs   Korean ko   Spanish (MEX) es_MX
Danish da   Lao lo   Swahili sw
Dutch nl   Latvian lv   Swedish sv
English en   Lithuanian lt   Tamil ta
English (UK) en_GB   Macedonian mk   Telugu te
English (US) en_US   Malay ms   Thai th
Estonian et   Marathi mr   Turkish tr
Filipino fil   Norwegian nb   Ukrainian uk
Finnish fi   Persian fa   Urdu ur
French fr   Polish pl   Uzbek uz
German de   Hausa  ha    Vietnamese vi
Malayalam ml   Zulu zu  

简介

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally