Buscar leads por termo

Encontrar contatos que mencionaram um produto, campanha ou objeção específica em mensagens.

Caso de uso clássico: o time de vendas quer ligar para todos que perguntaram sobre o "Plano Pro" nos últimos 30 dias. Ou marketing quer saber quem citou "concorrente X" para uma campanha de retenção.

Estratégia

O endpoint GET /contacts/message-search agrupa contatos por mensagens que contêm os termos. Você pode buscar:

Um termo único com q=...
Lista de termos com keywords=termo1,termo2,termo3 (separados por vírgula, ponto e vírgula ou quebra de linha)
Frases com vírgula via parâmetro repetível keyword=...&keyword=...

Buscar por um único termo

curl -G "https://crm.oficinamartech.com/api/contacts/message-search" \
  -H "Authorization: Bearer $OFM_API_KEY" \
  --data-urlencode "organization_id=$ORG_ID" \
  --data-urlencode "q=Plano Pro" \
  --data-urlencode "from=2026-04-20" \
  --data-urlencode "to=2026-05-20"

const url = new URL("https://crm.oficinamartech.com/api/contacts/message-search");
url.searchParams.set("organization_id", ORG_ID);
url.searchParams.set("q", "Plano Pro");
url.searchParams.set("from", "2026-04-20");
url.searchParams.set("to", "2026-05-20");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${OFM_API_KEY}` },
});
const { data } = await res.json();
console.log(`${data.length} contatos mencionaram "Plano Pro" em 30 dias`);

Buscar por múltiplos termos (qualquer um)

curl -G "https://crm.oficinamartech.com/api/contacts/message-search" \
  -H "Authorization: Bearer $OFM_API_KEY" \
  --data-urlencode "organization_id=$ORG_ID" \
  --data-urlencode "keywords=Plano Pro,Plano Premium,upgrade" \
  --data-urlencode "match=any"

match=any retorna contatos que mencionaram pelo menos um dos termos.

Buscar por múltiplos termos (todos)

curl -G "https://crm.oficinamartech.com/api/contacts/message-search" \
  -H "Authorization: Bearer $OFM_API_KEY" \
  --data-urlencode "organization_id=$ORG_ID" \
  --data-urlencode "keywords=preço,desconto" \
  --data-urlencode "match=all"

match=all retorna contatos que mencionaram todos os termos (em qualquer mensagem).

Frases com vírgula

Quando o termo contém vírgula (atrapalha o split de keywords), use keyword repetível:

curl -G "https://crm.oficinamartech.com/api/contacts/message-search" \
  -H "Authorization: Bearer $OFM_API_KEY" \
  --data-urlencode "organization_id=$ORG_ID" \
  --data-urlencode "keyword=R$ 1.500, 12x sem juros" \
  --data-urlencode "keyword=preço final"

Filtros adicionais

direction: inbound (cliente falou), outbound (atendente falou), all
channel: whatsapp, whatsapp_cloud_api, instagram, telegram, email
from / to: ISO 8601 ou YYYY-MM-DD
messages_limit: 0-20 mensagens de contexto retornadas junto com cada contato

Por padrão, a busca é em mensagens inbound (do cliente). Use direction=all para incluir mensagens enviadas pelo atendente.

Limites

Até 10 termos por requisição (terms acima do 10º são ignorados)
Termos com menos de 2 caracteres são descartados
Termos com mais de 200 caracteres são truncados
Acentos e capitalização são normalizados automaticamente