# Callback Voice API V3 - Developer Guide

## 1. Overview

The Callback Voice API enables you to update an existing callback request, schedule a callback request for a customer phone number, and cancel an existing callback request.

| Operation | Method | Endpoint |
|  --- | --- | --- |
| Update Callback Voice | PUT | `/api/v3/voice/callback?taskId={taskId}` |
| Schedule Callback Voice | POST | `/api/v3/voice/callback` |
| Cancel Callback Request | POST | `/api/v3/voice/cancel-callback?taskId={taskId}` |


## 2. Base URL and environment

All API calls are sent to:

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

So the Callback resources in production are:

```
https://api3.sprinklr.com/{env}/api/v3/voice/callback
https://api3.sprinklr.com/{env}/api/v3/voice/cancel-callback
```

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

## 3. Authentication and common headers

API headers include the mandatory information sent with the request URL and body. This information provides the request context and authorisation credentials required to access protected resources.

| Key | Value | Description |
|  --- | --- | --- |
| Authorization | `Bearer {token}` | Credential used by the API to authenticate a user with the server. |
| Key | `api-key` | API key used to authenticate the application with the server. |
| Content-Type | `application/json` | Determines the media type of the request body. |
| Accept | `application/json` | Determines the acceptable response type from the server. |


## 4. API operations

### 4.1 Update Callback Voice

**PUT `/api/v3/voice/callback?taskId={taskId}`**

Use this API to update an existing callback request.

#### Query parameters

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| taskId | Required | Unique identifier of the callback request to update. | String |


#### Request parameters

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| campaignId | Required | Unique identifier of the campaign associated with the callback request. | String |
| phoneNumber | Required | Customer phone number associated with the callback request. | String |
| workQueueId | Required | Unique identifier of the work queue where the callback request will be routed. | String |
| workQueueName | Optional | Name of the work queue associated with the callback request. | String |


#### Example request

```bash
curl -X PUT \
  'https://api3.sprinklr.com/{env}/api/v3/voice/callback?taskId={taskId}' \
  -H 'Authorization: Bearer {Enter your Access Token}' \
  -H 'Key: {Enter your API KEY}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "campaignId": "66000002_8109",
    "phoneNumber": "+911234567891",
    "workQueueId": "6a74bc57cdd721d009417358",
    "workQueueName": " WorkQueue-Mithilesh Qa6"
  }'
```

#### Example response

```json
{
  "data": {
    "taskId": "6a755b2d2588ae8f2fe87702"
  },
  "errors": []
}
```

#### Response parameters

| Parameter | Sub-parameter | Description | Type |
|  --- | --- | --- | --- |
| data |  | Contains details of the updated callback request. | Object |
|  | taskId | Unique identifier of the callback task. | String |
| errors |  | Contains errors encountered during request processing, if any. | Array |


### 4.2 Schedule Callback Voice

**POST `/api/v3/voice/callback`**

Use this API to schedule a callback request for a customer phone number and associate it with a work queue.

#### Request parameters

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| campaignId | Required | Unique identifier of the campaign associated with the callback request. | String |
| phoneNumber | Required | Customer phone number for which the callback request is created. | String |
| workQueueId | Required | Unique identifier of the work queue where the callback request will be routed. | String |
| workQueueName | Optional | Name of the work queue associated with the callback request. | String |


#### Example request

```bash
curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/voice/callback' \
  -H 'Authorization: Bearer {Enter your Access Token}' \
  -H 'Key: {Enter your API KEY}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "campaignId": "66000002_8109",
    "phoneNumber": " +911234567891",
    "workQueueId": "6a74bc57cdd721d009417358",
    "workQueueName": " WorkQueue-S Qa6"
  }'
```

#### Example response

```json
{
  "data": {
    "taskId": "6a756d2d7496d1dc4e4c9f21"
  },
  "errors": []
}
```

#### Response parameters

| Parameter | Sub-parameter | Description | Type |
|  --- | --- | --- | --- |
| data |  | Contains details of the created callback request. | Object |
|  | taskId | Unique identifier of the callback task created by the system. | String |
| errors |  | Contains errors encountered during request processing, if any. | Array |


### 4.3 Cancel Callback Request

**POST `/api/v3/voice/cancel-callback?taskId={taskId}`**

Use this API to cancel an existing callback request.

#### Query parameters

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| taskId | Required | Unique identifier of the callback request to cancel. | String |


#### Example request

```bash
curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/voice/cancel-callback?taskId={taskId}' \
  -H 'Authorization: Bearer {Enter your Access Token}' \
  -H 'Key: {Enter your API KEY}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
```

#### Example response

```http
HTTP/1.1 204 No Content
```

#### Response parameters

| Parameter | Description | Type |
|  --- | --- | --- |
| HTTP Status Code | Indicates the result of the cancel operation. | Integer |
| 204 No Content | Indicates that the callback request was successfully cancelled. | Status Code |


### 5. Use cases

The Callback Voice API can be used to manage customer callback requests throughout their lifecycle. The following are common use cases.

#### 5.1 Schedule a customer callback

Use the **Schedule Callback Voice** API to create a callback request for a customer and route it to the appropriate work queue.

This is useful when:

- A customer requests a callback instead of waiting for an available agent.
- A callback needs to be associated with a specific campaign.
- The callback needs to be routed to a specific work queue for handling.


**API:** `POST /api/v3/voice/callback`

#### 5.2 Update an existing callback request

Use the **Update Callback Voice** API when an existing callback request needs to be modified.

This is useful when:

- The customer phone number associated with a callback request needs to be updated.
- The campaign associated with the callback request needs to be changed.
- The callback request needs to be routed to a different work queue.
- The work queue information associated with the callback request needs to be updated.


The callback request is identified using its unique `taskId`.

**API:** `PUT /api/v3/voice/callback?taskId={taskId}`

#### 5.3 Cancel a callback request

Use the **Cancel Callback Request** API when a previously created callback request is no longer required.

This is useful when:

- A customer no longer requires a callback.
- A callback request was created incorrectly or is no longer valid.
- An application needs to remove a pending callback request as part of its callback management workflow.


The callback request to cancel is identified using its unique `taskId`.

**API:** `POST /api/v3/voice/cancel-callback?taskId={taskId}`

#### 5.4 Manage the callback request lifecycle

The Callback Voice APIs can be used together to manage the lifecycle of a callback request.

A typical workflow can include:

1. **Schedule the callback** using `POST /api/v3/voice/callback`.
2. Store the `taskId` returned when the callback request is created.
3. **Update the callback** using `PUT /api/v3/voice/callback?taskId={taskId}` if the callback details need to change.
4. **Cancel the callback** using `POST /api/v3/voice/cancel-callback?taskId={taskId}` if the callback is no longer required.


## 6. Migration from V2 to V3

The Voice Callback APIs have been reorganised in **V3** so that HTTP methods, rather than URL action names, express intent. Below is a comparison of **V2 vs V3 endpoints and behavior**:

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Schedule Callback | `POST /api/v2/voice/schedule-callback` | `POST /api/v3/voice/callback` | Path changes only; the method stays POST. |
| Update Callback | `POST /api/v2/voice/update-callback` | `PATCH /api/v3/voice/callback?taskId={taskId}` | Method changes from POST to PATCH. `taskId` is added to the query string and remains required in the body. `campaignId`, `workQueueId` and `workQueueName` are no longer updatable. |
| Cancel Callback | `POST /api/v2/voice/cancel-callback` | `POST /api/v3/voice/cancel-callback?taskId={taskId}` | `taskId` moves from the request body to the query string, and the request body is dropped. Method and action name are unchanged. |