Skip to content

WhatsApp

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.

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: the number of an active person in the workspace. ai_agent: an AI agent’s own number.
  • Use the id in from. Without from, 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.

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.

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 }

Sending text with the window closed responds 422 whatsapp_window_closed, at no cost. The API refuses before calling 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
}
]
}

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.

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

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: 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_name to 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).

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.

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

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

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