Conversas e mensagens (API)

Listar conversas, ler o histórico, enviar mensagem e pausar ou reativar a IA.

Listar conversas

curl "https://www.scalacrm.com/api/v1/conversations?status=open&limit=100" \
  -H "Authorization: Bearer sk_live_…"

Filtros: status (open/closed), contact_id, connection_id, assigned_user_id.

Ler uma conversa

curl https://www.scalacrm.com/api/v1/conversations/6e7f… \
  -H "Authorization: Bearer sk_live_…"

Repare no campo window_open: ele diz se a janela de 24 horas do WhatsApp está aberta. É a informação que decide o que você pode enviar — com ela fechada, só template aprovado passa.

Ler o histórico

curl "https://www.scalacrm.com/api/v1/conversations/6e7f…/messages?limit=100" \
  -H "Authorization: Bearer sk_live_…"

Filtro opcional direction=inbound|outbound. Pagina por cursor como todas as listas.

Enviar mensagem

# texto
curl -X POST https://www.scalacrm.com/api/v1/conversations/6e7f…/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: msg-pedido-9931" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "text": "Seu pedido saiu para entrega!" }'

# mídia (a URL precisa ser pública e HTTPS)
-d '{ "type": "media", "media": { "url": "https://…/nota.pdf", "file_name": "nota.pdf" } }'

# template aprovado
-d '{ "type": "template", "template": { "name": "confirmacao_pedido", "params": ["Maria", "9931"] } }'

Use Idempotency-Key aqui mais do que em qualquer outro lugar. O efeito é uma mensagem no WhatsApp de um cliente real, e não dá para desfazer. Um retry sem chave manda a mesma mensagem duas vezes.

Se o envio não for possível agora — janela fechada, template não aprovado naquela caixa, número não alcançável — você recebe 400 invalid_request com a explicação. O pedido estava certo; o envio é que não cabe.

Template é por caixa. Um template aprovado numa conexão não vale em outra: a Meta aprova por WABA. A API confere isso e recusa com mensagem clara.

Pausar ou reativar a IA

curl -X PATCH https://www.scalacrm.com/api/v1/conversations/6e7f… \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "ai_enabled": false }'

O mesmo PATCH também muda status (open/closed) e assigned_user_id.