System messages webhook reference | Developer Documentation

Check WhatsApp customer identifier changes in ChatArchitect

If a conversation appears under a changed customer number or you receive an identifier-change notice, review the connection and available identifiers before linking CRM records. An automatic merge can put a conversation or task against the wrong customer.

The ChatArchitect API quick start does not specify system-message callbacks, business-scoped user IDs or automatic contact migration. Ask support to confirm the notice format and behavior for your API application or ready-made integration.

Determine which identifier changed

Meta's current system-event reference describes two different changes: a customer phone-number change with a new number that can be shared, and a business-scoped user ID change that reports an ID rather than a phone number. Some identifiers can be absent, and these system messages do not include the usual sender contacts array. This is platform context; confirm how the ChatArchitect connection represents any such notice.

• Check the affected business connection and the type of change before interpreting an identifier.
• Keep phone numbers and user IDs in separate fields. Do not copy a user ID into a phone-number field.
• Use only the previous/current identifiers actually provided by the supported contract. Do not infer a previous identity from the last message or a matching display name.
• Where the notice supplies no phone number, preserve that distinction. Missing phone data does not by itself prove that receipt failed.

Review the proposed contact change

1. Identify the receiving integration, connected business number and affected conversation. Record when the issue appeared and the available event or conversation reference.
2. For a custom application, obtain a redacted supported notice with the change type, available previous/current identifiers and their connection scope. Confirm missing-field and duplicate-event handling using the webhook overview.
3. Compare the identifiers with the existing customer record and any newly created record. Review the match using your established customer-verification process.
4. Keep a change that cannot be matched for investigation according to your data policy. Do not merge unrelated conversations solely because their names look alike.
5. Before updating a record, review what happens to linked conversations, open tasks and future sends. Confirm which fields the integration changes and which remain unchanged.
6. After an authorized record update, check the conversation's customer association and the destination used for the next permitted reply. Review scheduled sends that still reference an older destination.

If the customer has contacted you from a new number without a supported change notice, use your normal verification and contact-update process. A new incoming text alone does not establish a safe link to an earlier record.

Use a support-provided redacted example to validate a custom handler's mapping before applying it to live records. A real customer does not need to change their number merely to generate a test event.

When records split or the notice is incomplete

This checklist concerns a customer's number or user ID. Changing the business number connected to ChatArchitect is a separate task covered by the business-number guide.

For support, provide the connection, integration version, time with time zone, available reference and the record association you expected. Redact customer numbers and identifiers in diagnostic material according to the data-handling guide. See Meta's system-event reference for platform details; it does not establish ChatArchitect's identifier support or automatic CRM migration.