Mande WhatsApp pelas linhas que o seu workspace já tem no Preflow: avisos de pedido, boletos, lembretes, confirmações. Antes, veja Autenticação e acessos, Idempotência e Erros.
Acessos: whatsapp:read para consultar e whatsapp:send para enviar e subir arquivo.
1. Escolha a linha
Seção intitulada “1. Escolha a linha”curl https://api.preflow.sale/v1/whatsapp/senders -H "Authorization: Bearer $PREFLOW_API_KEY"{ "data": [ { "id": "8c5d…", "kind": "person", "phone": "+5511988887777", "owner": { "id": "1f2e…", "name": "Ana Souza" }, "is_default": true, "status": "online" }, { "id": "b71a…", "kind": "ai_agent", "phone": "+5511977776666", "owner": { "id": "b71a…", "name": "Clara" }, "is_default": false, "status": "online" } ]}person: o número de uma pessoa ativa do workspace.ai_agent: o número próprio de um agente de IA.- Use o
idemfrom. Semfrom, vale a linha padrão da chave, que o administrador escolhe em Configurações → Integrações → API e webhooks. - O WhatsApp Business do celular de uma pessoa é o telefone pessoal dela e não aparece aqui: a API só usa números da empresa e dos agentes de IA.
- As respostas do contato chegam nessa mesma linha.
2. A janela de 24 h
Seção intitulada “2. A janela de 24 h”O WhatsApp só aceita texto livre e mídia até 24 h depois da última mensagem do contato para aquela linha. Fora disso, só template aprovado.
curl "https://api.preflow.sale/v1/whatsapp/window?to=%2B5511999998888&from=8c5d…" \ -H "Authorization: Bearer $PREFLOW_API_KEY"{ "to": "+5511999998888", "from": { "id": "8c5d…", "phone": "+5511988887777" }, "open": false, "last_inbound_at": null, "expires_at": null }Mandar texto com a janela fechada responde 422 whatsapp_window_closed, sem
custo. A API recusa antes de chamar o WhatsApp.
3. Templates
Seção intitulada “3. Templates”curl https://api.preflow.sale/v1/whatsapp/templates -H "Authorization: Bearer $PREFLOW_API_KEY"{ "data": [ { "id": "c0a1…", "name": "pedido_enviado", "display_name": "Pedido enviado", "language": "pt_BR", "category": "utility", "status": "approved", "body": "Oi {{nome}}, o pedido {{pedido}} saiu para entrega.", "variables": ["nome", "pedido"], "header": null } ]}Por padrão a lista traz só os aprovados para o provedor do workspace
(?status=all traz todos). Templates são criados e aprovados na tela do Preflow.
4. Mandar
Seção intitulada “4. Mandar”Informe o destino (to em E.164 ou lead_id) e um conteúdo: text,
template ou media. Idempotency-Key é obrigatório. Com lead_id e to
juntos, to tem que ser um telefone desse lead.
Texto (janela aberta):
curl -X POST https://api.preflow.sale/v1/whatsapp/messages \ -H "Authorization: Bearer $PREFLOW_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-1234-saiu" \ -d '{"to":"+5511999998888","from":"8c5d…","text":"Seu pedido 1234 saiu para entrega.","client_reference":"pedido-1234"}'Template (qualquer momento). As variáveis vão pelo nome ou pela posição
("1", "2"…), e todas são obrigatórias:
{ "lead_id": "3f0c…", "template": { "name": "pedido_enviado", "language": "pt_BR", "variables": { "nome": "Ana", "pedido": "1234" } }}Mídia: primeiro suba o arquivo (seção 5), depois:
{ "to": "+5511999998888", "media": { "file_id": "7d1e…", "caption": "Segue o boleto." } }Resposta 201:
{ "id": "e4b2…", "to": "+5511999998888", "from": { "id": "8c5d…", "kind": "person", "phone": "+5511988887777" }, "lead_id": null, "contact_id": "a9d3…", "conversation_id": "0f6e…", "type": "text", "template": null, "client_reference": "pedido-1234", "status": "sent", "error": null, "message_id": "5c7b…", "created_at": "2026-11-16T15:04:05Z", "updated_at": "2026-11-16T15:04:06Z"}O que acontece no Preflow:
- Número que ainda não é lead vira contato (não lead). Telefone de um lead
vai para o lead. Use
contact_namepara nomear o contato novo. - A mensagem aparece na conversa e na linha do tempo com o rótulo “Integração”.
- Não tira a conversa de quem conduz. Se a IA conduzia o lead, ela continua conduzindo; se o contato responder, segue o atendimento de sempre.
- Não conta como toque nos painéis do time (Sala de Guerra, esforço por canal, metas).
- Passa pelas mesmas regras de qualquer envio do Preflow: quem pediu para não
receber mensagens (
privacy_suppressed), contato pausado até uma data (contact_paused), contato encerrado ou perdido (contact_blocked), plano e créditos (insufficient_credits), linha pausada por qualidade (sender_unavailable).
Status e incerteza
Seção intitulada “Status e incerteza”GET /v1/whatsapp/messages/{id} devolve o status da entrega: sent,
delivered, read ou failed.
Se o WhatsApp não confirmar a tempo, o envio responde 202 com
"status": "unknown" e nada é reenviado, nem repetindo a mesma
Idempotency-Key (que passa a responder 409 request_outcome_unknown).
Consulte GET /v1/whatsapp/messages/{id}: quando a mensagem tiver saído, o
status passa para sent e depois delivered/read. Não mande de novo com
outra chave antes de conferir, ou o contato recebe duas vezes.
5. Arquivos
Seção intitulada “5. Arquivos”curl -X POST https://api.preflow.sale/v1/files \ -H "Authorization: Bearer $PREFLOW_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: boleto-1234" \ -d '{"filename":"boleto-1234.pdf","content_type":"application/pdf","size":48211}'{ "id": "7d1e…", "filename": "boleto-1234.pdf", "content_type": "application/pdf", "size": 48211, "upload": { "method": "PUT", "url": "https://api.preflow.sale/storage/v1/object/upload/sign/…", "headers": { "content-type": "application/pdf" }, "expires_at": "2026-11-16T17:04:05Z" }}Envie os bytes para upload.url com PUT e os cabeçalhos indicados, dentro de
2 h. Depois use o id em media.file_id. O arquivo enviado tem que ter o
tamanho (size) e o tipo (content_type) declarados, ou o envio responde
file_not_uploaded / media_type_not_allowed. Limite de 60 arquivos por minuto
e 1.000 por dia por chave; o arquivo é apagado 30 dias depois do upload.
Tipos aceitos: imagens JPEG, PNG e WebP; PDF; áudio OGG, MP3, M4A e AAC; vídeo MP4 e 3GP; texto; Word, Excel e PowerPoint. Até 16 MB.
6. Histórico e mídia recebida
Seção intitulada “6. Histórico e mídia recebida”curl "https://api.preflow.sale/v1/whatsapp/messages?to=%2B5511999998888&limit=50" \ -H "Authorization: Bearer $PREFLOW_API_KEY"Traz todas as mensagens com o telefone, recebidas e enviadas, da mais nova para
a mais antiga. origin diz quem mandou: api, cadence, ai, human ou
whatsapp_app (pelo app do celular). Mensagens da API trazem api_message_id
e client_reference.
Para baixar a mídia de uma mensagem: GET /v1/whatsapp/messages/{id}/media.
A resposta é o arquivo, com o Content-Type original e
Content-Disposition: attachment. Trate como arquivo enviado por terceiros.
Limites e custo
Seção intitulada “Limites e custo”- 60 envios por minuto por chave, e 60 por minuto por linha (somando todas as chaves do workspace).
- O custo é a tabela de WhatsApp do Preflow (a mesma da tela). Recusa do WhatsApp devolve o crédito.
- Mensagens em massa para listas frias prejudicam a qualidade da linha e podem pausar o número. Para prospecção, use as cadências do Preflow.