# Set up the RCS CONVERSATION_STARTED webhook event

Configure the `CONVERSATION_STARTED` webhook event to receive real-time notifications when an end user replies to an RCS message and initiates a conversational session. Use this event to track when the billing model changes from non-conversational to conversational, and to monitor traffic types (A2P or P2A) for billing purposes.

This tutorial walks through creating a subscription with a notification profile, sending an RCS message, and handling the webhook payloads that Infobip delivers to your endpoint.

This tutorial focuses specifically on the CONVERSATION_STARTED event. To set up webhooks for other messaging events such as delivery reports, seen reports, and inbound messages, refer to [Set up webhook notifications for messaging events](https://www.infobip.com/docs/tutorials/set-up-webhook-notifications-for-messaging-events).

## Products and channels [#products-channels]

Use the following Infobip products to set up the CONVERSATION_STARTED webhook event for RCS.

| Product | Description |
| --- | --- |
| RCS | Channel used to send and receive rich business messages. |
| Subscriptions API | Create subscriptions and notification profiles to receive webhook events. |

## Prerequisites [#prerequisites]

- Infobip account. If you do not have an account, [sign up](https://www.infobip.com/signup) for a free trial account.
- Infobip API key with the `rcs:message:send` scope. Learn how to [create an API key with the correct scope](https://www.infobip.com/docs/api//essentials/api-authentication).
- HTTP client for making API requests. This tutorial uses `cURL`, but you can use any HTTP client or the [official Infobip SDK](https://www.infobip.com/docs/api//getting-started/sdks) for your preferred programming language.
- RCS agent/sender with the **Billing category** set to **Conversational**. To configure a custom RCS sender, contact your Account Manager.
- Destination phone number for testing. If the RCS agent is not launched, you can send messages only to whitelisted phone numbers.
- Publicly accessible webhook endpoint URL where Infobip can send event notifications.

## Process overview [#process-overview]

1. Create a subscription and notification profile for the `CONVERSATION_STARTED` event.
2. Send an RCS message to initiate a conversation.
3. Handle the delivery report and the `CONVERSATION_STARTED` webhook payload.

## Step 1: Create the subscription and notification profile

Create a subscription that defines which message events should trigger webhook notifications to your endpoint. For this tutorial, subscribe to the `CONVERSATION_STARTED` event.

A complete list of available events for each Infobip product is available in the [event subscriptions](https://www.infobip.com/docs/cpaas-x/subscriptions-management/event-subscriptions) documentation.

```bash
curl -X POST "https://{YOUR_BASE_URL}/subscriptions/1/subscription/RCS" \
-H "Authorization: App {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "subscriptionId": "RCS-Conversation-Started",
  "name": "RCS Conversation Started Webhook",
  "events": [
    "CONVERSATION_STARTED"
  ],
  "resources": [
    "YOUR_RCS_SENDER"
  ],
  "profile": {
    "profileId": "NOTIF-RCS_CONV",
    "webhook": {
      "notifyUrl": "YOUR_WEBHOOK_URL"
    },
    "security": {
      "authId": "BASIC_auth",
      "type": "BASIC",
      "credentials": {
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD"
      }
    }
  }
}'
```

```json
{
  "subscriptionId": "RCS-Conversation-Started",
  "profile": {
    "profileId": "NOTIF-RCS_CONV",
    "security": {
      "authId": "BASIC_auth"
    }
  }
}
```

**Key points:**

- `subscriptionId`: Must not contain whitespaces. Use hyphens or underscores instead (e.g., `RCS-Conversation-Started`).
- `events`: Set to `CONVERSATION_STARTED` to receive notifications when an end user initiates a conversational session.
- `resources`: Specify your RCS sender name.
- `profile`: Notification profile with the webhook URL and security settings. You can create a new notification profile by providing details as described in the API schema, or pass in an existing `profileId` to reuse a previously created profile.

To set up webhooks from the [Infobip web interface](https://www.infobip.com/signup) instead of the API, refer to the [Create and manage subscriptions](https://www.infobip.com/docs/cpaas-x/subscriptions-management/create-manage-subscriptions) documentation.

## Step 2: Send an RCS message

After the subscription is created, send an RCS message to initiate a conversation. The message must be sent from an RCS sender with the Billing category set to Conversational.

```bash
curl -X POST "https://{YOUR_BASE_URL}/rcs/2/messages" \
-H "Authorization: App {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "sender": "YOUR_RCS_SENDER",
      "destinations": [
        {
          "to": "YOUR_DESTINATION_NUMBER"
        }
      ],
      "content": {
        "text": "Hello! Reply to this message to start a conversation.",
        "type": "TEXT"
      },
      "webhooks": {
        "delivery": {
          "url": "YOUR_WEBHOOK_URL",
          "intermediateReport": true,
          "notify": true
        }
      }
    }
  ]
}'
```

```json
{
  "messages": [
    {
      "to": "YOUR_DESTINATION_NUMBER",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ACCEPTED",
        "description": "Message sent to next instance"
      },
      "messageId": "msg_12345678-1234-5678-9012-123456789abc"
    }
  ]
}
```

## Step 3: Handle webhook notifications

After sending the RCS message, your webhook endpoint receives notifications at different stages of the conversation lifecycle.

### Delivery report with conversation metadata

When the RCS message is delivered, the delivery report includes a new `conversation` parameter:

```json
{
  "results": [
    {
      "messageId": "msg_12345678-1234-5678-9012-123456789abc",
      "to": "YOUR_DESTINATION_NUMBER",
      "sender": "YOUR_RCS_SENDER",
      "sentAt": "2026-05-22T10:00:00.000+0000",
      "doneAt": "2026-05-22T10:00:01.000+0000",
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "conversation": {
        "canInitiate": true,
        "id": null
      }
    }
  ]
}
```

The `conversation` object indicates:

- `canInitiate: true` means the message is not part of an active conversation and can start one.
- `id: null` means no conversation session exists yet.

### CONVERSATION_STARTED event

When the end user replies to the message, a conversational session begins. The `CONVERSATION_STARTED` event is triggered on your webhook, along with the traffic type:

```json
{
  "results": [
    {
      "messageId": "msg_12345678-1234-5678-9012-123456789abc",
      "trafficType": "A2P_CONVERSATION",
      "event": {
        "type": "CONVERSATION_STARTED"
      },
      "conversation": {
        "type": "A2P",
        "id": "3b87aaa2-0809-44c5-9a57-154fdc4ac97d",
        "timeWindow": {
          "startTime": "2026-05-22T10:05:00.000+0000",
          "endTime": "2026-05-23T10:05:00.000+0000"
        }
      }
    }
  ],
  "eventCount": 1,
  "pendingEventCount": 0
}
```

The `trafficType` indicates the billing classification:

- `A2P_CONVERSATION`: Application-to-person, the business initiated the conversation.
- `P2A`: Person-to-application, the end user initiated the conversation.

For more information about billing, refer to [RCS global billing types](https://www.infobip.com/docs/rcs/billing-types/global-billing-types).

### Subsequent delivery reports

After a conversation starts, delivery reports for new messages include the conversation ID:

```json
{
  "results": [
    {
      "messageId": "msg_87654321-4321-8765-2109-cba987654321",
      "to": "YOUR_DESTINATION_NUMBER",
      "sender": "YOUR_RCS_SENDER",
      "sentAt": "2026-05-22T10:10:00.000+0000",
      "doneAt": "2026-05-22T10:10:01.000+0000",
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "conversation": {
        "canInitiate": false,
        "id": "3b87aaa2-0809-44c5-9a57-154fdc4ac97d"
      }
    }
  ]
}
```

The `conversation` object now shows:

- `canInitiate: false` means the message is part of an active conversation.
- `id` contains the unique conversation identifier.

## Implementation outcome [#outcome]

After completing this tutorial, your system will automatically receive real-time notifications when:

- An RCS message is delivered, including whether it can initiate a conversation.
- An end user replies and starts a conversational session (`CONVERSATION_STARTED` event).
- Subsequent messages are part of an active conversation, identified by the conversation ID.

## Additional resources [#additional-resources]

- [Set up webhook notifications for messaging events](https://www.infobip.com/docs/tutorials/set-up-webhook-notifications-for-messaging-events) — covers delivery, seen, inbound, and typing indicator webhooks
- RCS API reference
- [RCS documentation](https://www.infobip.com/docs/rcs)
- [RCS billing types](https://www.infobip.com/docs/rcs/billing-types/global-billing-types)
- [Subscription management](https://www.infobip.com/docs/cpaas-x/subscriptions-management)
- [Response status and error codes](https://www.infobip.com/docs/essentials/api-essentials/response-status-and-error-codes)
- [Broadcast](https://www.infobip.com/docs/broadcast)
- Infobip SDKs