SAAS WhatsApp API send - nxtele/http-api-document GitHub Wiki

发送消息

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

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

请求参数

header参数：

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

body参数：

参数名	类型	必选	示例值	说明
tenant_id	Long	是	1	租户ID
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	是	template	支持以下消息类型的发送： template 模板
template	JsonObject	是	-	仅type= template时为必须，模板消息内容

消息类型

模板消息参数：

参数名	类型	必选	示例值	说明
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时，设置模板内容的变量信息；
parameters	array[parameter JsonObject]	否	-	组件参数列表。

parameter object参数：

参数名	类型	必选	示例值	说明
type	String	是	-	其中：1）当component object的 type=header时，可以为image；2）当component object的 type=body时，取值为text； 3）当component object的 type=button且sub_type=URL时，取值为text； 4）当component object的 type=button且sub_type= COPY_CODE时，取值为coupon_code
sub_type	String	否	-	所创建的按钮类型，type=button时必须，可以是URL,COPY_CODE。 type为其它类型时无该项。
text	String	否	-	仅type= text时为必须，设置对应参数的文本内容。type为其它类型时无该项
image	JsonObject	否	-	仅type= image时为必须，设置对应参数的图片内容，image object定义参照图片消息。type为其它类型时无该项
coupon_code	String	否	-	仅type= coupon_code时为必须，设置对应参数的负载内容，coupon_code object定义COPY_CODE消息。type为其它类型时无该项

image object参数：

参数名	类型	必选	示例值	说明
link	String	是	-	图片的URL链接。必须是 HTTP/HTTPS URLs。

component object参数：

参数名	类型	必选	示例值	说明
index	int	否	-	type=button且sub_type=url时并且url带有变量时必填，位置必须要和创建模板的位置保持一致；

请求示例

参照请求示例

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

body（application/json）参数：

{
    "tenant_id" : 1,
    "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": "header",
				"parameters": [{
					"type": "image",
					"image": {
						"link": "https://imglink"
					}
				}]
			}
			{
				"type": "body",
				"parameters": [    // 严格按照变量顺序填写参数,重复多次的变量也须多次赋值
					{
						"type": "text",  
						"text": "David"  // {{First Name}}
					},
					{
						"type": "text",
						"text": "China"   // {{国家}}
					},
					{
						"type": "text",
						"text": "China"   // {{国家}}
					},
                                        {
						"type": "text",
						"text": "86138XXX"   // {{手机号码}}
					}
				]
			}
		]
	}
}

模板消息2（参数模板消息） body（application/json）参数：

{
    "tenant_id" : 1,
    "appkey": "f543ertg",
    "business_phone": "185xxxx8399",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "86136xxxx9759",
    "type": "template",
    "template": {
        "name": "test_00045",
        "language": {
            "code": "pt_BR",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "button",
                "sub_type": "url",
                "index": 0,
                "parameters": [
                    {
                        "type": "text",
                        "text": "85xxxx"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "url",
                "index": 1,
                "parameters": [
                    {
                        "type": "text",
                        "text": "Firstxxxx"
                    }
                ]
            }
        ]
    }
}

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

{
  "tenant_id": 123,
  "appkey": "8exxxxyos",
  "business_phone": "852xxxx867",
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "86136xxxx759",
  "type": "template",
  "template": {
    "name": "ten_btn4",
    "language": {
      "code": "en_US",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "COPY_CODE",
        "index": 3,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "123123"
          }
        ]
      }
    ]
  }
}

响应参数

参数名	类型	说明
code	Integer	结果编码
data	JsonObject	请求结果
message	String	请求结果说明
traceId	String	链路追踪ID

data object参数：

参数名	类型	说明
message_id	String	消息ID

响应示例

成功示例

{
	"code": 0,
	"message": "",
	"data": {
		"message_id": "gBGGhSNXV1dfAglVQ0RRuE3YWhc"
	},
	"traceId": "56bf81643292cd6a89ecde64ae00db13"
}

响应码说明

code	message	解决办法
0	请求成功
-1	请求失败	请联系技术人员排除问题
1000~100X	鉴权问题	详情查看API鉴权部分
21058	参数异常	tenant_id 必填
21059	参数异常	app_key 必填
21060	参数异常	business_phone 必填
21061	参数异常	to (接受方号码) 必填
21062	参数异常	type 必填,可选值[template]
21063	参数异常	template 必填
22020	业务异常	客户不存在
22041	业务异常	云平台发送失败
22042	业务异常	发送WhatsApp信息失败
22049	业务异常	business_phone={0}的商户不存在
22089	业务异常	号码不可用(No Core App)
22090	业务异常	非法的号码
22091	业务异常	非WhatsApp用户
22092	业务异常	不存在语言包: {0}
22093	业务异常	模板不存在
22123	业务异常	商户手机号错误
22124	业务异常	应用不存在/不可用
22122	业务异常	应用没有对应国家报价
22125	业务异常	账号余额不足
22126	业务异常	该whatsapp号码未绑定应用
22141	业务异常	WhatsApp发送失败，具体看message字段

模板语言

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