---
title: "WhatsApp Event"
method: POST
path: "/whatsapp"
tags: ["Webhooks"]
---

# WhatsApp Event

`POST /whatsapp` (webhook)

Signed direct WhatsApp message and reaction notifications owned by an agent identity. Select these event types before access is approved without enabling the channel. Only received events may include requested conversation context. Unknown delivery is not a failure or permission to resend. If your organization has a signing key, every webhook includes three headers:
- `X-Inkbox-Request-ID` — UUID for deduplication.
- `X-Inkbox-Timestamp` — Unix timestamp in seconds.
- `X-Inkbox-Signature` — `sha256={HMAC-SHA256 hex digest}` over `{request_id}.{timestamp}.{raw_body}`.

## Payload

- WhatsAppWebhookPayload
  - `id` string, required
  - `event_type` 'whatsapp.reaction_received' | 'whatsapp.received' | 'whatsapp.sent' | 'whatsapp.delivered' | 'whatsapp.delivery_failed' | 'whatsapp.delivery_unconfirmed', required
  - `timestamp` string, date-time, required
  - `data` WhatsAppWebhookData, required
    - `message` WebhookWhatsAppMessage, required
      - `id` string, uuid, required
      - `agent_identity_id` string, uuid, required
      - `conversation_id` string, uuid, required
      - `direction` 'inbound' | 'outbound', required
      - `local_number` string, required
      - `remote_number` string, required
      - `sender_number` string, required
      - `participants` string[], required
      - `reply_to_message_id` string, uuid, nullable
      - `thread_id` string, uuid, nullable
      - `thread_root_message_id` string, uuid, nullable
      - `reactions` WhatsAppReactionResponse[]
        - `id` string, uuid, required
        - `target_message_id` string, uuid, required
        - `conversation_id` string, uuid, required
        - `agent_identity_id` string, uuid, required
        - `direction` 'inbound' | 'outbound', required
        - `remote_number` string, nullable, required
        - `reaction` union, required
          - 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | 'eyes'
          - 'custom'
        - `custom_emoji` string, nullable, required
        - `emoji` string, required
        - `status` 'queued' | 'sending' | 'applied' | 'removed' | 'failed' | 'uncertain' | 'superseded', required
        - `revision` integer, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `removed_at` string, date-time, nullable, required
      - `content` string, nullable, required
      - `media` WhatsAppMediaResponse[], required
        - `id` string, uuid, required
        - `filename` string, required
        - `content_type` string, required
        - `size` integer, nullable, required
        - `status` 'pending' | 'ready' | 'unavailable', required
        - `url` string, nullable, required
      - `status` 'received' | 'queued' | 'sending' | 'sent' | 'delivered' | 'failed' | 'uncertain' | 'cancelled', required
      - `delivery_state` 'pending' | 'delivered' | 'unknown', required
      - `recipients` WhatsAppRecipientResponse[], required
        - `remote_number` string, required
        - `delivery_status` 'received' | 'queued' | 'sending' | 'sent' | 'delivered' | 'failed' | 'uncertain' | 'cancelled', required
        - `delivery_state` 'pending' | 'delivered' | 'unknown', required
        - `error_code` string, nullable, required
        - `error_detail` string, nullable, required
        - `sent_at` string, date-time, nullable, required
        - `delivered_at` string, date-time, nullable, required
        - `failed_at` string, date-time, nullable, required
      - `is_read` boolean, required
      - `is_blocked` boolean
      - `error_code` string, nullable, required
      - `error_detail` string, nullable, required
      - `source_at` string, date-time, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `sent_at` string, date-time, nullable, required
      - `delivered_at` string, date-time, nullable, required
      - `failed_at` string, date-time, nullable, required
      - `status_observed_at` string, date-time, nullable, required
      - `status_refresh_pending` boolean
    - `reaction` WhatsAppReactionResponse
      - `id` string, uuid, required
      - `target_message_id` string, uuid, required
      - `conversation_id` string, uuid, required
      - `agent_identity_id` string, uuid, required
      - `direction` 'inbound' | 'outbound', required
      - `remote_number` string, nullable, required
      - `reaction` union, required
        - 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | 'eyes'
        - 'custom'
      - `custom_emoji` string, nullable, required
      - `emoji` string, required
      - `status` 'queued' | 'sending' | 'applied' | 'removed' | 'failed' | 'uncertain' | 'superseded', required
      - `revision` integer, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `removed_at` string, date-time, nullable, required
    - `context` object, nullable
    - `contacts` WebhookContact[]
      - `id` string, uuid, required
      - `name` string, nullable, required
      - `memories` string[]
    - `agent_identities` WebhookAgentIdentity[]
      - `id` string, uuid, required
      - `agent_handle` string, required
      - `display_name` string, nullable

## Acknowledgement `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) - [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) - [OpenAPI document](https://skmtc.dev/inkbox/apis/inkbox-api/revisions/7e848337e8bf?raw)