Integracao com Kommo CRM

A integracao com o Kommo CRM dispara templates de WhatsApp automaticamente a partir do seu funil de vendas: quando um lead e criado ou quando um lead entra numa etapa que voce escolher. O telefone e o nome vem do contato vinculado ao lead no Kommo — voce nao precisa digitar nada.

Exemplos de uso:

• Lead entra na etapa "Proposta enviada" → recebe template com o resumo da oferta.
• Lead criado em qualquer funil → recebe boas-vindas em segundos.
• Lead entra em "Sem resposta" → recebe follow-up 24 horas depois (delay por regra).

Pre-requisitos

1. Conexao de WhatsApp ativa no UltronChat (a pagina Kommo so existe em conexoes WhatsApp).
2. Plano Pro ou superior — no Essencial os eventos chegam mas ficam SKIPPED.
3. Template de WhatsApp aprovado (status APPROVED na Meta).
4. Conta no Kommo — qualquer plano serve para conectar; a inscricao automatica do webhook exige usuario admin e plano Kommo Advanced ou superior (senao, cadastre o webhook manualmente — ver abaixo).

Passo 1 — Gerar o token no Kommo

O UltronChat usa um token de longa duracao de uma integracao privada do Kommo para validar sua conta e buscar os dados do contato na hora do disparo.

1. No Kommo, va em Configuracoes → Integracoes → + Criar integracao.
2. Preencha:
   • URL de redirecionamento: qualquer URL HTTPS valida (ex.: https://ultronchat.ai). Esse campo e obrigatorio no Kommo, mas nao e usado pelo UltronChat.
   • Webhook de notificacao revogada: deixe vazio.
   • Permitir acesso: Todos — pode manter marcado.
   • Controle de duplicatas e Fontes multiplas: deixe desmarcados.
   • Nome: UltronChat (ou o que preferir).
3. Salve, abra a integracao criada e va na aba Chaves e escopos.
4. Clique em Gerar token de longa duracao, selecione todos os escopos e copie o token (um codigo longo comecando com eyJ... — ele so aparece uma vez).
5. Anote tambem o subdomain da sua conta: e o que aparece na URL antes de .kommo.com (ex.: em https://minhaempresa.kommo.com, o subdomain e minhaempresa).

Passo 2 — Conectar no UltronChat

1. Abra Dashboard → sua conexao WhatsApp → Kommo.
2. Cole o subdomain e o token e clique em Conectar.
3. O UltronChat testa o token na hora contra a API do Kommo e confere se ele pertence mesmo ao subdomain informado. Badge "Token valido" = conectado.

O token fica criptografado no banco e nunca aparece de novo na tela — o campo fica vazio e serve apenas para colar um token novo ao reconectar.

Passo 3 — Inscrever o webhook

O Kommo precisa avisar o UltronChat quando algo acontece. A pagina mostra a URL do webhook, unica desta conexao — mantenha-a secreta.

Opcao A — automatica (recomendada): clique em Assinar webhook automaticamente. Funciona se o seu usuario Kommo for admin e a conta estiver no plano Advanced ou superior.

Opcao B — manual: clique em Copiar e, no Kommo, va em Configuracoes → Integracoes → Webhooks, cole a URL e marque os eventos "Lead criado" e "Etapa do lead alterada".

O Kommo desativa webhooks que falham repetidamente por ~2 horas. Se voce desativar a integracao no UltronChat por muito tempo, pode ser preciso reativar o webhook no Kommo depois.

Passo 4 — Criar regras de disparo

Em Regras de disparo → + Nova regra:

Campo	O que faz
Evento	Lead criado (add_lead) ou Etapa do lead alterada (status_lead).
Funil	Para etapa alterada: obrigatorio. Para lead criado: opcional ("Qualquer funil").
Etapa	So para etapa alterada: a regra dispara quando o lead entra nessa etapa.
Template	Um template de WhatsApp com status APPROVED.
Variaveis	Mapeie cada {{N}} do template para um campo (tabela abaixo).
Atraso	Imediato, 5 min, 1h, 6h, 24h, 48h, 72h ou personalizado em minutos (max 7 dias).

Os dropdowns de funil e etapa sao carregados direto do seu Kommo (por isso o token precisa estar valido).

Variaveis disponiveis

Fonte	Valor
Primeiro nome do contato	first_name do contato no Kommo (ou 1a palavra do nome completo)
Nome completo do contato	Nome do contato vinculado ao lead
Telefone do contato	Telefone resolvido (formato internacional)
Email do contato	Email do contato
Nome do lead	Titulo do card no Kommo
ID do lead	Numero do lead
Valor do lead	Campo "valor de venda" (numero cru, sem simbolo de moeda)
Nome do funil	Nome do pipeline
Nome da etapa	Nome da etapa nova
Texto fixo	Um texto que voce digita e vale para todos os disparos

Variavel que nao existir no lead (ex.: contato sem email) resolve como vazio — o template e enviado mesmo assim.

Como o disparo funciona

1. O Kommo envia o evento para a URL do webhook.
2. O UltronChat confere: integracao ativa, subdomain confere, plano permite, existe regra ativa para aquele evento/funil/etapa.
3. Enriquecimento: o webhook do Kommo nao traz o telefone — o UltronChat busca o contato principal do lead pela API do Kommo (usando seu token) e extrai telefone, nome e email.
4. O telefone e normalizado: numeros brasileiros com DDD (10-11 digitos) ganham o codigo do pais 55 automaticamente; internacionais precisam vir completos.
5. Envio imediato — ou agendamento, se a regra tem atraso. No envio agendado tudo e re-validado (regra ativa? plano ok? template aprovado?).

Reenvio e duplicidade

• Retries do Kommo (mesmo evento reenviado ate 5x) nao geram mensagem duplicada.
• Lead que sai e volta para a mesma etapa em outro momento dispara de novo — e um evento novo de verdade.
• Editar um lead sem mudar de etapa nao dispara nada.

Historico de disparos

A tabela no fim da pagina mostra cada evento processado:

Status	Significado
QUEUED	Agendado (regra com atraso) — mostra o horario previsto
SENT	Template enviado ao WhatsApp
DELIVERED / READ	Confirmacoes de entrega/leitura vindas da Meta
FAILED	Envio falhou (ex.: numero invalido para WhatsApp)
SKIPPED	Evento ignorado — a coluna de motivo explica

Motivos de SKIPPED mais comuns

Motivo	Causa e solucao
no_contact	O lead nao tem contato vinculado no Kommo. Vincule um contato ao card.
no_phone	O contato existe mas nao tem telefone (ou o numero nao e normalizavel).
plan_not_allowed	Conta no plano Essencial — faca upgrade para Pro.
kommo_token_invalid	Token revogado/expirado no Kommo — cole um token novo e reconecte.
subdomain_mismatch	O evento veio de uma conta Kommo diferente da cadastrada (a URL do webhook vazou ou foi colada na conta errada).

Pausar ou desconectar

• Toggle "Ativar integracao Kommo": desligado, os eventos recebidos sao ignorados (nada e registrado nem enviado). As regras ficam salvas.
• Regras individuais tambem tem toggle proprio.
• Para desconectar de vez, revogue o token no Kommo (a integracao passa a registrar kommo_token_invalid) e/ou apague o webhook no Kommo.

Sincronizar o CRM do UltronChat com o Kommo

Alem de receber eventos do Kommo, a integracao tambem trabalha no sentido contrario: o que acontece no UltronChat pode ser espelhado automaticamente na sua conta Kommo. Tudo e opcional e comeca desligado — ative apenas o que quiser no card "Sincronizar CRM → Kommo" da pagina Kommo.

Sincronizacao	O que faz
Contatos	Cliente atendido pela IA (com telefone ou email) vira contato no Kommo, com a tag ultronchat. Se o contato ja existe la (mesmo telefone), apenas vinculamos — nada e sobrescrito.
Leads	Quando a IA registra os dados do cliente na conversa (nome, email, telefone via ferramenta de CRM), o contato vira um lead no Kommo, no funil e etapa default que voce escolher — no maximo 1 lead por contato.
Estagio	Mudar o estagio de um contato no CRM do UltronChat (Novo, Engajado, Qualificado, Cliente, Perdido) move o lead vinculado para a etapa do Kommo que voce mapear.
Escalacao	Quando um cliente pede atendimento humano, criamos uma tarefa (prazo de 24h) + nota com o resumo da conversa no lead/contato vinculado no Kommo.

Configuracao:

1. Clique em "Carregar funis" para listar os funis da sua conta.
2. Para Leads: escolha o funil/etapa onde leads novos devem entrar (ou deixe "Funil padrao do Kommo").
3. Para Estagio: mapeie cada estagio do CRM para um funil + etapa do Kommo. Estagio sem mapeamento simplesmente nao sincroniza.
4. Ative os toggles desejados e clique em Salvar.

O rodape do card mostra as ultimas sincronizacoes com status (OK, SKIPPED com motivo, FAILED). A sincronizacao e assincrona e nao interfere no atendimento: se o Kommo estiver fora do ar ou o token invalido, o atendimento segue normal e apenas o sync fica registrado como falha.

Importante: quando o UltronChat move um lead de etapa (sync de estagio), o evento que o Kommo dispara de volta e ignorado automaticamente — suas regras de disparo de template nao sao acionadas por mudancas feitas pelo proprio UltronChat (protecao anti-loop).

Importar audiencia do Kommo

O card "Importar audiencia do Kommo" puxa os contatos dos leads de um funil (e opcionalmente de uma etapa especifica) e cria uma lista de contatos reutilizavel para campanhas de WhatsApp:

1. Clique em "Carregar funis" e escolha o funil (e a etapa, se quiser).
2. De um nome para a lista e confirme.
3. O import roda em segundo plano: leads sem telefone (ou com numero invalido) sao contados como rejeitados; o restante entra na lista.
4. Ao terminar, a lista aparece na sua pagina de listas de contatos e pode ser usada como audiencia de campanha.

Regras importantes: numeros que ja pediram SAIR (opt-out) continuam excluidos de campanhas mesmo se vierem no import; rodar o import de novo nao duplica contatos; o volume e limitado a ~10.000 leads por import.

Problemas comuns

• Badge "Token invalido" — o token foi revogado no Kommo (ex.: a integracao privada foi apagada) ou expirou. Gere um novo token de longa duracao e cole em "Reconectar".
• Dropdown de funis vazio — recarregue a pagina apos conectar; se persistir, teste o token com o botao "Testar token".
• Movi o lead e nada chegou — confira, nesta ordem: (1) webhook inscrito no Kommo com os dois eventos marcados; (2) regra ativa com o funil E a etapa certos; (3) historico de disparos — se ha linha SKIPPED, o motivo diz o que falta; se nao ha linha nenhuma, o evento nao chegou (webhook).
• Chegou duas vezes — verifique se nao ha duas regras ativas cobrindo o mesmo evento/etapa.
• Sync de contato/lead nao aconteceu — confira: (1) o toggle correspondente esta ativo e salvo; (2) o token esta valido; (3) o cliente tem telefone ou email registrado no CRM (sem identidade nao ha como buscar no Kommo — motivo no_identity); (4) para sync de estagio, o estagio precisa estar mapeado (motivo stage_unmapped) e o contato precisa ter um lead vinculado (motivo no_link — leads sao criados pelo sync de Leads).
• Import terminou com muitos rejeitados — normalmente sao leads cujo contato nao tem telefone no Kommo, ou telefones sem DDD/invalidos.