Skip to main content

WhatsApp Webhooks

Agent Skill

Automate this endpoint with an AI agent using the 2chat-whatsapp skill:

npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp

In here you can see what a WhatsApp webhook event has as payload.

New Message Received​

The field sent_by will have the value user, and if the sender is part of your contacts, you will also find a contact field inside the payload.

The value of remote_phone_number is the phone number of the user that sent you the message.

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2023-04-18T22:17:50Z",
   "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "media":{
         "url":"https://2chat-user-data.s3.amazonaws.com/ACC28526e8e-ac01-4b1f-ac11-939f2b7fca73/example.jpeg",
         "type":"image",
         "mime_type":"image/jpeg"
      }
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number": "+595981445566",
   "sent_by":"user",
   "contact":{
      "first_name":"Johny",
      "last_name":"Doe",
      "profile_pic_url":"https://2chat-user-data.s3.amazonaws.com/example-profile-pic.jpeg"
   }
}

New Order Received​

Inside the message field, you will find an object containing the order details.

{
    "id": "MSGa13150ca-13e5-4c0a-b979-f45980830c10",
    "uuid": "MSGa13150ca-13e5-4c0a-b979-f45980830c10",
    "session_key": "WW-WPN66037eca-9ad1-4c96-9eff-526a90a48c77-5215533334444@c.us",
    "message": {
        "text": "ADIDAS | CLASSIC BACKPACK | LEGEND INK MULTICOLOUR Regular, NIKE | SWOOSH PRO FLAT PEAK CAP Regular",
        "order": {
            "subtotal": 0,
            "total": 0,
            "currency": null,
            "created_at": 1710021608,
            "products": [
                {
                    "id": "6562709013816345",
                    "name": "ADIDAS | CLASSIC BACKPACK | LEGEND INK MULTICOLOUR Regular",
                    "price": 150.5,
                    "currency": "USD",
                    "quantity": 1,
                    "data": null,
                    "thumbnail_url": "https://2chat-user-data-dev.s3.amazonaws.com/order/product/6562709013816345.jpeg"
                },
                {
                    "id": "7096834393683427",
                    "name": "NIKE | SWOOSH PRO FLAT PEAK CAP Regular",
                    "price": 210.0,
                    "currency": "USD",
                    "quantity": 1,
                    "data": null,
                    "thumbnail_url": "https://2chat-user-data-dev.s3.amazonaws.com/order/product/7096834393683427.jpeg"
                }
            ]
        }
    },
    "created_at": "2024-03-09T22:00:08",
    "remote_phone_number": "+5215533334444",
    "channel_phone_number": "+595981445566",
    "sent_by": "user",
    "contact": {
        "first_name": null,
        "last_name": null,
        "profile_pic_url": null
    }
}

New Message Sent​

The field sent_by will have the value agent.

The value of remote_phone_number is the phone number of the user you sent the message to.

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2023-04-18T22:17:50Z",
   "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "text": "this is the text content of the message"
   },
   "remote_phone_number":"+5215533334444",
   "sent_by":"agent",
}

Message Read​

{
   "event": "message.read",
   "message_uuid": "MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "channel_uuid": "WPN1045d068-6c42-4157-8325-41e3c5710dc6",
   "timestamp":"2024-04-18T22:17:50Z",
}

WhatsApp Number Status Change​

QR code received​

{
   "event": "qr-received",
   "channel_uuid": "WPN1045d068-6c42-4157-8325-41e3c5710dc6",
   "timestamp":"2024-07-05T19:36:46.523497+00:00Z",
   "payload": {
        "qr": "value-to-represent-as-qr-code" }
   }
}

Number disconnected​

{
  "event": "disconnected",
  "channel_uuid": "WPN1045d068-6c42-4157-8325-41e3c5710dc6",
  "timestamp": "2025-11-11T11:27:45.860587+00:00Z",
  "payload": {
    "reason": "LOGOUT"
  }
}

WhatsApp Conversion Tracking​

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2023-04-18T22:17:50Z",
   "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "text": "hello!",
      "context":  {
         "conversionSource": "FB_Ads",
         "conversionData": {},
         "sourceUrl": "https://fb.me/....",
         "description": "example description used in the advert",
         "title": "Example title.",
      }
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number": "+595981445566",
   "sent_by":"user",
   "contact":{
      "first_name":"Johny",
      "last_name":"Doe",
      "profile_pic_url":"https://2chat-user-data.s3.amazonaws.com/example-profile-pic.jpeg"
   }
}

WhatsApp Reply with a Quoted Message​

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2024-10-18T22:17:50Z",
   "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "text": "hello! I'm quoting your image",
      "quoted_msg":  {
         "id": "MSG5ccf419e-adb9-407e-b222-d968105679a5",
         "uuid": "MSG5ccf419e-adb9-407e-b222-d968105679a5",
         "created_at":"2024-10-18T22:10:02Z",
         "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
         "message":{
            "text": "this is a simple image with a caption",
            "media":{
               "url":"https://2chat-user-data.s3.amazonaws.com/ACC28526e8e-ac01-4b1f-ac11-939f2b7fca73/example.jpeg",
               "type":"image",
               "mime_type":"image/jpeg"
            }
         },
         "remote_phone_number": "+5215533334444",
         "channel_phone_number": "+595981445566",
         "sent_by": "user"
      }
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number": "+595981445566",
   "sent_by": "agent",
   "contact": {
      "first_name": "Johny",
      "last_name": "Doe",
      "profile_pic_url": "https://2chat-user-data.s3.amazonaws.com/example-profile-pic.jpeg"
   }
}

WhatsApp Reply with a Quoted Message We Could Not Resolve​

Replies are also delivered on WhatsApp Business API (WABA) channels. There, WhatsApp only tells us which message was quoted, not what it said, so we look it up on our side. When we cannot find it — most often a message that was just sent and has not been acknowledged by WhatsApp yet — quoted_msg carries the identifiers instead of the message, so you can still match it against a message you sent:

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2026-09-09T22:17:50Z",
   "session_key":"WA-WAN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "text": "Ok",
      "quoted_msg": {
         "wa_msg_id": "A54F87036BB4375065005BC986ED6F54",
         "wamid": "wamid.HBgTUFkuMTk1NzY0MTI3NTExNjE0NBUUABEYIEE1NEY4NzAzNkJCNDM3NTA2NTAwNUJDOTg2RUQ2RjU0AA==",
         "quoted_my_message": true
      }
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number": "+595981445566",
   "sent_by": "user"
}

quoted_my_message is true when the contact replied to a message you sent, and false when they replied to one of their own.

WhatsApp Product Enquiry​

Sent when the contact writes to you from a product's page in your catalog. It is a question about a product, not a purchase: there is no cart and no order object. name and thumbnail_url are resolved from your catalog when we can read it, and name falls back to the retailer id otherwise.

{
   "id":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "uuid":"MSGcf20bbdb-0a8a-4eef-bca1-aa2ea22c5294",
   "created_at":"2026-09-09T22:17:50Z",
   "session_key":"WA-WAN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "message":{
      "text": "Do you have this one in blue?",
      "referred_product": {
         "catalog_id": "1063878672684162",
         "product_retailer_id": "m2mcfj7cmf",
         "name": "Backpack 20L",
         "thumbnail_url": "https://scontent.xx.fbcdn.net/v/example.jpg"
      }
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number": "+595981445566",
   "sent_by": "user"
}

WhatsApp Message Reaction​

{
   "reaction":"💯",
   "message":{
      "_2chat_link":"https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
      "created_at":"2025-02-11T16:26:10",
      "id":"MSGf45f4173-46dd-43a2-bd62-0d7c6ec0ba98",
      "message":{
         "media":{
            "mime_type":"image/png",
            "type":"image",
            "url":"https://2chat-user-data.s3.amazonaws.com/ACC28526e8e-ac01-4b1f-ac11-939f2b7fca73/example.jpeg"
         },
         "text":"Test from 2Chat API with image"
      },
      "read":false,
      "received":false,
      "remote_phone_number":"+5215533334444",
      "channel_phone_number":"+595981445566",
      "sent":true,
      "sent_by":"api",
      "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
      "uuid":"MSGf45f4173-46dd-43a2-bd62-0d7c6ec0ba98"
   }
}

WhatsApp Message Edited​

{
   "_2chat_link":"https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "contact":{
      "device":"android",
      "first_name":"Johny",
      "friendly_name":"Hoho",
      "last_name":"Doe",
      "profile_pic_url":null
   },
   "created_at":"2025-03-04T19:58:54",
   "edited_at":"2025-03-04T13:59:13Z",
   "id":"MSG4cde2029-aac3-4316-81f5-a7e24ac31a56",
   "message":{
      "old_text":"The original message",
      "text":"The edited message"
   },
   "remote_phone_number":"+5215533334444",
   "channel_phone_number":"+595981445566",
   "sent_by":"user",
   "session_key":"WW-WPN1045d068-6c42-4157-8325-41e3c5710dc6-5215533334444@c.us",
   "uuid":"MSG4cde2029-aac3-4316-81f5-a7e24ac31a56"
}

WhatsApp Call Received​

info

WhatsApp doesn't inform about the duration of the call.

{
   "event": "whatsapp.call.received",
   "id": "MSGd5b02306-41b6-468d-838a-8bb45407aba1",
   "uuid": "MSGd5b02306-41b6-468d-838a-8bb45407aba1",
   "session_key": "WW-WPN66037eca-9ad1-4c96-9eff-526a90a48c77-5215533334444@c.us",
   "created_at": "2025-12-09T05:07:41",
   "remote_phone_number": "+5215533334444",
   "_2chat_link": "https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WW-WPN66037eca-9ad1-4c96-9eff-526a90a48c77-5215533334444@c.us",
   "channel_phone_number": "+595981461442",
   "channel": {
      "id": "WPN66037eca-9ad1-4c96-9eff-526a90a48c77",
      "uuid": "WPN66037eca-9ad1-4c96-9eff-526a90a48c77",
      "friendly_name": "2Chat PY",
      "phone_number": "+595981461442",
      "iso_country_code": "PY",
      "pushname": "Carlos de 2Chat",
      "server": "595981461442@c.us",
      "platform": "iphone",
      "connection_status": "C",
      "enabled": true,
      "is_business_profile": true,
      "channel_type": "WW",
      "sync_contacts": true,
      "timezone": "America/Asuncion",
      "lang": "es",
      "created_at": "2023-02-15T19:15:17Z",
      "updated_at": "2025-12-09T05:05:23Z",
      "timezone_phone_number": "America/Asuncion"
   },
   "from_number": "+5215533334444",
   "contact": {
      "uuid": "CON46313bb0-e148-42c2-bb1c-55e8b90187ef",
      "first_name": "Jessie",
      "last_name": "Smith",
      "name": "Jessie Smith",
      "channel_uuid": null,
      "profile_pic_url": "https://2chat-user-data-dev.s3.amazonaws.com/ACC91be87af-5a29-4034-b599-342f2aeb5d52/pp/contacts/123123.jpeg",
      "last_updated": "2025-11-11T02:42:55Z"
   }
}

WhatsApp Call Made​

info

WhatsApp doesn't inform about the duration of the call.

{
  "event": "whatsapp.call.made",
  "channel": {
    "id": "WPN66037eca-9ad1-4c96-9eff-526a90a48c77",
    "uuid": "WPN66037eca-9ad1-4c96-9eff-526a90a48c77",
    "friendly_name": "My number",
    "phone_number": "+595981445566",
    "iso_country_code": "PY",
    "pushname": "My number",
    "server": "595981445566@c.us",
    "platform": "iphone",
    "connection_status": "C",
    "enabled": true,
    "is_business_profile": true,
    "channel_type": "WW",
    "sync_contacts": true,
    "timezone": "America/Asuncion",
    "lang": "es",
    "created_at": "2023-02-15T19:15:17Z",
    "updated_at": "2025-10-29T00:28:49Z",
    "timezone_phone_number": "America/Asuncion"
  },
  "to_number": "+525522334455",
  "contact": {
    "uuid": "CON66f23c6f-ce12-40fa-b31d-68855cfea440",
    "first_name": "Jessie",
    "last_name": "Smith",
    "name": "Jessie Smith",
    "last_updated": "2025-09-29T16:37:20Z"
  }
}