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.

Products and channels

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

Prerequisites

• Infobip account. If you do not have an account, sign up (opens in a new tab) 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 (opens in a new tab).
• HTTP client for making API requests. This tutorial uses cURL, but you can use any HTTP client or the official Infobip SDK (opens in a new tab) 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

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 (opens in a new tab) 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.

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"
      }
    }
  }
}'

{
  "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 (opens in a new tab), or pass in an existing profileId to reuse a previously created profile.

Step 2: Send an RCS message

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

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
        }
      }
    }
  ]
}'

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

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

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

Subsequent delivery reports

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

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

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

• Set up webhook notifications for messaging events — covers delivery, seen, inbound, and typing indicator webhooks
• RCS API reference (opens in a new tab)
• RCS documentation
• RCS billing types
• Subscription management
• Response status and error codes
• Broadcast
• Infobip SDKs (opens in a new tab)