File Format - Outreach Templated WhatsApp
Outreach Templated WhatsApp File Format
The Outreach Templated WhatsApp file allows integrators to send WhatsApp messages that use a pre-configured Tulip template through Tulip’s Outreach system. Templates are configured in Admin Console and support replacement terms (dynamic variables) that are populated at processing time using the provided context entities.
The first line of an Outreach Templated WhatsApp CSV file must be the header row. Each subsequent row creates a separate outreach job.
File Prefix: TOTW
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 Templated WhatsApp entity.
| CSV Header | Data Type | Required | Description |
|---|---|---|---|
Template ID | string | Yes | Tulip template UUID or External ID. Only approved, non-archived templates can be sent. |
Employee ID | string | No | Employee UUID or External ID — used if the template has employee replacement terms |
Customer ID | string | No | Customer UUID or External ID — used if the template has customer replacement terms |
Store ID | string | No | Store UUID or External ID — used if the template has store replacement terms |
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. |
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. |
Variable 1 … Variable N | string | No | Per-position overrides for the template variables. Number the columns consecutively starting at Variable 1. |
Replacement Terms and Variable Overrides
If a template contains replacement terms (e.g., {{employeename}}, {{customerfirstname}}, {{storename}}), the corresponding context entity must be provided through Employee ID, Customer ID, or Store ID. The template content is populated at the time the file is processed — the final resolved content is stored on the job record.
The Variable N columns override individual template positions. A value supplied in Variable 1 wins over server-side replacement-term hydration for the first template position, Variable 2 for the second, and so on. Omitted positions hydrate from the customer, employee, and store context. Because positions are taken from the column order, fill the Variable columns consecutively — leaving a gap shifts the positions of every override after it.
Session Window
Templated WhatsApp messages are not subject to the 24-hour customer service window, so they can be sent to a customer at any time. Free-form messages, sent with a Outreach WhatsApp file, do require an open window.
Gates
Rows are rejected and reported as failed records when:
whatsapp_opt_in_required— the customer has not opted in to WhatsApp messaging.whatsapp_store_not_permitted— no store group is configured to send WhatsApp messages.- The referenced template is not sendable, for example when it is archived or has not been approved.
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.
- Template replacement terms are resolved when the file is processed, not when the message is sent.
Outreach Templated WhatsApp CSV Example
See the following Outreach Templated WhatsApp CSV sample file.