Webhooks
WEBHOOKS
Através do Zap2Go é possível receber de forma ativa os eventos ocorridos no sistema. Antes de começar acesso o portal zap2Go no menu [Empresa].
Antes de começar configure sua URl Webhook e os tipos de eventos que deseja receber.
Para inserir mais de um endpoint, basta adicionar um pipe "|" e o segundo endereço. Exemplo:
http://endpoint1.com.br/|http://endpoint2.com.br.
Os seguintes eventos podem ser recebidos diretamente pelo sistema do contratante:
| TIPO (type) | DESCRIÇÃO | OCORRÊNCIA |
| MessageCreated | Mensagem adicionada. | Ocorre quando uma mensagem é criada na base. |
| MessageSent | Ocorre quando uma mensagem foi enviada para o cliente | Isto ocorre quando uma mensagem partiu do Zap2Go para um cliente. A solicitação pode ter sito feita pelos diversos canais e meios (front, API, respostas automáticas, etc). |
| MessageDelivered | Mensagem foi entregue ao cliente. | Ocorre quando o Zap2Go recebe a informação do WhatsApp de que a mensagem foi entregue na conversa com o cliente (quando ocorre o segundo 'v'). Este evento depende de o cliente estar com o Whatsapp conectado. Em 96% das vezes ocorre em menos de 3 minutos após o envio. - |
| MessageError | Ocorreu um erro para entregar uma mensagem. | Ocorre quando uma mensagem não pôde ser enviada ao cliente. Este evento pode acontecer por: - número do cliente não possuir WhatsApp (mais comum). - algum erro no processo de envio que impediu de completar (exceção), que pode ser decorrente de: - filtros de envio (palavras não permitidas). - erros de formato (caracteres, conteúdo, etc). - falha de funcionamento da plataforma. Obs: existe retentativa para alguns motivos de erro, o que pode causar mais de um retorno de evento de erro para a mesma mensagem. |
| MessageReceived | Cliente enviou uma mensagem para o sistema. | Ocorre quando o cliente enviou uma mensagem para a plataforma. Isto ocorrerá em todos os casos em que o sistema receber uma mensagem, independentemente de já estar em "atendimento" ou não, de ter tido uma resposta automática ou não. |
| ClientEvent | Algum evento detectado a partir do cliente. | Ocorre quando é detectado algum evento a partir do cliente. |
| ClientCheckNumber | Cliente teve número checado (serviço de checagem) | |
| DeviceEvent | Dispositivo de chip próprio do cliente desconectou ou conectou. | Evento ocorre quando o contratante possui um aparelho chip próprio associado a uma carteira do sistema. Quando ocorre a desconexão, o contratante deve providenciar a reconexão. |
| ServiceStarted | Sessão de atendimento de cliente foi iniciada, | Ocorre quando um atendimento de um cliente é iniciado. Este evento pode ocorrer por: - atendimento iniciado no front. - atendimento aberto por API. |
| ServiceFinished | Sessão de atendimento de cliente foi encerrada. | Ocorre quando um atendimento de um cliente é encerrado. Este evento pode acontecer por: - processo automático previamente configurado na carteira para encerrar atendimentos por ociosidade. - processo manual executado pelo usuário após encerrar um atendimento com um cliente. - processo executado por API para envio do atendimento |
| ActiveQueueError | Solicitação de envio de ativo com erro. | Ocorre quando a solicitação de envio de ativo resultou em erro. Uma solicitação de envio de ativo é processada de forma assíncrona. Quando a solicitação é feita, via API, é retornado um id (queue id). Algum tempo depois, a solicitação é processada e:
|
REGRAS GERAIS
Todos os dados são retornados em JSON - UTF-8.
Todos os eventos enviados possuem um código único de identificação.
Os eventos ficam armazenados em nosso sistema por 3 dias para auditoria e retentativa.
O sistema do contratante pode receber mais de uma vez o mesmo evento caso não tenha ocorrido retorno 200 no envio ou por outra razão de processamento. Caso o contratante precise marcar unicidade, pode utilizar o token ou id informado em cada caso.
O sistema do contratante pode receber os eventos "fora de ordem" devido a: retentativas, natureza do processo do whatsapp, etc.
Os eventos têm formato único e os campos preenchidos podem variar de acordo com a natureza do evento ocorrido. Recomenda-se tratar por padrão todas as inrormações como "anuláveis" (aceitam nulo) para efeito de tratamento.
Os objetos JSON de cada evento podem ter propriedades aumentadas ao longo do tempo. A documentação atualizada estará sempre no acesso teste.
ESTRUTURAS DOS OBJETOS E PROPRIEDADES
| MESSAGE | Mensagem de WhtasApp enviada ou recebida (ou com erro) do sistema. Possui atributos que cobrem todos os tipos de mensagem tratados no Zap2Go |
| CLIENT | Um Cliente, ou seja, um usuário do Whatsapp que se contacte com sua carteira. Possui os atributos de número do telefone correspondentes. |
| DEVICE | Informações de um aparelho/chip próprio conectado/desconectado do cliente. |
| SERVICE | Informação referente a um atendimento de cliente |
| ACTIVEQUEUE | |
| CAMPAIGNID | Id da campanha eventualmente acionada |
| MESSAGEID | Id da mensagem |
| CLIENTID | Id do Cliente acionado |
CONFIGURANDO O END-POINT DE WEBHOOKS
Para que sua empresa receba os webhooks, precisa disponibilizar uma rota url de API (webapi) que permita fazer POST.
Para maiores informações sobre esta configuração, consulte este item.
Disponibilizamos no GitHub a estrutura de classes em C# e um exemplo de como implementar os Webhooks (sempre confira nesta página se a estrutura das classes está atualizada).
SIMULANDO A CHAMADA DOS WEBHOOKS
Para simular o recebimento de um webhook, o cliente pode chamar uma rota única:
Mook
| ENDPOINT | /v1/WebHook/Mook | ||
| METHOD | POST | ||
| PARAMETERS | TYPE | DEMANDED | NOTES |
| walletId | int | obrigatório | id da carteira |
| type | string | obrigatório | informar um dos tipos acima. |
| variation | string | obrigatório | normalmente informar "SUCCESS" ou a variação esperada (para simular erros e outros cenários - consultar a equipe Zap2Go). |
| route | string | obrigatório | informar uma rota completa onde deseja receber o Webhook. Caso não informado, será utilizada a rota originalmente cadastrada para o contratante (empresa). |
SEND EXAMPLE
{
"walletId": 999999,
"type": "ServiceStarted",
"variation": "SUCCESS",
"route": "https://webhook.myCompany.com/Chat/base/post/instance/"
}FORMATO DOS WEBHOOKS RECEBIDOS
Todos os webhooks recebidos contém uma estrutura base e um objeto dentre os listados acima.
Esta estrutura é apresentada abaixo:
| Atributo | Conteúdo |
| Type | Tipo do evento que está sendo enviado conforme lista acima (MessageSent ...) |
| TransactionToken | Token único gerado para cada webhook enviado. Pode ser usado para localizar informações sobre o webhook em nossa base dados, junto ao Suporte. |
| GenTime | Horário da geração do Webhook (pode ser diferente do envio). Horário padrão do Brasil. |
| WalletName | Nome da carteira de onde o webhook foi gerado. |
| WalletId | Id padrão da carteira onde o webhook foi gerado. |
| ObjectType | Tipo do objeto, conforme lista acima. |
| Data | Objeto de dados do webhook. Os atributos são diferentes para cada objeto, conforme abaixo. |
Estrutura dos objetos retornados no atributo "Data"
OBS:
podem ser adicionados novos atributos a qualquer momento por serem novos desenvolvimentos ou solicitações.
Favor tratar em seu código para que isso não gere erro em seu processamento.
OS formatos/tipos de dados, assim como o nome das propriedades não são alterados.
Considerar todas as propriedades como anuláveis para evitar erros de processamento.
Os datatypes informados estão baseados em C#
MESSAGE
| ID | int | id da mensagem gerado no Zap2Go |
| QUEUEID | int? | id da fila de mensagem gerado, caso esta mensagem tenha sido enviada via API do Ativo. Esse id pode passar a ser nulo após alguns dias de geração, e serve apenas como referência temporária para seu sistema. Esse Id será nulo se: (1) a mensagem for recebida, (2) a mensagem for enviada por outro meio que não API. |
| SOURCE | string | Qual a origem da mensagem: - SPAM: mensagem enviada como ativo ou mailing inicial - USER: mensagem enviada pelo usuário durante o atendimento de chat - CLIENT: mensagem enviada pelo cliente. - BOT: mensagem enviada de forma automática em automação. |
| TYPE | string | tipo da mensagem enviada: TEXT, BUTTON etc |
| USERID | int? | Id do usuário do Zap2Go que enviou o sistema quando aplicável. |
| USEREXTERNALID | string | Código externo do usuário (ou login do usuário) quando aplicável. |
| DEVICEID | int? | Id do dispositivo por onde a mensagem foi entregue - indica qual o dispositivo (virtual ou físico) foi usado para envio da mensagem. Considere utilizar essa informação caso utilize chips próprios. |
| PHONENUMBER | string | fone do remetente da mensagem (caso o evento seja MessageReceived) ou do destinatário da mensagem. |
| CLIENTID | int | id do remetente/destinatário de acordo com a base de dados do Zap2Go. |
| EXTERNALID | string | código externo do cliente (informado em algum envio de mensagem) |
| TEXT | string | parte texto da mensagem. |
| FILE | string | arquivo da mensagem, que pode estar em: - base 64 com a identificação do mime type no início - url. * OBS: para evitar request de grnade volume, o base64 não é retornado nas MESSAGES[] do evento ServiceFinished. |
| FILENAME | string | nome do arquivo enviado/recebido, quando aplicável. |
| BUTTONS | string | JSON com um array de botões (id, label) dos botões. |
| CREATEDATE | DateTime | Data de criação da mensagem (horário padrão o Brasil). |
| SENTDATE | DateTime? | Data de envio da mensagem (horário padrão o Brasil). (envio = primeiro 'v' da mensagem marcado) |
| DELIVERYDATE | DateTime? | Data de entrega da mensagem (horário padrão o Brasil). (entrega = segundo 'v' da mensagem marcado) |
| READDATE | DateTime? | Data de leitura da mensagem (horário padrão o Brasil) (leitura = ambos os 'v' marcados em azul). Depende de o cliente ter habilitado marcação de leitura) |
| ERROR | string | Mensagem que indica que a mensagem não foi/será enviada por erro ou expiração. |
SERVICE
| ID | int | Id do atendimento ao cliente |
| USERID | int? | Id do usuário do Zap2Go que efetuará/efetuou o atendimento |
| USEREXTERNALID | string | Código externo do usuário (ou login do usuário) quando aplicável. |
| PHONENUMBER | string | Número do telefone do cliente (DDI+DDD+TELEFONE). |
| CLIENTID | int | ID do cliente na base do Zap2Go |
| EXTERNALID | string | código externo do cliente (informado em algum envio de mensagem) |
| CLIENTDOCUMENT | string | documento o cliente. Informação fornecida ao enviar ativo ou mailing (normalmente CPF/CNPJ) |
| STARTDATE | DateTime | Início do atendimento (horário padrão do Brasil) |
| ENDDATE | DateTime? | Horário do término do atendimento (horário padrão do Brasil) |
| REASONCODE | string | Código do motivo de encerramento - este código é cadastrado no Zap2Go e pode ser usado um código interno do contratante. Se não foi cadastrado um código do contratante, será retornado Z2G_<id interno do Zap2Go> |
| PROTOCOL | string | Protocolo de atendimento gerado em processo de atendimento automático se aplicável. |
| NOTES | string | Observações colocadas pelo usuário ao encerrar o atendimento. |
| MESSAGES | MESSAGE [ ] | Esta propriedade estará preenchida no evento ServiceFinished Array com as mensagens enviadas e recebidas durante este atendimento. A estrutura de cada objeto é a da classe MESSAGE acima. OBS: a "atribuição" de mensagens a um atendimento é feita com base em:
|
CLIENT
| ID | int | Id do cliente na base do Zap2Go - cliente é qualquer usuário de canal do zap2go que tenha enviado/recebido uma mensagem. sua identificação é unívoca pelo número do telefone(ddi+ddd+telefone) |
| EXTERNALID | string | Código externo do cliente, caso tenha sido atribuído pelo contratante um código de identifiação. |
| DOCUMENT | string | CNPJ ou CPF ou outra informação fornecida pelo contratante para identificar o cliente. |
| EVENT | string | Evento ocorrido com o cliente: CHANGED, WHATSAPPSTATUS, PRESENCE |
| NAME | string | Nome do cliente informado pelo contratante |
| PHONENUMBER | string | Número do telefone do cliente no formato DDI+DDD+TELEFONE |
| string | Endereço do e-mail do cliente quando aplicável | |
| WHATSAPPSTATUS | bool? | booleano: true = cliente possui whatsapp, false = cliente não possui whatsapp Obs: esse status é verificado quando há uma tentativa de envio de mensagem, e a cada intervalo de tempo. |
| WHATSAPPNAME | string | Nome do usuário no whatsapp |
| EMAILSTATUS | bool? | booleano: true ou false |
DEVICE
| INTERNALCODE | string | Id do dispositivo conforme base de dados do Zap2Go. |
| EXTERNALID | string | Número do telefone do dispositivo no formato DDI+DDD+TELEFONE |
| EVENT | string | O que ocorreu com o dispositivo: DISCONNECTED, CONNECTED |
ACTIVEQUEUE
| ID | int | Queue id - id da requisição de envio do Active. |
| INSERTDATE | DateTime | Data/hora de inclusão da requisição. |
| PROCESSEDDATE | DateTime | Data/hora da última tentativa de processamento da requisição. |
| ERROR | string | Erro ocorrido para processamento da requisição, que impediu a geração da mensagem. |
TAG
| ID | int | Id da ocorrência na base do Za2Go. |
| USERID | int | Id do usuário do Zap2Go que efetuou o atendimento. |
|
CLIENTID |
int | ID do cliente na base do Zap2Go |
|
USERDOCUMENT |
string | CPF do usuário do Zap2Go que efetuou o atendimento. |
| USEREXTERNALID | string |
Código externo do operador, caso tenha sido atribuído pelo contratante um código de identifiação. |
|
CLIENTEXTERNALID |
string |
Código externo do cliente, caso tenha sido atribuído pelo contratante um código de identifiação. |
| DATE | DateTime | Data/hora de inclusão. |
| TAG | string | Descrição da etiqueta. |
| REASONCODE | int | Id do motivo de finalização na base do Zap2Go. |
| NOTES | string | Observações |
| MESSAGES | MESSAGE[] | Esta propriedade estará preenchida no evento TagEvent Array com as mensagens marcadas com Tag. A estrutura de cada objeto é a da classe MESSAGE acima. OBS: a "atribuição" de mensagens a um atendimento é feita com base em:
|