How to connect to a personalized service channel July 21, 2023 18:20 Updated Index: Prerequisites Receiving a new ticket Assigning a ticket to an agent Receiving messages from the customer Messages originated by the agent Message flow Closing a ticket It may be beneficial for your business to conduct human customer service through a preferred tool. With this in mind, BLiP allows you to connect a personalized platform as a customer service channel. Prerequisites To carry out customer service using a custom service channel, there are some prerequisites: Add the API URL that will receive the service information. Add an authentication key, which will be sent in each API request to confirm BLiP's identity (Optional). Choose whether the created tickets will use BLiP's service rules. If so, add the possible queues for the ticket (Optional). For a complete service flow, the following steps are involved: Receiving a new ticket Once the bot forwards the conversation to customer service, if the custom channel is active, the URL registered in step 1 will receive a POST request with the message of a new ticket created. At this initial stage, the ticket is stored in BLiP with the status "Waiting". If the authentication token exists, configured in step 2, it will be sent in the request header. Example of a return with the data of the created ticket: { "type": "application/vnd.iris.ticket+json", "content": { "id": "{TICKET_ID}", "sequentialId": "{TICKET_SEQUENTIAL_ID}", "ownerIdentity": "{BOT_ID}", "customerIdentity": "{CUSTOMER_ID}", "customerDomain": "{CUSTOMER_DOMAIN}", "provider": "Webhook", "status": "Waiting", "storageDate": "2019-11-08T20:15:59.415Z", "rating": 0, "unreadMessages": 0, "closed": false, "customerInput": { "type": "text/plain", "value": "Hello world!" } }, "id": "Ticket:{TICKET_ID}:Waiting", "from": "{TICKET_ID}@desk.msging.net/Webhook"} In some cases, the request may return the status "Closed by Attendant" or "Error". In these situations, it is important to check the integration URL registered in the custom channel and verify if the integration URL is active. Additional handling can be done in the "Builder" of the service box configuration, setting up exception flows to direct to specific blocks, making error scenarios more transparent and well-handled. Example of an error return caused by unavailability of the integration channel: { "type": "application/vnd.iris.create-ticket-response+json", "resource": { "status": "Error" }, "method": "set", "status": "success", "id": "{TICKET_ID}", "from": "{TICKET_ID}@desk.msging.net/Webhook", "to": "webhooks@msging.net/default",} Assigning a ticket to an agent Once the ticket is created, it becomes the responsibility of the API that receives the ticket to handle it and assign it to an agent. This action is performed through a status change request. At this stage, BLiP expects to receive the status "Open" along with the agent's identifier. Therefore, it is recommended that the custom channel's API return this response before performing any other manipulations on the ticket status, thus avoiding flow inconsistencies. The command to update the ticket within the platform can be sent using the BLiP Desk extension, as shown in the following example: Example of a request for status change with agent assignment: { "id": "{COMMAND_ID}", "to": "postmaster@desk.msging.net", "method": "set", "uri": "/tickets/change-status", "type": "application/vnd.iris.ticket+json", "resource": { "id": "{TICKET_ID}", "status": "Open", "agentIdentity": "{AGENT_ID}" }} After sending the above request, BLiP associates the agent with the ticket, updating its status to "In Progress". From this stage onwards, the ticket will be ready to exchange messages. Receiving messages from the customer After assigning a ticket to an agent, any message sent by the user to the bot will be redirected to the URL registered in step 1. The message sent by the customer using BLiP will follow the LIME protocol standard, which can be consulted in the BLiP documentation. At this stage, customer interactions with BLiP generate events, allowing identification of whether the customer sent a message, is typing (composing), or even paused typing (paused). Example of a message sent using Blip: Example of a message sent using Blip: { "type": "text/plain", "content": "Olá, sou seu cliente! Poderia me ajudar?!", "id": "fwd:{MESSAGE_ID}", "from": "{TICKET_ID}@desk.msging.net/Webhook"} Example of a typing message: { "type": "application/vnd.lime.chatstate+json", "content": { "state": "composing" }, "id": "fwd:{MESSAGE_ID}", "from": "{TICKET_ID}@desk.msging.net/Webhook"} Messages originated by the agent Once a ticket is assigned to an agent, it becomes possible to send messages to the customer and start the customer service. To do this, simply send a message to the desired ticket with content supported by the Lime Protocol and documented by BLiP. An example of a message that can be sent to the customer by the agent. Example of a message sent from the agent to the customer: { "type": "text/plain", "content": "Olá, vou continuar com seu atendimento!", "id": "{MESSAGE_ID}", "to": "{TICKET_ID}@desk.msging.net/Webhook",} Message flow Once the message traffic has started, it may be useful to monitor this flow in real-time. For this purpose, the BLiP Desk extension also provides calls (APIs) that return this information. Using the "threads" request, you can retrieve information in different ways, such as messages sent by the customer, messages sent by the agent, the most recent conversation flow, among others. The following example retrieves the last 20 messages ordered in a conversation with the bot, given a specific customer. Example of a request retrieving the message flow: { "Id": "{COMMAND_ID}", "method":"get","uri":"threads-merged/{CUSTOMER_ID}?$take=20&direction=desc", "type":"application/vnd.iris.thread-message+json"} Example of the return with the exchanged messages: "type": "application/vnd.lime.collection+json", "resource": { "total": 2, "itemType": "application/vnd.iris.thread-message+json", "items": [ { "id": "424385e7-b150-4fec-963e-8cf680e5299c", "direction": "received", "type": "text/plain", "content": "Meu nome é Maria.", "date": "2023-07-20T18:50:34.267Z", "status": "consumed", "metadata": { "#uniqueId": "506ab59f-65d9-42e7-8ace-dbab75990c2e", "date_created": "1689879034244", "#date_processed": "1689879034259", "$internalId": "506ab59f-65d9-42e7-8ace-dbab75990c2e", "$originatorSessionRemoteNode": "postmaster@0mn.io/#omni-gateway-lime-7ffzk", "$elapsedTimeToStorage": "00:00:00.0108285" } }, { "id": "18394a27-5772-41b5-b7be-28f292816154", "direction": "received", "type": "text/plain", "content": "Olá, preciso de ajuda!", "date": "2023-07-20T18:21:22.500Z", "status": "consumed", "metadata": { "#uniqueId": "addd53c1-e48b-4c35-b19d-3189de896d6d", "date_created": "1689877282456", "#date_processed": "1689877282466", "$internalId": "addd53c1-e48b-4c35-b19d-3189de896d6d", "$originatorSessionRemoteNode": "postmaster@0mn.io/#omni-gateway-lime-7ffzk", "$elapsedTimeToStorage": "00:00:00.0365423" } }} Closing a ticket When it's necessary to close a ticket in progress, you can simply send the command to change the ticket's status. Once the ticket is closed, it cannot be updated further. This command can be sent using the BLiP Desk extension. An example of the command: { "id": "{COMMAND_ID}", "to": "postmaster@desk.msging.net", "method": "set", "uri": "/tickets/change-status", "type": "application/vnd.iris.ticket+json", "resource": { "id": "{TICKET_ID}", "status": "ClosedAttendant }} For more information, visit the discussion on the subject in our community or the videos on our channel. 😃 Related articles Audience file configuration - Bulk notification sending Creating interactive messages in WhatsApp Service History for Agents, on Blip Desk Builder variables How to save a contact's WhatsApp number