WABA Webhooks

Agent Skill

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

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

In here you can see what a WhatsApp Business API (WABA) webhook event has as payload.

Message Sent

Triggers when a new WhatsApp message is sent.

The sent_by field will be api when the message was sent via the API, or agent when sent through the 2Chat interface.

The to_number field is the phone number of the recipient.

{
  "id": "MSG42c01a92-ace3-4de3-a5e9-2fbbf8b22d25",
  "uuid": "MSG42c01a92-ace3-4de3-a5e9-2fbbf8b22d25",
  "session_key": "WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "message": {
    "text": "Hola Carlos desde API"
  },
  "created_at": "2026-02-18T18:01:35",
  "remote_phone_number": "+595986541230",
  "_2chat_link": "https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "channel_phone_number": "+16173518454",
  "sent_by": "api",
  "event": "whatsapp.waba.message.sent",
  "channel": {
    "uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
    "friendly_name": "2Chat Gupshup Integration",
    "iso_country_code": "US",
    "verified_name": "APPROVED",
    "phone_number": "+16173518454",
    "connection_status": "C",
    "created_at": "2025-11-19 23:04:18",
    "updated_at": "2026-02-02 19:41:12"
  },
  "to_number": "+595986541230",
  "contact": {
    "uuid": "CONc1f24408-ad5b-4168-89d1-3a258f784fbe",
    "first_name": "Carlos",
    "last_name": "Gimenez",
    "name": "Carlos Gimenez",
    "channel_uuid": null,
    "profile_pic_url": "https://2chat-user-data.s3.amazonaws.com/ACC91be87af-5a29-4034-b599-342f2aeb5d52/pp/contacts/example.jpeg",
    "last_updated": "2026-01-05T13:03:43Z"
  }
}

Message Received

Triggers when a new WhatsApp message is received on your WABA number.

The sent_by field will be user because the message originates from the contact, and remote_phone_number is the phone number of the person who sent you the message.

{
  "id": "MSG1e265247-8c72-5020-98ac-9bbdf562ad36",
  "uuid": "MSG1e265247-8c72-5020-98ac-9bbdf562ad36",
  "session_key": "WA-WAN7c43ea2d-f225-45d2-bda9-60f4746f1572-14085550176",
  "message": {
    "text": "Hello"
  },
  "created_at": "2026-07-28T19:25:23",
  "remote_phone_number": "+14085550176",
  "_2chat_link": "https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WA-WAN7c43ea2d-f225-45d2-bda9-60f4746f1572-14085550176",
  "channel_phone_number": "+13024855297",
  "sent_by": "user",
  "contact": {
    "first_name": null,
    "last_name": null,
    "profile_pic_url": null,
    "friendly_name": "Carlos",
    "device": null
  }
}

Quick Reply

Triggers when a contact responds by tapping a quick reply button.

The message.quick_reply field is true to indicate the incoming message came from a quick reply button rather than free-form text, and message.text holds the label of the button the contact selected. The sent_by field is user because the message originates from the contact.

{
  "id": "MSG7b3e9a41-2c8d-4f6a-b1e0-9d4c5a2f83b1",
  "uuid": "MSG7b3e9a41-2c8d-4f6a-b1e0-9d4c5a2f83b1",
  "session_key": "WA-WAN8f21cc03-5d7a-4e19-bb62-1a3f9e0d7c48-14085550176",
  "message": {
    "text": "I want to learn more",
    "quick_reply": true
  },
  "created_at": "2026-07-02T13:22:03",
  "remote_phone_number": "+14085550176",
  "_2chat_link": "https://app.2chat.io/live-chat/STE3a9f1c47-8b2e-4d61-9f03-6c5a4e21d8b7/WA-WAN8f21cc03-5d7a-4e19-bb62-1a3f9e0d7c48-14085550176",
  "channel_phone_number": "+16195550143",
  "sent_by": "user",
  "contact": {
    "first_name": null,
    "last_name": null,
    "profile_pic_url": null,
    "friendly_name": "Carlos",
    "device": null
  }
}

Message Receipt Sent

Triggers when a message you sent has been transmitted to the WhatsApp network and is on its way to the recipient.

{
  "id": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb",
  "uuid": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb",
  "session_key": "WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "message": {
    "text": "Hi Juan. We are writing you to ask you if you received our package with track-id 1. Please confirm."
  },
  "created_at": "2026-02-18T17:34:17",
  "remote_phone_number": "+595986541230",
  "_2chat_link": "https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "channel_phone_number": "+16173518454",
  "sent_by": "agent",
  "sent": true,
  "received": false,
  "read": false,
  "event": "whatsapp.waba.message.receipt.sent",
  "channel_uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
  "message_uuid": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb"
}

Message Receipt Received

Triggers when a message you sent is received on the app of its intended receiver.

{
  "id": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb",
  "uuid": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb",
  "session_key": "WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "message": {
    "text": "Hi Juan. We are writing you to ask you if you received our package with track-id 1. Please confirm."
  },
  "created_at": "2026-02-18T17:34:17",
  "remote_phone_number": "+595986541230",
  "_2chat_link": "https://app.2chat.io/live-chat/STEc5ca017c-6e16-4e1a-9960-c180b1f51682/WA-WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7-595986541230",
  "channel_phone_number": "+16173518454",
  "sent_by": "agent",
  "sent": true,
  "received": true,
  "read": false,
  "event": "whatsapp.waba.message.receipt.received",
  "channel_uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
  "message_uuid": "MSG68e4fc6c-6a81-43aa-967e-4a71f11234eb"
}

Template Created

Triggers when a new message template is submitted to WhatsApp through 2Chat — via Create WABA Template or from the web app. The creator already gets the result in the HTTP response; this event is for every other subscriber.

status is the initial status: usually PENDING, though some AUTHENTICATION templates are approved on the spot.

{
  "event": "whatsapp.waba.template.created",
  "channel_uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
  "timestamp": "2026-02-18T17:31:02.114000Z",
  "payload": {
    "template_uuid": "TMP1b44a079-c75c-4403-bc8f-a75c4ce5cd23",
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "status": "PENDING",
    "previous_status": null,
    "rejection_reason": null
  }
}

Template Status Updated

Triggers when WhatsApp finishes reviewing a message template, or changes its status afterwards (for example pausing a template with poor feedback). Only APPROVED templates can be sent.

Use template_uuid directly as the template_uuid of Send WABA Message.

{
  "event": "whatsapp.waba.template.status.updated",
  "channel_uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
  "timestamp": "2026-02-18T17:34:17.221000Z",
  "payload": {
    "template_uuid": "TMP1b44a079-c75c-4403-bc8f-a75c4ce5cd23",
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "status": "APPROVED",
    "previous_status": "PENDING",
    "rejection_reason": null
  }
}

Field	Description
`payload.template_uuid`	UUID of the template whose status changed
`payload.status`	New status: `APPROVED`, `REJECTED`, `PAUSED`, `DISABLED` or `DELETED`
`payload.previous_status`	Status the template had before this change
`payload.rejection_reason`	Why WhatsApp rejected the template, when `status` is `REJECTED`

Template Deleted

Triggers when one of your message templates is deleted — through 2Chat (Delete WABA Template or the web app) or directly in WhatsApp Manager. The template can no longer be sent.

In every template event, status reflects the template's state on WhatsApp, never a 2Chat-internal state. Deleting a template is not instant on WhatsApp's side: it enters PENDING_DELETION and is retained for about 30 days before the definitive DELETED, so this event usually arrives with status: "PENDING_DELETION". On some carriers the template is removed immediately instead; in that case status comes directly as DELETED.

{
  "event": "whatsapp.waba.template.deleted",
  "channel_uuid": "WAN3ff9fb72-6ecd-4c2a-9055-4836d8ed33d7",
  "timestamp": "2026-02-19T09:12:45.310000Z",
  "payload": {
    "template_uuid": "TMP1b44a079-c75c-4403-bc8f-a75c4ce5cd23",
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "status": "PENDING_DELETION",
    "previous_status": "APPROVED",
    "rejection_reason": null
  }
}

If WhatsApp later reports a further transition (for example the final DELETED after the retention window), it arrives as a regular Template Status Updated event.

WABA Webhooks

Message Sent​

Message Received​

Quick Reply​

Message Receipt Sent​

Message Receipt Received​

Template Created​

Template Status Updated​

Template Deleted​