SAAS WhatsApp API webhook - nxtele/http-api-document GitHub Wiki

webhook

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

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

状态回复

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

响应参数

body参数：

参数名 类型 说明
statuses array[status JsonObject] 结果编码
business_phone String 商户电话
messaging_product String 消息类型，固定值”whatsapp“
  • status object参数：
参数名 类型 说明
conversation JsonObject 会话信息
errors array[error JsonObject] 错误信息
recipient_id String 收件人WhatsApp_id
timestamp String 回调时间戳
status String 消息的状态，sent（已发送），delivered（已送达)，read（已读），failed（发送失败），deleted（已删除）
id String 消息ID
  • conversation object参数：
参数名 类型 说明
id String 会话ID
expiration_timestamp String 会话过期时间戳
origin JsonObject 会话类型信息
  • origin object参数：
参数名 类型 说明
type String 会话类型
  • cost object参数:
参数名 类型 说明
currency String 币种
foreign_price number 客户售价（客户币种费用）
cdr_type Integer cdr类型， 1（消息），4（营销会话），5（通知会话），6（验证会话），7（服务会话），8（免费会话），9（国际验证），10（MM Lite Api）
message_id String wa消息id
direction Integer 方向，1（下行），2（上行）
  • error object参数：
参数名 类型 说明
code Integer 错误码
title String 错误信息

响应示例

消息已发送

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "sent",
      "timestamp": "1660019986",
      "recipient_id": "86176xxxx0819",
      "conversation": {
        "id": "72569257438b471cae074da84bed1b83",
        "expiration_timestamp": "1660106400",
        "origin": {
          "type": "business_initiated"
        }
      },
      "costs": [
        {
          "cdr_type": 5,
          "currency": "CNY",
          "direction": 1,
          "foreign_price": 0.1713
        }
      ]
    }
  ]
}

消息已送达

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "delivered",
      "timestamp": "1660019987",
      "recipient_id": "86176xxxx0819",
      "conversation": {
        "id": "72569257438b471cae074da84bed1b83",
        "origin": {
          "type": "business_initiated"
        }
      }
    }
  ]
}

消息已读

{
  "statuses": [
    {
      "id": "wamid.edcf691d49c04b939c8e3331f07f9cd1",
      "status": "read",
      "timestamp": "1660019990",
      "recipient_id": "86176xxxx0819"
    }
  ]
}

消息发送失败

{
  "statuses": [
    {
      "errors": [
        {
          "code": 470,
          "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
        }
      ],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
    }
  ]
}

消息已删除

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