messages webhook reference | Developer Documentation
Route WhatsApp message events correctly in ChatArchitect
An incoming customer text and a delivery result require different actions in the receiving application. Select the event family before reading its nested fields; otherwise a status update can create an empty chat item or an incoming message can overwrite a sending result.
Use the ChatArchitect API quick start for the documented examples and the webhook overview for the broader connection workflow. For a ready-made CRM or help desk connector, inspect its supported display and processing behavior rather than adding Meta field paths to its settings.
Choose the event family and its content handler
| Documented case | Fields to inspect | Processing purpose |
|---|---|---|
| Incoming customer text | Root type is message; payload.type is text. The example uses payload.source, payload.id and payload.payload.text. | Route the item to the intended customer conversation using the verified business connection and source mapping. |
| Outgoing delivery result | Root type is message-event; payload.type is the result kind. Inspect the available destination, reference and failure details. | Update the relevant sending attempt using the confirmed correlation rule. Do not create a new customer chat from the status. |
| Another type or incomplete shape | Inspect the actual envelope and the supported contract for that connection. | Route for the defined handler or investigation; do not guess a text or delivery result from a familiar nested field. |
The root type and nested payload.type have different jobs. For the documented text case, read the content at payload.payload.text. For a documented failed result, failure information can be provided under payload.payload; inspect its available reason rather than treating that object as customer text.
Meta's direct messages reference uses messages and statuses arrays inside its own envelope. Its outgoing status describes a sending result, not the complete sent content. Those structures are provider context; they are not the ChatArchitect envelope shown in the quick start.
Keep supported routes explicit
- Apply the callback verification mechanism agreed for the connection, then validate the received data shape. The quick start does not specify universal signature headers or acknowledgement timing.
- Identify the connected business account or number using the confirmed mapping. Select the root event handler before processing the nested content.
- For an incoming item, follow the text-routing guide for the documented text case. Confirm a separate handler before using additional message types.
- For an outgoing result, follow the delivery-status guide. An accepted send and its final status are separate results.
- Apply the integration's reference and duplicate-handling rules within the established connection scope. Identical message text alone is not a duplicate key.
- Record receiver receipt, validation, routing and business-processing outcomes separately so a displayed item can be traced to the correct handler.
Receiving a status is not evidence that a customer replied. An incoming payload.id and the synchronous outgoing messageId do not become interchangeable because both refer to messages. Obtain the correlation rules for the actual sending and receiving routes.
Locate an error before changing a business record
Meta distinguishes system/app/account errors, errors attached to an incoming message and errors attached to an outgoing status in its provider envelope. Do not copy those paths into a ChatArchitect parser without a supported sample. Identify which operation the actual event describes.
| Observed result | Next check |
|---|---|
| Status callback creates an empty incoming item | Review the root event branch and which handler expected customer text. |
| Incoming item changes an unrelated sending result | Check event family, connection and the confirmed reference mapping. |
| Incoming content is unsupported or unavailable | Keep the type/notice and use the unavailable-message checklist. |
| Own send fails | Inspect the attempt and failure details with the sending-error checklist. |
| No event reaches the receiver | Review registration, reachability and receipt with the receiver test guide. |
| Event has a user ID without a phone number | Confirm identifier handling before selecting or creating a customer record. |
Check routing with a controlled local sample
Use the documented redacted text and status examples to test each branch separately. Confirm that the text branch cannot update a delivery result and that the status branch cannot create an incoming chat. Check malformed or unconfirmed cases according to the agreed contract instead of adding a fabricated default event.
A local sample checks your application, not actual callback forwarding, service retries or connector support. After the handler is reviewed, any live check needs an agreed permitted test and inspection of receiver, processing and display separately.
For support, provide the connection, time with time zone, root/nested type, available reference, validation outcome and intended versus observed handler. Redact content following the data-handling guide. See Meta's messages overview for its provider envelope.
No comments to display
No comments to display