Skip to content

WhatsApp API createTemplateAsync

Jump to bottom
GiuFLim edited this page May 19, 2025 · 1 revision

异步创建消息模板

在WhatsApp应用下的指定的单个号码创建新的消息模板。
需要注意的是，如果创建模板时使用了富媒体交互模板，需要同时提交富媒体示例文件，富媒体示例文件通过“模板示例媒体上传”API接口上传。

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

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

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

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 牛信云WhatsApp应用的appkey
business_phone String 是 86158xxx1795 商户的WhatsApp号码列表，需要带国码,如185xxx99
messaging_product String 是 whatsapp 发送消息的通道，应用于WhatsApp消息的发送时，值必须为“whatsapp”
category String 是 MARKETING 模板类型
枚举值:
"MARKETING" : "包括促销或优惠、信息更新或邀请客户回应/采取行动的信息。任何不符合效用或身份验证用途均为营销",
"UTILITY" : "促成商定的某个具体请求或交易，或向客户提供与进行中的交易相关的最新信息，包括售后通知和定期账单",
"AUTHENTICATION" ："使商家可以使用一次性密码验证用户身份，可能会在登录过程的多个步骤中出现（如帐号认证、帐号找回、诚信挑战）"
language String 是 zh_CN 语言编码，例如zh_CN
name String 是 模板名称
message_send_ttl_seconds int 否 模板发送的过期时间.
针对身份验证模板，将该参数设为 30 到 900 秒(即 30秒 到 15 分钟)；
针对交易相关模板，将该参数设为 30 至 43200 秒(30 秒至 12 小时);
针对营销相关模板，将该参数设为 43200 至 2592000 秒(12 小时至 30 天)
components array[component object] 是 模板组件
  • component object参数:
参数名 类型 是否必须 说明
type string 必须 组件类型，取值包括：HEADER, BODY, FOOTER, BUTTONS,CAROUSEL
format string 必须/无 仅type= HEADER时有此项且为必须项，type!=HEADER时，无此项。
描述HEADER里内容的类型。取值范围包括：TEXT，DOCUMENT，IMAGE， VIDEO
text string 必须/无 type= HEADER且format=text时，为必须项；type=BODY时，为必须项；
type=FOOTER时，为必须项；type=BUTTONS时，无此项。
example object 必须/无 变量示例，当HEADER或者BODY内容中配置了变量时，为必须项。否则无此项。
buttons array[button object] 必须/无 仅type=BUTTONS时，为必须项，否则无此项。
add_security_recommendation boolean 必须/无 添加安全建议 身份验证模板 type = BODY 时可选 值为 true/false。
code_expiration_minutes integer 必须/无 验证码的失效时间 身份验证模板 type = FOOTER 时可选 值的可填范围是 1-90。
cards array[card object] 必须/无 仅type=CAROUSEL 必填,轮播模板卡片.
  • card object参数:
参数名 类型 是否必须 说明
components array[component object] 必须/无 轮播模板组件. 且component的type取值为HEADER, BODY, BUTTONS.
  • example object参数:
参数名 类型 是否必须 说明
header_handle string 必须/无 当HEADER中 format=DOCUMENT或format=IMAGE或format=VIDEO时，与custom_header_handle_url二选一，否则无此项，如果与custom_header_handle_url同时存在时，以custom_header_handle_url为准。上传文件模板示例 获取 header_handle 值
custom_header_handle_url string 必须/无 当HEADER中 format=DOCUMENT或format=IMAGE或format=VIDEO时，与header_handle二选一，否则无此项,示例媒体url建议小于1M，否则会超时。如果与header_handle同时存在时，以custom_header_handle_url为准
header_text array[string] 必须/无 当HEADER中 format=TEXT时为必须项，否则无此项
body_text array[array[string]] 必须/无 当BODY内容文本中配置了变量时为必须项，根据变量配置，数组中可能有1个或多个值。当BODY内容文本中未配置变量则无此项。
  • button object参数:
参数名 类型 是否必须 说明
type string 必须/无 按钮类型，包括QUICK_REPLY, URL , PHONE_NUMBER,COPY_CODE，FLOW .
1. QUICK_REPLY即快速回复按钮；
2. URL即行动号召url按钮;
3. PHONE_NUMBER即行动号召phone_number按钮;
4. COPY_CODE 复制优化码
5. FLOW
text string 必须 按钮的显示文字
url string 必须/无 行动号召按钮上配置的网址，仅type=URL时为必须项。如果是动态url，则需带上后缀变量{{1}}。
phone_number string 必须/无 行动号召按钮上配置的电话，仅type= PHONE_NUMBER时为必须项
example array[string] 必须/无 type=URL，且为动态url时为必须项，例如:https://www.baidu.com/user
type=COPY_CODE,为必填项，并且类型为String
otp_type string 必须/无 验证码按钮类型 固定值 ONE_TAP 或者 COPY_CODE ；ONE_TAP的含义是一键填充 COPY_CODE的含义是复制验证码
autofill_text string 必须/无 自动填充按钮文本，展示在按钮上的文案，仅otp_type = ONE_TAP 时为必须项
package_name string 必须/无 安卓包名，仅otp_type = ONE_TAP 时为必须项
signature_hash string 必须/无 应用hash，仅otp_type = ONE_TAP 时为必须项
flow_id string 必须/无 当type =Flow时有值, WhatsApp 提供的流程的唯一标识符。流程必须已发布
flow_action string 必须/无 当type =Flow时有值, navigate 或 data_exchange 默认：navigate
navigate_screen string 必须/无 当type =Flow时有值, 仅在 flow_action 为 navigate 时，此为必要项。流程的第一个屏幕的.

请求示例

  • 普通文本模板 body（application/json） 参数：
{
    "appkey": "8eoxxxos",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "name": "normal_text",
    "category": "MARKETING",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "text": "hello world"
        }
    ]
}
  • 丰富模板 body（application/json） 参数：
{
    "appkey": "8exxxos",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "name": "normal_text3",
    "category": "MARKETING",
    "language": "en_US",
    "components": [
        {
            "type": "HEADER",
            "format": "TEXT",
            "text": "ni{{1}}hao",
            "example": {
                "header_text": [
                    "AA"
                ]
            }
        },
        {
            "type": "BODY",
            "text": "hello{{1}}world{{2}}hahah",
            "example": {
                "body_text": [
                    [
                        "BB",
                        "CC"
                    ]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "I am footer"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "QUICK_REPLY",
                    "text": "I am QR1"
                },
                {
                    "type": "QUICK_REPLY",
                    "text": "I am QR2"
                }
            ]
        }
    ]
}
  • header带有媒体模板 body（application/json） 参数：
{
	"appkey": "8exxxos",
	"messaging_product": "whatsapp",
	"business_phone": "185xxx99",
	"name": "otp_1",
	"category": "MARKETING",
	"language": "en_US",
	"components": [{
			"type": "HEADER",
			"format": "IMAGE",
			"example": {
				"header_handle": "4:ZG93bl93YS5xxxg"
			}
		},
		{
			"type": "BODY",
			"text": "hello{{1}}world{{2}}hahah",
			"example": {
				"body_text": [
					[
                        "BB",
                        "CC"
                    ]
				]
			}
		},
		{
			"type": "FOOTER",
			"text": "I am footer"
		},
		{
			"type": "BUTTONS",
			"buttons": [{
					"type": "QUICK_REPLY",
					"text": "I am QR1"
				},
				{
					"type": "QUICK_REPLY",
					"text": "I am QR2"
				}
			]
		}
	]
}
  • 复制优化码
{
    "appkey": "8exxxs",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "category": "MARKETING",
    "name": "mkt_cpoy_code",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "text": "hello world"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                "type": "COPY_CODE",
                "example": "250FF"
                }
            ]
        }
    ]
}
  • Flow
{
    "appkey": "8exxxs",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "category": "MARKETING",
    "name": "mkt_flow",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "text": "hello world"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "FLOW",
                    "text": "Flow Demo",
                    "flow_id": "1090xxxxxx438317",
                    "flow_action": "navigate",
                    "navigate_screen": "WELCOME_SCREEN"
                }
            ]
        }
    ]
}
  • 简单MARKETING模板 body（application/json） 参数：
{
	"appkey": "8exxxs",
	"messaging_product": "whatsapp",
	"business_phone": "185xxx99",
	"name": "otp_test",
	"category": "MARKETING",
	"language": "en",
	"components": [
		{
			"type": "BODY",
			"text": "Your code is {{1}},  please do not share with others.",
			"example": {
				"body_text": [
					[
                        "10086"
                    ]
				]
			}
		}
	]
}
  • 身份验证-复制验证码
{
    "appkey": "8exxxs",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "category": "AUTHENTICATION",
    "name": "otp_test_01",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "add_security_recommendation": true
        },
        {
            "type": "FOOTER",
            "code_expiration_minutes": 5
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "COPY_CODE",
                    "text": "Copy Code"
                }
            ]
        }
    ]
}
  • 身份验证-一键自动填写
{
    "appkey": "8exxxs",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "category": "AUTHENTICATION",
    "name": "otp_test_02",
    "language": "zh_CN",
    "components": [
        {
            "type": "BODY",
            "add_security_recommendation": true
        },
        {
            "type": "FOOTER",
            "code_expiration_minutes": 5
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "ONE_TAP",
                    "text": "Copy Code2",
                    "autofill_text": "Autofill2",
                    "package_name": "com.example.myapplication",
                    "signature_hash": "K8a%2FAINcGX7"
                }
            ]
        }
    ]
}
  • 轮播模板示例，对应发送API中的轮播模板示例
{
    "appkey": "8exxxs",
    "messaging_product": "whatsapp",
    "business_phone": "185xxx99",
    "name": "carousel_template_media_cards_v1",
    "language": "en_US",
    "category": "marketing",
    "components": [
        {
            "type": "body",
            "text": "Rare succulents for sale! {{1}}, add these unique plants to your collection. Each of these rare succulents are {{2}} if you checkout using code {{3}}. Shop now and add some unique and beautiful plants to your collection!",
            "example": {
                "body_text": [
                    [
                        "Pablo",
                        "30%",
                        "30OFF"
                    ]
                ]
            }
        },
        {
            "type": "carousel",
            "cards": [
                {
                    "components": [
                        {
                            "type": "header",
                            "format": "image",
                            "example": {
                                "header_handle": [
                                    "4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
                                ]
                            }
                        },
                        {
                            "type": "body",
                            "text": "Add a touch of elegance to your collection with the beautiful Aloe 'Blue Elf' succulent. Its deep blue-green leaves have a hint of pink around the edges."
                        },
                        {
                            "type": "buttons",
                            "buttons": [
                                {
                                    "type": "quick_reply",
                                    "text": "Send me more like this!"
                                },
                                {
                                    "type": "url",
                                    "text": "Shop",
                                    "url": "https://www.luckyshrub.com/rare-succulents/{{1}}",
                                    "example": [
                                        "BLUE_ELF"
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "components": [
                        {
                            "type": "header",
                            "format": "image",
                            "example": {
                                "header_handle": [
                                    "4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
                                ]
                            }
                        },
                        {
                            "type": "body",
                            "text": "The Crassula Buddha's Temple is sure to be a conversation starter with its tiny temple shaped leaves, intricate details, and lacy texture."
                        },
                        {
                            "type": "buttons",
                            "buttons": [
                                {
                                    "type": "quick_reply",
                                    "text": "Send me more like this!"
                                },
                                {
                                    "type": "url",
                                    "text": "Shop",
                                    "url": "https://www.luckyshrub.com/rare-succulents{{1}}",
                                    "example": [
                                        "BUDDHA"
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "components": [
                        {
                            "type": "header",
                            "format": "image",
                            "example": {
                                "header_handle": [
                                    "4:bWtsLmpwZWc=:aW1hZ2UvanBlZw==:--_2A:e:1740735962::"
                                ]
                            }
                        },
                        {
                            "type": "body",
                            "text": "The Echeveria 'Black Prince' is a stunning succulent, with near-black leaves, adorned with a hint of green around the edges, giving it its striking appearance."
                        },
                        {
                            "type": "buttons",
                            "buttons": [
                                {
                                    "type": "quick_reply",
                                    "text": "Send me more like this!"
                                },
                                {
                                    "type": "url",
                                    "text": "Shop",
                                    "url": "https://www.luckyshrub.com/rare-succulents{{1}}",
                                    "example": [
                                        "BLACK_PRINCE"
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

响应参数

参数名 类型 说明
code Integer 结果编码
data JsonObject 请求结果
message String 请求结果说明
  • data JsonObject 参数：
参数名 类型 说明
id String 模板id
status String 一般为APPROVED，REJECTED，PENDING
审核状态枚举枚举值:
APPROVED: 使用中 IN_APPEAL: 已提出上诉
PENDING: 待处理 REJECTED: 已拒绝
PENDING_DELETION: 待删除 DELETED: 已删除
DISABLED: 不可用 PAUSED: 暂时停用 LIMIT_EXCEEDED: 超出限制
category String 枚举值：MARKETING,UTILITY,AUTHENTICATION

响应示例

成功示例

{
    "code": 0,
    "data": {
        "requestId": "d167cd24738d4e6094e0319f5a4073f7"
    },
    "message": "请求成功"
}

失败示例

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

webhook

成功回调

{
    "code": 0,
    "message": "请求成功",
    "data": {
        "id": "239686****38311",
        "status": "APPROVED",
        "category": "MARKETING"
    },
    "requestId": "d167cd24738d4e6094e0319f5a4073f7"
}

失败回调

{
    "code": -1,
    "message": "这种语言的内容已存在",
    "data": [],
    "requestId": "d167cd24738d4e6094e0319f5a4073f7"
}

响应码说明

code message 解决办法
0 请求成功
-1 请求失败 请联系技术人员排除问题
1000~100X 鉴权问题 详情查看API鉴权部分
9000 参数异常 参数遗漏，请检查必须的参数
9001 系统业务错误 请联系技术人员排除问题
9002 商户手机号错误 请确认商户号码是否属于whatsapp号码
9006 该whatsapp号码未绑定应用 请联系业务人员处理应用和手机号绑定操作

支持的模板语言

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