4.4. Webhooks
Antes do passo a passo para criação de Webhooks, saiba seu significado:
Os Webhooks são as respostas ou retornos de chamada HTTP estabelecidos em cada conta. Essas ocorrências são acionadas quando uma ação (temos como exemplo a criação de mensagens) acontece. Você pode gerar mais de um Webhook para uma conta. Ok?
Então, agora que você já sabe o que são os Webhooks, vamos para a criação:
Clique em ‘Configurações’ (conforme demarcamos na imagem com o número 01) e depois em ‘Integrações’ (conforme demarcamos na imagem com o número 02). Veja abaixo:
Você irá para a página abaixo. Clique em ‘Configurar’ para Webhooks.
Agora clique no botão verde ‘Adicionar novo Webhooks’, conforme tela abaixo:
Será exibido um painel central (conforme imagem abaixo).
Insira a URL para qual a requisição POST deve ser encaminhada.
Depois, selecione os eventos (ou ocorrências) que deseja se inscrever. A opção permite que você ouça apenas os eventos relevantes na Evolvy.
Por fim, clique no botão azul “Criar webhook”.
A Evolvy enviará uma solicitação POST com a seguinte carga útil aos URLs configurados para várias atualizações acontecendo em sua conta.
Em exemplo de carga útil de Webhook:
{
"event": "message_created", // O nome do evento
"id": "1" // Mensagem ID
"content": "Hi" // Conteúdo da mensagem
"created_at": "2023-01-01 18:12:45 UTC", // Hora em que a mensagem foi enviada
"message_type": "incoming", // Este será um tipo de entrada, saída ou modelo. O usuário do Widget envia mensagens
recebidas e o agente envia mensagens enviadas ao usuário.
"content_type": "enum", // Este é um enum, pode ser imput_select, cards, form ou text. O message_type servirá de modelo,
caso o content_type for um desses. O valor padrão é o texto.
"content_ attributes": { } // Este será um objeto. Valores diferentes são definidos abaixo.
"source_id": "", // Este seria o id externo se a caixa de entrada fosse uma integração com Twitter ou Facebook.
"sender": { // Isso forneceria os detalhes do agente que enviou a mensagem.
"id": "1",
"name": "Agent",
"email": "[email protected]"
},
"contact": { // Isso forneceria os detalhes do usuário que enviou a mensagem.
"id": "1",
"name": "contact-name"
},
"conversation": { // Isso forneceria os detalhes da conversa.
"display_id": "1", // Este é o id da conversa que vc poderá ver no painel.
"additional_attributes": {
"browser": {
"device_name": "Macbook",
"browser_name": "Chrome",
"platform_name": "Macintosh",
"browser_version": "80.0.3987.122",
"platform_version": "10.15.2"
},
"referer": "http://www.evolvy.com",
"initiated_at": "Wed Jan 05 2023 - 19:24:12 GMT-0700 (Horário Padrão de Brasília)"
}
},
"account": { // Isso forneceria os detalhes da conta.
"id": "1",
"name": "Evolvy",
}
}
Ocorrências (eventos) de Webhook com suporte na Evolvy:
A Evolvy publica várias ocorrências nos terminais configurados de Webhook. Se você deseja configurar um Webhook, aprenda aqui com a gente!
Cada ocorrência tem sua estrutura de carga útil com base no tipo de modelo em que está atuando. Veja a ocorrência a seguir, que descreve os principais objetos que usamos na Evolvy e seus atributos.
Objetos
Uma ocorrência (evento) pode conter qualquer um dos objetos a seguir como uma carga útil.
Os diferentes tipos de objetos suportados na Evolvy são os seguintes:
Conta
A seguinte carga útil será retornada para uma conta.
{
"id": "integer",
"name": "string"
}
Caixa de entrada
A seguinte carga será retornada para uma caixa de entrada.
{
"id": "integer",
"name": "string"
}
Contato
A seguinte carga útil será retornada para um contato.
{
"id": "integer",
"name": "string",
"avatar": "string",
"type": "contact",
"account": {
// <...Account Object>
}
}
Do utilizador
A seguinte carga será retornada para um agente/administrador.
{
"id": "integer",
"name": "string",
"email": "string",
"type": "user"
}
Conversação
A seguinte carga será retornada para uma conversa.
{
"additional_attributes": {
"browser": {
"device_name": "string",
"browser_name": "string",
"platform_name": "string",
"browser_version": "string",
"platform_version": "string",
},
"referer": "string",
"initiated_at": {
"timestamp": "iso-datetime"
}
},
"can_replay": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"contact_inbox": {
"id": "integer",
"contact_id": integer",
"inbox_id": "integer",
"source_id": "string",
"created_at": "datetime",
"updated_at": "datetime",
"hmac_verified": "boolean"
},
"messages": ["Array of message objects"],
"meta": {
"sender": {
// Objeto de Contato
"assignee": {
// Objeto de Usuário
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"acount_id": "integer",
}
Mensagem
{
"id": "integer",
"content": "string",
"message_type": "integer"
"created_at": "unix-timestamp",
"private": "boolean",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "object",
"sender": {
"type": "string - contac/user"
.// Usuário ou Objeto de Contato
},
"account": {
// Objeto de Conta
},
"conversation": {
// Objeto de Conversa
},
"inbox": {
// Objeto de Caixa de Entrada
},
}
Um exemplo de Carga Útil de Webhook
{
"event": "event_name"
// Atributos relacionados ao evento
Ocorrências de Webhook
A Evolvy suporta as seguintes ocorrências (eventos) de Webhook abaixo. Você pode assiná-las enquanto configura um Webhook no painel ou usando a API.
conversa_criada
Essa ocorrência será acionada quando uma nova conversa for criada na conta.
{
"event": "conversation_created"
// <...Atributos de Conversação>
}
conversa_atualizada
Essa ocorrência será acionada quando houver alteração em algum dos atributos da conversa.
{
"event": "conversation_updated",
"changed_attributes": [
{
"attribute_name>": {
"current_value": "",
"previous_value": ""
}
}
]
// <...Atributos de Conversação>
}
conversa_status_alterado
Essa ocorrência será acionada quando o status da conversa for modificado.
Observação: se você estiver usando APIs de bot de agente, ao invés de Webhooks, esse evento ainda não será compatível.
{
"event": "conversation_status_changed"
// <... Atributos de Conversação>
}
mensagem_criada
Essa ocorrência será acionada quando uma mensagem for criada em uma conversa. A carga útil para a ocorrência é a seguinte:
{
"event": "message_created"
// <... Atributos de Mensagem>
}
mensagem_atualizada
Essa ocorrência será acionada quando uma mensagem for atualizada em uma conversa. A carga útil para a ocorrência é a seguinte:
{
"event": "message_updated"
// <... Atributos de Mensagem>
}
webwidget_triggered
Essa ocorrência será acionada quando o usuário final abrir o widget de Chat ao Vivo.
{
"id":,
"contact": {
// <...Objeto de Contato>
},
"inbox": {
// <... Objeto de Caixa de Entrada>
},
"account": {
// <...Objeto de Conta>
},
"current_conversation": {
// <...Objeto de Conversa>
},
"source_id": "string",
"event": "webwidget_triggered",
"event_info": {
"initiated_at": {
"timestamp": "date_string"
},
"referer": "string",
"widget_language": "string",
"browser_language": "string",
"browser": {
"browser_name": "string",
"browser_version": "string",
"device_name": "string",
"platform_name": "string",
"platform_version": "string",
}
}
}