Integração Kommo

Como integrar agentes Triadeflow com Kommo CRM. Kommo é o CRM padrão para clientes brasileiros que buscam funil simples e custo baixo.

Quando usar Kommo

Cliente já tem conta Kommo
Operação simples de funil de vendas
Volume moderado (<50k conversas/mês)
Cliente prefere interface mais leve que GHL

Para clientes com necessidades mais complexas (múltiplos funis, automações avançadas, calendário nativo), considerar GHL.

Provider de mensageria

Kommo usa Evolution API como provider de WhatsApp. Detalhes em .claude/integrations/evolution-api.md.

Setup do tenant

1. Acesso ao Kommo do cliente

Você precisará:

Subdomínio: {cliente}.kommo.com
API Token (gerar em Settings > API)
ID do Pipeline alvo
IDs dos Stages relevantes

2. Criar pipeline (se não existe)

Stages padrão Triadeflow (adaptar ao cliente):

Stage	Função
Inbound	Lead recém chegado, agente assumiu
Em qualificação	Agente está fazendo perguntas
Qualificado	Lead atende critérios, pronto pra avançar
Agendado	Reunião marcada
Em negociação	Humano assumiu, conversando preço
Convertido	Fechou
Perdido	Não converteu (registrar motivo)

Anote os IDs e adicione ao config.yaml:

crm:
  type: kommo
  base_url: https://{cliente}.kommo.com
  api_token: ${TENANT_KOMMO_TOKEN}
  pipeline_id: 1234567
  stages:
    inbound: 1111
    em_qualificacao: 1112
    qualificado: 1113
    agendado: 1114
    em_negociacao: 1115
    convertido: 1116
    perdido: 1117

3. Custom fields

Cada tipo de agente requer campos diferentes. Para agent-sdr no nicho saúde:

Campo	Tipo	Origem
Convênio	Select	Pergunta inicial
Queixa principal	Text	Conversa
Tempo do incômodo	Select	Pergunta padronizada
Tentou tratamento?	Boolean	Conversa
Urgência	Select (alta/média/baixa)	LLM-as-judge
Origem	Select	UTM ou pergunta

Adicionar IDs dos custom_fields ao config:

crm:
  custom_fields:
    convenio: 555111
    queixa_principal: 555112
    tempo_incomodo: 555113
    tentou_tratamento: 555114
    urgencia: 555115
    origem: 555116

4. Webhook reverso

Para mudanças no Kommo dispararem ações no agente (ex: humano marcou “Convertido” → agente para de seguir):

Configurar webhook em Kommo:

URL: https://{tipo}.triadeflow.com/webhook/kommo/{tenant_id}
Eventos: lead_status_changed, lead_responsible_changed

Operações comuns no código

Criar lead

from triadeflow_core.crm.kommo import KommoClient

client = KommoClient(config.crm)

lead_id = await client.create_lead(
    name=user_name,
    phone=user_phone,
    pipeline_id=config.crm.pipeline_id,
    stage_id=config.crm.stages["inbound"],
    custom_fields={
        "origem": "whatsapp",
    },
    tags=["agente_sdr", "auto_criado"],
)

Atualizar custom field

await client.update_lead(
    lead_id=lead_id,
    custom_fields={
        "convenio": "Bradesco Saúde",
        "urgencia": "alta",
    }
)

Mover de stage

await client.move_lead(
    lead_id=lead_id,
    stage_id=config.crm.stages["qualificado"]
)

Atribuir a humano (handoff)

await client.assign_lead(
    lead_id=lead_id,
    user_id=config.handoff.kommo_user_id,
    note="Cliente solicitou atendimento humano"
)

Adicionar nota (audit trail)

await client.add_note(
    lead_id=lead_id,
    text="Agente qualificou: convênio Bradesco, urgência alta, agendou 15/05"
)

Erros comuns

Token expirado

Kommo OAuth tokens expiram em 24h. Use refresh_token automaticamente:

# triadeflow-core já trata isso, mas se você precisar manual:
new_token = await client.refresh_token(refresh_token=stored_refresh_token)

Rate limit

Kommo limita ~7 req/seg. Use tenacity com backoff e considere batch quando possível.

Custom field ID não bate

Cada cliente tem IDs diferentes de custom fields. Nunca hardcode IDs no código. Tudo no config.yaml.

Mapping de timezones

Kommo armazena timestamps em UTC. Converter para timezone do tenant antes de exibir ou comparar:

from datetime import datetime
import pytz

tz = pytz.timezone(config.horario.timezone)  # America/Sao_Paulo
local_time = utc_time.replace(tzinfo=pytz.UTC).astimezone(tz)

MCP Kommo (alternativa)

A Triadeflow tem um MCP server próprio para Kommo: mcp_kommo (GitHub: triadeflow-ia/mcp_kommo).

Quando ativado, Claude Code pode operar diretamente no Kommo via natural language (“move o lead 123 para qualificado”) sem precisar escrever código de integração.

Configurar em .mcp.json:

{
  "mcpServers": {
    "kommo": {
      "url": "https://mcp-kommo.triadeflow.com/sse",
      "transport": "sse"
    }
  }
}

Referências internas

Stays.net to Kommo (Miracasa) — caso real complexo de integração
Kiwify to Kommo (Dr. Milena) — webhook de pagamento
AppSheet to Kommo (Petisco) — sync bidirecional com CNPJ

Detalhes em .claude/examples/integrations/.

Versão: 1.0