Contatos

Contatos são cadastros isolados por workspace. O mesmo cliente pode falar com bots de workspaces diferentes, mas o MEX mantém cadastro, identidades, conversas e memória separados para cada contexto.

Quando um contato é criado

O MEX pode criar ou vincular contatos automaticamente quando chega uma mensagem por WhatsApp, Telegram, Instagram ou Webchat. Também é possível cadastrar contatos manualmente pelo painel em Contatos.

Cada contato pode ter várias identidades:

Campo	Uso
`channel`	Canal de origem, como `whatsapp_cloud`, `telegram`, `instagram` ou `webchat`
`remote_jid`	Identificador do cliente naquele canal
`phone_e164`	Telefone normalizado quando o canal permite identificar com segurança
`external_id`	ID externo do provedor quando disponível

API do painel

As rotas abaixo usam o JWT do usuário do painel e o header X-Workspace-Id.

curl "https://api.mex.aillom.com.br/api/contacts?limit=50&q=joao" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Workspace-Id: UUID_DO_WORKSPACE"

Criar contato

curl -X POST https://api.mex.aillom.com.br/api/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Workspace-Id: UUID_DO_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "João Silva",
    "phone_e164": "+5511999999999",
    "email": "joao@exemplo.com",
    "company_name": "Exemplo LTDA",
    "tags": ["lead", "vip"]
  }'

Obter contato completo

curl https://api.mex.aillom.com.br/api/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Workspace-Id: UUID_DO_WORKSPACE"

A resposta inclui o cadastro, identidades, memória estruturada e conversas recentes.

Memória do contato

A memória do contato é separada da memória da conversa. Ela serve para guardar dados úteis de longo prazo para a IA, como resumo, fatos confirmados, preferências e tarefas abertas.

curl -X PUT https://api.mex.aillom.com.br/api/contacts/{id}/memory \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Workspace-Id: UUID_DO_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Cliente pediu orçamento e prefere atendimento por WhatsApp.",
    "facts": { "produto_interesse": "plano pro" },
    "preferences": { "canal": "whatsapp" },
    "open_tasks": [{ "task": "retornar proposta" }],
    "lifecycle_stage": "lead",
    "lead_score": 80
  }'

:::info Memória global do contato usa agent_id: null. Se precisar de memória específica por agente, envie agent_id no corpo da requisição. :::

Isolamento por workspace

O MEX nunca deve compartilhar o contexto de um contato entre workspaces. Exemplo: se uma pessoa fala com um bot de pizzaria e depois com um bot de clínica médica, cada workspace tem seu próprio contato, histórico, RAG, ferramentas e memória.

Para integrações, sempre envie o X-Workspace-Id correto no painel/API autenticada. Em rotas com Workspace API Key, o workspace é resolvido pela própria chave.