# Buscar contatos por mensagens

Retorna contatos de uma organização que mencionaram uma palavra, frase ou lista de termos em mensagens.

## Rota

```http
GET https://crm.oficinamartech.com/api/contacts/message-search
Authorization: Bearer crm_live_<prefixo>_<segredo>
```

## Autenticação

Use uma API key criada em Configurações > API no CRM.

- Cabeçalho HTTP: `Authorization: Bearer crm_live_<prefixo>_<segredo>`
- Escopos necessários: `contacts:read + messages:read`
- O token completo só é exibido uma vez na criação.

## Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `organization_id` | `UUID` | sim | Identificador da organização consultada. Continua obrigatório mesmo com API key. |
| `q` | `string` | não | Palavra ou frase única para busca. Exemplo: produto exemplo. |
| `keywords` | `string` | não | Lista separada por vírgula, ponto e vírgula ou quebra de linha. |
| `keyword` | `string[]` | não | Parâmetro repetível para múltiplas frases. |
| `match` | `any | all` | não | Define se qualquer termo basta ou se todos devem aparecer. Padrão: any. |
| `direction` | `inbound | outbound | all` | não | Filtra mensagens recebidas, enviadas ou ambas. Padrão: inbound. |
| `channel` | `whatsapp | whatsapp_cloud_api | instagram | telegram | email` | não | Filtra conversas por canal. |
| `from` | `date-time` | não | Início do período em ISO 8601. |
| `to` | `date-time` | não | Fim do período em ISO 8601. |
| `limit` | `integer` | não | Quantidade de contatos retornados por página. Máximo: 100. Padrão: 50. |
| `offset` | `integer` | não | Deslocamento da página atual. Use junto com limit para paginação. |
| `messages_limit` | `integer` | não | Amostras de mensagens por contato. Máximo: 20. Padrão: 3. |

## Exemplo cURL

```bash
curl 'https://crm.oficinamartech.com/api/contacts/message-search?organization_id=<ORG_ID>&q=produto%20exemplo&limit=50&offset=0' \
  -H 'Authorization: Bearer crm_live_<prefixo>_<segredo>' \
  -H 'accept: application/json'
```

## Resposta 200

```json
{
  "data": [
    {
      "contact": {
        "id": "00000000-0000-4000-9000-000000000001",
        "name": "Contato Exemplo",
        "phone": "+5500000000000"
      },
      "match_count": 2,
      "messages": [
        {
          "id": "message_example_001",
          "direction": "inbound",
          "channel": "whatsapp",
          "content": "Tenho interesse no produto exemplo",
          "created_at": "2026-05-19T15:34:00.000Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "has_more": false
  }
}
```

## Erros

| Status | Significado |
| --- | --- |
| 400 | Parâmetros inválidos, paginação fora do limite ou nenhum termo informado. |
| 401 | API key ausente, inválida, revogada ou expirada. |
| 403 | Escopo ausente ou organização não autorizada para a chave. |
| 500 | Erro interno. Repetir com backoff e registrar o request. |

## Paginação

Use `limit`, `offset` e `pagination.has_more` para percorrer as páginas.

Atualizado em 19/05/2026.