Send WhatsApp messages from the lines your workspace already has in Preflow: order updates, invoices, reminders, confirmations. First, read Authentication and scopes, Idempotency and Errors.
Scopes: whatsapp:read to query and whatsapp:send to send and upload files.
1. Pick the line
Section titled “1. Pick the line”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: the number of an active person in the workspace.ai_agent: an AI agent’s own number.- Use the
idinfrom. Withoutfrom, the key’s default line applies; the admin chooses it in Settings → Integrations → API & webhooks. - A person’s WhatsApp Business app on their phone is their personal phone and doesn’t show up here: the API only uses company and AI agent numbers.
- The contact’s replies come in on that same line.
2. The 24-hour window
Section titled “2. The 24-hour window”WhatsApp only accepts free-form text and media up to 24 h after the contact’s last message to that line. Outside the window, only an approved template works.
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 }Sending text with the window closed responds 422 whatsapp_window_closed, at no
cost. The API refuses before calling WhatsApp.
3. Templates
Section titled “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 } ]}By default the list only includes templates approved for the workspace’s provider
(?status=all returns all of them). Templates are created and approved on the
Preflow screen.
4. Send
Section titled “4. Send”Provide the destination (to in E.164 or lead_id) and one content type:
text, template or media. Idempotency-Key is required. With both lead_id
and to, to must be one of that lead’s phone numbers.
Text (window open):
curl -X POST https://api.preflow.sale/v1/whatsapp/messages \ -H "Authorization: Bearer $PREFLOW_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1234-shipped" \ -d '{"to":"+5511999998888","from":"8c5d…","text":"Your order 1234 is out for delivery.","client_reference":"order-1234"}'Template (any time). Variables go by name or by position ("1", "2"…), and
all of them are required:
{ "lead_id": "3f0c…", "template": { "name": "pedido_enviado", "language": "pt_BR", "variables": { "nome": "Ana", "pedido": "1234" } }}Media: first upload the file (section 5), then:
{ "to": "+5511999998888", "media": { "file_id": "7d1e…", "caption": "Here's your invoice." } }201 response:
{ "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": "order-1234", "status": "sent", "error": null, "message_id": "5c7b…", "created_at": "2026-11-16T15:04:05Z", "updated_at": "2026-11-16T15:04:06Z"}What happens in Preflow:
- A number that isn’t a lead yet becomes a contact (not a lead). A lead’s phone
number goes to that lead. Use
contact_nameto name the new contact. - The message shows up in the conversation and on the timeline with the “Integration” label.
- It doesn’t take the conversation away from whoever is handling it. If the AI was handling the lead, it keeps handling it; if the contact replies, the usual flow continues.
- It doesn’t count as a touch on the team’s dashboards (War Room, effort per channel, goals).
- It goes through the same rules as any send in Preflow: people who asked not to
receive messages (
privacy_suppressed), contacts paused until a date (contact_paused), closed or lost contacts (contact_blocked), plan and credits (insufficient_credits), lines paused for quality (sender_unavailable).
Status and uncertainty
Section titled “Status and uncertainty”GET /v1/whatsapp/messages/{id} returns the delivery status: sent,
delivered, read or failed.
If WhatsApp doesn’t confirm in time, the send responds 202 with
"status": "unknown" and nothing is resent, not even when you repeat the same
Idempotency-Key (which then responds 409 request_outcome_unknown). Check
GET /v1/whatsapp/messages/{id}: once the message goes out, the status moves to
sent and then delivered/read. Don’t send again with a different key before
checking, or the contact gets it twice.
5. Files
Section titled “5. Files”curl -X POST https://api.preflow.sale/v1/files \ -H "Authorization: Bearer $PREFLOW_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-1234" \ -d '{"filename":"invoice-1234.pdf","content_type":"application/pdf","size":48211}'{ "id": "7d1e…", "filename": "invoice-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" }}Send the bytes to upload.url with PUT and the headers listed, within 2 h.
Then use the id in media.file_id. The uploaded file must match the declared
size (size) and type (content_type), or the send responds
file_not_uploaded / media_type_not_allowed. Limit of 60 files per minute and
1,000 per day per key; the file is deleted 30 days after upload.
Accepted types: JPEG, PNG and WebP images; PDF; OGG, MP3, M4A and AAC audio; MP4 and 3GP video; text; Word, Excel and PowerPoint. Up to 16 MB.
6. History and received media
Section titled “6. History and received media”curl "https://api.preflow.sale/v1/whatsapp/messages?to=%2B5511999998888&limit=50" \ -H "Authorization: Bearer $PREFLOW_API_KEY"Returns every message with that phone number, received and sent, newest first.
origin says who sent it: api, cadence, ai, human or whatsapp_app (from
the phone app). Messages sent through the API include api_message_id and
client_reference.
To download a message’s media: GET /v1/whatsapp/messages/{id}/media. The
response is the file, with its original Content-Type and
Content-Disposition: attachment. Treat it as a file sent by a third party.
Limits and cost
Section titled “Limits and cost”- 60 sends per minute per key, and 60 per minute per line (across all of the workspace’s keys).
- The cost follows Preflow’s WhatsApp price table (the same as in the app). A refusal from WhatsApp refunds the credit.
- Bulk messages to cold lists hurt the line’s quality and can get the number paused. For prospecting, use Preflow’s cadences.