Webhook de Offloading

Aprenda como criar sua própria integração de handover humano por meio do Webhook de Offloading

O webhook de offloading permite integrar qualquer plataforma de chat ao vivo para transferência para atendimento humano. Você pode usar o webhook para:

• Receber mensagens de entrada do usuário

• Receber mensagens de saída do bot

• Agir sobre solicitações de offloading de um usuário

O Webhook de Offloading é para transferir usuários do bot para um agente humano. O canal Webhook é um canal de integração personalizado; certifique-se de não confundir os dois!

Configuração

Para configurar seu Chatlayer Offloading Webhook, acesse Configurações > Offloading e crie uma Webhook integração.

Insira a URL da API do seu webservice e um Token de Verificação que permita validar as requisições recebidas.

Enviaremos uma requisição de teste para a URL da sua API quando você clicar em Salvar para validar se o seu webservice está ativo e pronto para receber requisições, conforme descrito no método Health Check.

Parabéns! Você está pronto para começar a usar sua integração personalizada de transferência para atendimento humano.

Referência de Implementação do Webservice

Seu webservice precisará implementar os seguintes métodos da API para que possamos nos comunicar com ele. Todas as requisições chegarão em formato JSON na URL da API configurada durante a configuração do webhook de offloading no Chatlayer. Cada requisição POST em JSON tem um corpo com um event parâmetro que permite distinguir entre os diferentes tipos de dados recebidos. Os diferentes tipos são explicados abaixo.

Esperamos um código de status HTTP 200 para cada requisição feita ao webservice. Os dados da resposta devem estar em formato JSON.

Verificação de Saúde da API

GET <your_api_url>

Você deve enviar a resposta conforme descrito na aba Response.

Parâmetros de Consulta

Nome	Tipo	Descrição
challenge.verifyToken	string	O verifyToken permite validar que a requisição foi feita pelo Chatlayer

200

{ "status": "ok" }

Mensagens

POST <your_api_url>

Parâmetros de Consulta

Nome	Tipo	Descrição
challenge.verifyToken	string	O verifyToken permite validar que a requisição foi feita pelo Chatlayer

Corpo da Requisição

Nome	Tipo	Descrição
timestamp	string	O momento em que a mensagem foi gerada
messages	matriz	Um array de mensagens do usuário e do bot
event	string	O tipo de requisição, neste caso messages
canal	string	O tipo de canal
sessionId	string	O ID da sessão do usuário
version	string	A versão do bot, DRAFT ou LIVE
botId	string	O ID do bot

200 Não esperamos um corpo de resposta.

Os itens no array messages têm o seguinte formato -

{
    "actor": "bot" | "user",
    "message": UserMessage | BotMessage
}

BotMessage os objetos seguem a mesma estrutura da API do Webhook Channel, documentada aqui.

// Exemplo de mensagem de bot de texto
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-18878e66-03fb-4ee7-b2c4-eb9db1848291",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "text": "Olá, bem-vindo"
            },
            "timestamp": "2021-11-15T07:38:31.387Z"
        }
    ],
    "timestamp": "2021-11-15T07:38:31.387Z"
}

// Exemplo de mensagem de bot com resposta rápida
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-d3dac415-5263-482c-a30b-d1588c52d918",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "text": "Olá, bem-vindo"
            },
            "timestamp": "2021-11-15T07:47:08.383Z"
        },
        {
            "actor": "bot",
            "message": {
                "text": "Escolha o que você quer fazer?",
                "quick_replies": [
                    {
                        "title": "Executar API a partir do código",
                        "payload": "{\"title\":\"Executar API a partir do código\",\"caption\":\"Executar API a partir do código\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"19f87132-e23c-4335-877d-6a36f511c2cc\",\"originalTitle\":\"Executar API a partir do código\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "Plugin de API",
                        "payload": "{\"title\":\"Plugin de API\",\"caption\":\"Plugin de API\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"e0b327e0-bfa0-42a7-9685-c68491625b6e\",\"originalTitle\":\"Plugin de API\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "SendMessageFromCode",
                        "payload": "{\"title\":\"SendMessageFromCode\",\"caption\":\"SendMessageFromCode\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"c125a34e-7fec-4385-8333-6a91e25cdcff\",\"originalTitle\":\"SendMessageFromCode\"}",
                        "content_type": "text"
                    }
                ]
            },
            "timestamp": "2021-11-15T07:47:08.384Z"
        }
    ],
    "timestamp": "2021-11-15T07:47:08.383Z"
}

// carrossel / mensagem de template genérico
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-39ac2f23-07ce-4878-bd7d-729e6b39efdf",
    "event": "messages",
    "messages": [
        {
            "actor": "bot",
            "message": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "generic",
                        "elements": [
                            {
                                "title": "Item 1",
                                "image_url": "https://st.depositphotos.com/1708346/1858/i/600/depositphotos_18582903-stock-photo-carousel-at-night.jpg",
                                "buttons": [
                                    {
                                        "title": "Docs",
                                        "url": "https://docs.chatlayer.ai",
                                        "type": "web_url"
                                    }
                                ]
                            },
                            {
                                "title": "Item 2",
                                "image_url": "https://st.depositphotos.com/1708346/1858/i/600/depositphotos_18582903-stock-photo-carousel-at-night.jpg",
                                "subtitle": "Subtítulo do Item 2",
                                "buttons": [
                                    {
                                        "title": "Docs",
                                        "url": "https://docs.chatlayer.ai",
                                        "type": "web_url"
                                    }
                                ],
                                "default_action": {
                                    "url": "https://docs.chatlayer.ai",
                                    "type": "web_url"
                                }
                            }
                        ]
                    }
                }
            },
            "timestamp": "2021-11-15T08:24:32.871Z"
        }
    ],
    "timestamp": "2021-11-15T08:24:32.871Z"
}

UserMessage os objetos podem ter as seguintes estruturas:

// Exemplos de UserMessage

// Introdução
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-942c05c5-b9b7-4319-81e7-6d687afaa23f",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-942c05c5-b9b7-4319-81e7-6d687afaa23f",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "preferredLanguage": "en",
                    "firstname": "Visitante",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:28:05.872Z",
                "messageType": "intro",
                "id": "61921a15cdee7f37a16ee5fc"
            },
            "timestamp": "2021-11-15T08:28:05.872Z"
        }
    ],
    "timestamp": "2021-11-15T08:28:05.908Z"
}

// Texto
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:26:13.154Z",
                "messageType": "text",
                "text": "oi",
                "id": "619219a5cdee7f9f1b6ee5f7"
            },
            "timestamp": "2021-11-15T08:26:13.154Z"
        }
    ],
    "timestamp": "2021-11-15T08:26:13.193Z"
}

// Upload
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "1636964964162",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "1636964964162",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "firstname": "Visitante"
                },
                "timestamp": "2021-11-15T08:29:38.900Z",
                "messageType": "fileUploadInputResult",
                "urls": [
                    "https://minio.dev.chatlayer.ai/chatlayer-dev-eu-storage/f42af93e42b350fd7b874300c775756b168cc9ea4475b0c8c80e947228a26404/1636964964162_full.png"
                ],
                "data": {
                    "uploadStatus": "SUCCEEDED",
                    "fileUrl": "https://minio.dev.chatlayer.ai/chatlayer-dev-eu-storage/f42af93e42b350fd7b874300c7asdasdcc9ea4475b0c8c80e947228a26404/1636964964162_full.png"
                },
                "id": "61921a72cdee7fd1c56ee614"
            },
            "timestamp": "2021-11-15T08:29:38.900Z"
        }
    ],
    "timestamp": "2021-11-15T08:29:38.934Z"
}}

// Localização
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-8f5873aa-8fee-471a-9467-81e30dec693d",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:26:13.154Z",
                "messageType": "location", 
                "coordinates": { "lat": 0, "long": 0 } 
                "id": "619219a5cdee7f9f1b6ee5f7"
            },
            "timestamp": "2021-11-15T08:26:13.154Z"
        }
    ],
    "timestamp": "2021-11-15T08:26:13.193Z"
}

// Postback
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-6d09d652-a971-47ab-8484-223a86ff316e",
    "event": "messages",
    "messages": [
        {
            "actor": "user",
            "message": {
                "channelType": "web",
                "sender": {
                    "id": "emulator-6d09d652-a971-47ab-8484-223a86ff316e",
                    "botId": "ko3123ze",
                    "botType": "web",
                    "isEmulator": "true"
                },
                "timestamp": "2021-11-15T08:33:39.276Z",
                "messageType": "postback",
                "title": "Definir Variáveis",
                "parameters": [],
                "nextDialogstateId": "071abbc7-1d6e-4689-adef-1ea825178a72",
                "id": "61921b63cdee7f21ab6ee621"
            },
            "timestamp": "2021-11-15T08:33:39.276Z"
        }
    ],
    "timestamp": "2021-11-15T08:33:39.309Z"
}

Transferência

POST <your_api_url>

Corpo da Requisição

Nome	Tipo	Descrição
payload	objeto	O payload que você configurou no action dialogstate
canal	string
transcript	matriz	Um array contendo todas as mensagens enviadas ao longo da conversa.
event	string	O tipo de requisição, neste caso offload
timestamp	string
sessionId	string
version	string
botId	string

200 Para um offloading bem-sucedido, esperamos a seguinte resposta

{
    "offloadSuccess": true,
    "pauseBot": true
}

Os itens no array transcript têm o mesmo formato da messages método descrito acima.

Um exemplo da solicitação de offload pode ser o seguinte:

// Algum código
{
    "botId": "ko3123ze",
    "version": "DRAFT",
    "sessionId": "emulator-714a7b79-d674-4a62-a9a9-49581d7451e5",
    "timestamp": "2021-11-15T08:36:21.527Z",
    "event": "offload",
    "transcript": [
        {
            "actor": "bot",
            "message": {
                "text": "Olá, bem-vindo"
            },
            "timestamp": "2021-11-15T08:36:11.991Z"
        },
        {
            "actor": "bot",
            "message": {
                "text": "Escolha o que você quer fazer?",
                "quick_replies": [
                    {
                        "title": "Executar API a partir do código",
                        "payload": "{\"title\":\"Executar API a partir do código\",\"caption\":\"Executar API a partir do código\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"19f87132-e23c-4335-877d-6a36f511c2cc\",\"originalTitle\":\"Executar API a partir do código\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "Plugin de API",
                        "payload": "{\"title\":\"Plugin de API\",\"caption\":\"Plugin de API\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"e0b327e0-bfa0-42a7-9685-c68491625b6e\",\"originalTitle\":\"Plugin de API\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "carrossel",
                        "payload": "{\"title\":\"carrossel\",\"caption\":\"carrossel\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"0844670c-ee9f-43eb-9102-f50321cb4921\",\"originalTitle\":\"carrossel\"}",
                        "content_type": "text"
                    },
                    {
                        "title": "primeiras opções",
                        "payload": "{\"title\":\"primeiras opções\",\"caption\":\"primeiras opções\",\"type\":\"quickreply\",\"parameters\":[],\"nextDialogstateId\":\"13fc7f3e-80e5-45b8-862b-d2ff436eae0e\",\"originalTitle\":\"primeiras opções\"}",
                        "content_type": "text"
                    }
                ]
            },
            "timestamp": "2021-11-15T08:36:11.992Z"
        },
        {
            "actor": "user",
            "message": {
                "parameters": [],
                "text": "primeiras opções",
                "messageType": "postback",
                "title": "primeiras opções",
                "nextDialogstateId": "13fc7f3e-80e5-45b8-862b-d2ff436eae0e",
                "channelType": "emulator",
                "sender": {
                    "id": "emulator-714a7b79-d674-4a62-a9a9-49581d7451e5",
                    "botId": "ko3123ze"
                }
            },
            "timestamp": "2021-11-15T08:36:15.009Z"
        },
        {
            "actor": "bot",
            "message": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "button",
                        "text": "O que você quer fazer?",
                        "buttons": [
                            {
                                "title": "Definir Variáveis",
                                "type": "postback",
                                "payload": "{\"title\":\"Definir Variáveis\",\"caption\":\"Definir Variáveis\",\"type\":\"button\",\"originalTitle\":\"Definir Variáveis\",\"nextDialogstateId\":\"071abbc7-1d6e-4689-adef-1ea825178a72\",\"parameters\":[]}"
                            },
                            {
                                "title": "transferir",
                                "type": "postback",
                                "payload": "{\"title\":\"transferir\",\"caption\":\"transferir\",\"type\":\"button\",\"originalTitle\":\"transferir\",\"nextDialogstateId\":\"408c102e-7215-48f8-a76c-5a45d70dcd9d\",\"parameters\":[]}"
                            }
                        ]
                    }
                }
            },
            "timestamp": "2021-11-15T08:36:15.010Z"
        }
    ]
}

Receitas

Transferência de atendimento humano solicitada pelo usuário

Use um bloco de ação "Enviar para o provedor de offload" para acionar uma offload chamada à sua API.

Enviando mensagens como agente

Use o API de ações da conversa para enviar mensagens como agente.

Perguntas frequentes sobre Webhook Offloading

Aqui você pode encontrar perguntas frequentes sobre o offloading via webhook

Por que recebo requisições no endpoint de offloading mesmo quando o usuário ainda não foi transferido?

Enviamos os detalhes de todas as conversas que estão acontecendo entre o usuário e o bot para o endpoint de offloading sob o event: "messages" para que você possa assumir a conversa, se necessário. Isso também permitiria aos clientes acompanhar todas as conversas, se necessário.