Skip to content

SAAS WhatsApp API send

Jump to bottom
zjc1750514326 edited this page Mar 10, 2025 · 43 revisions

发送消息

通过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（参数模板消息） image 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

简介

短信

语音

云呼叫中心（NXLink）

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

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally