In the technical detail below you will find the different endpoints available to queue, close a conversation in Live, or maintain dialogue with agents. In this material you can see more information about how to receive the responses.
⇒ Keep in mind that you must previously have the botId and the botToken to start using Live externally. You will request both through Service Request.
The data that is in red will be considered mandatory from now on.
1. Queue: in this endpoint we will need the ID of the target group belonging to Live and the data of the user who wants to speak with an agent.
● Endpoint: POST https://gateway.aivo.co/api/v1/live-handler/queue/external
● Body
{ "botId": INT, "groupsId": [INT], "botToken": "STRING", "protocolId": 28, "user": { "hash": "STRING", "firstname": "STRING", "lastname":"STRING", "email":"STRING", "phone": "STRING", "extra": [ "Dato A": "STRING", "Dato B": "INT" ] }, "status": "queued", "lastSender": "user" } |
● Key data
- The groupsId field must include the ID of the group to which you want to queue the conversation.
- You will get this from the GET endpoint https://live-public-api.agentbot.net/group.
- The hash must be unique per user and we recommend that it be alphanumeric, as seen in this example, b9e8f46b56efbacea7a6a4cdab3.
- We will concatenate _botToken to the sent hash. Keep this in mind for the rest of the endpoints.
- The protocolId, status and lastSender fields must be fixed, following the example of the item body: 28, “queued” and “user”.
- The extra field in the user array is used to add any data that the agent wishes to observe when responding, for example, a ticket number; and it must have the following format:
| "extra": [ "Ticket": 2024 ] |
● Response: in case of success, the endpoint will return a conversationId, which will remain in the queued state until it is serviced, in the section.
| { "conversationId": "e169f21f-6f7e-44cd-9bf5-dd6b51d8b24b", "customToken": “token”, "messageQueueId": 0, "notAttended": 0 } |
● Curl example
| curl --location 'https://live-handler.agentbot.net/conversations/queue/external' \ --header 'Content-Type: application/json' \ --data '{ "botId": 1000, "groupsId": [ 2179 ], "botToken": "7114636682f3c091557758286be4a94c", "protocolId": 1, "user": { "hash": "b9e8f46b56efbacea7a6a4cdab", "firstname": "Brian", "lastname": “Rodriguez”, "email": null, "phone": "5492236638596", "username": null, "picture": null, "extra": [ ] }, "status": "queued", "lastSender": "user" }' |
2. Message to Agent: when the conversation is attended by an agent, it will be necessary to communicate to the agent what the client writes.
● Endpoint: POST https://gateway.aivo.co/api/v1/live-handler/{{conversationId}}/client/message
● Body
| { "message": [ { "action": "text", "value": "Hello, my name is Tomás and I need to know the balance of my account", "source": "user" } ] } |
● Key data
- ConversationId must be the one obtained at the gluing endpoint.
- The action field will determine what type of message was sent, it can be text, file or image.
- In the value field, if it is a file or image, you must enter the S3 address or where the data is stored.
● Curl example
curl --location 'https://live-handler.agentbot.net/conversations/16d1e0f9-6243-4284-8a57-16460a265908/client/message' \ --header 'Content-Type: application/json' \ --data '{ "message": [ { "action": "text", "value": "Hola, mi nombre es Tomas y necesito saber el saldo de mi cuenta.", "source": "user" } ] }' |