API de Push e Webhook

Neste documento será apresentado o uso do PUSH e WEBHOOK em nossa plataforma.

Esta funcionalidade pode ser encontrada no em CONFIGURAÇÕES → Avançado → API/WEBHOOK

Depois é possível escolher entre configurar a API e Webhook e visualizar os logs de requisições.

PUSH

Esta função permite o envio de mensagens via API.

Cada envio, abrirá um novo ticket na fila de pendente, se não houver um ticket aberto para o contato na conexão (canal) escolhido para envio. A ação após o envio permitirá fechar automaticamente ou manter o ticket aberto.

A URL e o token podem ser gerados na plataforma. Para utilizar a URL (endpoint), basta clicar em ADICIONAR para criar a configuração para a API e preencher os campos de Dados API (PUSH) como mostra a imagem abaixo:

Os campos para preenchimento são:

Nome da API: identificação da API
Enviar por: escolher uma conexão (canal) disponível para o envio

As ações disponíveis após o envio são:

Fechar atendimento: encerra o ticket após o envio.
Manter atendimento aberto: o ticket permanece aberto na fila de pendente do departamento.
Redirecionar atendimento: escolher a fila/departamento para transferir o ticket aberto pelo envio

Créditos Push

O consumo de créditos push está diretamente associado ao envio de mensagens por meio de webhooks específicos. É importante destacar que nem todos os webhooks consomem créditos, apenas aqueles relacionados ao envio de mensagens push. Esse sistema serve como um mecanismo de controle para gerenciar o volume de envios e garantir que eles ocorram de maneira regulamentada.

Os créditos push podem ser adquiridos e liberados de duas formas:

Créditos recorrentes: São liberados automaticamente pela automação no momento da renovação do plano do cliente. Sempre que o plano é renovado, o sistema realiza a liberação automática dos créditos, sem a necessidade de solicitação manual.

Caso seja necessário, qualquer ajuste ou solicitação de créditos push pode ser feito diretamente com a equipe de suporte, que pode auxiliar na liberação manual ou na correção de eventuais problemas no saldo.

A quantidade de créditos podem ser localizados na aba de funil no canto direito:

Durante o envio de mensagens via webhook push, o sistema verifica automaticamente o saldo disponível e realiza o desconto correspondente. Esse processo garante que o consumo esteja sempre dentro dos limites definidos, prevenindo o envio de mensagens sem créditos disponíveis.

Além disso, o saldo pode ser monitorado em tempo real na página da API, permitindo um controle mais eficiente. Quando o saldo se aproxima do limite, é possível solicitar uma nova liberação de créditos diretamente com o suporte, evitando qualquer interrupção no fluxo de envio.

Portanto, a aquisição e o gerenciamento adequado dos créditos push são essenciais para garantir o funcionamento eficiente dos envios via webhooks na JetSales, assegurando que a operação ocorra de maneira controlada e sem interrupções.

ENVIO DE MENSAGEM

Método: POST

https://chat-jetsales-exampleapi.jetsalesbrasil.com/v1/api/external/{apiId}

HEADERS

Key

Value

Authorization

bearer [Token da API]

Para Citar Grupos na API Push:
- Ao enviar uma mensagem para um grupo usando a API, é necessário especificar o número do grupo com o sufixo @g.us. Isso é fundamental para garantir que a mensagem seja direcionada ao grupo correto.
- Exemplo de como deve ser o campo number:
  "number": "[email protected]"
- Essa abordagem é necessária para garantir que a mensagem seja enviada corretamente para o grupo via API, já que os números de grupos no WhatsApp possuem esse formato distinto.
Envio de Imagem com Template via API Oficial:
- Se você estiver utilizando um template com mídia (imagem) na API oficial, o procedimento é o seguinte:
  - Ao enviar uma mensagem com um template de imagem, você deve deixar o campo templateMediaId vazio. Com isso, a imagem que está salva no template será automaticamente vinculada à mensagem.
  - Exemplo de como o JSON deve ser estruturado:
    { "templateId": "xxxxxxxxxxxxxxxxxxxxxxxxx", "params": ["param1", "param2", "param3"], "number": "556400000000", "externalKey": "123456", "templateMediaId": " " }

EXEMPLO DE RETORNO (API Oficial e Não Oficial)

Após realizar uma requisição de envio de mensagem (seja ela para um número individual ou grupo, com ou sem template), o retorno da API vai fornecer uma resposta estruturada com as informações relevantes da transação.

Para envio de imagem dentro de um template (API oficial):

Quando você enviar uma mensagem utilizando um template com mídia, o sistema retorna o templateMediaId, que é o identificador da mídia vinculada ao template utilizado. Caso você tenha deixado o campo templateMediaId vazio, o sistema usará a mídia configurada no template.

Exemplo de resposta com sucesso (com template de mídia):

{ "templateId": "xxxxxxxxxxxxxxxxxxxxxxxxx", "templateMediaId": "yyyyyyyyyyyyyyyyyyyy", "number": "556400000000", "externalKey": "123456" }

Explicação dos campos:

templateId: O ID do template utilizado para o envio.
templateMediaId: O ID da mídia vinculada ao template. Se não foi enviado, o campo retornará com o identificador da mídia do template.
number: O número para o qual a mensagem foi enviada.
externalKey: A chave externa para rastreamento da requisição.

Exemplo de resposta para envio de mensagem para um grupo:

Se você enviou uma mensagem para um grupo (usando o formato @g.us), o retorno da API seguirá o mesmo formato, com a confirmação do número do grupo para garantir que a mensagem foi direcionada corretamente:

{ "body": "MENSAGEM", "number": "[email protected]", "externalKey": 123456 }

Explicação dos campos:

body: O conteúdo da mensagem enviada.
number: O número do grupo para o qual a mensagem foi enviada, incluindo o sufixo @g.us.
externalKey: A chave externa utilizada para rastrear essa requisição.

Considerações Importantes:

Mesmo quando o envio é de imagem ou mídia, o campo body deve ser preenchido, mesmo que seja com um espaço em branco, como mostrado no exemplo de envio de mídia.
Grupos: Para enviar mensagens para um grupo, sempre utilize o formato number: "[email protected]" no campo number. Isso é essencial para que a mensagem seja direcionada ao grupo e não a um contato individual.

WEBHOOK

Esta função permite o envio de dados do contato/atendimento a partir de um determinado evento (gatilho) que ocorre na plataforma.

Onde cadastro o webhook?

Para cadastrar o webhook basta acessar a plataforma e ir em CONFIGURAÇÕES -> API/WEBHOOK -> ADICIONAR e em seguida preencher os campos de WEBHOOKS como mostra a imagem abaixo (logo após os campos de cadastro de API):

Campos a serem preechidos são:

URL Webhook: endereço que a plataforma deve fazer uma requisição para informar da ocorrência do evento
Token de autenticação: código conhecido apenas pela plataforma e o sistema destino
- Obs: será enviado como authorization no header. Se existir prefixo, deverá ser informado aqui. Ex.: Bearer, Token

Eventos

Mensagem criada
Status da mensagem
Contato criado:
Contato atualizado:
Novo atendimento
Atendimento iniciado:
Atendimento transferido:
Atendimento finalizado:
Atendimento atualizado:
Atualização da conexão:

Clique no ícone de ajuda ao lado do nome do evento para visualizar um exemplo de payload para cada evento disponível.

Lista de Configurações para a API e Webhook

Após adicionar a configuração para o PUSH (API) e/ou Webhook, eles aparecerão na listagem com algumas informações:

Nome da API: identificação da API
URL: endereço para requisição do envio da mensagem
Token Autenticação: caso tenha sido informado para o webhook.
Webhook: URL para o webhook

Exemplo de API cadastrada

Para cada registro, é possível realizar algumas ações:

Copiar URL com autenticação: utilizado na requisição para envio de PUSH (API)
Copiar token: utilizado na requisição para envio de PUSH (API)
Editar configuração: utilizado na requisição para envio de PUSH (API) ou envio de dados para Webhook
Gerar novo token: utilizado na requisição para envio de PUSH (API)
Deletar configuração: remove a configuração para envio de PUSH (API) e/ou Webhook cadastrada

Editar Configuração de PUSH (API) e Webhook

No final do formulário de edição, existe a opção de ativar/desativar uma configuração para não precisar excluir sem necessidade.

Logs

É possível fazer uma pesquisa pelos logs de requisição para a API ou envio de dados para o webhook.

Após preencher os campos para o filtro de pesquisa, aperte o botão ATUALIZAR para conferir o resultado na tabela abaixo.

Tabela

Campo

Descrição

ID de identificação da requisição

Nome

Nome da API

Evento

Nome do evento da plataforma

Tipo

Webhook ou API (Push)

Status

Falha ou sucesso (200)

Data

Data e hora da requisição

Ação

Detalhe do evento

Detalhe do Evento

Webhook

URL:

Envio:

Payload
Header

Retorno:

Status
Body
Header

Eventos Disponíveis

Contato criado ("event": "NewContact")

{ "contact": { "id": 17256, "name": "Nome do Contato", "number": "559999009900", "email": "", "profilePicUrl": "https://pps.whatsapp.net/v/...", "tags": [ "Cliente", "OutraTag" ], "extraInfo": [], "leadStatus": { "id": 2, "status": "Em atendimento ", "color": "#0000d6", "active": true, "createdAt": "2023-03-20T17:31:12.723Z", "updatedAt": "2023-03-20T17:31:12.723Z", "userId": 1, "tenantId": 1 }, "wallets": [ { "id": 1, "name": "Administrador", "ContactWallet": { "id": 44, "contactId": 17256, "walletId": 1, "tenantId": 1, "createdAt": "2023-06-05T12:07:48.557Z", "updatedAt": "2023-06-05T12:07:48.557Z" } } ] }, "tenantId": 1, "event": "NewContact" }

Atendimento Iniciado ("event": "StartedTicket")

{ "ticket": { "id": 9902, "status": "open", "unreadMessages": 0, "lastMessage": "Aguarde, logo você será atendido.\n\nNosso atendimento atendimento é de Segunda a Sexta das 08h as 19h aos sábados das 08h as 11:30, se você chegou após esse horário deixe sua solicitação e iremos lhe atender no próximo horário de atendimento.", "channel": "whatsapp", "answered": true, "isGroup": false, "isActiveDemand": false, "isCreatedAPI": false, "lastInteractionBot": "2023-06-05T12:06:38.486Z", "botRetries": 0, "closedAt": null, "lastMessageAt": "1685966800307", "startedAttendanceAt": 1685966829586, "userId": 1, "contactId": 17256, "whatsappId": 1, "autoReplyId": null, "stepAutoReplyId": null, "chatFlowId": null, "stepChatFlow": null, "queueId": 2, "closingReasonId": null, "tenantId": 1, "apiConfig": null, "createdAt": "2023-06-01T13:32:05.089Z", "updatedAt": "2023-06-05T12:07:09.586Z", "contact": { "id": 17256, "name": "Nome do contato", "number": "559999009900", "email": "", "profilePicUrl": "https://pps.whatsapp.net/v/...", "pushname": "Nome do contato", "observations": null, "telegramId": null, "messengerId": null, "instagramPK": null, "isUser": true, "isWAContact": true, "isGroup": false, "leadStatusId": null, "tenantId": 1, "customFields": { "cpf": "12312312311" }, "tags": [], "createdAt": "2023-05-21T21:15:15.480Z", "updatedAt": "2023-06-05T12:06:24.474Z", "extraInfo": [], "leadStatus": null, "wallets": [] }, "user": null }, "tenantId": 1, "event": "StartedTicket" }

Atendimento Transferido ( "event": "TransferOfTicket")

Atualização da Conexão ("event": "ConnectionStatusUpdate")

{ "connection": { "UrlWabaWebHook": "", "UrlMessengerWebHook": "", "id": 1, "name": "Linha 2", "qrcode": "", "status": "CONNECTED", "battery": "20", "plugged": false, "isActive": true, "isRejectCall": true, "callRejectedMessage": null, "isDeleted": false, "retries": 0, "isDefault": true, "instagramUser": null, "fbPageId": null, "type": "whatsapp", "number": "5599999999999", "phone": {}, "tenantId": 1, "createdAt": "2021-03-12T02:23:17.000Z", "updatedAt": "2023-06-05T12:46:57.643Z", "chatFlowId": 1, "defaultQueueId": 6 }, "tenantId": 1, "event": "ConnectionStatusUpdate" }

Contato Atualizado ("event": "UpdateContact")

Atendimento Finalizado ("event": "FinishedTicket")

Mensagem criada ("event": "NewMessage")

{ "message": { "mediaName": null, "mediaUrl": null, "msgCreatedAt": "2023-06-05T12:06:40.000Z", "id": "e3b501ba-91ab-4066-a8da-3b67da787f4e", "wabaMediaId": null, "isDeleted": false, "userId": null, "scheduleDate": null, "ticketId": 9902, "body": "Aguarde, logo você será atendido.\n\nNosso atendimento atendimento é de Segunda a Sexta das 08h as 19h aos sábados das 08h as 11:30, se você chegou após esse horário deixe sua solicitação e iremos lhe atender no próximo horário de atendimento.", "contactId": 17256, "fromMe": true, "read": true, "mediaType": "chat", "timestamp": "1685966800", "quotedMsgId": null, "sendType": "bot", "tenantId": 1, "note": false, "isTransfer": false, "status": "sended", "ack": 0, "messageId": "3EB037CACC8DF2BD474D5E", "updatedAt": "2023-06-05T12:06:40.079Z", "createdAt": "2023-06-05T12:06:40.079Z", "idFront": null }, "tenantId": 1, "event": "NewMessage" }

Atendimento Atualizado ("event": "UpdateOnTicket")

Novo atendimento ("event": "NewTicket")

Status da mensagem ("event": "AckMessage")

{ "ack": 2, "id": "a9985ce6-671a-48e9-b7a0-ce479ffd95fc", "messageId": "3EB081AFDAE68EAFBBC2F2", "ticketId": 9902, "tenantId": 1, "event": "AckMessage" }

AnteriorIntegrações (Webhook/API)PróximoFuncionamento e consumo dos créditos de Push/API

Atualizado há 1 mês