Como integrar webhooks?
O que é um webhook e como integrá-lo à plataforma
Neste artigo você aprenderá o que é um webhook e como integrá-lo à plataforma.
Leitura estimada: 05 minutos
O que é um webhook?
Webhooks são um método pelo qual os servidores Botmaker se comunicam com os servidores clientes quando ocorrem determinados eventos. Por exemplo, quando um bot envia uma mensagem, uma mensagem de webhook é disparada. Desta forma, os clientes poderiam integrar estes eventos a um sistema para, por exemplo, recolher todas as mensagens enviadas por um bot.
Usar: Lembre-se que para usar esta funcionalidade você deve ter uma função de superadministrador ou uma função com permissão para a tela de webhooks.
Integrar webhooks na Botmaker
Para acessar a tela de webhooks, vá paraMenu>Integrações>Webhooks.
Na tela de webhooks do Botmaker você pode:
- Crie, edite e exclua webhooks.
- Conecte webhooks aos seus canais preferidos.
- Configure quais tipos de mensagens você deseja ser notificado.
- Receba notificações sobre alterações de variáveis.
- Teste webhooks: com ferramentas para testar se eles detectam e processam corretamente diferentes notificações.
Como criar um webhook?
Para criar um novo webhook, basta clicar em Novo webhook. Uma janela pop-up será aberta onde você deverá preencher todos os campos.
Você já criou seu webhook.
Usar: Você pode ter vários webhooks. No entanto, você não pode ter mais de um webhook para o mesmo canal.
O que você encontrará em cada webhook?
Botões na barra azul superior:
- Ativar ou desativar este webhook
- Edite-o
- Delete isso
Teste o webhook: A partir daqui você pode testar a mensagem que o webhook enviará com base nas suas configurações. Lembre-se de ter o webhook ativado sobre , caso contrário esta opção não funcionará.
Registros de erros: Aqui você tem mais detalhes dos erros mais recentes.
No histograma você pode ver a quantidade de:
- Respostas bem sucedidas
- Respostas lentas
- Respostas com erro
- Respostas rejeitadas, envio de mensagens bloqueado devido a falhas repetidas no webhook
Nos últimos 30 minutos você encontrará:
- Tempo mais rápido
- Tempo médio
- Tempo mais lento
Desta forma, você pode verificar o status de integridade do seu servidor. Se o webhook falhar mais de 100 vezes durante 10 minutos, novas mensagens deixarão de ser enviadas durante os próximos 10 minutos para evitar sobrecarregar o servidor (essas mensagens serão perdidas). Por isso é importante manter o funcionamento do cluster de servidores que receberá as mensagens do webhook.
Usar: Esta funcionalidade não está ativa por padrão, pois tem um custo adicional. Para ativá-lo vá para a seção "Conta". Lá você encontrará uma seção específica com o título “webhook” onde poderá registrar a funcionalidade com apenas um clique.
Mensagens enviadas em webhooks
Os exemplos a seguir se aplicam a mensagens em webhooks enviadas pela plataforma e pela API Botmaker.
Abaixo você verá exemplos:
Formato de notificação de mensagens recebidas e enviadas: JSON
{
//versão do formato
"em": "1.1",
// marca que é uma notificação de mensagem
"tipo": "mensagem",
//plataforma de chat e campos do canal:
//o nome da plataforma de chat
"chatPlatform": "webchat" | "whatsapp" | "mensageiro" | "telegrama" | "Twitter" | ...,
//whatsapp: número de telefone do usuário
// messenger, telegram o twitter: id de usuario en plataforma,
"contactId": string,
// se o canal for WhatsApp, número da linha do bot
"whatsappNumber": "+551149331774"
// se o canal não for WhatsApp, id do chat na plataforma de chat
"chatIdInChatPlatform": "AR4Q1S3P1U",
//id do canal de chat no Botmaker
"chatChannelId": string,
// fim da plataforma de chat e campos do canal
//campos do usuário:
//ID do usuário no Botmaker
"customerId": string,
//nome e sobrenome do usuário
"primeiroNome": string,
"sobrenome": string,
//data e hora de criação do usuário (formato AAAA-MM-DDThh:mm:ss.sssZ)
"customerCreationTime": "2021-02-28T23:59:00.147Z",
// data e hora de início da sessão à qual pertencem as mensagens (formato AAAA-MM-DDThh:mm:ss.sssZ)
"sessionCreationTime":"2021-03-08T19:28:45.147Z",
//campos do usuário terminam
"whatsappNickName": string,
// quando os modelos são enviados pela API do Botmaker, o valor deste campo corresponde ao `webhookNotificationId` retornado pela API
"txId": string,
// mensagens: array. Múltiplas mensagens podem ser geradas em resposta a uma mensagem do usuário;
// isso geralmente acontece quando o bot responde
"mensagens": [
{
//id da mensagem no Botmaker (a notificação de status refere-se a este id)
"_id_":"PHW3S2KV4VRWL17BBM1U",
//data e hora da mensagem
"data":"2021-03-08T19:44:14.388Z",
// mensagem de texto
"mensagem": "Olá, como vai você?",
//nome de quem gerou a mensagem. O nome de usuário ou operador, ou "Bot" se for o bot
"fromName":"Ignácio Ferrari",
//categoria de quem enviou a mensagem
"de": "bot" | "usuário" | "operador",
//flag que marca se pertence ao usuário
"fromCustomer": verdadeiro | indefinido,
// flag que marca se era um botão (o texto da "mensagem" será o rótulo do botão)
"isButton": verdadeiro | indefinido,
// flag que indica se possui imagem, vídeo, áudio ou documento
"hasAttachment": verdadeiro | indefinido,
//urls do anexo
"imagem": "https://...",
"áudio": "https://...",
"vídeo": "https://...",
"arquivo": "https://...",
// se a mensagem foi emitida por um operador (from == "operador"), serão enviados os seguintes campos: operadorId, nomeoperador, operadorEmail, operadorRole
//id do operador no Botmaker
"operatorId": "bxj99dyfxEsdopib9ZuboIG5Tqr3",
"operatorName": "Pepe"
"operatorEmail": "pepe@domain.com",
"operatorRole": "ADMIN" | "CONFIGURADOR" | "SUPERVISOR" | "OPERADOR" | nomeRolCustom
//fila em que o usuário está no momento da mensagem
"queue":"idColaAtencion" | indefinido
// se a mensagem foi gerada por um intent (from == "bot"), o nome do intent é enviado
"intentName": "Nome de uma intenção"
// específicos para Whatsapp
// quando o usuário envia sua geolocalização
"localização": "lat. e longa",
// texto que acompanha a imagem
"legenda": string,
// para hsm/templates com botões:
"payload": string, // payload configurado por usuario
"botão": string, // rótulo do botão hsm
"templateName": string, // nome do template com botão
// Na API do Botmaker para envio de mensagens e acionamento de intents é possível enviar `webhookPayload` (v2.0) ou `clientPayload` (v1).
// `webhookPayload` (ou `clientPayload`) é usado para o usuário da API rastrear o envio da mensagem.
// Se a mensagem foi enviada via API do Botmaker, é neste campo que `webhookPayload` ou `clientPayload` é enviado novamente.
"clientPayload": string,
// quando o usuário entra na conversa seguindo um link de referência
"whatsappReferral": {
"sourceId": string,
"sourceURL": string,
"título": string,
"corpo": string
},
// quando a mensagem é uma finalização da compra do carrinho
"carrinho": {
"produtos": [
{ "sku": string, "quantidade": número }
]
}
},
//outras mensagens
{...},
{...}
],
// mudanças nas variáveis que ocorreram quando essas mensagens foram geradas
// mapeia nomedavariável -> novoValor
"variáveis": {
"varName1": "novo valor 1",
"varName2": "novo valor 2"
}
}
```
## Formato de notificação de status (Whatsapp)
```json
{
//versão do formato
"v": "1.0",
// id do bot no Botmaker (caso vários bots apontem para o mesmo webhook)
"businessId": string,
//ID do usuário no Botmaker
"customerId": string,
//whatsapp: número de telefone do usuário
// messenger, telegram o twitter: id de usuario en plataforma,
"contactId": string,
//id do canal de chat no Botmaker
"chatChannelId": string,
//o nome da plataforma de chat
"chatPlatform": "webchat" | "whatsapp" | "mensageiro" | "telegrama" | "Twitter",
// status da mensagem
//enviado: whatsapp enviou a mensagem
// entregue: a mensagem chegou ao telefone de destino
// lida: a mensagem foi lida
"status": "enviado" | "entregue" | "ler",
// data e hora da mudança de estado (formato AAAA-MM-DDThh:mm:ss.sssZ)
"statusChangeTime": "2021-03-01T00:00:00.000Z",
// id da mensagem no Botmaker que mudou de estado (este id refere-se a algum id de mensagem de saída, do bot ou operador)
"mensagemId": string,
// Na API do Botmaker para envio de mensagens e acionamento de intents é possível enviar `webhookPayload` (v2.0) ou `clientPayload` (v1).
// `webhookPayload` (ou `clientPayload`) é usado para o usuário da API rastrear o envio da mensagem.
// Se a mensagem foi enviada via API do Botmaker, é neste campo que `webhookPayload` ou `clientPayload` é enviado novamente.
"clientPayload": string,
// quando os modelos são enviados pela API do Botmaker, o valor deste campo corresponde ao `webhookNotificationId` retornado pela API
"intentTxId": string,
"erro": [ { "mensagem": string, "código": string } ]
}
```
É possível acompanhar o resultado de um envio através da API do Botmaker ouvindo os webhooks de status.
Para isso,
- envie à API um `webhookPayload` (ou `clientPayload` na v1) e ao receber uma notificação de status, marque `clientPayload` e marque que clientPayload foi enviado ou apresentou erro.
- salve o `webhookNotificationId` retornado pela API e verifique `intentTxId` na notificação de status.
Escrito por: Time Botmaker
Atualizado: 22/03/2024