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:
- End Customer wants to talk to an agent
- End Customer sends Text/Image/Video/PDF ( or other media) to the Agent
- The interaction details updated to end customer through ticket ID & details
- Additional information about Agent Availability ( Queue Status, Typing status etc)
- Agent connection established
- Two-way communication between the end customer and agent
- Closure of the ticket
Use Ticket-closed in the Raise Ticket node to perform specific actions when a live chat closes, instead of using the ticket-close event.
1. Design principles
- 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.)
- Details of the end customer’s channel will be transferred to the 3rd party system for proper reconciliation.
- 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
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
- Bot gives an option to connect to a Live Agent.
- Bot goes into a paused state once the agent gets connected.
- When the bot is in paused state, the 2-way communication between the agent and end customer takes place.
- 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) 1. Request is in queue 2. Ticket is created & OPEN 3. Ticket is created & ASSIGNED |
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.
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": "[email protected]"
},
"ticket": {
"conversationHistory": "https://google.com",
"source": "web",
"ticketPriority": "medium",
"ticketCategory": "sales",
"conversationId": "efrfrfrfr",
"ticketGroupId": "14343",
"customFields": {}
}
}
}'
Click here for {{domainName}}createTicket
Response
{
status: success/failure
data: {ticketId: 25633, isAgentAvailable: true/false, isQueued: true/false }
message: <Description of Error/ Success Message>
}
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”: “[email protected]”
}
"ticket": {
“messageType”: “text”,
“message”: “hello”
“messageId”: “efefe-eefe-fefef-feefefe”,
“ticketId”: “275333”,
“source”: “web”,
“conversationId” : “yguyegdee”
}
}
}'
Refer here 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”: “[email protected]”
}
"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 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 |
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>
}