Skip to content

SAAS WhatsApp API webhook

Jump to bottom
张锦城 edited this page Jun 9, 2026 · 31 revisions

webhook

对提供的webhook地址，进行WhatsApp业务相关的推送信息（目前webhook支持推送状态回复、模板按钮点击回调）

  • URL：webhook_url
  • Method：POST
  • Content-Type：application/json

状态回复

对调用WhatsApp-API发送消息的场景，提供消息的回执情况

响应参数

body参数：

参数名 类型 说明
app_id String 应用ID
business_phone String 商户电话
channel Integer 通道类型，WhatsApp 固定值为 2
contacts array[contact Object] 联系人信息。状态回调中可能返回；用户采用匿名化后，手机号相关字段可能没有值。
merchant_phone String 商户电话
messaging_product String 消息类型，固定值”whatsapp“
metadata Object 商户号码元信息
statuses array[status Object] 状态对象
wabaId String WABA ID
  • metadata Object参数：
参数名 类型 说明
display_phone_number String 商户展示号码
phone_number_id String 商户号码ID
  • contact Object参数：
参数名 类型 说明
profile Object 用户信息，该字段不一定存在
wa_id String 用户的电话号码【用户采用匿名化后，该字段可能没有值】
user_id String 将设置为 WhatsApp 用户的 BSUID。未返回 BSUID 时，该字段可能省略。
parent_user_id String 如果您已启用父级 BSUID，此属性会被设为用户的父级 BSUID。否则，该属性会被完全省略。
  • profile Object参数：
参数名 类型 说明
name String 值将设为 WhatsApp 用户的显示名。
username String 如果用户已启用匿名化功能，将设置为 WhatsApp 用户的匿名账户。对于 sent 状态消息 Webhook 或用户未启用匿名化功能的情况，此属性将被完全省略。
  • status Object参数：
参数名 类型 说明
biz_opaque_callback_data String 发送消息时携带的追踪参数，该字段不一定存在
conversation Object 会话信息，failed 状态可能不返回
errors array[error Object] 错误信息，仅失败场景返回
id String 消息ID（发送消息时返回的ID）
meta_message_id String Meta 原始消息ID，该字段不一定存在；发送引用消息时可能用到该字段值，id 与 meta_message_id 并存时使用 meta_message_id 作为被引用的消息ID，否则使用 id
pricing Object 计费模式，failed 状态可能不返回
recipient_id String 用户的电话号码【用户采用匿名化后，该字段可能没有值】
recipient_user_id String 如果您将消息发送给用户的 BSUID 或父级 BSUID，此属性会被设为该用户的 BSUID 或父级 BSUID。否则，这会被省略。
parent_recipient_user_id String 如果您已启用父级 BSUID，此属性会被设为用户的父级 BSUID。否则，这会被完全省略。
timestamp String 回调时间戳
status String 消息的状态，sent（已发送），delivered（已送达)，read（已读），failed（发送失败），deleted（已删除）
costs array[cost Object] 费用信息，通常在 sent 状态返回
  • conversation Object参数：
参数名 类型 说明
id String 会话ID
expiration_timestamp String 会话过期时间戳，通常在 sent 状态返回
origin Object 会话类型信息
  • origin Object参数：
参数名 类型 说明
type String 会话类型，例如 utility（通知会话）、marketing（营销会话）、authentication（验证会话）、service（服务会话）、referral_conversion（免费会话）、marketing_lite（MM Lite API会话）
  • pricing Object参数：
参数名 类型 说明
billable boolean 指示给定消息或对话是否计费
category String 计费类别，例如 utility、marketing、authentication、service、referral_conversion、marketing_lite
pricing_model String 计费模型，例如 PMP、CBP
type String 计费类型，例如 regular、free_customer_service、free_entry_point
  • cost Object参数：
参数名 类型 说明
cdr_type Integer cdr类型，1（消息），4（营销会话），5（通知会话），6（验证会话），7（服务会话），8（免费会话），9（国际验证），10（MM Lite Api）
currency String 币种
direction Integer 方向，1（下行），2（上行）
foreign_price number 客户售价（客户币种费用）
message_id String WA 消息ID
price number 平台结算价格，该字段不一定存在
  • error Object参数：
参数名 类型 说明
code Integer 错误码
meta_code Integer Meta 错误码，该字段不一定存在
title String 错误信息

匿名化相关字段补充说明

当用户启用匿名化时，状态回调中的手机号字段可能不会返回：

  • recipient_id：用户的电话号码，匿名化后可能没有值。
  • contacts[].wa_id：用户的电话号码，匿名化后可能没有值。
  • recipient_user_id / contacts[].user_id：用户的 BSUID；如果发送时使用 BSUID 或父级 BSUID，回调会返回对应值。
  • parent_recipient_user_id / contacts[].parent_user_id：父级 BSUID；仅在启用父级 BSUID 时返回。
  • contacts[].profile.username：匿名账户；对于 sent 状态消息或用户未启用匿名化时会省略。

响应示例

消息已发送

{
  "app_id": "547",
  "business_phone": "62895303xxxx",
  "channel": 2,
  "contacts": [
    {
      "user_id": "US.36196856xxxx4656",
      "wa_id": "1859967xxxx"
    }
  ],
  "merchant_phone": "62895303xxxx",
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "62895303xxxx",
    "phone_number_id": "1034730xxxxx9406"
  },
  "statuses": [
    {
      "biz_opaque_callback_data": "NX_AI_SOURCE",
      "conversation": {
        "expiration_timestamp": "1780904196",
        "id": "3776abb4f63181b0ba423a556f6xxxx",
        "origin": {
          "type": "utility"
        }
      },
      "costs": [
        {
          "cdr_type": 5,
          "currency": "USD",
          "direction": 1,
          "foreign_price": 0.0000,
          "message_id": "wamid.HBgLMTg1OTk2Nzk3OTQVAgARGBI2RDd...",
          "price": 0.0000
        }
      ],
      "id": "NX_AI_SOURCE-1cfaf78ac39041d58e14d80fxxxx",
      "meta_message_id": "wamid.HBgLMTg1OTk2Nzk3OTQVAgARGBI2RDd...",
      "pricing": {
        "billable": true,
        "category": "utility",
        "pricing_model": "PMP",
        "type": "regular"
      },
      "recipient_id": "1859967xxxx",
      "recipient_user_id": "US.36196856xxxx4656",
      "status": "sent",
      "timestamp": "1780904196"
    }
  ],
  "wabaId": "1007605xxxxx6973"
}

消息已送达

{
  "app_id": "547",
  "business_phone": "62895303xxxx",
  "channel": 2,
  "contacts": [
    {
      "user_id": "DE.36196866xxxx4557",
      "wa_id": "4917766xxxx"
    }
  ],
  "merchant_phone": "62895303xxxx",
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "62895303xxxx",
    "phone_number_id": "1034730xxxxx9406"
  },
  "statuses": [
    {
      "biz_opaque_callback_data": "NX_AI_SOURCE",
      "conversation": {
        "id": "d826cad84c494a0922d709751dxxxx",
        "origin": {
          "type": "utility"
        }
      },
      "id": "NX_AI_SOURCE-0b67fa1a357a4193a6ce1d25xxxx",
      "meta_message_id": "wamid.HBgMNDkxNzc2Njk4NTM2FQIAERgSNkUw...",
      "pricing": {
        "billable": true,
        "category": "utility",
        "pricing_model": "PMP",
        "type": "regular"
      },
      "recipient_id": "4917766xxxx",
      "recipient_user_id": "DE.36196866xxxx4557",
      "status": "delivered",
      "timestamp": "1780904268"
    }
  ],
  "wabaId": "1007605xxxxx6973"
}

消息已读

{
  "app_id": "433",
  "business_phone": "9665356xxxx",
  "channel": 2,
  "contacts": [
    {
      "user_id": "SA.13082051xxxx8477",
      "wa_id": "9665984xxxx"
    }
  ],
  "merchant_phone": "9665356xxxx",
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "9665356xxxx",
    "phone_number_id": "2159038xxxxx0007"
  },
  "statuses": [
    {
      "biz_opaque_callback_data": "NX_AI_SOURCE",
      "conversation": {
        "id": "683b09b74d09aed49ad8b02ac4xxxx",
        "origin": {
          "type": "utility"
        }
      },
      "id": "NX_AI_SOURCE-7af1311983974721b8854d72xxxx",
      "meta_message_id": "wamid.HBgMOTY2NTk4NDk5NzUyFQIAERgSNUM0...",
      "pricing": {
        "billable": true,
        "category": "utility",
        "pricing_model": "PMP",
        "type": "regular"
      },
      "recipient_id": "9665984xxxx",
      "recipient_user_id": "SA.13082051xxxx8477",
      "status": "read",
      "timestamp": "1780904326"
    }
  ],
  "wabaId": "2574232xxxxx9503"
}

消息发送失败

{
  "app_id": "547",
  "business_phone": "62895303xxxx",
  "channel": 2,
  "contacts": [
    {
      "wa_id": "1775391xxxx"
    }
  ],
  "merchant_phone": "62895303xxxx",
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "62895303xxxx",
    "phone_number_id": "1034730xxxxx9406"
  },
  "statuses": [
    {
      "biz_opaque_callback_data": "NX_AI_SOURCE",
      "errors": [
        {
          "code": 131026,
          "title": "Message undeliverable"
        }
      ],
      "id": "NX_AI_SOURCE-c0c971b05dbc448b94ccb77dxxxx",
      "meta_message_id": "wamid.HBgLMTc3NTM5MTczNzgVAgARGBI0OEY...",
      "recipient_id": "1775391xxxx",
      "status": "failed",
      "timestamp": "1780904362"
    }
  ],
  "wabaId": "1007605xxxxx6973"
}

消息已删除

deleted 状态保留历史兼容格式，实际字段以回调返回为准。

{
  "statuses": [
    {
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "deleted",
      "timestamp": "TIMESTAMP",
      "type": "message",
      "message": {
        "recipient_id": "WHATSAPP_ID"
      }
    }
  ]
}

模板按钮点击回调

对调用WhatsApp-API发送模板消息的场景，提供点击按钮消息的回执情况（只支持模板中快速回调按钮点击的回调）

响应参数

body参数：

参数名 类型 说明
contacts array[contact JsonObject] 联系人信息
messages array[message JsonObject] 回调信息
business_phone String 商户电话
messaging_product String 消息类型，固定值”whatsapp“
  • contact object参数：
参数名 类型 说明
profile object 联系人信息
wa_id String wa id
  • profile object参数：
参数名 类型 说明
name String 姓名
  • message object参数：
参数名 类型 说明
button object 按钮信息
from String 收件人WhatsApp号码
id String 消息id
timestamp String 回调时间戳
type String 类型
wa_ext String 发送模板消息时参数、模板名称、模板id等信息
context object 仅当有人回复您的一条消息时，才会包含此对象。包含有关原始消息内容的信息，例如发送者的 ID 和消息的 ID
tag_name String 意向标签名称
  • button object参数：
参数名 类型 说明
payload String 按钮id
text String 按钮名称
  • context object参数：
参数名 类型 说明
from String 收件人号码
id String 仅当有人回复您的一条消息时包含有关原始消息的发送者的ID或者消息的ID

响应示例

{
    "business_phone":"1xxxxxxxxxx",
    "contacts":[
        {
            "profile":{
                "name":"姓名"
            },
            "wa_id":"861xxxxxxxxxx"
        }
    ],
    "messages":[
        {
            "button":{
                "payload":"按钮id",
                "text":"模板按钮名称"
            },
           "context":{
                        "from":"185xxxxxx99",
                        "id":"wamid.9ce86df19d7941c3965cac2a131a0b0e"
            },
            "from":"861xxxxxxxx59",
            "id":"wamid.HBgNODYxMzYwMzAxOTc1ORUCABIYFjNFQjA0NUJBNDczOTIzQUZBOUQ0OUEA",
            "timestamp":"1692266760",
            "type":"button",
            "tag_name":"意向标签名称",
            "wa_ext":"{\"templateId\":233,\"templateName\":\"模板名称\",\"components\":[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"xxxx\"},{\"type\":\"text\",\"text\":\"xxxx\"},{\"type\":\"text\",\"text\":\"xxxxx\"}]}]}"
        }
    ],
    "messaging_product":"whatsapp"
}

简介

短信

语音

云呼叫中心（NXLink）

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

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

NXLINK(HKG)

NXLINK(IDN)

NXLINK(CHL)

AI Agent

RCS

Clone this wiki locally