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入参参数签名，公共约定

parameter 参数：

参数名 类型 必选 示例值 说明
phone String 是 86158xxxx1795 消息发送方的WhatsApp号码，需要带国码。如86158xxxx1795

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入参参数签名，公共约定

parameter 参数：

参数名 类型 必选 示例值 说明
phone String 是 86158xxxx1795 消息发送方的WhatsApp号码，需要带国码。如86158xxxx1795

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时必填

参数请求示例

{
        "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"
	}]
	
}

获取模板详情

通过API获取模板详情

  • URL：https://api.nxcloud.com/saas/wa/template/{phone}/{id}?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
id int 是 1 模板id

返回参数说明

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

data

参数名 类型 说明
id Long meta模板id
channel int 渠道类型 2：WhatsApp
name String 模板名称
status String 模板状态
language String 模板语言缩写
quality_score JsonObject 模板质量
category String 模板类型名称 MARKETING、UTILITY
category_type String 模板类型 1：MARKETING，2：UTILITY
is_close_auto_flow int 是否关闭未分配会话 0：不关闭 1:关闭
components int array[component JsonObject]
  • component object参数：
参数名 类型 示例值 说明
type String - 模板内容，HEADER（页眉） 、BODY（消息体）、FOOTER（页脚）、BUTTONS(按钮)
format String - text、IMAGE、DOCUMENT、VIDEO
text String - 页眉文本内容
media_id String - 媒体id
h String - 模板媒体id
example example JsonObject - 事例
filename String - 媒体文件名称
buttons array [button JsonObject] - 当type 为BUTTONS时
  • example object参数：
参数名 类型 示例值 说明
header_handle String - 消息头部变量 媒体链接
file_name String - 消息头部变量 媒体文件名称
body_text array [String] - 消息体变量值
  • button object参数：
参数名 类型 示例值 说明
type String - 按钮类型，QUICK_REPLY(快速回复按钮)、URL(行动号召url按钮)、PHONE_NUMBER(行动号召phone_number按钮)、FLOW(表单按钮)
text String - 按钮名称
buttonReqs object -
  • buttonReqs object参数：
参数名 类型 示例值 说明
type String - 按钮类型，QUICK_REPLY(快速回复按钮)、URL(行动号召url按钮)、PHONE_NUMBER(行动号召phone_number按钮)、FLOW(表单按钮)
text String - 按钮名称
customizeType object - 按钮自定义类型，当按钮类型为QUICK_REPLY时有值,conventional(常规)、unsubscribe(退订)
payload String - 按钮id
flow_id String - 流id
navigate_screen String - 流程中的起始屏幕
flow_action String - 流行为,可选值:navigate,data_exchange; 默认值:navigate
buttonEvents array [buttonEvent object ] - 按钮关联事件
  • buttonEvent object参数：
参数名 类型 示例值 说明
event String - 事件类型，tag(标签)、text(文本)、template(模板)
tagName String - 标签名称
tagId object - 标签Id
templateId String - 模板Id
templateName String - 模板名称
buttonEvents array [buttonEvent object ] - 按钮关联事件

响应示例1



响应示例2




响应示例3


{
    "code": 0,
    "message": "",
    "data": {
        "namespace": null,
        "name": "test_99",
        "category": "MARKETING",
        "category_type": 1,
        "components": [
            {
                "type": "HEADER",
                "format": "TEXT",
                "text": "头部文本",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BODY",
                "format": null,
                "text": "模板内容",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "FOOTER",
                "format": null,
                "text": "脚部",
                "buttons": null,
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            },
            {
                "type": "BUTTONS",
                "format": null,
                "text": null,
                "buttons": [
                    {
                        "type": "FLOW",
                        "text": "按钮",
                        "payload": null,
                        "url": null,
                        "phone_number": null,
                        "flow_id": "803348158336427",
                        "navigate_screen": "SIGN_IN",
                        "flow_action": "NAVIGATE",
                        "buttonReqs": null
                    }
                ],
                "parameters": null,
                "sub_type": null,
                "index": null,
                "example": null,
                "filename": null,
                "url": null,
                "media_id": null,
                "h": null,
                "media_type": null
            }
        ],
        "language": "sq",
        "status": "APPROVED",
        "id": 432230866355873,
        "quality_score": {
            "score": "UNKNOWN"
        },
        "tag_ids": [
            33989
        ],
        "is_close_auto_flow": 0
    },
    "traceId": "67a05b8528114fa29edeb6616458b12a"
}






参数名
类型
必选
示例值
说明






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