Message events - Kapso Documentation

All webhook payloads use v2 format with phone_number_id at the top level.

Payload structure

Webhook payloads separate message data from conversation data:

message.kapso - Message-scoped only: direction, status, processing_status, statuses (raw status history), origin, has_media, content (text representation), transcript (for audio), media helpers (media_data, media_url, message_type_data)
conversation - Top-level identifiers such as id, contact_name, phone_number, phone_number_id, and, when available, business_scoped_user_id, parent_business_scoped_user_id, and username. Optional conversation.kapso contains summary metrics only (counts, last-message metadata, timestamps) — it never contains contact_name
phone_number_id - Included at top level for routing

Do not assume phone_number, from, to, or wa_id are always present. Timestamps use two formats: conversation.kapso fields are UTC with microseconds (2025-10-28T17:25:01.000000Z), every other ISO timestamp carries a UTC offset (2025-10-28T14:25:01-03:00). message.timestamp is a Unix epoch string. Parse all three.

WhatsApp webhook events

Sent only to phone-number webhooks (/whatsapp/phone_numbers/{phone_number_id}/webhooks).

Message received

whatsapp.message.receivedFired when a new WhatsApp message is received from a customer. Supports message buffering for batch delivery.

Message sent

whatsapp.message.sentFired when a message is successfully sent to WhatsApp

Message delivered

whatsapp.message.deliveredFired when a message is successfully delivered to the recipient’s device

Message read

whatsapp.message.readFired when the recipient reads your message

Message failed

whatsapp.message.failedFired when a message fails to deliver

Conversation created

whatsapp.conversation.createdFired when a new WhatsApp conversation is initiated

Conversation ended

whatsapp.conversation.endedFired when a WhatsApp conversation ends (agent action, manual closure, or 24-hour inactivity)

Conversation inactive

whatsapp.conversation.inactiveFired when no messages (inbound/outbound) for configured minutes (1-1440, default 60)

Contact identity changed

whatsapp.contact.identity_changedFired when a contact receives a new business-scoped user ID

Marketing preference changed

whatsapp.contact.marketing_preference_changedFired when a contact stops or resumes marketing messages from one of your numbers

Payload structures

Kapso sends the event name in the X-Webhook-Event header. The examples below show unbuffered request bodies. If buffering is enabled for whatsapp.message.received, the request body uses a batch envelope with type, batch: true, data: [...], and batch_info; each data item has the same shape as the unbuffered whatsapp.message.received payload below. See Batched webhook format for a full batched payload example.

whatsapp.message.received

{
  "message": {
    "id": "wamid.123",
    "timestamp": "1730092800",
    "type": "text",
    "from": "16315551181",
    "from_user_id": "US.13491208655302741918",
    "from_parent_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "text": { "body": "Hello" },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": false,
      "content": "Hello"
    }
  },
  "conversation": {
    "id": "conv_123",
    "contact_name": "John Doe",
    "phone_number": "16315551181",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T14:25:01-03:00",
    "created_at": "2025-10-28T13:40:00-03:00",
    "updated_at": "2025-10-28T14:25:01-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "messages_count": 1,
      "last_message_id": "wamid.123",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T17:25:01.000000Z",
      "last_message_text": "Hello",
      "last_inbound_at": "2025-10-28T17:25:01.000000Z",
      "last_outbound_at": null
    }
  },
  "is_new_conversation": true,
  "phone_number_id": "123456789012345"
}

whatsapp.message.sent

{
  "message": {
    "id": "wamid.456",
    "timestamp": "1730092860",
    "type": "text",
    "to": "15551234567",
    "text": { "body": "On my way" },
    "kapso": {
      "direction": "outbound",
      "status": "sent",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.456",
          "status": "sent",
          "timestamp": "1730092860",
          "recipient_id": "15551234567"
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T14:31:00-03:00",
    "created_at": "2025-10-28T13:40:00-03:00",
    "updated_at": "2025-10-28T14:31:00-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "messages_count": 2,
      "last_message_id": "wamid.456",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T17:31:00.000000Z",
      "last_message_text": "On my way",
      "last_inbound_at": "2025-10-28T17:25:01.000000Z",
      "last_outbound_at": "2025-10-28T17:31:00.000000Z"
    }
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.message.delivered

{
  "message": {
    "id": "wamid.456",
    "timestamp": "1730092888",
    "type": "text",
    "to": "15551234567",
    "text": { "body": "On my way" },
    "kapso": {
      "direction": "outbound",
      "status": "delivered",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.456",
          "status": "sent",
          "timestamp": "1730092860",
          "recipient_id": "15551234567"
        },
        {
          "id": "wamid.456",
          "status": "delivered",
          "timestamp": "1730092888",
          "recipient_id": "15551234567"
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T14:31:28-03:00",
    "created_at": "2025-10-28T13:40:00-03:00",
    "updated_at": "2025-10-28T14:31:28-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.message.failed

{
  "message": {
    "id": "wamid.789",
    "timestamp": "1730093200",
    "type": "text",
    "to": "15551234567",
    "text": { "body": "This message failed" },
    "kapso": {
      "direction": "outbound",
      "status": "failed",
      "processing_status": "completed",
      "origin": "cloud_api",
      "has_media": false,
      "statuses": [
        {
          "id": "wamid.789",
          "status": "sent",
          "timestamp": "1730093100",
          "recipient_id": "15551234567"
        },
        {
          "id": "wamid.789",
          "status": "failed",
          "timestamp": "1730093200",
          "recipient_id": "15551234567",
          "errors": [
            {
              "code": 131047,
              "title": "Re-engagement message",
              "message": "More than 24 hours have passed since the recipient last replied"
            }
          ]
        }
      ]
    }
  },
  "conversation": {
    "id": "conv_123",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T15:00:00-03:00",
    "created_at": "2025-10-28T13:40:00-03:00",
    "updated_at": "2025-10-28T15:00:00-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "is_new_conversation": false,
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.created

{
  "conversation": {
    "id": "conv_789",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T14:00:00-03:00",
    "created_at": "2025-10-28T14:00:00-03:00",
    "updated_at": "2025-10-28T14:00:00-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "messages_count": 0,
      "last_message_id": null,
      "last_message_type": null,
      "last_message_timestamp": null,
      "last_message_text": null,
      "last_inbound_at": null,
      "last_outbound_at": null
    }
  },
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.ended

{
  "conversation": {
    "id": "conv_789",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "ended",
    "last_active_at": "2025-10-28T15:10:45-03:00",
    "created_at": "2025-10-28T14:00:00-03:00",
    "updated_at": "2025-10-28T15:10:45-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345",
    "kapso": {
      "messages_count": 15,
      "last_message_id": "wamid.999",
      "last_message_type": "text",
      "last_message_timestamp": "2025-10-28T18:10:45.000000Z",
      "last_message_text": "Thanks!",
      "last_inbound_at": "2025-10-28T18:10:45.000000Z",
      "last_outbound_at": "2025-10-28T18:10:30.000000Z"
    }
  },
  "phone_number_id": "123456789012345"
}

whatsapp.conversation.inactive

{
  "conversation": {
    "id": "conv_789",
    "contact_name": "John Doe",
    "phone_number": "15551234567",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "status": "active",
    "last_active_at": "2025-10-28T13:00:00-03:00",
    "created_at": "2025-10-28T12:00:00-03:00",
    "updated_at": "2025-10-28T13:00:00-03:00",
    "metadata": {},
    "phone_number_id": "123456789012345"
  },
  "since_message": {
    "id": "msg_anchor",
    "whatsapp_message_id": "wamid.ANCHOR",
    "direction": "inbound",
    "created_at": "2025-10-28T13:00:00-03:00"
  },
  "inactivity": {
    "minutes": 60
  },
  "phone_number_id": "123456789012345"
}

whatsapp.contact.identity_changed

{
  "contact": {
    "id": "contact_123",
    "customer_id": "customer_456",
    "wa_id": "15551234567",
    "profile_name": "John Doe",
    "display_name": "John Doe",
    "business_scoped_user_id": "US.13491208655302741918",
    "parent_business_scoped_user_id": "US.ENT.506847293015824",
    "username": "@testusername",
    "created_at": "2025-10-28T14:00:00-03:00",
    "updated_at": "2025-10-28T15:10:45-03:00",
    "sandbox": false,
    "metadata": {}
  },
  "previous": {
    "business_scoped_user_id": "US.OLD.13491208655302741918",
    "parent_business_scoped_user_id": "US.OLD.ENT.506847293015824"
  },
  "phone_number_id": "123456789012345"
}

contact holds the identity after the change; previous holds the business-scoped user IDs Meta reported for the contact before it. Either previous value can be null when Meta does not send it. Use it to re-key stored identifiers in your own system. Fired for Meta’s user_changed_number and user_changed_user_id system messages. Those system messages do not produce a whatsapp.message.received event. See Business-scoped user IDs.

whatsapp.contact.marketing_preference_changed

{
  "contact": {
    "id": "contact_123",
    "wa_id": "15551234567",
    "profile_name": "John Doe",
    "display_name": "John Doe",
    "created_at": "2025-10-28T14:00:00-03:00",
    "updated_at": "2025-10-28T15:10:45-03:00",
    "metadata": {}
  },
  "marketing_preference": {
    "status": "stopped",
    "previous_status": "resumed",
    "detail": "User requested to stop marketing messages",
    "occurred_at": "2025-10-28T15:10:45-03:00",
    "sequence": 4821
  },
  "phone_number_id": "123456789012345"
}

status is stopped or resumed. previous_status is the state before this change, and is null the first time Kapso hears about the contact’s preference. detail is the free-text reason Meta sends, and can be null. occurred_at is the timestamp WhatsApp reported for the change. Kapso only records preference changes that carry one: an event Kapso cannot place in time cannot be ordered against what it already knows, so it is rejected at ingest and raised for investigation rather than applied. sequence increases with every preference change Kapso records, and is what you should compare to decide which of two deliveries is newer. Deliveries are at-least-once and are not guaranteed to arrive in order, so if you store the contact’s preference, keep the sequence you last applied and only apply a delivery whose sequence is strictly greater — a redelivery of the same event carries the same value, and applying it again would repeat your side effects. Do not order on occurred_at alone: WhatsApp reports it to the second, so a rapid stop and resume can share a value. The preference is scoped to the phone number it arrived on: stopping marketing on one of your numbers does not stop it on the others. The event only fires when the state actually changes, so a repeated stop from Meta does not produce a second delivery. Once a contact is stopped, Kapso refuses marketing template sends to them on that number with error code marketing_preference_stopped. Utility and authentication templates and free-form session messages are unaffected. Broadcasts mark those recipients suppressed and do not charge for them. See Marketing opt-outs and Broadcasts.

Multiple inactivity timeouts

Create separate webhooks for different timeout thresholds:

// First webhook: 5 minute warning
{
  "events": ["whatsapp.conversation.inactive"],
  "inactive_after_minutes": 5
}

// Second webhook: 30 minute escalation
{
  "events": ["whatsapp.conversation.inactive"],
  "inactive_after_minutes": 30
}

Each webhook fires independently when its threshold is reached.

Message origin

The message.kapso.origin field indicates how the message entered the system:

cloud_api - Sent via Kapso API (outbound jobs, flow actions, API calls)
business_app - Echoed from WhatsApp Business App (when using the Business App)
history_sync - Backfilled during message history imports (only if project ran sync)

Status history

The message.kapso.statuses array contains the complete history of raw Meta status events for a message, ordered chronologically. Each entry is the unmodified payload from Meta’s webhook.

Status object structure

Each status object in the array follows Meta’s webhook format:

{
  "id": "<WHATSAPP_MESSAGE_ID>",
  "status": "<STATUS>",
  "timestamp": "<UNIX_TIMESTAMP>",
  "recipient_id": "<PHONE_NUMBER>",
  "pricing": {
    "billable": true,
    "pricing_model": "<PRICING_MODEL>",
    "category": "<PRICING_CATEGORY>"
  },
  "errors": [
    {
      "code": 131031,
      "title": "<ERROR_TITLE>",
      "message": "<ERROR_MESSAGE>",
      "error_data": {
        "details": "<ERROR_DETAILS>"
      },
      "href": "<ERROR_CODES_URL>"
    }
  ],
  ...
}

Field	Included when
`pricing`	Sent status, plus delivered or read
`errors`	Failed to send or deliver

See Meta’s status webhook reference for the complete schema. Use this field to track the full lifecycle of outbound messages and understand failure causes. The array only appears when status events have been recorded.

Message types

The message.type field can be one of:

text - Plain text message
image - Image attachment
video - Video attachment
audio - Audio/voice message
document - Document attachment
location - Location sharing
template - WhatsApp template message
interactive - Interactive message (buttons, lists)
reaction - Message reaction
contacts - Contact card sharing

Message type-specific data

Media messages (image/video/document)

{
  "message": {
    "id": "wamid.789",
    "timestamp": "1730093000",
    "type": "image",
    "image": {
      "caption": "Photo description",
      "id": "media_id_123"
    },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": true,
      "content": "Photo description Image attached (photo.jpg) [Size: 200 KB | Type: image/jpeg] URL: https://api.kapso.ai/media/...",
      "media_url": "https://api.kapso.ai/media/...",
      "media_data": {
        "url": "https://api.kapso.ai/media/...",
        "filename": "photo.jpg",
        "content_type": "image/jpeg",
        "byte_size": 204800
      },
      "message_type_data": {
        "caption": "Photo description"
      }
    }
  }
}

Audio messages

{
  "message": {
    "id": "wamid.790",
    "timestamp": "1730093100",
    "type": "audio",
    "audio": {
      "id": "media_id_456"
    },
    "kapso": {
      "direction": "inbound",
      "status": "received",
      "processing_status": "pending",
      "origin": "cloud_api",
      "has_media": true,
      "content": "[Audio attached] (voice.ogg) [Size: 50 KB | Type: audio/ogg] URL: https://api.kapso.ai/media/...\nTranscript: Hello, I need help with my order",
      "transcript": {
        "text": "Hello, I need help with my order"
      },
      "media_url": "https://api.kapso.ai/media/...",
      "media_data": {
        "url": "https://api.kapso.ai/media/...",
        "filename": "voice.ogg",
        "content_type": "audio/ogg",
        "byte_size": 51200
      }
    }
  }
}

Location messages

{
  "message": {
    "type": "location",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "San Francisco",
      "address": "San Francisco, CA, USA"
    }
  }
}

Template messages

{
  "message": {
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": {
        "code": "en_US"
      },
      "components": [...]
    }
  }
}

Interactive messages

{
  "message": {
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "btn_1",
        "title": "Confirm"
      }
    }
  }
}

Reaction messages

{
  "message": {
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNNTU0MTIzNDU2Nzg5MA",
      "emoji": "👍"
    }
  }
}

Contact messages

When you send a request contact info CTA and the user taps it, WhatsApp sends a contacts message. It includes the user’s phone number and keeps BSUID identity when available.

{
  "type": "contacts",
  "from_user_id": "US.13491208655302741918",
  "contacts": [
    {
      "origin": "contact_request",
      "phones": [
        {
          "phone": "+16505551234",
          "wa_id": "16505551234"
        }
      ]
    }
  ]
}

If the user shares a contact directly from WhatsApp instead, origin is other and the payload can include a vCard.

​Payload structure

​WhatsApp webhook events

Message received

Message sent

Message delivered

Message read

Message failed

Conversation created

Conversation ended

Conversation inactive

Contact identity changed

Marketing preference changed

​Payload structures

​whatsapp.message.received

​whatsapp.message.sent

​whatsapp.message.delivered

​whatsapp.message.failed

​whatsapp.conversation.created

​whatsapp.conversation.ended

​whatsapp.conversation.inactive

​whatsapp.contact.identity_changed

​whatsapp.contact.marketing_preference_changed

​Multiple inactivity timeouts

​Message origin

​Status history

​Status object structure

​Message types

​Message type-specific data

​Media messages (image/video/document)

​Audio messages

​Location messages

​Template messages

​Interactive messages

​Reaction messages

​Contact messages