Pular para o conteúdo

WhatsApp

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.

Janela do terminal
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 id em from. Sem from, 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.

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.

Janela do terminal
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.

Janela do terminal
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.

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):

Janela do terminal
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_name para 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).

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.

Janela do terminal
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.

Janela do terminal
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.

  • 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.