Set up the RCS CONVERSATION_STARTED webhook event

View as Markdown

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.

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 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.
HTTP client for making API requests. This tutorial uses cURL, but you can use any HTTP client or the official Infobip SDK 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]

Create a subscription and notification profile for the CONVERSATION_STARTED event.
Send an RCS message to initiate a conversation.
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 documentation.

Create subscription endpoint

json

1curl -X POST "https://{YOUR_BASE_URL}/subscriptions/1/subscription/RCS" \

2-H "Authorization: App {YOUR_API_KEY}" \

3-H "Content-Type: application/json" \

4-d '{

5 "subscriptionId": "RCS-Conversation-Started",

6 "name": "RCS Conversation Started Webhook",

7 "events": [

8 "CONVERSATION_STARTED"

9 ],

10 "resources": [

11 "YOUR_RCS_SENDER"

12 ],

13 "profile": {

14 "profileId": "NOTIF-RCS_CONV",

15 "webhook": {

16 "notifyUrl": "YOUR_WEBHOOK_URL"

17 },

18 "security": {

19 "authId": "BASIC_auth",

20 "type": "BASIC",

21 "credentials": {

22 "username": "YOUR_USERNAME",

23 "password": "YOUR_PASSWORD"

24 }

25 }

26 }

27}'

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 instead of the API, refer to the Create and 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.

Send RCS message endpoint

json

1curl -X POST "https://{YOUR_BASE_URL}/rcs/2/messages" \

2-H "Authorization: App {YOUR_API_KEY}" \

3-H "Content-Type: application/json" \

4-d '{

5 "messages": [

6 {

7 "sender": "YOUR_RCS_SENDER",

8 "destinations": [

9 {

10 "to": "YOUR_DESTINATION_NUMBER"

11 }

12 ],

13 "content": {

14 "text": "Hello! Reply to this message to start a conversation.",

15 "type": "TEXT"

16 },

17 "webhooks": {

18 "delivery": {

19 "url": "YOUR_WEBHOOK_URL",

20 "intermediateReport": true,

21 "notify": true

22 }

23 }

24 }

25 ]

26}'

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

2 "results": [

3 {

4 "messageId": "msg_12345678-1234-5678-9012-123456789abc",

5 "to": "YOUR_DESTINATION_NUMBER",

6 "sender": "YOUR_RCS_SENDER",

7 "sentAt": "2026-05-22T10:00:00.000+0000",

8 "doneAt": "2026-05-22T10:00:01.000+0000",

9 "status": {

10 "groupId": 3,

11 "groupName": "DELIVERED",

12 "id": 5,

13 "name": "DELIVERED_TO_HANDSET",

14 "description": "Message delivered to handset"

15 },

16 "conversation": {

17 "canInitiate": true,

18 "id": null

19 }

20 }

21 ]

22}

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

2 "results": [

3 {

4 "messageId": "msg_12345678-1234-5678-9012-123456789abc",

5 "trafficType": "A2P_CONVERSATION",

6 "event": {

7 "type": "CONVERSATION_STARTED"

8 },

9 "conversation": {

10 "type": "A2P",

11 "id": "3b87aaa2-0809-44c5-9a57-154fdc4ac97d",

12 "timeWindow": {

13 "startTime": "2026-05-22T10:05:00.000+0000",

14 "endTime": "2026-05-23T10:05:00.000+0000"

15 }

16 }

17 }

18 ],

19 "eventCount": 1,

20 "pendingEventCount": 0

21}

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.

Subsequent delivery reports

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

json

2 "results": [

3 {

4 "messageId": "msg_87654321-4321-8765-2109-cba987654321",

5 "to": "YOUR_DESTINATION_NUMBER",

6 "sender": "YOUR_RCS_SENDER",

7 "sentAt": "2026-05-22T10:10:00.000+0000",

8 "doneAt": "2026-05-22T10:10:01.000+0000",

9 "status": {

10 "groupId": 3,

11 "groupName": "DELIVERED",

12 "id": 5,

13 "name": "DELIVERED_TO_HANDSET",

14 "description": "Message delivered to handset"

15 },

16 "conversation": {

17 "canInitiate": false,

18 "id": "3b87aaa2-0809-44c5-9a57-154fdc4ac97d"

19 }

20 }

21 ]

22}

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 — covers delivery, seen, inbound, and typing indicator webhooks
RCS API reference
RCS documentation
RCS billing types
Subscription management
Response status and error codes
Broadcast
Infobip SDKs