Contatos

As pessoas com quem a organização conversa e os canais de cada uma.

Operação	Endpoint
Listar contatos	`GET /contacts`
Ler um contato	`GET /contacts/{id}`

Listar contatos

GET/contacts

Lista os contatos da organização, do mais recente para o mais antigo. Para achar um contato pelo telefone, use phone.

Permissão exigida na chave: contatos:read.

Parâmetros de consulta

Nome	Tipo	Obrigatório	Descrição
`limit`	inteiro	não	Quantos itens por página, de 1 a 100. Padrão 50.
`cursor`	texto	não	Valor de `next_cursor` da página anterior. Omita para a primeira página.
`status`	`customer`, `lead`, `former_customer`, `prospect`, `contact`	não	Só contatos nesta situação.
`phone`	texto	não	Só o contato com este telefone, com DDI. Pontuação é ignorada: +55 (11) 98765-4321 vale.
`updated_after`	texto	não	Só contatos alterados a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.

Resposta 200

Uma página de objetos Contact em data, e next_cursor para a próxima. Veja Paginação.

Erros

Status	Quando
`400`	`invalid_parameter`: Parâmetro inválido.
`401`	`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.
`403`	`insufficient_scope`: Escopo insuficiente.
`429`	`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.
`500`	`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.

O corpo segue o formato de Erros.

Exemplo

curl "https://app.conectaai.io/api/v1/contacts" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"

Resposta 200:

{
  "data": [
    {
      "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "name": "Maria Souza",
      "status": "customer",
      "blocked": false,
      "custom_fields": {},
      "channels": [
        {
          "channel": "whatsapp",
          "identifier": "5511987654321",
          "kind": "phone",
          "verified": false
        }
      ],
      "created_at": "2026-11-09T14:32:05.120Z",
      "updated_at": "2026-11-09T14:32:05.120Z"
    }
  ],
  "next_cursor": null
}

Ler um contato

GET/contacts/{id}

Devolve um contato da organização pelo identificador, com os canais dele.

Permissão exigida na chave: contatos:read.

Parâmetros de caminho

Nome	Tipo	Obrigatório	Descrição
`id`	texto	sim	Identificador do recurso.

Resposta 200

Um objeto Contact.

Erros

Status	Quando
`401`	`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.
`403`	`insufficient_scope`: Escopo insuficiente.
`404`	`not_found`: Recurso não encontrado.
`429`	`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.
`500`	`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.

O corpo segue o formato de Erros.

Exemplo

curl "https://app.conectaai.io/api/v1/contacts/<id>" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"

Resposta 200:

{
  "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "name": "Maria Souza",
  "status": "customer",
  "blocked": false,
  "custom_fields": {},
  "channels": [
    {
      "channel": "whatsapp",
      "identifier": "5511987654321",
      "kind": "phone",
      "verified": false
    }
  ],
  "created_at": "2026-11-09T14:32:05.120Z",
  "updated_at": "2026-11-09T14:32:05.120Z"
}

Objeto Contact

Uma pessoa com quem a organização conversa.

Campo	Tipo	Descrição
`id`	texto	Identificador do contato.
`name`	texto	Nome do contato.
`status`	`customer`, `lead`, `former_customer`, `prospect`, `contact`	customer: cliente. lead: interessado. former_customer: ex-cliente. prospect: em prospecção. contact: só contato.
`blocked`	booleano	A equipe bloqueou o contato.
`custom_fields`	objeto	Campos personalizados da organização.
`channels`	lista de objeto	Canais por onde o contato fala com a organização.
`channels[].channel`	`whatsapp`, `voice`, `instagram`, `messenger`, `telegram`, `email`, `sms`, `webchat`, `app`	Canal.
`channels[].identifier`	texto	Identificador no canal. Telefone só com dígitos, com DDI (5511987654321); nos canais sem telefone, um identificador opaco.
`channels[].kind`	`phone`, `bsuid`	phone: é um telefone. bsuid: identificador opaco do canal.
`channels[].verified`	booleano	O canal foi verificado como da pessoa.
`created_at`	texto	Quando o contato foi criado. Data e hora em ISO 8601, UTC.
`updated_at`	texto	Última alteração do contato. Data e hora em ISO 8601, UTC.

Conversas Etiquetas