# Live Stream Chat API V3 — Developer Guide

- **Applies to:** Sprinklr Live Stream Chat API V3 (`/api/v3/liveChat/event`)
- **V2 API reference:** [Live Stream Chat APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/live-stream-chat)


## 1. Overview

A Sprinklr Live Stream Chat Event represents a real-time messaging session attached to a live video or product launch.
It allows brands to engage with customers during live broadcasts, capture conversations, and manage event lifecycle (create, fetch, update, start, stop).

**Live Stream Chat V3 exposes full CRUD on a single resource path — `/api/v3/liveChat/event` — differentiated by HTTP method:**

| **Operation** | **Method** | **Path** |
|  --- | --- | --- |
| Create event | POST | `/api/v3/liveChat/event` |
| Get event | GET | `/api/v3/liveChat/event?eventId=` or `?eventIds=` |
| Update event (full replace) | PUT | `/api/v3/liveChat/event?eventId={id}` |
| Update event (partial) | PATCH | `/api/v3/liveChat/event?eventId={id}` |
| Delete event | — | Not exposed in V3 |


This is the central design change from V2, which spread the same capabilities across multiple endpoints (`create-or-update-live-stream-event`, `fetch-live-stream-event`, `start-live-stream-event`, `end-live-stream-event`).

## 2. Base URLs and environments

All API calls are sent to the production endpoint:

```
https://api3.sprinklr.com/{env}/api/v3
```

So the live chat resource in production is:

```
https://api3.sprinklr.com/{env}/api/v3/liveChat/event
```

Replace `{env}` with your assigned environment identifier (`prod0`, `prod2`, etc.).

## 3. Authentication and common headers

All Live Chat API calls are authenticated with OAuth 2.0.

| Header | Value | Purpose | Required on |
|  --- | --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Authenticates the user with the server | All requests |
| `Key` | `{{apiKey}}` | Authenticates the application with the server | All requests |
| `Content-Type` | `application/json` | Declares the request body media type | All requests |
| `Accept` | `application/json` | Declares the acceptable response type | All requests |


## 4. Write Operations

### 4.1 Create a Live Chat Event

**`POST /api/v3/liveChat/event`**

Creates a new live chat event for sending or receiving messages.

#### Request Parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required for updating | Live stream event ID. Note: Only used when updating an existing event. | String |
| name | Required | Live stream event name | String |
| startTime | Required | Starting time of the live stream event | Long |
| endTime | Required | Ending time of the live stream event | Long |
| chatApplicationId | Required | Unique identifier for the live chat application. Must be a valid application ID. | String |


#### Steps to extract Chat Application ID and Event ID from Sprinklr UI

1. In **Sprinklr Service > Listen**, select **Live Stream Care**.
2. The section displays all available live stream events.
3. Find the event you want and click the **three‑dots (⋮)** icon next to its name.
4. From the drop‑down menu, choose **Embed**.
5. The embed code appears.
6. From this code, extract the **Chat Application ID** and the **Stream Event ID**.


#### Example Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "BR Test Stream New",
  "startTime": 1781246718000,
  "endTime": 1781346918000,
  "chatApplicationId": "app_66000112"
}'
```

### 4.2 Update a Live Chat Event

**`PUT /api/v3/liveChat/event?eventId={id}`**

Updates details of a live chat event.

#### Query parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| eventId | Required | Live stream event ID. This is the live chat stream ID you received in the Create Live Chat Event API response. You can also get this ID from the Sprinklr UI. | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required for updating | Live stream event ID. Note: Only used when updating an existing live chat event. | String |
| name | Required | Live stream event name | String |
| startTime | Required | Starting time of the live stream event | Long |
| endTime | Required | Ending time of the live stream event | Long |
| chatApplicationId | Required | Refers to the unique identifier for the live chat application. Must be a valid live chat application ID. | String |


#### Example Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event?eventId=6a8f9511c7c795c9441a70fa' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "id": "6a8f9511c7c795c9441a70fa",
  "name": "BR Test Stream Updated",
  "startTime": 1791070319000,
  "endTime": 1791246718000,
  "chatApplicationId": "app_66000112"
}'
```

### 4.3 Patch Live Chat Event

**`PATCH /api/v3/liveChat/event?eventId={id}`**

Updates the status of a live chat event.

#### Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| eventId | Required | Live stream event ID. This is the live chat stream ID you received in the Create Live Chat Event API response. You can also get this ID from the Sprinklr UI (see steps below). | String |


#### Request Body Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| streamStatus | Required | Status of the live chat stream. **Supported Values:** `SCHEDULED`, `IN_PROGRESS`, `STOPPED`. | String |


### Status Behavior Notes

- **STOPPED**: When the event status is updated to `STOPPED`, the system automatically sets the **endTime** to the current time.
- **IN_PROGRESS**: To update an event to `IN_PROGRESS`, the event must currently be in `SCHEDULED` status (future start time). Once updated, the system automatically sets the **startTime** to the current time.


#### Example Request — Start Event

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event?eventId=6a8f9511c7c795c9441a70fa' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "streamStatus": "IN_PROGRESS"
}'
```

#### Example Request — End Event

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event?eventId=6a8f9511c7c795c9441a70fa' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "streamStatus": "STOPPED"
}'
```

## 5. Read Operations

### 5.1 GET — Fetch Live Stream Chat Event

Using this API, you can fetch a single chat event for the given live chat stream ID.

**API Endpoint**

```
https://api3.sprinklr.com/{env}/api/v3/liveChat/event
```

#### Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| eventId | Required | Live stream event ID. This is the live chat stream ID you received in the Create Live Chat Event API response. You can also get this ID from the Sprinklr UI. | String |


#### Steps to extract Chat Application ID and Event ID from Sprinklr UI

1. In **Sprinklr Service > Listen**, select **Live Stream Care**.
2. The section displays all available live stream events.
3. Find the event you want and click the **three‑dots (⋮)** icon next to its name.
4. From the drop‑down menu, choose **Embed**.
5. The embed code appears.
6. From this code, extract the **Chat Application ID** and the **Stream Event ID**.


#### Example Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event?eventId=6a8f9511c7c795c9441a70fa' \
--header 'Authorization: Bearer {Enter your Access Token}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json'
```

### 5.2 GET — Fetch Bulk Live Stream Chat Events

Using this API, you can fetch multiple chat events for the given live chat stream IDs.

**API Endpoint**

```
https://api3.sprinklr.com/{env}/api/v3/liveChat/event
```

#### Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| eventIds | Required | Provide all event IDs as a comma‑separated list. This is the live chat stream ID you received in the Create Live Chat Event API response. You can also get this ID from the Sprinklr UI. | String |


#### Example Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/liveChat/event?eventIds=6a28fa36dea489ac372bc154,6a292953190af7da16bbf439,6a292c63190af7da16bda5ed,6a292c7ce1b8b9fd832cba95' \
--header 'Authorization: Bearer {Enter your Access Token}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json'
```

## 5. Response format and parameters

{
"data": { ... },
"errors": []
}

| **Field** | **Type** | **Description** |
|  --- | --- | --- |
| data | Object/Array | Event object(s) returned |
| errors | Array | Error messages (empty if none) |


### Event object fields

Each event object inside `data` contains the following fields:

| **Parameter** | **Description** | **Type** |
|  --- | --- | --- |
| id | Unique identifier for the live stream chat event | String |
| name | Name of the live stream chat event | String |
| startTime | Starting time of the live stream chat event | Long |
| endTime | Ending time of the live stream chat event | Long |
| streamStatus | Status of the live chat stream. Examples: `SCHEDULED`, `STOPPED`, `IN_PROGRESS`. | String |
| chatApplicationId | Unique chat application ID of the live chat present on Sprinklr | String |


### Example — Single Event Response

```json
{
    "data": {
        "id": "6a8f9511c7c795c9441a70fa",
        "name": "Test Stream-Deepak02",
        "startTime": 1781070319000,
        "endTime": 1781246718000,
        "streamStatus": "STOPPED",
        "chatApplicationId": "app_66000112"
    },
    "errors": []
}
```

### Example — Bulk Event Response

```json
{
    "data": [
        {
            "id": "6a292953190af7da16bbf439",
            "name": "Test Stream-Deepak02",
            "startTime": 1781070319000,
            "endTime": 1781246718000,
            "streamStatus": "STOPPED",
            "chatApplicationId": "app_66000112"
        },
        {
            "id": "6a292c63190af7da16bda5ed",
            "name": "Test Stream-Deepak02",
            "startTime": 1781070318000,
            "endTime": 1781246718000,
            "streamStatus": "STOPPED",
            "chatApplicationId": "app_66000112"
        }
    ],
    "errors": []
}
```

## 6. Response codes

| **HTTP Code** | **Scenario** | **Description** |
|  --- | --- | --- |
| 200 OK | Success | Operation executed successfully |
| 400 Bad Request | Invalid Parameters | Missing or invalid request parameters |
| 401 Unauthorized | Authentication Failed | Invalid or missing Authorization token |
| 403 Forbidden | Insufficient Permissions | User lacks permission |
| 404 Not Found | Resource Missing | Event not found |
| 500 Internal Server Error | Server Error | Unexpected server‑side error occurred |


## 7. Migration from V2 to V3

The Live Stream Chat APIs have been redesigned in V3 for consistency and clarity.
Here’s a comparison of V2 vs V3 endpoints and behavior:

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Create/Update Event | `POST /api/v2/live-chat/create-or-update-live-stream-event` | `POST /api/v3/liveChat/event` (create) / `PUT /api/v3/liveChat/event?eventId={id}` (update) | V2 combined create/update into one POST; V3 separates into POST (create) and PUT (update). |
| Fetch Single Event | `GET /api/v2/live-chat/fetch-live-stream-event/{id}` | `GET /api/v3/liveChat/event?eventId={id}` | Path parameter in V2 vs query parameter in V3. |
| Fetch Multiple Events | `POST /api/v2/live-chat/fetch-live-stream-events` | `GET /api/v3/liveChat/event?eventIds={id1,id2,...}` | V2 used POST with body; V3 uses GET with comma-separated query parameter. |
| Start Event | `GET /api/v2/live-chat/start-live-stream-event/{id}` | `PATCH /api/v3/liveChat/event?eventId={id}` with `streamStatus=IN_PROGRESS` | Lifecycle control unified under PATCH in V3. |
| End Event | `GET /api/v2/live-chat/end-live-stream-event/{id}` | `PATCH /api/v3/liveChat/event?eventId={id}` with `streamStatus=STOPPED` | Lifecycle control unified under PATCH in V3. |