Text messages webhook reference | Developer Documentation

Route incoming WhatsApp texts from ChatArchitect to your application

Use this guide for the incoming text event documented in the ChatArchitect API quick start. It helps you identify the message, validate the fields, route it to the right conversation and investigate a missing or repeated item. For a ready-made CRM or help desk connector, check the integration's incoming-chat workflow and contact support when its behavior is unclear.

The webhook overview separates incoming messages from outgoing results. Prepare the receiver using the endpoint checklist and verify it with the staged test guide.

Recognize the documented incoming text

Use a small local fixture to check field paths

The following is a reduced synthetic fixture for a local parser test. References and text are illustrative; other envelope fields from the quick start are omitted. It is an incoming-event example, not a registration or message-send request.

{
  "type": "message",
  "payload": {
    "id": "<incoming_message_reference>",
    "source": "<sender_phone>",
    "type": "text",
    "payload": {
      "text": "Local test: please check order 1042."
    }
  }
}

Read the two nested payload objects at their documented levels. The text is at payload.payload.text. A root message-event belongs to the outgoing-result workflow; it should not create an incoming chat item.

Validate and route the item

1. Apply the agreed sender-verification method. Confirm the callback authentication/signature requirements for your connection. Field validation checks data shape; use the supported verification mechanism before trusting an event.
2. Validate the event shape. Check valid JSON, the root and nested types, the source, message reference and text fields required for this handler. Handle an incomplete item according to the agreed contract.
3. Identify the connection. Use the mapping verified for your registered receiver and account. Confirm how a callback identifies the correct business connection before handling several numbers in one application.
4. Select the conversation. Combine the verified connection with the source value. The same customer can contact different business numbers; check the intended route before updating a conversation.
5. Apply your duplicate rule. Use the message reference and connection scope established for the integration. Preserve separate messages with identical text; content equality alone is insufficient.
6. Separate receipt from processing. Record the receiver's receipt time with time zone and the processing outcome. Follow the agreed acknowledgement response and timing, and track failures in your application's processing.

The current quick start recommends safe duplicate processing but does not define universal reference uniqueness, delivery order, callback signature headers or acknowledgement timing. Obtain the relevant details before relying on them in your handler. A synchronous outgoing messageId and an incoming payload.id have different roles; an incoming text is not automatically a reference to one specific outgoing attempt.

Check the conversation with a permitted test contact

1. Send a distinctive incoming text to the intended business number and compare the received event's source, reference and text with the item shown in the application.
2. Send a second, identical text. Check that it is preserved as a separate incoming message using the verified event identity rule.
3. In a controlled local test, replay the same fixture and inspect duplicate handling. That replay tests your application; it does not establish the service's redelivery schedule.
4. Check line breaks and the characters your users need. Display received text as message content so those characters retain their intended meaning.
5. Reply using the ordinary text-reply guide. Inspect the outgoing attempt and its later status separately from receiving the customer's text.

If a text is missing, repeated or routed incorrectly

For support, provide the connection, receipt/test time with time zone, available message reference, validation/routing outcome and exact error. Use a redacted sample when needed and apply the data-handling guide to your application's records.

The direct Meta envelope is described in Meta's text-message reference. Its optional fields do not establish the ChatArchitect callback contract; use the current ChatArchitect guide and details confirmed for your connection.