> For the complete documentation index, see [llms.txt](https://docs.channel360.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.channel360.co.za/api-usage/using-the-channel360-v1.1-api/conversations.md). # Conversations ### What are conversations? A **conversation** includes all messages exchanged within a 24-hour window. This window starts when the first business message is sent or when the customer first messages the business, depending on the conversation type. WhatsApp supports two conversation types: #### Business-initiated conversations A **business-initiated conversation** starts when the business sends a message to an opted-in customer using a WhatsApp template message. These conversations are typically used for notifications, updates, reminders, alerts, or other proactive communication. #### Customer-initiated conversations A **customer-initiated conversation** starts when a customer sends a message to the business. These conversations are typically used for support, sales enquiries, account help, or general information requests. *** ### Standard business flow 1. Subscribe to `message:appUser` webhook events. 2. Receive an inbound customer message containing the `appUserId`. 3. Reply to the customer using the received `appUserId` {% hint style="info" %} You can only use the following endpoint to reply within the 24-hour customer messaging window: ``` /v1.1/org/:orgId/whatsapp/appuser/:appuser/reply ``` The reply endpoint is available only after the customer has messaged your business first, and only within 24 hours of that inbound message. {% endhint %} *** ### Handling missing phone numbers in `message:appUser` events The `message:appUser` webhook event may not always include the user’s phone number. This should not be treated as a blocker or integration failure. Meta is introducing broader changes around WhatsApp usernames and user privacy. These changes may affect WhatsApp integrations across multiple providers, not only Channel360. Depending on the user’s privacy settings and Meta’s rollout, the phone number may or may not be present in certain webhook events. For this reason, integrations should not assume that an inbound `message:appUser` event will always contain the user’s phone number. *** ### Recommended source of truth The destination phone number should remain the source of truth in your own system. When sending a WhatsApp notification, the destination phone number is still required. Your system should already know which customer, sales representative, admin user, or internal process the notification is being sent to. You should store that destination number against your own internal reference before sending the notification. For example, your system may store: ```json { "internalCustomerId": "customer_12345", "destinationPhoneNumber": "+27821234567", "notificationPurpose": "sales_rep_assignment", "status": "notification_sent" } ``` *** ### Mapping outbound notifications to Channel360 identifiers When the notification delivery webhook is received, use the returned Channel360 identifiers to enrich the record stored in your system. Relevant identifiers may include: ```json { "destination.destinationId": "...", "notification._id": "...", "matchResult.appUser._id": "...", "matchResult.conversation._id": "..." } ``` These identifiers should be stored against the same internal record that originally contained the destination phone number. Example: ```json { "internalCustomerId": "customer_12345", "destinationPhoneNumber": "+27821234567", "notificationPurpose": "sales_rep_assignment", "destinationId": "destination_abc123", "notificationId": "notification_abc123", "appUserId": "appUser_abc123", "conversationId": "conversation_abc123" } ``` Once this mapping has been stored, future inbound messages can be correlated without relying on the phone number being present in the `message:appUser` payload. *** ### Correlating inbound replies When the customer replies, the inbound `message:appUser` event can be matched back to your internal record using one or more of the Channel360 identifiers. Recommended correlation fields include: ```json { "conversation._id": "...", "appUser._id": "...", "notification._id": "..." } ``` In most cases, the preferred identifiers are: 1. `conversation._id` 2. `appUser._id` 3. `notification._id`, where applicable This allows your system to identify the correct customer, process, or notification flow even when the phone number is not present on the inbound event. *** ### Recommended implementation flow 1. Send the WhatsApp notification using the destination phone number. 2. Store your internal reference together with that destination phone number. 3. When the notification delivery event is received, store the returned identifiers against the same record: * `destination.destinationId` * `notification._id` * `matchResult.appUser._id` * `matchResult.conversation._id` 4. When the user replies and the `message:appUser` event is received, use `conversation._id` or `appUser._id` to identify the same customer or process in your system. *** ### Why this approach is recommended This approach allows you to continue supporting: * Customer identification * Reply correlation * Reporting * Notification tracking * Internal process mapping without depending on the phone number being present in the `message:appUser` webhook payload. Although a client object containing the number may sometimes be included through a special webhook setting, this should not be treated as the preferred long-term pattern. The safer approach is to keep the phone number in your own system and bind it to the returned `appUser`, `conversation`, and `notification` identifiers through the notification delivery event. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.channel360.co.za/api-usage/using-the-channel360-v1.1-api/conversations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.