Webhooks
Antes de seguirmos para o passo a passo de criação de Webhooks, é importante compreender o que são e como funcionam.
Os Webhooks são respostas ou retornos de chamadas HTTP estabelecidos em cada conta da Nexloo. Essas ocorrências são acionadas quando eventos específicos acontecem, como a criação de mensagens. É possível configurar vários Webhooks para uma única conta.
Agora que você está familiarizado com o conceito de Webhooks, vamos ao processo de criação:
Passo a Passo:
- Na tela inicial da Nexloo, clique em ‘Configurações’.
- Em seguida, selecione ‘Integrações’.
- Você será redirecionado para a página de configurações de integrações. Clique em ‘Configurar’ para Webhooks.
- Agora, clique no botão verde ‘Adicionar novo Webhook’.
- Um painel central será exibido. Insira a URL para a qual deseja enviar a requisição POST.
- Em seguida, selecione os eventos ou ocorrências aos quais deseja se inscrever. Isso permite que você ouça apenas os eventos relevantes na Nexloo.
- Por fim, clique no botão azul “Criar webhook”.
Após a configuração, a Nexloo enviará uma solicitação POST com uma carga útil específica para as URLs configuradas, notificando sobre várias atualizações 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.nexloo.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": "Nexloo",
}
}
Ocorrências de Webhook Suportadas na Nexloo:
A Nexloo suporta várias ocorrências de Webhook, permitindo que você acompanhe os eventos importantes em sua conta. Abaixo estão algumas das ocorrências suportadas:
- conversa_criada
- conversa_atualizada
- conversa_status_alterado
- mensagem_criada
- mensagem_atualizada
- webwidget_triggered
Cada ocorrência possui uma estrutura de carga útil específica, contendo informações relevantes sobre o evento. Você pode configurar Webhooks no painel da Nexloo ou utilizando a API correspondente.
Objetos
Uma ocorrência (evento) pode conter qualquer um dos objetos a seguir como uma carga útil.
Os diferentes tipos de objetos suportados na Nexloo 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 Nexloo 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",
}
}
}