Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lfautomatiza.com/llms.txt

Use this file to discover all available pages before exploring further.

Contatos são as pessoas que conversam com sua equipe. Cada contato pode ter múltiplas conversas (uma por canal/inbox) e atributos personalizados ilimitados.

​
Listar contatos

GET /api/v1/accounts/{account_id}/contacts
ParâmetroDescrição
qBusca textual em nome, e-mail, telefone, identifier
pagePaginação (15 itens por página)
sortname, phone_number, email, created_at (use -name pra desc)
include_contact_inboxestrue retorna também as inboxes do contato
curl "https://chat.lfautomatiza.com/api/v1/accounts/1/contacts?q=carlos&page=1" \
  -H "api_access_token: $TOKEN"

​
Detalhe do contato

GET /api/v1/accounts/{account_id}/contacts/{id}

{
  "id": 542,
  "name": "Carlos Antônio",
  "email": "carlos@empresa.com.br",
  "phone_number": "+5521999544338",
  "identifier": "crm-id-1234",
  "thumbnail": "https://cdn.lfautomatiza.com/...",
  "additional_attributes": {
    "city": "Rio de Janeiro",
    "country": "Brazil",
    "company_name": "ACME Corp"
  },
  "custom_attributes": {
    "valor_lifetime": 12500,
    "categoria": "vip"
  },
  "contact_inboxes": [
    { "source_id": "5521999544338", "inbox": { "id": 1, "name": "WhatsApp Principal" } }
  ]
}

​
Criar contato

POST /api/v1/accounts/{account_id}/contacts
CampoTipoObrigatórioDescrição
inbox_idinteger✅Onde o contato será criado
namestringNome do contato
emailstringE-mail (precisa ser único por conta)
phone_numberstringE.164 (+5521999544338)
identifierstringID externo (ex: ID do CRM)
avatar_urlstringURL pública de imagem
additional_attributesobjectMetadata sistêmica (cidade, empresa, etc.)
custom_attributesobjectAtributos customizados que você definiu
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/contacts \
  -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 1,
    "name": "Maria Silva",
    "email": "maria@empresa.com",
    "phone_number": "+5511999887766",
    "identifier": "crm-9876",
    "custom_attributes": {
      "fonte": "google-ads",
      "categoria": "lead-quente"
    }
  }'

​
Atualizar contato

PATCH /api/v1/accounts/{account_id}/contacts/{id}
PUT /api/v1/accounts/{account_id}/contacts/{id}

curl -X PATCH https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/542 \
  -H "api_access_token: $TOKEN" \
  -d '{ "email": "novo@email.com" }'

​
Excluir contato

DELETE /api/v1/accounts/{account_id}/contacts/{id}
Exclusão é irreversível e remove todas as conversas e mensagens vinculadas. Considere usar bloqueio em vez de exclusão se for por motivo de comportamento.

​
Buscar contatos

Busca textual otimizada (mais rápida que o GET com q): 
GET /api/v1/accounts/{account_id}/contacts/search

curl "https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/search?q=carlos&include=conversations" \
  -H "api_access_token: $TOKEN"

​
Filtro avançado

POST /api/v1/accounts/{account_id}/contacts/filter

curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/filter \
  -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [
      {
        "attribute_key": "country",
        "filter_operator": "equal_to",
        "values": ["Brazil"]
      },
      {
        "attribute_key": "custom_attributes.categoria",
        "filter_operator": "equal_to",
        "values": ["vip"],
        "query_operator": "and"
      }
    ]
  }'

​
Conversas do contato

GET /api/v1/accounts/{account_id}/contacts/{id}/conversations
Retorna todas as conversas (em qualquer canal) que esse contato já teve.

​
Inboxes vinculadas

Cada contato pode estar em múltiplas inboxes (canais). Lista vinculações atuais: 
GET /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes
Cria nova vinculação (ex: cadastrar e-mail do contato que já existe como WhatsApp): 
POST /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes

curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/542/contact_inboxes \
  -H "api_access_token: $TOKEN" \
  -d '{ "inbox_id": 3, "source_id": "carlos@empresa.com.br" }'

​
Inboxes em que esse contato pode receber

GET /api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes
Lista inboxes onde o contato tem identificador válido pra receber mensagem proativa (útil pra UI de “iniciar nova conversa”).

​
Notas do contato

MétodoEndpoint
GET/contacts/{contact_id}/notes
POST/contacts/{contact_id}/notes
PATCH/contacts/{contact_id}/notes/{id}
DELETE/contacts/{contact_id}/notes/{id}
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/542/notes \
  -H "api_access_token: $TOKEN" \
  -d '{ "content": "Cliente VIP — prioridade total." }'

​
Importação em massa (CSV)

POST /api/v1/accounts/{account_id}/contacts/import
Multipart com o arquivo CSV. Colunas suportadas:
Coluna CSVMapeamento
nameNome
emailE-mail
phone_numberTelefone em E.164
identifierID externo
additional_attributes_*Atributos sistêmicos (ex: additional_attributes_city)
custom_attributes_*Atributos customizados (ex: custom_attributes_categoria)
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/contacts/import \
  -H "api_access_token: $TOKEN" \
  -F "import_file=@contatos.csv"
Tamanho recomendado por arquivo: até 50.000 linhas. Acima disso, divida em arquivos menores pra evitar timeout.

​
Bloquear contato

POST /api/v1/accounts/{account_id}/contacts/{id}/block
POST /api/v1/accounts/{account_id}/contacts/{id}/unblock
Contato bloqueado não consegue iniciar novas conversas. Mensagens existentes ficam preservadas.

​
Mesclar contatos (merge)

Quando o mesmo cliente aparece em 2 cadastros (ex: WhatsApp + e-mail criaram separados): 
POST /api/v1/accounts/{account_id}/actions/contact_merge

curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/actions/contact_merge \
  -H "api_access_token: $TOKEN" \
  -d '{ "base_contact_id": 542, "mergee_contact_id": 543 }'
Todas as conversas, notas e atributos do mergee_contact_id migram pro base_contact_id.

​
Códigos de resposta

CódigoQuando acontece
200 OKSucesso em GET/PATCH
201 CreatedContato criado
204 No ContentExcluído com sucesso
400 Bad RequestPayload inválido
403 ForbiddenSem permissão
404 Not FoundContato não existe
422 Unprocessable EntityE-mail ou telefone já existe na conta