Primeira chamada

Vamos usar o endpoint GET /contacts/message-search, que busca contatos que mencionaram um termo específico em mensagens.

O que você precisaCopy Anchor Link

• Uma API key criada com os escopos contacts:read e messages:read
• O organization_id (UUID) da sua organização — visível na URL do CRM ou em Configurações → Geral

Requisição mínimaCopy Anchor Link

Substitua <SUA_API_KEY> e <ORG_ID> pelos seus valores.

curl -G "https://crm.oficinamartech.com/api/v1/contacts/message-search" \
  -H "Authorization: Bearer <SUA_API_KEY>" \
  --data-urlencode "organization_id=<ORG_ID>" \
  --data-urlencode "q=orçamento" \
  --data-urlencode "limit=10"

Resposta esperadaCopy Anchor Link

{
  "data": [
    {
      "contact": {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "organization_id": "<ORG_ID>",
        "name": "Maria Silva",
        "phone": "+5511999999999",
        "email": "maria@example.com",
        "avatar_url": null,
        "source": "whatsapp"
      },
      "match_count": 3,
      "conversations_count": 2,
      "first_matched_at": "2026-05-15T14:23:00.000Z",
      "last_matched_at": "2026-05-19T18:42:00.000Z",
      "messages": []
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 1,
    "has_more": false,
    "next_offset": null
  },
  "query": {
    "organization_id": "<ORG_ID>",
    "terms": ["orçamento"],
    "match": "any",
    "direction": "inbound",
    "channel": null,
    "from": null,
    "to": null
  }
}

Entendendo o retornoCopy Anchor Link

• data[] — array de contatos que mencionaram o termo
• match_count — número de mensagens do contato que contêm o termo
• pagination — controles de paginação (veja guia)
• query — eco dos parâmetros normalizados (útil para debug)

E se der erro?Copy Anchor Link

• 401 Unauthorized — verifique se o header Authorization está presente e a chave é válida
• 403 Forbidden — chave válida mas sem o escopo necessário (contacts:read + messages:read)
• 400 Bad Request — algum parâmetro inválido. A resposta inclui details com o problema

Veja Erros e retry para detalhes.

Próximos passosCopy Anchor Link

• Entender paginação
• Buscar por múltiplos termos
• Referência completa do endpoint