Home

 

Como configurar e usar o WhatsApp no K|Notify (Twilio e Insider One)

O K|Notify não abre conversas no WhatsApp. Ele envia avisos (notificações) para o celular das pessoas, usando a conta da sua empresa em um provedor de envio.

Hoje o sistema trabalha com dois provedores:

  • Twilio
  • Insider One (WhatsApp Transactional API)

Você escolhe um provedor por aplicativo. Depois disso, o envio pela tela, por rotina, por lote ou por outro sistema segue o mesmo caminho: o K|Notify coloca o aviso na fila e o provedor escolhido entrega no WhatsApp.

Este artigo é para o administrador: o que precisa existir antes, como preencher as telas e como acompanhar se a mensagem saiu, chegou e foi lida.

O que você precisa entender antes de começar

Pense no envio em três etapas:

  1. Alguém dispara o aviso (tela Home, Envio em lote, rotina ou outro sistema).
  2. O K|Notify guarda o aviso.
  3. O serviço de envio lê a fila e pede ao provedor (Twilio ou Insider One) para entregar no WhatsApp.

O número que envia a mensagem é o da empresa (cadastrado no aplicativo). O número que recebe é o celular da pessoa.

Importante: o WhatsApp exige modelos de mensagem aprovados para a maioria dos envios automáticos. Essa aprovação acontece fora do K|Notify, no painel da Twilio ou da Insider One (e no WhatsApp). Sem o modelo aprovado, o provedor recusa o envio.

1. Escolher o provedor no aplicativo

Caminho: menu do seu usuário (canto superior direito) → Configurações → Aplicativos → abrir ou criar o aplicativo → seção WhatsApp.

No campo Gateway WhatsApp, selecione:

Opção na tela Quando usar
Twilio Sua empresa já tem conta Twilio com WhatsApp.
Insider One Sua empresa envia pelo WhatsApp Transactional API da Insider One.

Se o gateway não estiver selecionado, a opção WhatsApp fica desligada nas telas de envio.

Depois de escolher o gateway, a tela mostra só os campos daquele provedor. Preencha, salve o aplicativo e só então teste um envio.

2. Configurar a Twilio

Antes, a empresa precisa ter, diretamente na Twilio:

  • conta ativa;
  • WhatsApp habilitado;
  • número remetente aprovado;
  • modelos de mensagem aprovados (quando o tipo de aviso exigir template).

No K|Notify, com o gateway Twilio, preencha:

  1. Conta Twilio (accountSid) — o identificador da conta, copiado do painel da Twilio.
  2. authToken (gateway) — a senha de acesso da conta Twilio. Guarde com cuidado; é informação confidencial.
  3. Número (com o código do País) — o número que vai aparecer como remetente, com DDI. Exemplo: 5511999999999 ou +5511999999999.

A tela lembra: a contratação e a configuração do serviço Twilio são feitas pelo cliente. O K|Notify só usa a conta que você informar.

Como a Twilio envia a mensagem

Há dois jeitos de preencher o conteúdo:

Texto livre
Digite a mensagem normalmente. O K|Notify envia esse texto para a Twilio.

Modelo (template)
Use este formato, tudo em uma linha, separado por ponto e vírgula:

ContentSid:HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx;Variavel1:Maria;Variavel2:Unidade Centro
  • ContentSid é o código do modelo já aprovado na Twilio.
  • Variavel1, Variavel2, Variavel3… são os trechos variáveis do modelo, na ordem em que o modelo espera.

Se a mensagem contiver ContentSid:, o K|Notify trata como template. Se não contiver, trata como texto livre.

Como o status volta na Twilio

A Twilio não precisa de webhook no K|Notify. De tempos em tempos, o próprio sistema consulta a Twilio e atualiza se a mensagem foi enviada, entregue ou lida.

3. Configurar a Insider One

Antes, a empresa precisa ter, diretamente na Insider One:

  • acesso ao WhatsApp Transactional API;
  • número remetente cadastrado;
  • modelos de mensagem aprovados (nome do template igual ao que você vai usar no K|Notify).

No K|Notify, com o gateway Insider One, preencha:

  1. Insider One – URL Retorno API — anote aqui a mesma URL que você cadastrou no portal da Insider One. Este campo não dispara o retorno sozinho; serve para registrar o que foi configurado lá.
  2. Insider One – API Key — a chave gerada na Insider One para a API transacional. No painel da Insider ela aparece ligada ao envio (X-INS-AUTH-KEY). É confidencial.
  3. Insider One – Número que envia — o remetente cadastrado na Insider. Exemplo: +5511999999999. Se você digitar sem o +, o K|Notify inclui.

Como a Insider One envia a mensagem

Neste momento o K|Notify envia pela Insider One somente por template. O conteúdo da notificação precisa seguir este formato:

templateName:nome_do_template;Variavel1:Maria;Variavel2:Unidade Centro;Variavel3:1
  • templateName é o nome do modelo cadastrado na Insider One (não é o texto da mensagem).
  • Variavel1, Variavel2, Variavel3… preenchem os campos variáveis do corpo do modelo, na ordem.

Exemplo realista:

templateName:aviso_agendamento;Variavel1:João Silva;Variavel2:Cardiologia;Variavel3:20/08/2026 14h

Se templateName: não estiver na mensagem, o envio pela Insider One não segue.

Os modelos são enviados com idioma português do Brasil (pt_BR). O template na Insider One precisa estar cadastrado nesse idioma.

Como o status volta na Insider One (obrigatório)

Diferente da Twilio, a Insider One avisa o K|Notify quando a mensagem muda de situação (enviada, entregue, lida). Para isso você precisa de três peças:

  1. Um endereço (URL) da API do K|Notify.
  2. Uma chave de API do K|Notify, com permissão específica.
  3. Essa URL e essa chave cadastradas no portal da Insider One.

Passo A — Criar a chave no K|Notify

Caminho: Configurações → Chaves de API → Nova chave.

  1. Dê um nome fácil de reconhecer, por exemplo: Callback Insider One.
  2. Em Permissões, marque InsiderOne – Callback.
  3. Salve.

A chave secreta aparece só uma vez. Copie e guarde em local seguro. Se perder, será preciso gerar outra chave.

Essa chave não é a API Key da Insider One. São coisas diferentes:

Chave Onde nasce Para que serve
API Key da Insider One Portal da Insider One O K
Chave de API do K Notify (InsiderOne – Callback) Tela Chaves de API

Passo B — Informar o retorno no portal da Insider One

Peça ao responsável técnico da Insider One (ou cadastre no painel deles) um webhook com:

  • Método: POST
  • Endereço: https://SEU-SERVIDOR-DA-API/api/Callback/InsiderOne
    Troque SEU-SERVIDOR-DA-API pelo endereço real da API do K|Notify da sua instalação (o time de infraestrutura ou o suporte Kentech informa esse valor).
  • Cabeçalho de autenticação:
Authorization: Bearer COLE_AQUI_A_CHAVE_GERADA_NO_KNOTIFY

Copie essa mesma URL no campo Insider One – URL Retorno API do aplicativo, só para ficar registrado.

Quando a Insider One avisar o status, o K|Notify atualiza:

| Status recebido | O que o K|Notify registra |
| — | — |
| sent | data/hora de envio |
| delivered | data/hora de entrega (e mantém o envio, se ainda não existir) |
| read | data/hora de leitura (e mantém envio e entrega, se ainda não existirem) |

Se a chave estiver errada ou sem a permissão InsiderOne – Callback, o retorno é recusado e o status não atualiza.

4. Liberar quem envia e quem recebe

Configurar o aplicativo não basta. Também é preciso dizer quem pode disparar WhatsApp e em qual celular a pessoa recebe.

Quem pode enviar

Caminho: Configurações → Usuários → editar o usuário.

Em Método de Envio, marque WhatsApp. Isso libera o canal para aquela pessoa disparar avisos.

Administradores continuam podendo enviar mesmo quando essa marcação não estiver no próprio cadastro.

Quem recebe (número do celular)

Caminho: lista de Usuários → Outras Ações → Métodos para Recebimento.

  1. Método: WhatsApp.
  2. Celular: DDI + DDD + número. A máscara da tela ajuda no formato brasileiro (+55).

Sem esse método de recebimento, o usuário cadastrado não entra na lista de destinos WhatsApp.

Rotinas automáticas

Caminho: Configurações → Rotinas → editar a rotina.

Marque WhatsApp nos métodos da rotina. A rotina usa o gateway já configurado no aplicativo associado.

5. Enviar na prática

Pela tela Home

No menu Home:

  1. Escolha o aplicativo em De.
  2. Escolha o usuário, o grupo ou (quando a tela permitir) um envio avulso.
  3. Marque WhatsApp.
  4. Preencha o título e a mensagem (texto livre na Twilio, ou o formato de template da seção 2 ou 3).
  5. Envie.

Se o WhatsApp estiver cinza / desmarcado, o aplicativo provavelmente está sem gateway.

Por Envio em lote

No menu Envio em lote, o raciocínio é o mesmo: aplicativo com gateway, canal WhatsApp marcado e conteúdo no formato certo para o provedor.

Número do celular

O sistema limpa espaços, parênteses, hífens e o sinal +. Depois dessa limpeza, o número precisa ter menos de 14 dígitos. Um celular brasileiro com DDI costuma ter 13 dígitos, por exemplo 5511999999999. Número maior que isso é recusado com “Celular inválido”.

6. Integrar outro sistema (API)

Use esta seção se outro sistema da empresa (prontuário, ERP, site) for disparar o WhatsApp sem alguém clicar na tela.

Autenticação

Crie uma chave em Configurações → Chaves de API, com a permissão Registrar Notificação.

Todas as chamadas levam o cabeçalho:

Authorization: Bearer SUA_CHAVE

Registrar o aviso

  • Método: POST
  • Endereço: https://SEU-SERVIDOR-DA-API/api/Notificacoes/RegistrarNotificacao
  • Corpo: lista em JSON. Cada item é um aviso.

Campos mais usados:

Campo O que informar
appId Código do aplicativo já configurado com Twilio ou Insider One
clienteid Código do cliente no K
tp_notificacao WHATSAPP (pessoa já cadastrada) ou WHATSAPPA (envio avulso, sem cadastro)
v_token Com WHATSAPP: identificador (token) do usuário ou grupo. Com WHATSAPPA: pode ser o celular, se autonomo estiver vazio
autonomo Celular do destino no envio avulso (WHATSAPPA)
mensagem Texto livre (Twilio) ou o formato de template da seção 2 / 3
titulo Título do aviso
dt_agendamento Opcional. Se informar, o envio espera essa data/hora
integracao_sid Opcional. Código do seu sistema para evitar duplicar o mesmo aviso

Exemplo de envio avulso com template da Insider One:

[
  {
    "appId": 1,
    "clienteid": 1,
    "tp_notificacao": "WHATSAPPA",
    "autonomo": "5511999997777",
    "titulo": "Lembrete de consulta",
    "mensagem": "templateName:aviso_agendamento;Variavel1:Maria;Variavel2:Cardiologia;Variavel3:20/08/2026 14h"
  }
]

Exemplo de template Twilio para pessoa já cadastrada:

[
  {
    "appId": 1,
    "clienteid": 1,
    "tp_notificacao": "WHATSAPP",
    "v_token": "TOKEN_DO_USUARIO",
    "titulo": "Lembrete de consulta",
    "mensagem": "ContentSid:HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx;Variavel1:Maria;Variavel2:Cardiologia"
  }
]

Resposta em caso de sucesso traz "resultado": "OK" e o código interno da notificação. Isso significa que o aviso entrou na fila. A entrega no WhatsApp acontece em seguida, pelo provedor.

Retornos comuns:

Retorno Significado simples
OK Aviso registrado
ERRO 101 Aplicativo (appId) inválido
ERRO 102B Usuário não encontrado ou sem WhatsApp cadastrado
ERRO 104 Faltou o tipo da notificação
ERRO 105 No envio avulso, faltou o destino (autonomo)
ERRO 201 Já existe aviso com o mesmo integracao_sid
ERRO 901 Licença do K

O webhook da Insider One não usa essa permissão de registrar notificação. Ele usa a permissão InsiderOne – Callback, no endereço POST /api/Callback/InsiderOne, como na seção 3.

7. Acompanhar se a mensagem chegou

Depois do envio, o K|Notify guarda o andamento:

  • queued (Insider One) ou accepted / queued (Twilio): o provedor aceitou e a mensagem está a caminho.
  • sent: saiu
  • delivered: chegou no aparelho
  • read: foi lida

Essas datas ficam no histórico da notificação (dt_whatsapp_sent, dt_whatsapp_delivered, dt_whatsapp_read).

Lembrete:

  • Twilio: o próprio K|Notify pergunta o status à Twilio.
  • Insider One: o status só atualiza se o webhook (chave + URL) estiver certo no portal da Insider.

O K|Notify não recebe respostas de conversa. Ele só dispara o aviso e registra o status de entrega.

8. Problemas frequentes

A opção WhatsApp não aparece ou não deixa marcar
O aplicativo está sem Gateway WhatsApp. Selecione Twilio ou Insider One e salve.

Erro de API Key / autenticação na Insider One
O campo Insider One – API Key do aplicativo está vazio ou diferente da chave do painel da Insider.

Erro de template (templateName) não informado
No gateway Insider One, a mensagem precisa começar com templateName:. Texto livre não é enviado por esse provedor.

ContentSid na Twilio e nada acontece como template
Confira se está escrito exatamente ContentSid: (sem espaço no meio) e se o código é o do modelo aprovado.

Celular inválido
Faltou DDI, ou o número ficou com 14 dígitos ou mais depois da limpeza.

A mensagem sai, mas nunca muda para entregue/lida (Insider One)
O webhook não está chegando. Confira a URL .../api/Callback/InsiderOne, o Authorization: Bearer ... e se a chave tem a permissão InsiderOne – Callback.

Limite de taxa excedido
O provedor recusou por excesso de envios em pouco tempo. Aguarde e tente de novo, ou fale com o provedor sobre o limite da conta.

Template recusado pelo WhatsApp
O modelo ainda não foi aprovado, o nome está diferente, as variáveis estão em quantidade/ordem errada, ou (na Insider One) o idioma do modelo não é pt_BR.

Resumo rápido

  1. No aplicativo, escolha o gateway: Twilio ou Insider One.
  2. Preencha conta/chave e o número que envia.
  3. Na Insider One, crie também a chave de retorno em Chaves de API e cadastre o webhook no portal deles.
  4. Libere WhatsApp no usuário que envia e cadastre o celular em Métodos para Recebimento.
  5. Na mensagem, use texto livre (só Twilio) ou o formato de template:
  6. Twilio: ContentSid:...;Variavel1:...
  7. Insider One: templateName:...;Variavel1:...
  8. Acompanhe enviado / entregue / lido no histórico da notificação.

Se algum endereço de API ou valor de conta não estiver claro na sua instalação, peça ao suporte Kentech o endereço da API e confira, com o provedor, se o número e os templates já estão aprovados no WhatsApp.