Skip to content

SAAS saas_plat openapi template

Jump to bottom
zjc1750514326 edited this page Jun 25, 2024 · 47 revisions

获取模板消息列表

通过API获取模板消息列表

  • URL：https://api.nxcloud.com/saas/wa/template/{phone}?page_number={page_number}&page_size={page_size}&name={name}&tenant_id={tenant_id}
  • Method：GET
  • 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入参参数签名，公共约定

parameter 参数：

参数名 类型 必选 示例值 说明
phone String 是 86158xxxx1795 消息发送方的WhatsApp号码，需要带国码。如86158xxxx1795
tenant_id Long 是 1 租户ID
page_number int 是 1 页数
page_size int 是 10 每页个数
name String 否 模板名称 模板名称

返回参数说明

参数名 类型 说明
data array[data JsonObject] 请求结果
message string 请求结果说明
code integer 结果编码

data

参数名 类型 说明
id Long 模板id
channel int 渠道类型 2：WhatsApp
name String 模板名称
content String 模板内容
created_at String 模板创建时间
updated_at String 模板修改时间
status int 模板状态
language String 模板语言缩写
language_name String 模板语言名称
unsubscribe String 模板是否退订
quality String 模板质量
category String 模板类型名称 MARKETING、UTILITY
category_type String 模板类型 1：MARKETING，2：UTILITY
waRejectedReason String 模板被拒原因
is_close_auto_flow int 是否关闭未分配会话 0：不关闭 1:关闭

响应示例

{
    "code": 0,
    "message": "",
    "data": {
        "list": [
            {
                "id": 314,
                "channel": 2,
                "name": "buttontest22",
                "content": "Hello, I am the new virtual assistant. I can help you discover products or provide support. Please reach out if I can help!",
                "created_at": "2024-06-25 14:31:26",
                "updated_at": "2024-06-25 15:27:39",
                "status": 2,
                "language": "en_GB",
                "language_name": "English (UK)",
                "unsubscribe": "",
                "additional": null,
                "quality": "UNKNOWN",
                "category": "MARKETING",
                "category_type": 1,
                "waRejectedReason": "",
                "is_close_auto_flow": 0
            }   
        ],
        "total": 1,
        "has_next_page": false
    },
    "traceId": "16f9ca88e70844a8a088f9a4a3806e5e"
}

创建模板消息

通过API获取模板消息列表

  • URL：https://api.nxcloud.com/saas/wa/template/{phone}
  • 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
name String 是 test_1 模板名称(不能为中文)
language String 是 模板语言 如 af
category_type int 是 模板类型 模板类型 1：MARKETING，2：UTILITY
content String 是 模板内容 模板内容
headerText String 否 模板头部文本
mediaName String 否 模板头部富媒体名称
mediaId String 否 模板头部富媒体Id
mediaType String 否 模板头部富媒体类型 IMAGE, DOCUMENT, VIDEO
templateMediaId String 否 模板头部富媒体模板Id
footerText String 否 模板页眉
buttonComponents array[buttonComponent JsonObject] 否 模板按钮
  • buttonComponent object参数：
参数名 类型 必选 示例值 说明
type String 是 - 按钮类型，QUICK_REPLY(快速回复按钮)、URL(行动号召url按钮)、PHONE_NUMBER(行动号召phone_number按钮)、FLOW(表单按钮)
customizeType String 否 - 按钮自定义类型，当按钮类型为QUICK_REPLY必填,conventional(常规)、unsubscribe(退订)
text String 是 - 按钮名称
text String 是 - 按钮名称
flow_id String 否 - 流Id，当按钮类型为FLOW必填
buttonEvents array[buttonEvent JsonObject] 否 - 按钮关联事件。
  • buttonEvent object参数：
参数名 类型 必选 示例值 说明
event String 是 - 事件类型，tag(标签)、text(文本)、template(模板)
tagName String 否 - 标签名称，当事件类型为tag时必填
tagId String 否 - 标签Id，当事件类型为tag时必填
text String 否 - 文本内容，当事件类型为text时必填
templateId String 否 - 模板Id，当事件类型为template时必填
templateName String 否 - 模板名称，当事件类型为template时必填

参考截图示例1

6558A92F-E539-4eca-8FF4-A39E865B3284

参数请求示例1

{
    "name": "test_23",
    "tenant_id ": 123,
    "language": "af",
    "category_type": 1,
    "content": "发送消息内容：WhatsApp:{{WhatsApp}}，结束消息",
    "shortLink": null,
    "variable": null,
    "channel": 2,
    "headerType": "3",
    "headerText": "",
    "footerText": "脚部",
    "buttonType": "2",
    "mediaName": "1705406614735.jpg",
    "templateMediaId": "4:MTcwNTQwNjYxNDczNS5qcGc=:aW1hZ2UvcG5n:ARYVc4sZwi3xB-cwPixWwFGyXYwd_SZ4JyGw89jmzar1IWgtWQtJmZTokdNe0wJ8LzUM_8QV0wqfw-Lzu5nk0_j2j75qeAxXQMBYLl247jV-tw:e:1719648253:1407008009801826:100084713375965:ARaNsT4tjB0mMOdhv48",
    "mediaId": "1167113681293447",
    "flowsButtonText": "",
    "openFlowsId": null,
    "tag_ids": [
        33991
    ],
    "is_close_auto_flow": 0,
    "buttonComponents": [
        {
            "customizeType": "conventional",
            "text": "按钮1",
            "type": "QUICK_REPLY",
            "payload": "",
            "tags": 33991,
            "template_id": 314,
            "buttonEvents": [
                {
                    "event": "tag",
                    "tagId": 33991,
                    "tagName": "Viber标签"
                },
                {
                    "event": "template",
                    "templateId": 314,
                    "templateName": "buttontest22"
                }
            ]
        },
        {
            "customizeType": "conventional",
            "text": "按钮2",
            "type": "QUICK_REPLY",
            "payload": "测试文本",
            "autoReplyType": "3",
            "tags": 33991,
            "buttonEvents": [
                {
                    "event": "tag",
                    "tagId": 33991,
                    "tagName": "Viber标签"
                },
                {
                    "event": "text",
                    "text": "测试文本"
                }
            ]
        },
        {
            "customizeType": "conventional",
            "text": "按钮3",
            "type": "QUICK_REPLY",
            "payload": "",
            "autoReplyType": "2",
            "template_id": 313,
            "buttonEvents": [
                {
                    "event": "template",
                    "templateId": 313,
                    "templateName": "test_8"
                }
            ]
        }
    ]
}

参考截图示例2

76EB1C0C-5C32-4633-A58A-A8D6E42A5460

参数请求示例2

{
	"name": "test_45",
	"language": "af",
        "tenant_id": 1,
	"category_type": 1,
	"content": "模板内容https://119.91.210.214:10001/api/shortLink/doAccess/Y3Mjmq  内容结束",
	"headerText": "测试头部",
	"footerText": "脚部",
	"mediaName": "",
	"templateMediaId": "",
	"mediaId": "",
	"mediaType": "",
	"flowsButtonText": "",
	"tag_ids": [],
	"is_close_auto_flow": 0,
	"buttonComponents": [{
		"text": "电话",
		"type": "PHONE_NUMBER",
		"url": "",
		"phoneNumber": "8613128xxxx"
	},
	{
		"text": "网址1",
		"type": "URL",
		"url": "https://testnxlink.nxcloud.com/",
		"phoneNumber": ""
	},
	{
		"text": "网址2",
		"type": "URL",
		"url": "https://www.baidu.com/",
		"phoneNumber": ""
	}]
}

参考截图示例3

image

参数请求示例3

{
	"name": "test_99",
	"language": "sq",
        "tenant_id": 1,
	"category_type": 1,
	"content": "模板内容",
	"headerText": "头部文本",
	"footerText": "脚部",
	"mediaName": "",
	"templateMediaId": "",
	"mediaId": "",
	"tag_ids": [33989],
	"is_close_auto_flow": 0,
	"buttonComponents": [{
		"type": "flow",
		"text": "按钮",
		"flow_id": "803348158336427"
	}]
}

更新模板

通过API更新模板

  • URL：https://api.nxcloud.com/saas/wa/template/{phone}
  • Method：PUT
  • 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
id Long 是 1 模板Id
name String 是 test_1 模板名称(不能为中文)
language String 是 模板语言 如 af
category_type int 是 模板类型 模板类型 1：MARKETING，2：UTILITY
content String 是 模板内容 模板内容
headerText String 否 模板头部文本
mediaName String 否 模板头部富媒体名称
mediaId String 否 模板头部富媒体Id
mediaType String 否 模板头部富媒体类型 IMAGE, DOCUMENT, VIDEO
templateMediaId String 否 模板头部富媒体模板Id
footerText String 否 模板页眉
buttonComponents array[buttonComponent JsonObject] 否 模板按钮
  • buttonComponent object参数：
参数名 类型 必选 示例值 说明
type String 是 - 按钮类型，QUICK_REPLY(快速回复按钮)、URL(行动号召url按钮)、PHONE_NUMBER(行动号召phone_number按钮)、FLOW(表单按钮)
customizeType String 否 - 按钮自定义类型，当按钮类型为QUICK_REPLY必填,conventional(常规)、unsubscribe(退订)
text String 是 - 按钮名称
text String 是 - 按钮名称
flow_id String 否 - 流Id，当按钮类型为FLOW必填
buttonEvents array[buttonEvent JsonObject] 否 - 按钮关联事件。
  • buttonEvent object参数：
参数名 类型 必选 示例值 说明
event String 是 - 事件类型，tag(标签)、text(文本)、template(模板)
tagName String 否 - 标签名称，当事件类型为tag时必填
tagId String 否 - 标签Id，当事件类型为tag时必填
text String 否 - 文本内容，当事件类型为text时必填
templateId String 否 - 模板Id，当事件类型为template时必填
templateName String 否 - 模板名称，当事件类型为template时必填

参数请求示例2

{
        "id": 317,	
        "name": "test_99",
	"language": "sq",
        "tenant_id": 1,
	"category_type": 1,
	"content": "模板内容",
	"headerText": "头部文本",
	"footerText": "脚部",
	"mediaName": "",
	"templateMediaId": "",
	"mediaId": "",
	"mediaType": "",
	"tag_ids": [33989],
	"is_close_auto_flow": 0,
	"buttonComponents": [{
		"type": "flow",
		"text": "按钮",
		"flow_id": "803348158336427"
	}]
	
}
参数名 类型 必选 示例值 说明
code int 否 参照请求示例 模板消息内容，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
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；
text String 否 - 仅type= text时为必须，设置对应参数的文本内容。type为其它类型时无该项
image JsonObject 否 - 仅type= image时为必须，设置对应参数的图片内容，image object定义参照图片消息。type为其它类型时无该项
  • image object参数：
参数名 类型 必选 示例值 说明
link String 是 - 图片的URL链接。必须是 HTTP/HTTPS URLs。

请求示例

参照请求示例

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

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"   // {{手机号码}}
					}
				]
			}
		]
	}
}

响应参数

参数名 类型 说明
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