> 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.

For the current transition guidance, see [WhatsApp usernames and BSUID](/api-usage/using-the-channel360-v1.1-api/conversations/whatsapp-usernames-and-bsuid.md).

***

### 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.