Skip to main content
POST
Preview a transmission

Authorizations

Authorization
string
header
required

Personal access token (izap_pat_…) sent as Authorization: Bearer ; dashboard session JWTs are also accepted.

Headers

business-id
string<uuid>
required

Body

application/json

Validate CSV recipients against a template and create a DRAFT transmission.

No messages are sent. recipients are parsed CSV rows (header -> value); each row must contain phone_column and the columns that fill the template's variables. Confirm the returned draft id with confirm_transmission to send.

name
string
required

Human label for the transmission.

Required string length: 1 - 255
recipients
Recipients · object[]
required

Parsed CSV rows; each row maps a string column header to its string cell value. Must include the phone column and the columns that supply the template's variables.

Required array length: 1 - 5000 elements
business_id
string<uuid> | null
header_media_document_id
string | null

UUID or filename of a document or video in the business's media library to use as the template's DOCUMENT or VIDEO header. Mutually exclusive with the other header media sources.

header_media_filename
string | null

Name recipients see for a DOCUMENT header. Ignored for image and video headers.

Maximum string length: 240
header_media_image_id
string | null

UUID or filename of an image in the business's media library to use as the template's IMAGE header. Mutually exclusive with the other header media sources.

header_media_url
string | null

Public https:// URL of the file for the template's media header (an image for an IMAGE header, a PDF for a DOCUMENT header, an MP4 for a VIDEO header). Required when the template was approved with a media header; the same file goes to every recipient. Mutually exclusive with the library header fields.

Maximum string length: 2048
max_messages_per_minute
integer
default:60

Sending pace cap. Must be between 1 and 200 messages per minute.

Required range: 1 <= x <= 200
message_text
string | null

Text to send. Required for 'whatsapp_freeform', which only reaches contacts inside the WhatsApp customer-service window; others are skipped.

Maximum string length: 4096
phone_column
string
default:phone

Name of the CSV column holding the recipient phone number (E.164 or local).

Required string length: 1 - 255
scheduled_at
string<date-time> | null

When to send. Omit or null to send immediately on confirm. If the value has no timezone offset it is interpreted in 'timezone'.

sender_phone_number
string | null

Which of the business's connected WhatsApp numbers sends the transmission, e.g. '+5562999998888' (any formatting). Omit to send from the business's oldest connected number.

Maximum string length: 32
template_language
string
default:pt_BR

Template language/locale code as registered with Meta, e.g. 'pt_BR'.

Required string length: 2 - 15
template_name
string
default:freeform

Name of the pre-approved WhatsApp Cloud API template to send. Required for 'whatsapp_template'; not accepted for 'whatsapp_freeform', which stores a fixed default.

Required string length: 1 - 512
timezone
string | null

IANA timezone used to interpret a naive 'scheduled_at'. Defaults to the business's configured timezone (America/Sao_Paulo when none is set).

transmission_type
enum<string>
default:whatsapp_template

Transmission kind: 'whatsapp_template' or 'whatsapp_freeform'.

Available options:
whatsapp_template,
whatsapp_freeform
variable_columns
string[] | null

For positional templates ({{1}}, {{2}}, ...): the ordered CSV header names mapping to {{1}}, {{2}}, ... If omitted, the first non-phone columns are used in order. Ignored for templates with named placeholders.

Maximum array length: 50

Response

Successful Response

business_id
string<uuid>
required
column_mapping
Column Mapping · object
required
duplicate_count
integer
required
estimated_duration_seconds
integer
required
invalid_count
integer
required
name
string
required
phone_column
string
required
recipient_count
integer
required
sample_errors
PreviewRowErrorOut · object[]
required
scheduled_at
string<date-time> | null
required
status
string
required
template_language
string
required
template_name
string | null
required
transmission_id
string<uuid>
required
transmission_type
string
required
uses_named_variables
boolean
required
valid_count
integer
required
warnings
string[]
required
not_on_whatsapp_count
integer
default:0
outside_window_count
integer
default:0
sender_phone_number
string | null
warning_details
TransmissionWarningOut · object[]