---
# System prepended metadata

title: Custom Live Agent API Specification

---

---
title: Custom Live Agent API Specification
sidebar_label : Custom Live Agent
---

# Custom Live Agent API Specification

This document elaborates on the integration approach for a custom live agent to integrate with Yellow. The following are the major use cases covered in this document: 
1. End Customer wants to talk to an agent
2. End Customer sends Text/Image/Video/PDF ( or other media) to the Agent
3. The interaction details updated to end customer through ticket ID & details
4. Additional information about Agent Availability ( Queue Status, Typing status etc)
5. Agent connection established
6. Two-way communication between the end customer and agent
7. Closure of the ticket

## 1. Design principles

1. The integration approach is defined to be channel agnostic, the 3rd party system should consider Yellow as the channel and Yellow will ensure that the end customer connects with an agent from any channel ( Web, WhatsApp etc.) 
2. Details of the end customer’s channel will be transferred to the 3rd party system for proper reconciliation. 
3. The receiving system should be able to define custom parameters for their consumption and as needed for the business use case. 

### 1.1 Workflow Diagram


![](https://i.imgur.com/FCyWNDp.png)


## 2. Business Use Cases

### 2.1 Initiate Conversations 

An end customer who uses the bot, will encounter the following action while connecting with a live agent

1. Bot gives an option to connect to a Live Agent.
2. Bot goes into a paused state once the agent gets connected.
3. When the bot is in paused state, the 2-way communication between the agent and end customer takes place. 
4. Once the agent ends the conversation, the bot takes over. 

The following are the business use cases that should be supported by the third-party tool to enable this conversation:

| # | Use-case | Required |Remarks|
| -------- | -------- | -------- |----|
| 1     | Send Message {text + media}       |   Yes   |Chat history will be present in the first message as a link  |
|2|Send typing event|No|
|3|Create Ticket |Yes|Response should contain ticketIDScenarios ( Ticket Lifecycle)  <br/>1. Request is in queue <br/>2. Ticket is created & OPEN <br/>3. Ticket is created & ASSIGNED<br/> |
|4|User details {Channel ID, Sender ID, Unique ID}|Yes|
|5|Transfer to a particular group|No|Department wise, as per business need|
|6| Ability to pass custom parameter|Yes|
|7|Is User Active| No|
|8|Custom Parameters|Yes|Ability to pass custom parameters as per business need|


### 2.2 Enable conversation

The following are the use cases & details required for a two-way communication between a third party system & Yellow.

:::note
For this, Yellow’s webhook must be configured at third party systems end.
:::

|S.no| Type| Required | Remarks |
|------|----|--------|--------|
|1|Event name/code specification|Yes|
|2|Agent message {text + media}|Yes|
|3|Agent assigned{along with agent details}|Yes|Agent details like agent name, department should be received
|4|Queue Positioning|No|
|5|Closed ticket|Yes|Closed ticket event|
|6|Updation of any ticket detail (e.g. transferred to another agent)|No|
|7|Is Agent active?|No|

---


## 3. API Specification

The header that will be common across all the APIs which the third party needs to create is an auth token:

```
Authorization: {{token}}
Content-type: application/json
```

### 3.1 Create Ticket 

|URL|{{domainName}}/createTicket/{{companyName}}|
|---|---|
|METHOD|POST|


#### Body Parameters

|Name|Data type|Description|Mandatory|
|---|---|---|---|
|senderId|string|Unique identifier of the user generated by Yellow.AI|Y|
|messageId|string|Unique identifier of every sent message|Y|
|source|string|Channel from where the message can be sent|Y|
|conversationId|string|Unique identifier of this conversation|Y|
|userName|string|Name of the user/customer|Y|
|userMobile|string|Mobile number of the user, accepts 10 digit mobile number|Y|
|userEmail|string|Email Id of the user|Y|
|conversationHistory|string|The URL of the conversation prior to connecting to the agent|Y|
|ticketPriority|string|Priority of the ticket, possible values low/medium/high|Y|
|ticketCategory|string|Category to which a ticket may belong|N|
|ticketGroupId|string|If we want the ticket to get assigned to a particular group of agents, we need to add this|N|
|customFields|object| Use this if any custom key value pairs need to be passed. The data type of the values can be string/number/boolean/object|N|
|conversationHistoryJSON| array| The JSON of the conversation prior to connecting to the agent| N| 

#### CURL

```
curl --location --request POST '{{domainName}}createTicket/{{companyName}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "body": {
        "user": {
            "userName": "Shubh",
            "userMobile": "99999999",
            "senderId": "11111111211111",
            "userEmail": "test@gmail.com"
        },
        "ticket": {
            "conversationHistory": "https://google.com",
 	"source": "web",
            "ticketPriority": "medium",
            "ticketCategory": "sales",
            "conversationId": "efrfrfrfr",
            "ticketGroupId":  "14343", 
            "customFields": {}
           }
        }
}'


```
Click [here](http://localtest.locobuzz.com/Webhook/RoyalEnfieldChatbot) for {{domainName}}createTicket

#### Response

```
{
status: success/failure
data: {ticketId: 25633, isAgentAvailable: true/false, isQueued: true/false }
message: <Description of Error/ Success Message>
} 
 
```
:::note
If queuing is enabled, the createTicket API should respond isAgentAvailable flag as false and isQueued flag as true.
:::


### 3.2 Send Message to Agent

|URL|{{domainName}}sendMessage/{{companyName}}|
|---|---|
|METHOD|POST|

#### Body Parameters

|Name|Data type|Description|Mandatory|
|---|---|---|---|
|senderId|string|Unique identifier of the user generated by Yellow.ai|Y|
|userName|string|Name of the user|Y|
|userEmail|string|Email Id of the user|N|
|message|string|Message sent by the user|Y|
|messageId|string|Unique identifier of every sent message|Y|
|ticketId|string|Generated ticketId from API 1|Y|
|source|string|Channel in which the message can be sent|Y|
|conversationId|string|Unique identifier of this conversation|Y|
|messageType|string|Type of the message sent,the value will be **text**|Y|


#### CURL

```
curl --location --request POST '{{domainName}}sendMessage/{{companyName}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "body": {
        “user”:{
         “senderId”: “11111”,
         “userName”: “Mahesh”,
        “userEmail”: “test@gmail.com”
         }
        "ticket": {
           “messageType”: “text”,
            “message”: “hello”
            “messageId”: “efefe-eefe-fefef-feefefe”,
            “ticketId”: “275333”,
             “source”: “web”,
            “conversationId” : “yguyegdee”
           }
        }
}'

```

Refer [here](http://localtest.locobuzz.com/Webhook/RoyalEnfieldChatbot) for {{domainName}}sendMessage/

#### Response

``` 
{
“status”: “success/failure”
“data”: {ticketId: 25633}
“message”: “<Description of Error/ Success Message>”
}
 

```

### 3.3 Send User Media to Agent

|URL|{{domainName}}sendMedia/{{companyName}}|
|---|---|
|METHOD|POST|


#### Body Parameters

|Name|Data type|Description|Mandatory|
|---|---|---|---|
|senderId|string|Unique identifier of the user generated by Yellow.AI|Y|
|userName|string|Name of the user| Y|
|userEmail|string|Email Id of the user| N|
|mediaJson|object|Has two properties. The first property is “type”, and its possible values are image/video/file. The second property is “url” which will have the url of the media|Y|
|messageId|string|Unique identifier of every sent message|Y|
|ticketId|number|Generated ticketId from API 1|Y|
|source|string|Channel in which the message is sent|Y|
|conversationId|string|Unique identifier of this conversation|Y|
|messageType|string|Type of the message sent, the value will be media|Y|

#### CURL

```
curl --location --request POST '{{domainName}}sendMedia/{{companyName}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "body": {
        “user”:{
         “senderId”: “11111”,
         “userName”: “Mahesh”,
        “userEmail”: “test@gmail.com”
         }
        "ticket": {
           “messageType”: “media”,
            “mediaJson”: {“type”:”image/video/file”,“url”: “https://image.com”},
            “messageId”: “efefe-eefe-fefef-feefefe”,
            “ticketId”: “275333”,
             “source”: “web”,
            “conversationId” : “yguyegdee”
           }
        }
}'

```

Click [here](http://localtest.locobuzz.com/Webhook/RoyalEnfieldChatbot) for {{domainName}}sendMedia/.

#### Response

```
{
“status”: “success/failure”,
“data”: {ticketId: 25633}
“message”: “<Description of Error/ Success Message>”
}

```

## 4. Webhook

| URL  | https://cloud.yellow.ai/integrations/genericIntegration/custom-live-agent  |
| ---- | -------- |
| Method | POST     |
|x-auth-token|Will be provided by yellow|
|Response Code|200|

:note
 You need to append the region of your bot to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your bot, you can also refer the following list for the same.

* r1 = MEA
* r2 = Jakarta
* r4= USA
* r5 = Europe
* r3 = Singapore


For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to India, you can use origin domain itself.
:::

### 4.1 Text message sent by the agent 

**Event**
- Text message sent by the agent

**Payload**
```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "payload-received-from-agent"
"message": {
"type": "text”,
"payLoad": {
"content": "Hello"
}
}
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}


```
**Response**

```
{
“status”: “success”,
data: {"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "payload-received-from-agent"
"message": {
"type": "text”,
"payLoad": {
"content": "Hello"
}
}
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
},
message: <Description of Error/ Success Message>
}


```

### 4.2 Media message sent by the Agent  

**Event**
- Media message sent by the Agent 


**Payload**
```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "payload-received-from-agent"
"message": {
"type": "media",
"payLoad": {
"content": {“type”: “image/video/file”, “mediaUrl”: “https://www.google.com”}
}
}
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}

```

**Response**
```
{
status: success
data: {"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "payload-received-from-agent"
"message": {
"type": "media”,
"payLoad": {
"content": {“type”: “image/video/file”, “mediaUrl”: “https://www.google.com”}
}
}
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
},
message: <Description of Error/ Success Message>
}

```

### 4.3 Ticket assignment to the agent 

**Event**
- Ticket assignment to the agent 


**Payload**
```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "ticket-assigned"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}


```
**Response**

```
{
status: success
data: {"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "ticket-assigned"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
message: <Description of Error/ Success Message>
}

```

### 4.4 Closure of ticket

**Event**
- Closure of ticket


**Payload**

```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "ticket-closed"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"ticketResolvedTime": 4545454
}

```
**Response**
```
{
status: success
data: {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "ticket-closed"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"ticketResolvedTime": 4545454}
message: <Description of Error/ Success Message>
}


```

### 4.5 Agent Logout during the conversation (After Working hours) 

**Event**
- Agent Logout during the conversation (After Working hours)


**Payload**
```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "agent-logout"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}


```
**Response**
```
{
status: success
data: {"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "agent-logout"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454}
message: <Description of Error/ Success Message>
}

```


### 4.6. Agent Logged In but not active in the conversation 

**Event**
- Agent Logged In but not active in the conversation 


**Payload**

```
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "agent-inactivity"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"inactivityDuration": 120,
"inactivityReason": "Network issue"
}

```
**Response**

```
{
status: success/failure
data: {"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4"
"event": "agent-inactivity"
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"inactivityDuration": 120,
"inactivityReason": "Network issue"}
message: <Description of Error/ Success Message>
}


```





