File Format - Outreach WhatsApp
Outreach WhatsApp File Format
The Outreach WhatsApp file allows integrators to send free-form WhatsApp messages through Tulip’s Outreach system. Each row in the CSV represents a single WhatsApp message to be sent.
The first line of an Outreach WhatsApp CSV file must be the header row. Each subsequent row creates a separate outreach job.
File Prefix: TOW
Minimum API Version: 2026-08
Feature Gate: The environment must have outreach-plus with WhatsApp enabled; otherwise, the file will fail to upload any records successfully.
Spec
The following table shows the accepted CSV columns for the Outreach WhatsApp entity.
| CSV Header | Data Type | Required | Description |
|---|---|---|---|
Message | string | Yes | Message body text |
To | string | Yes | Recipient phone number (E.164 format, e.g., +11234567890) |
From | string | No | WhatsApp-enabled sender phone number (E.164 format). If left blank, the sender is resolved from the tenant’s WhatsApp sender pool. |
Employee ID | string | No | Internal or External ID of the sending employee |
Customer ID | string | No | Internal or External ID of the recipient customer |
Campaign ID | string | No | Links the dispatch to a campaign |
Expiry Date | string | No | Expiration time in UTC ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). If the message has not been dispatched by this date, it will be marked as Expired. |
Start Date | string | No | Scheduled send time in UTC ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). If in the future, the message is held until this time. |
Media URL 1 … Media URL N | string | No | Publicly reachable URLs of the media to attach to the message. Number the columns consecutively starting at Media URL 1. |
Session Window
Free-form WhatsApp messages can only be delivered inside an open 24-hour customer service window, which starts when the customer sends a message to the business and closes 24 hours later. Rows targeting a customer with no open window fail with whatsapp_window_closed. To reach a customer outside the window, use a Outreach Templated WhatsApp file instead.
Gates
Rows are rejected and reported as failed records when:
whatsapp_opt_in_required— the customer has not opted in to WhatsApp messaging.whatsapp_window_closed— no 24-hour session window is open for the customer.whatsapp_store_not_permitted— no store group is configured to send WhatsApp messages.
Important Notes
- All dates must be in UTC ISO 8601 format (
YYYY-MM-DDTHH:mm:ssZ). - Phone numbers must include country code (e.g.,
+12267903132). - Each CSV row creates a separate outreach job.
- Success/failure can be monitored in Admin Console under Outreach Jobs.
- A successfully processed row means the job has been accepted for sending. It does not guarantee delivery.
Outreach WhatsApp CSV Example
See the following Outreach WhatsApp CSV sample file.