Skip to main content

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

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-caseRequiredRemarks
1Send Message {text + media}YesChat history will be present in the first message as a link
2Send typing eventNo
3Create TicketYesResponse should contain ticketIDScenarios ( Ticket Lifecycle)
1. Request is in queue
2. Ticket is created & OPEN
3. Ticket is created & ASSIGNED
4User details {Channel ID, Sender ID, Unique ID}Yes
5Transfer to a particular groupNoDepartment wise, as per business need
6Ability to pass custom parameterYes
7Is User ActiveNo
8Custom ParametersYesAbility 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.noTypeRequiredRemarks
1Event name/code specificationYes
2Agent message {text + media}Yes
3Agent assigned{along with agent details}YesAgent details like agent name, department should be received
4Queue PositioningNo
5Closed ticketYesClosed ticket event
6Updation of any ticket detail (e.g. transferred to another agent)No
7Is 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}}
METHODPOST

Body Parameters

NameData typeDescriptionMandatory
senderIdstringUnique identifier of the user generated by Yellow.AIY
messageIdstringUnique identifier of every sent messageY
sourcestringChannel from where the message can be sentY
conversationIdstringUnique identifier of this conversationY
userNamestringName of the user/customerY
userMobilestringMobile number of the user, accepts 10 digit mobile numberY
userEmailstringEmail Id of the userY
conversationHistorystringThe URL of the conversation prior to connecting to the agentY
ticketPrioritystringPriority of the ticket, possible values low/medium/highY
ticketCategorystringCategory to which a ticket may belongN
ticketGroupIdstringIf we want the ticket to get assigned to a particular group of agents, we need to add thisN
customFieldsobjectUse this if any custom key value pairs need to be passed. The data type of the values can be string/number/boolean/objectN
conversationHistoryJSONarrayThe JSON of the conversation prior to connecting to the agentN

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

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}}
METHODPOST

Body Parameters

NameData typeDescriptionMandatory
senderIdstringUnique identifier of the user generated by Yellow.aiY
userNamestringName of the userY
userEmailstringEmail Id of the userN
messagestringMessage sent by the userY
messageIdstringUnique identifier of every sent messageY
ticketIdstringGenerated ticketId from API 1Y
sourcestringChannel in which the message can be sentY
conversationIdstringUnique identifier of this conversationY
messageTypestringType of the message sent,the value will be textY

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}}
METHODPOST

Body Parameters

NameData typeDescriptionMandatory
senderIdstringUnique identifier of the user generated by Yellow.AIY
userNamestringName of the userY
userEmailstringEmail Id of the userN
mediaJsonobjectHas 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 mediaY
messageIdstringUnique identifier of every sent messageY
ticketIdnumberGenerated ticketId from API 1Y
sourcestringChannel in which the message is sentY
conversationIdstringUnique identifier of this conversationY
messageTypestringType of the message sent, the value will be mediaY

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

URLhttps://cloud.yellow.ai/integrations/genericIntegration/custom-live-agent
MethodPOST
x-auth-tokenWill be provided by yellow
Response Code200
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>
}