Skip to main content

WhatsApp Incoming Webhook Payload | Developer Documentation

Read a ChatArchitect WhatsApp callback payload

Use this reference to identify incoming text and outgoing delivery results at your receiver. The ChatArchitect API quick start documents two event envelopes. The examples below are reduced, synthetic illustrations of those shapes; identifiers and phones are placeholders. They are not a complete schema or evidence from a live connection.

Begin with the root type, then read the nested payload for that event. The message-routing guide explains handler selection; this page shows the documented JSON paths. Confirm additional types and fields before adding a handler.

Incoming text: root message

{
  "type": "message",
  "payload": {
    "id": "<example_incoming_reference>",
    "source": "<customer_phone>",
    "type": "text",
    "payload": {
      "text": "Hello"
    }
  }
}
JSON pathMeaning in the text example
typemessage: an incoming customer message.
payload.idThe incoming message reference; retain it within the confirmed connection and direction.
payload.sourceThe customer phone shown by this example. Apply the supported connection/contact mapping.
payload.typetext: the nested incoming message kind.
payload.payload.textThe incoming text content; route it to the intended conversation.

The root type and nested kind are separate fields. Validate the corresponding shape before using the text. The incoming-text checklist covers the connection, conversation and visible result. A missing field or unknown kind does not justify inventing text, a phone or an identifier mapping; use the unavailable-content guide for supported handling and diagnosis.

Outgoing result: root message-event

{
  "type": "message-event",
  "payload": {
    "id": "<example_outgoing_reference>",
    "type": "failed",
    "destination": "<customer_phone>",
    "payload": {
      "code": 1008,
      "reason": "User is not Opted in and Inactive"
    }
  }
}

The failure code and reason illustrate the quick-start example. Diagnose an actual failure using the code, reason and operation actually received; do not substitute this example into a real result.

JSON pathMeaning in the result example
typemessage-event: a result for an outgoing message.
payload.idThe available outgoing reference; apply the correlation rule confirmed for the connection.
payload.typeThe reported state: the quick start lists failed, sent, delivered and read.
payload.destinationThe customer phone in this outgoing example.
payload.payload.code / payload.payload.reasonAvailable failure details in the illustrated failed event; they need not be present for every state.

A send request can return submitted before this event reports failure. Keep the synchronous messageId, connection, recipient, attempt time and available callback reference together. The guide does not establish universal equality between messageId and payload.id, a fixed event order or delivery of every state. Preserve unmatched or duplicate observations for the agreed processing rule.

Use the delivery-state guide to interpret the state and the outgoing-error guide for diagnosis. An outgoing failed event differs from an incoming message whose content your tool cannot display.

Use the receiver route agreed for your connection

The receiving HTTPS route belongs to your application. The provider example /whatsapp/webhooks does not prescribe a required ChatArchitect receiver path. Follow the quick start's /webhook registration operation only after confirming the intended connection and effect on an existing callback.

Work through the receiver checklist and staged receiver test. Route preparation, local synthetic handling and observed live receipt establish different parts of the connection. A successful public page load does not prove that a callback is verified or processed by the intended handler.

Confirm incoming verification separately

Basic Auth with App key/Secret authenticates your API requests to ChatArchitect. It does not define how an incoming callback authenticates to your receiver. The quick start does not specify a verification header or signature, the incoming request method, acknowledgement response/timing or redelivery schedule. Confirm these details for your connection before relying on them.

The imported provider reference used a Meta envelope with object, entry and changes. That is not the ChatArchitect envelope illustrated above. Do not infer Bearer authentication, Meta field paths or a universal acknowledgement contract for ChatArchitect from a direct-provider schema.

Validate the boundary of your implementation

  • For incoming text, identify root message, nested text, source, reference and text path before routing.
  • For an outgoing result, identify root message-event, the reported state, destination and available failure details before updating the intended attempt.
  • Confirm connection scope, identifiers and duplicate handling independently. A phone and reference alone do not establish a universal CRM merge rule.
  • Request a supported sample for other incoming types, identifiers without phones or account/template notifications. Do not promote an unknown format into a confirmed feature.

Apply the data-handling guide to diagnostics. Share redacted event type, time, connection and available reference with support; keep credentials and customer content out of public reports.

For the broader workflow, see the webhook overview. Meta's incoming payload reference concerns its own provider interface; it is not a complete specification of the ChatArchitect callback.

No comments to display

Back to top