Skip to content

WhatsApp API createApp

Jump to bottom
momi00 edited this page Mar 15, 2023 · 7 revisions

发送消息

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

  • URL：https://api2.nxcloud.com/api/wa/integrator/embedded/register/createApp
  • Method：POST
  • Content-Type：applicatin/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 模板

消息类型

  1. 文本消息参数：
参数名 类型 必选 示例值 说明
text JsonObject 否 参照请求示例 文本消息内容，type=text必填
  • 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 否 - 图片描述
  1. 视频消息参数：
参数名 类型 必选 示例值 说明
video JsonObject 否 参照请求示例 视频消息内容，type=video必填
  • video object参数：
参数名 类型 必选 示例值 说明
link String 否（与id 二选一） - 视频文件的URL链接。必须是 HTTP/HTTPS URLs。
id String 否（与link 二选一） - 视频文件的存储ID，通过Media接口上传文件后获得。
caption String 否 - 视频描述
  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
1）当type=header时，设置模板头部的变量信息；
2）当type=body时，设置模板内容的变量信息；
3）当type=button时，设置模板按钮的变量信息
sub_type String 否 - 所创建的按钮类型，仅type=button时为必须，可以是url, quick_reply。type为其它类型时无该项。
index String 否 - 按钮的位置索引，仅type=button时为必须，仅type=button时为必须，按钮的序号，值域是0-2。
parameters array[parameter JsonObject] 否 - 组件参数列表。
  • 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；当component object的 type=button且sub_type= quick_reply时，取值为payload
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为其它类型时无该项

请求示例

文本消息请求示例

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
    }
}

图片消息请求示例

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": "科兴科学园"
    }
}

模板消息请求示例

  • 模板消息（参数模板消息）

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
		"name": "text_template",
		"language": {
			"code": "en_US",
			"policy": "deterministic"
		},
		"components": [
			{
				"type": "body",
				"parameters": [
					{
						"type": "text",
						"text": "David"
					},
					{
						"type": "text",
						"text": "B520"
					}
				]
			}
		]
	}
}
  • 模板消息（行动号召消息）

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
		"name": "tempalte_media_button_1",
		"language": {
			"code": "en_US",
			"policy": "deterministic"
		},
		"components": [
			{
				"type": "body",
				"parameters": [
					{
						"type": "text",
						"text": "David"
					}
				]
			},
			{
				"type": "header",
				"parameters": [
					{
						"type": "image",
						"image":{
							"link": "http://www.yjz8.cn/xx/1.png"
						}
					}
				]
			},
			{
				"type": "button",
				"sub_type": "url",
				"index": "0",
				"parameters": [
					{
						"type": "text",
						"text": "a"
					}
				]
			}
		]
	}
}
  • 模板消息（快速回复消息）

body（application/json） 参数：

{
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
		"name": "xy_button_tempalte",
		"language": {
			"code": "en_US",
			"policy": "deterministic"
		},
		"components": [
			{
				"type": "header",
				"parameters": [
					{
						"type": "text",
						"text": "header"
					}
				]
			},
			{
				"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"
					}
				]
			},
			{
				"type": "button",
				"sub_type": "quick_reply",
				"index": "2",
				"parameters": [
					{
						"type": "payload",
						"payload": "text3"
					}
				]
			}
		]
	}
}

响应参数

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

响应示例

成功示例

{
    "code": 0,
    "data": {
        "messaging_product": "whatsapp",
        "messages": [
            {
                "id": "gBGHhhdgYFCBnwIJ6QRYvhwQk7Nc"
            }
        ]
    },
    "message": "请求成功"
}

失败示例

{
    "code": -1,
    "message": "请求失败",
    "data": null
}

响应码说明

code message 解决办法
0 请求成功
-1 请求失败 请联系技术人员排除问题
1000~100X 鉴权问题 详情查看API鉴权部分
9000 参数异常 参数遗漏，请检查必须的参数
9001 系统业务错误 请联系技术人员排除问题
9002 商户手机号错误 请确认商户号码是否属于whatsapp号码
9003 应用不存在/不可用 联系业务人员处理云平台应用创建/禁用问题
9004 应用没有对应国家报价 联系业务人员处理应用报价问题
9005 账号余额不足 请联系业务人员充值
9006 该whatsapp号码未绑定应用 请联系业务人员处理应用和手机号绑定操作
9007 下游通信端异常 请联系技术人员排除问题
9099 WhatsApp error meta官方错误提示

模板语言

语言 代码   语言 代码   语言 代码
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         Vietnamese vi

简介

短信

语音

云呼叫中心（NXLink）

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

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally