<!-- Fonte: https://developers.conectaai.io/referencia/contatos · conecta/ai Desenvolvedores -->
> As pessoas com quem a organização conversa e os canais de cada uma. Referência gerada do contrato da API.

# Contatos

{/* Gerado por scripts/gerar-referencia.mjs a partir de openapi/openapi.json. Não edite: rode `pnpm referencia`. */}

# Contatos

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

| Operação | Endpoint |
|---|---|
| [Listar contatos](#listar-contatos) | `GET /contacts` |
| [Ler um contato](#ler-um-contato) | `GET /contacts/{id}` |

## Listar contatos

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](#objeto-contact) em `data`, e `next_cursor` para a próxima. Veja [Paginação](/paginacao).

### 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](/erros).

### Exemplo

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

Resposta `200`:

```json
{
  "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

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](#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](/erros).

### Exemplo

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

Resposta `200`:

```json
{
  "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. |