Skip to content

WhatsApp API Webhook

Jump to bottom
CodingMakeWordBetter edited this page Jun 14, 2023 · 26 revisions

Webhook

To the provided webhook address, push information related to WhatsApp business（currently webhook supports push status reply,message reply）

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

status reply

For the scenario of calling WhatsApp-API to send a message, provide the receipt of the message

Response parameters

body parameter：

parameter type illustrate
statuses array[status JsonObject] result encoding
business_phone String Merchant Phone
messaging_product String Message type, fixed value "whatsapp"
  • status object parameter：
parameter type illustrate
conversation JsonObject session information
errors array[error JsonObject] error message
recipient_id String recipient WhatsApp_id
timestamp String callback timestamp
status String The status of the message，sent，delivered，read，failed，deleted
id String message id
  • conversation object parameter：
parameter type illustrate
id String session id
expiration_timestamp String session expiration timestamp
origin JsonObject session type information
  • origin object parameter：
parameter type illustrate
type String session type 
"marketing": "(Effective from 2023-06-01) Merchants initiate conversations using message templates categorized as MARKETING", corresponding to direction=4 (marketing).
"utility": "(Effective from 2023-06-01) Merchants initiate conversations using message templates categorized as UTILITY", corresponding to direction=5 (notification).
"authentication": "(Effective from 2023-06-01) Merchants initiate conversations using message templates categorized as AUTHENTICATION", corresponding to direction=6 (verification).
"service": "(Effective from 2023-06-01) Users initiate conversations", corresponding to direction=7 (service).
"referral_conversion": "(Effective from 2023-06-01) (Free) Users initiate conversations by clicking on WhatsApp ads or Facebook Page call-to-action buttons", corresponding to direction=8 (free session).
  • error object parameter：
parameter type illustrate
code Integer error code
title String error message
  • Cost object parameters:
Parameter Name Type Description
currency String Currency
price number Customer price (in local currency CNY)
foreign_price number Customer price (in foreign currency)
cdr_type Integer CDR type. Starting from June 1, 2023, the following five types are used: 4 (marketing), 5 (notification), 6 (verification), 7 (service), 8 (free session). Types 1 (message), 2 (merchant session), and 3 (user session) will be deprecated.
message_id String WhatsApp message ID
direction Integer Direction: 1 (outgoing), 2 (incoming)

Response example

message sent

{
    "statuses":[
        {
            "id":"wamid.HBgNODYxNzYwNjA1MDgxORUCABEYEjI4RTcyNzFGRDVGQTQwQkQ1RAA=",
            "status":"sent",
            "timestamp":"1660019986",
            "recipient_id":"86176xxxx0819",
            "conversation":{
                "id":"72569257438b471cae074da84bed1b83",
                "expiration_timestamp":"1660106400",
                "origin":{
                    "type":"authentication"
                }
            },
            "costs":[
                {
                    "currency":"USD",
                    "price":0,
                    "foreign_price":0,
                    "cdr_type":4,
                    "message_id":"wamid.HBgNNjI4MTI4MTM3NTYwNBUCABEYEkMzODdBNTEzMTAxNDhFMEI5NQA=",
                    "direction":1
                },
                {
                    "currency":"USD",
                    "price":0.1381,
                    "foreign_price":0.02,
                    "cdr_type":4,
                    "message_id":"wamid.HBgNNjI4MTI4MTM3NTYwNBUCABEYEkMzODdBNTEzMTAxNDhFMEI5NQA=",
                    "direction":1
                }
            ]
        }
    ]
}

message delivered

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

message read

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

Failed to send message

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

message deleted

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

message reply

For scenarios where WhatsApp users send messages to merchant numbers, provide the push status of inbound messages

Response parameters

body parameters：

parameter type illustrate
contacts array[contact JsonObject] Provide contact information
messages array[message JsonObject] Inbound message
business_phone String Merchant Phone
messaging_product String Message type, fixed value "whatsapp"
  • contact object parameter：
parameter type illustrate
profile JsonObject Profile object
wa_id String WhatsApp ID of the contact
  • profile object parameter：
parameter type illustrate
name String Sender's profile name
  • message object parameter：
parameter type illustrate
from String Sender's WhatsApp ID
id String Message ID, this ID can be used to mark the message as read
timestamp String message receipt timestamp
type String Supported message types
1. text
2. image
3. video
4. voice
5. audio
6. document
7. location
8. sticker
cost JsonObject Cost information
  • Cost object parameters:
Parameter Name Type Description
currency String Currency
price number Customer price (in local currency CNY)
foreign_price number Customer price (in foreign currency)
cdr_type Integer CDR type. Starting from June 1, 2023, the following five types are used: 4 (marketing), 5 (notification), 6 (verification), 7 (service), 8 (free session). Types 1 (message), 2 (merchant session), and 3 (user session) will be deprecated.
message_id String WhatsApp message ID
direction Integer Direction: 1 (outgoing), 2 (incoming)
  • message type
  1. Text message parameters:
parameter type illustrate
text JsonObject Refer to the response example text message content, there is a value when type=text
  • text object parameter：
parameter type illustrate
body String message text
  1. Picture message parameters：
parameter type illustrate
image JsonObject Refer to the response example image message content, there is a value when type=image
  • image object parameter：
parameter type illustrate
id String The id of the media store, which can be used to get the media link
caption String Description of the picture
mime_type String MiME type of the media file
sha256 String Verification signature of media files
  1. Video message parameters：
parameter type illustrate
video JsonObject Refer to the response example video message content, there is a value when type=video
  • video object参数：
parameter type illustrate
id String The id of the media store, which can be used to get the media link
caption String Description of the video
mime_type String MiME type of the media file
sha256 String Verification signature of media files
  1. Voice message parameters：
parameter type illustrate
voice JsonObject Refer to the response exampleVoice message content, there is a value when type=voice
  • voice object parameter：
parameter type illustrate
id String The id of the media store, which can be used to get the media link
mime_type String MiME type of the media file
sha256 String Verification signature of media files
  1. Audio message parameters:
parameter type illustrate
audio JsonObject Refer to the response example Audio message content, there is a value when type=audio
  • audio object parameters：
parameter type illustrate
id String The id of the media store, which can be used to get the media link
mime_type String MiME type of the media file
sha256 String Verification signature of media files
  1. Document message parameters：
parameter type illustrate
document JsonObject Refer to the response example document message content, there is a value when type=document
  • document object参数：
parameter type illustrate
id String The id of the media store, which can be used to get the media link
mime_type String MiME type of the media file
sha256 String Verification signature of media files
filename String document file name
  1. Location message parameters：
parameter type illustrate
location JsonObject Refer to the response example Location message content, there is a value when type=location
  • location object parameters：
parameter type illustrate
longitude String Longitude information of the location
latitude String Location dimension information
name String the name of the location
address String Location details
  1. Sticker emoticon message parameters：
parameter type illustrate
sticker JsonObject Refer to the response example for the content of the sticker emoticon message, which has a value when type=sticker
  • sticker object parameter ：
parameter type illustrate
id String The id of the media store, which can be used to get the media link

Response example

Example of a text message response

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
      "text": {
        "body": "你好"
      },
      "timestamp": "1663053831",
      "type": "text"
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Image message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQk5kC-xMSoi3XpEwoF2ZkIg",
      "image": {
        "id": "2bc7102f-5491-40b1-a92f-338303eab9d3",
        "mime_type": "image/jpeg",
        "sha256": "0ed3d9d4db83ed7751314af5f2e9bf008edc49a101bebb9054a97f824cf2136b"
      },
      "timestamp": "1663053029",
      "type": "image"
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Video message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQysyxXFholwoQ-lCwUTTWfw",
      "timestamp": "1663054466",
      "type": "video",
      "video": {
        "id": "bfc0619d-995e-49da-9869-e911a34c43b9",
        "mime_type": "video/mp4",
        "sha256": "e0ceec95f44fec6282ab02f947ee92dbe481dacf0478618a997580a822acc88b"
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Voice message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQyrJn0a5IBKlmHZqf_uAuFw",
      "timestamp": "1663055136",
      "type": "voice",
      "voice": {
        "id": "25fdf335-d846-4e6c-9aa8-35f25abc564c",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "f321ac774459c50e376048d6f2c02fc2c14f13be85c5e52a67ec16a358b34de7"
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Audio message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "audio": {
        "id": "aab95384-fc19-4136-a330-97e1f8a4cb02",
        "mime_type": "audio/mpeg",
        "sha256": "9a73ab6362694fba48a5027c8443ceb34838009601ce480d85f08c600cf520f1"
      },
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQdSLi6R7UCDSsCqNkjrtczg",
      "timestamp": "1663053098",
      "type": "audio"
    }
  ],
  "merchant_phone": "86176xxxx819",
  "messaging_product": "whatsapp"
}

Documentation message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "document": {
        "caption": "null.txt",
        "filename": "null.txt",
        "id": "806bb2f3-d8cc-4477-8b4d-d89df862f6c0",
        "mime_type": "text/plain",
        "sha256": "90c7bd7c509aa1d68c09a67b9ba2d17022a6861681fbd75c8845ee48193e8646"
      },
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQGvyQjDNptdnjvjN0dkD90Q",
      "timestamp": "1663052759",
      "type": "document"
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Location message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQO8HTCPOtJUZLNLRo2dPufw",
      "location": {
        "address": "深圳市, 广东",
        "latitude": 22.550802897696343,
        "longitude": 113.93844723701477,
        "name": "KFC (肯德基)",
        "url": "http://www.kfc.com.cn"
      },
      "timestamp": "1663053163",
      "type": "location"
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Sticker emoticon message response example

{
  "contacts": [
    {
      "profile": {
        "name": "Jay"
      },
      "wa_id": "86176xxxx0819"
    }
  ],
  "messages": [
    {
      "from": "86176xxxx0819",
      "id": "ABGHhhdgYFCBnwIQ1kuKFSU5LfuDxSUPOjKIwA",
      "sticker": {
        "id": "1b0a4c77-c5e7-44fa-b2a3-b69941ed3c64",
        "metadata": {
          "emojis": [
            "☕",
            "🙂"
          ],
          "is-first-party-sticker": 1,
          "sticker-pack-id": "whatsappcuppy"
        },
        "mime_type": "image/webp",
        "sha256": "98267fedaeac67a4cc6b5e18a2444249fba5b6363a690115139675d53a63b0ff"
      },
      "timestamp": "1663054803",
      "type": "sticker"
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

Introduction

WhatsApp

Short message

Voice

Call Center(NXLink)

Call Center(Callbot)

Flash Call

Short links

邮件验证码

DID号码

通用

号码检测

Clone this wiki locally