getTemplateById

根据模板ID查询单个模板

通过 API 根据模板 ID 查询 WhatsApp 应用下单个模板详情。

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

鉴权机制

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

请求参数

header参数：

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	牛信云WhatsApp应用的appkey
business_phone	String	是	xxx	商户的WhatsApp号码，需要带国码
messaging_product	String	是	whatsapp	发送消息通道，值必须为“whatsapp”
bid_spec	Integer	否	1	如需返回竞价消息配置可传 1 【针对竞价消息模板】
template_id	String	是	1723376129022277	模板ID

请求示例

body（application/json）参数：

{
  "appkey": "xxx",
  "business_phone": "xxx",
  "messaging_product": "whatsapp",
  "template_id": "1723376129022277"
}

响应参数

参数名	类型	说明
code	Integer	结果编码
data	JsonObject	请求结果
message	String	请求结果说明

• data JsonObject参数：

参数名	类型	说明
id	string	模板ID
category	string	模板类型
language	string	模板语言
name	string	模板名称
status	string	审核状态
rejected_reason	string	拒绝原因
quality_score	object	模板质量
components	array[component object]	模板组件
parameter_format	string	变量类型：POSITIONAL（数字）/NAMED（名称）
bid_spec	object	竞价消息配置（仅在传入 bid_spec=1 且模板支持时返回）

• quality_score object参数：

参数名	类型	说明
score	string	模板质量枚举：GREEN（高）、YELLOW（中）、RED（低）、UNKNOWN（待定）
date	number	质量评分更新时间戳

• component object参数：

参数名	类型	说明
type	string	组件类型：HEADER、BODY、FOOTER、BUTTONS
format	string	仅 type=HEADER 时存在，可为 TEXT、DOCUMENT、IMAGE、VIDEO
text	string	文本内容（HEADER/BODY/FOOTER）
example	object	变量示例或媒体示例
buttons	array[button object]	仅 type=BUTTONS 时存在

• example object参数:

参数名	类型	说明
header_handle	string	头部媒体资源链接
custom_header_handle_url	string	自定义头部媒体资源链接，当创建/编辑时选择custom_header_handle_url 有值
header_text	array[string]	头部文本变量示例，数组中仅有1个值
body_text	array[array[string]]	内容文本变量示例，根据模板BODY的内容配置，数组中可能有1个或多个值

• 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时有此项
phone_number	string	行动号召按钮上配置的电话，仅type= PHONE_NUMBER时有此项
example	array[string]	示例的URL,例如:https://www.baidu.com/user
flow_id	string	当type =Flow时有值, WhatsApp 提供的流程的唯一标识符。流程必须已发布
flow_action	string	当type =Flow时有值, navigate 或 data_exchange 默认：navigate
navigate_screen	string	当type =Flow时有值, 仅在 flow_action 为 navigate 时，此为必要项。流程的第一个屏幕的.

• bid_spec object参数:

参数名	类型	是否必须	说明
bid_amount	Integer	必须	每 1,000 次消息送达的最高价格
bid_strategy	string	必须	固定值LOWEST_COST_WITH_BID_CAP

响应示例

成功示例

{
  "code": 0,
  "data": {
    "components": [
      {
        "format": "IMAGE",
        "type": "HEADER",
        "example": {
          "header_handle": [
            "https://scontent.whatsapp.xxx"
          ]
        }
      },
      {
        "text": "Hola",
        "type": "BODY"
      },
      {
        "buttons": [
          {
            "text": "Si quiero",
            "type": "QUICK_REPLY"
          },
          {
            "text": "No, gracias",
            "type": "QUICK_REPLY"
          },
          {
            "text": "Más información",
            "type": "QUICK_REPLY"
          }
        ],
        "type": "BUTTONS"
      }
    ],
    "rejected_reason": "NONE",
    "parameter_format": "POSITIONAL",
    "quality_score": {
      "date": 1779937958,
      "score": "UNKNOWN"
    },
    "name": "image_url_test",
    "language": "es_MX",
    "id": "1723376129022277",
    "category": "MARKETING",
    "status": "PENDING"
  },
  "message": "success"
}

失败示例

模板id错误或者已被删除

{
    "code": 0,
    "data": {
        "error": {
            "code": 100,
            "error_subcode": 33,
            "message": "Unsupported get request. Object with ID '1723376129022207' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api",
            "type": "GraphMethodException",
            "fbtrace_id": "A3UJLYUvR4j16Z0GaW_c6ry"
        }
    },
    "message": "success"
}

其他异常

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

响应码说明

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

对接注意事项

1. template_id 为必填，不能为空。
2. 如果要返回竞价消息配置，需传入 bid_spec=1。
3. 建议业务成功判定：code == 0 且 data.error 不存在。