Conversations

What are Conversations, and how to use them

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

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.

The endpoint supports replies to the received appUserId.

It does not allow a BSUID as a send destination. See WhatsApp usernames and BSUID.

---

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.

---

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:

{
  "internalCustomerId": "customer_12345",
  "destinationPhoneNumber": "[phone]",
  "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:

{
  "destination.destinationId": "...",
  "notification._id": "...",
  "matchResult.appUser._id": "...",
  "matchResult.conversation._id": "..."
}

The client object is present on message:appUser events.

It contains externalId and additionalIdentifiers.

Delivery events carry destination.destinationId instead.

That value is the phone number you sent to.

Use it to map Channel360 identifiers to your records.

These identifiers should be stored against the same internal record that originally contained the destination phone number.

Example:

{
  "internalCustomerId": "customer_12345",
  "destinationPhoneNumber": "[phone]",
  "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:

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