Create Campaign

curl --request POST \
  --url https://api.automatechats.com/api/campaigns/auto-trigger \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "September promo",
  "description": "Announce the monthly offer to every contact",
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "contact_selection_type": "all_contacts",
  "send_type": "IMMEDIATE",
  "variable_mapping": {
    "body": {
      "1": "firstName"
    }
  }
}
'

{
  "status": "success",
  "code": 201,
  "message": "Campaign created successfully",
  "data": {
    "campaign": {
      "id": "65f12ab3c9e4f1a2b3c4d5f1",
      "name": "September promo",
      "description": "Announce the monthly offer to every contact",
      "template_id": "123e4567-e89b-12d3-a456-426614174000",
      "contact_selection_type": "all_contacts",
      "total_contacts": 0,
      "total_contacts_skipped": 0,
      "preparation_status": "PREPARING",
      "preparation_version": 1,
      "audience_version": 1,
      "status": "DRAFT",
      "send_type": "IMMEDIATE",
      "scheduled_at": null,
      "workspace_id": 123,
      "is_auto_trigger": true,
      "created_at": "2026-09-22T12:00:00.000Z",
      "updated_at": "2026-09-22T12:00:00.000Z"
    },
    "summary": {
      "total_contacts": 0,
      "can_send_test": true
    }
  },
  "timestamp": "2026-09-22T12:00:00.000Z"
}

POST

api

campaigns

auto-trigger

curl --request POST \
  --url https://api.automatechats.com/api/campaigns/auto-trigger \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "September promo",
  "description": "Announce the monthly offer to every contact",
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "contact_selection_type": "all_contacts",
  "send_type": "IMMEDIATE",
  "variable_mapping": {
    "body": {
      "1": "firstName"
    }
  }
}
'

{
  "status": "success",
  "code": 201,
  "message": "Campaign created successfully",
  "data": {
    "campaign": {
      "id": "65f12ab3c9e4f1a2b3c4d5f1",
      "name": "September promo",
      "description": "Announce the monthly offer to every contact",
      "template_id": "123e4567-e89b-12d3-a456-426614174000",
      "contact_selection_type": "all_contacts",
      "total_contacts": 0,
      "total_contacts_skipped": 0,
      "preparation_status": "PREPARING",
      "preparation_version": 1,
      "audience_version": 1,
      "status": "DRAFT",
      "send_type": "IMMEDIATE",
      "scheduled_at": null,
      "workspace_id": 123,
      "is_auto_trigger": true,
      "created_at": "2026-09-22T12:00:00.000Z",
      "updated_at": "2026-09-22T12:00:00.000Z"
    },
    "summary": {
      "total_contacts": 0,
      "can_send_test": true
    }
  },
  "timestamp": "2026-09-22T12:00:00.000Z"
}

Use this endpoint to create a WhatsApp campaign from an external system. The campaign is marked as auto-trigger, so sending starts after recipient preparation finishes. You do not call a separate start endpoint.

This endpoint accepts an API key only. Send X-API-Key. JWT authentication is rejected with This endpoint is restricted to API key usage only.

How it works

Authenticate with your workspace API key.
The API validates the template, channel, audience, and billing features.
The campaign is stored with preparation_status: PREPARING and is_auto_trigger: true.
A background worker builds the recipient list.
When preparation is READY, the campaign starts automatically.

`send_type`	Status on create	What happens next
`IMMEDIATE`	`DRAFT`	Starts sending after preparation.
`SCHEDULED`	`SCHEDULED`	Sends at `scheduled_at` after preparation. `scheduled_at` must be in the future.

total_contacts is 0 in the create response. The worker updates the count after it loads the audience.

Example request

Your API key is channel-scoped. The backend reads the WhatsApp channel and phone_number_id from the key. Do not send channel_id or phone_number_id in the body.

curl --request POST \
  --url https://api.automatechats.com/api/campaigns/auto-trigger \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "September promo",
    "description": "Announce the monthly offer to every contact",
    "template_id": "123e4567-e89b-12d3-a456-426614174000",
    "contact_selection_type": "all_contacts",
    "send_type": "IMMEDIATE",
    "variable_mapping": {
      "body": {
        "1": "firstName"
      }
    }
  }'

If the channel wallet cannot cover the send, the campaign is auto-paused. Recharge the channel wallet, then start the campaign from the dashboard.

Channel

The send channel comes from your API key. Create the key against the WhatsApp number you want to send from. The API attaches that channel and phone number to the campaign automatically. Do not pass channel_id or phone_number_id in the request body. The template must belong to the same WhatsApp Business account as the API key’s channel. Fetch approved templates first with Fetch Approved Templates.

Audience

Set contact_selection_type and the matching fields.

Type	Required fields	Use when
`all_contacts`	None	Send to every contact in the workspace.
`quick_contacts`	`quick_contacts`	Send to an explicit phone list.
`csv_contacts`	`csv_contacts_string` or a CSV file reference, plus `csv_mapping`	Send to an uploaded list.
`segmented`	`segments`	Send to saved segments. Requires Targeted Segments.
`failed_contacts`	Previous failed-audience context	Retarget failed recipients.

csv_mapping uses 0-based column indexes. phone_column and country_code_column are required for CSV audiences.

Variable mapping

variable_mapping personalizes header, body, button, and carousel fields.

For all_contacts and segmented, map template variables to contact fields such as firstName, lastName, email, phoneNumber, or countryCode.
For csv_contacts, map to CSV keys such as name_column, email_column, or names from custom_field_mapping.
Use default_values when a contact field might be empty.

You can pass a field name (firstName) or a {{firstName}} placeholder. Both resolve at send time.

Feature and billing checks

send_type: SCHEDULED requires the Schedule Campaigns feature.
contact_selection_type: segmented requires Targeted Segments.
Starting a campaign counts against Broadcasts Per Month.
The template must be approved and available on the resolved channel’s WhatsApp Business account.

Authorizations

X-API-Key

string

header

required

Body

application/json

name

string

required

Campaign name.

Maximum string length: 255

Example:

"September promo"

template_id

string

required

Approved WhatsApp template UUID that belongs to the same WhatsApp Business account as the sending channel.

Example:

"123e4567-e89b-12d3-a456-426614174000"

contact_selection_type

enum<string>

required

How recipients are selected. segmented requires the Targeted Segments feature.

Available options:

all_contacts,

segmented,

csv_contacts,

quick_contacts,

failed_contacts

send_type

enum<string>

required

SCHEDULED requires scheduled_at in the future and the Schedule Campaigns feature.

Available options:

IMMEDIATE,

SCHEDULED

description

string

Optional campaign description.

Maximum string length: 1000

Example:

"Announce the monthly offer to every contact"

channel_id

string<uuid>

Not required for this endpoint. The channel-scoped API key supplies the send channel.

Example:

"b340b1b3-bf45-4a61-be71-853a31830dc5"

phone_number_id

string

Not required for this endpoint. The channel-scoped API key supplies the WhatsApp phone number ID.

Example:

"106294715428491"

contact_filters

object

Optional extra filters for segmented campaigns.

Show child attributes

segments

string[]

Segment IDs for segmented campaigns. Contacts in any listed segment are included.

Example:

["65e0bc51c12e4d70834b070e"]

quick_contacts

string[]

Phone numbers for quick_contacts. Each value must be a valid phone number. You can append inline variables after the number using a comma, pipe, or semicolon.

Example:

["919876543210", "918765432109"]

csv_contacts_string

string

Raw CSV text for csv_contacts. Must include a header row and at least one data row. Provide this or a CSV file reference.

Example:

"phone,country_code,name\n9876543210,+91,John"

csv_file_key

string

S3 key of a previously uploaded campaign CSV.

Example:

"workspaces/1/campaign-csvs/1730000000-abc123.csv"

csv_file_url

string

Public URL of a previously uploaded campaign CSV.

csv_mapping

object

0-based column indexes for csv_contacts.

Show child attributes

variable_mapping

object

Template personalization. Use contact field names such as firstName, CSV column keys such as name_column, or static values. Missing contact values fall back to default_values.

Show child attributes

scheduled_at

string<date-time>

ISO 8601 send time. Required when send_type is SCHEDULED. Must be in the future.

Example:

"2026-10-01T10:00:00.000Z"

Response

Campaign created. Recipient preparation is queued and sending starts automatically when the audience is ready.

status

string

Example:

"success"

code

integer

Example:

201

message

string

Example:

"Campaign created successfully"

data

object

Show child attributes

timestamp

string<date-time>

Getting Started

Core Features

API Reference

How it works

Example request

Channel

Audience

Variable mapping

Feature and billing checks

Authorizations

Body

Response

​How it works

​Example request

​Channel

​Audience

​Variable mapping

​Feature and billing checks

Authorizations

Body

Response

How it works

Example request

Channel

Audience

Variable mapping

Feature and billing checks