Errors messages webhooks reference | Developer Documentation
Investigate a WhatsApp sending error with ChatArchitect
Start with the operation and the specific outgoing attempt. An API request error, a later delivery failure and an error inside your receiver occur at different stages. Use this guide to collect the available evidence and choose the next check. The delivery-status guide explains the reported progress of an attempt.
Locate the stage that reported the problem
| Observation | What to keep | Next check |
|---|---|---|
| The sending tool or API request reports an error | Operation, HTTP/result information when available, exact error, connection and request time. | Check the supported request and input. A request timeout can leave the outcome unclear; investigate the original attempt before sending again. |
The API returned submitted | Returned messageId and your attempt context. | Inspect the later result. Queue acceptance alone does not establish delivery or failure. |
A matched message-event reports failed | Available callback reference, destination, code and explanation. | Read the reported failure and check the relevant connection, recipient or message preparation. |
| The receiver gets an event but your application rejects or cannot process it | Receipt, validation and processing outcomes separately. | Check the receiver contract and handler. A local processing error by itself does not establish an outgoing delivery failure. |
| An incoming item has unavailable content | Incoming reference and the available content/result. | Use the incoming-message checklist to investigate that item. |
For a ready-made CRM or help desk, record the labels and error actually shown by that tool. Confirm uncertain status or callback behavior for the integration. For a custom application, use the ChatArchitect API quick start as the source of request and event examples.
Read a failed event using the documented fields
The quick start's failure example uses the following fields. Keep optional details when supplied; confirm any other error shape before interpreting it as this event.
| Field in the example | Use in the investigation |
|---|---|
Root type = message-event | Identify the outgoing-result handler. |
payload.type = failed | Record the reported failure for the matched attempt. |
payload.destination | Keep the reported recipient together with the connection and request context. |
payload.id | Keep the callback reference and use the correlation rule verified for the connection. |
payload.payload.code | Preserve the code from the supplied example shape when available. |
payload.payload.reason | Preserve the failure explanation when supplied. |
Use the documentation for the system that reported the code. Confirm an unfamiliar code with support, using the exact explanation and attempt context. The imported direct Meta error-code example does not define the codes returned by your ChatArchitect connection.
Match the evidence to the original attempt
- Keep the tool/application, connected business number, recipient and your internal attempt reference together.
- Record request time, receiver receipt time and processing result with time zone.
- Keep both the synchronous
messageIdand available callbackpayload.id. The guide's examples do not establish universal equality between them. - If a result cannot be matched, retain it for investigation according to your record policy. The same recipient can be involved in several attempts.
- If only
submittedis known, check the registered receiver and later tool results before assigning a final outcome.
Use the actual explanation to choose the next action
| Issue to investigate | Relevant check |
|---|---|
| Request credentials or connection | Compare the issued values and intended account with the ChatArchitect credentials guide and supported API request. |
| Ordinary reply or recipient preparation | Check the recipient, permission and active service window using the text-reply guide. |
| Template selection, status or variable content | Compare the selected template and values with the template guide and approved list for the connection. |
| Sending volume or timing | Review the throughput checklist and confirm queue/retry behavior for the tool. |
| Missing callback or handler result | Work through the receiver test, keeping public routing, event receipt and processing separate. |
Before repeating a send, confirm the original outcome, what the sending tool has already retried and whether the new attempt is appropriate. Record a new attempt separately when it is deliberately sent. Reprocessing a received event and sending another customer message have different effects.
Prepare a focused support report
Provide the affected integration/connection, operation, recipient reference as needed, times with time zone, both available message references, latest observed result, exact code/explanation and local processing outcome. Use a redacted event sample when needed. Keep credentials and customer message content out of routine diagnostics; apply the data-handling guide to your application's records.
For the direct Meta interface, see Meta's error webhook reference. Its envelope and error fields belong to that interface. The ChatArchitect field checks above come from the current ChatArchitect guide.
No comments to display
No comments to display