Contatos

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âmetro	Descrição
`q`	Busca textual em nome, e-mail, telefone, identifier
`page`	Paginação (15 itens por página)
`sort`	`name`, `phone_number`, `email`, `created_at` (use `-name` pra desc)
`include_contact_inboxes`	`true` 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

Campo	Tipo	Obrigatório	Descrição
`inbox_id`	integer	✅	Onde o contato será criado
`name`	string		Nome do contato
`email`	string		E-mail (precisa ser único por conta)
`phone_number`	string		E.164 (`+5521999544338`)
`identifier`	string		ID externo (ex: ID do CRM)
`avatar_url`	string		URL pública de imagem
`additional_attributes`	object		Metadata sistêmica (cidade, empresa, etc.)
`custom_attributes`	object		Atributos 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étodo	Endpoint
`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 CSV	Mapeamento
`name`	Nome
`email`	E-mail
`phone_number`	Telefone em E.164
`identifier`	ID 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ódigo	Quando acontece
`200 OK`	Sucesso em GET/PATCH
`201 Created`	Contato criado
`204 No Content`	Excluído com sucesso
`400 Bad Request`	Payload inválido
`403 Forbidden`	Sem permissão
`404 Not Found`	Contato não existe
`422 Unprocessable Entity`	E-mail ou telefone já existe na conta

Visão geral

Conversas e mensagens

Organização

Operação

Kanban

Listar contatos

Detalhe do contato

Criar contato

Atualizar contato

Excluir contato

Buscar contatos

Filtro avançado

Conversas do contato

Inboxes vinculadas

Inboxes em que esse contato pode receber

Notas do contato

Importação em massa (CSV)

Bloquear contato

Mesclar contatos (merge)

Códigos de resposta

​Listar contatos

​Detalhe do contato

​Criar contato

​Atualizar contato

​Excluir contato

​Buscar contatos

​Filtro avançado

​Conversas do contato

​Inboxes vinculadas

​Inboxes em que esse contato pode receber

​Notas do contato

​Importação em massa (CSV)

​Bloquear contato

​Mesclar contatos (merge)

​Códigos de resposta

Listar contatos

Detalhe do contato

Criar contato

Atualizar contato

Excluir contato

Buscar contatos

Filtro avançado

Conversas do contato

Inboxes vinculadas

Inboxes em que esse contato pode receber

Notas do contato

Importação em massa (CSV)

Bloquear contato

Mesclar contatos (merge)

Códigos de resposta