Campaigns

Create a campaign

Create a campaign. For a supported messaging inbox, provide scheduled_at to schedule a one-off campaign; omitting it makes the campaign eligible for the next scheduler run. Website campaigns use trigger_rules instead. Channel-specific campaign availability and requirements still apply. One-off campaigns require at least one audience label for delivery. WhatsApp campaigns also require template_params with the selected template name, language, and any variable values. A successful creation response does not confirm delivery. Requires an account administrator and API access enabled for the account.

POST

api

accounts

{account_id}

campaigns

curl --request POST \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaign": {
    "title": "January announcement",
    "inbox_id": 12,
    "message": "Our January offers are here!",
    "scheduled_at": "2027-01-15T10:00:00Z",
    "audience": [
      {
        "type": "Label",
        "id": 5
      }
    ]
  }
}
'

{
  "id": 123,
  "title": "<string>",
  "description": "<string>",
  "account_id": 123,
  "inbox": {
    "id": 123,
    "name": "<string>",
    "website_url": "<string>",
    "page_id": "<string>",
    "instagram_id": "<string>",
    "business_id": "<string>",
    "provider_name": "<string>",
    "profile_id": "<string>",
    "line_channel_id": "<string>",
    "email": "<string>",
    "bot_name": "<string>",
    "inbox_identifier": "<string>",
    "channel_type": "<string>",
    "avatar_url": "<string>",
    "widget_color": "<string>",
    "website_token": "<string>",
    "enable_auto_assignment": true,
    "web_widget_script": "<string>",
    "welcome_title": "<string>",
    "welcome_tagline": "<string>",
    "greeting_enabled": true,
    "greeting_message": "<string>",
    "channel_id": 123,
    "working_hours_enabled": true,
    "enable_email_collect": true,
    "csat_survey_enabled": true,
    "auto_assignment_config": {},
    "out_of_office_message": "<string>",
    "working_hours": [
      {
        "day_of_week": 123,
        "closed_all_day": true,
        "open_hour": 123,
        "open_minutes": 123,
        "close_hour": 123,
        "close_minutes": 123,
        "open_all_day": true
      }
    ],
    "timezone": "<string>",
    "callback_webhook_url": "<string>",
    "allow_messages_after_resolved": true,
    "lock_to_single_conversation": true,
    "sender_name_type": "<string>",
    "business_name": "<string>",
    "branded_email_layout": "<string>",
    "hmac_mandatory": true,
    "selected_feature_flags": [
      "<string>"
    ],
    "reply_time": "<string>",
    "messaging_service_sid": "<string>",
    "phone_number": "<string>",
    "medium": "<string>",
    "provider": "<string>"
  },
  "sender": {},
  "message": "<string>",
  "template_params": {},
  "campaign_status": "active",
  "campaign_type": "ongoing",
  "enabled": true,
  "scheduled_at": 123,
  "started_at": 123,
  "completed_at": 123,
  "audience": [
    {
      "type": "<string>",
      "id": 123
    }
  ],
  "trigger_rules": {},
  "trigger_only_during_business_hours": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Authenticate with Authorization: Bearer <token> using a user API token from Profile Settings. Available in Chatwoot v4.19.0 and later.

Path Parameters

account_id

integer

required

The numeric ID of the account

Body

application/json

campaign

Website campaign · object

required

Choose the variant matching the inbox referenced by inbox_id. The channel type is stored on the inbox and cannot be inferred from this request by a schema validator. These variants describe the inputs needed for delivery; creation can accept incomplete inputs without guaranteeing that the campaign will send.

Website campaign
SMS campaign
WhatsApp campaign

Show child attributes

Response

Success

integer

Account-scoped campaign ID. Use this value in campaign API paths.

title

string

description

string | null

account_id

integer

inbox

object

Show child attributes

sender

object

Sender details, or an empty object when no sender is assigned.

message

string

template_params

object | null

campaign_status

enum<string>

Available options:

active,

processing,

completed

campaign_type

enum<string>

Derived from the inbox type; website campaigns are ongoing and supported messaging campaigns are one-off.

Available options:

ongoing,

one_off

enabled

boolean

scheduled_at

integer

Scheduled time in Unix seconds. Only present for one-off campaigns.

started_at

integer | null

Start time in Unix seconds. Only present for one-off campaigns.

completed_at

integer | null

Completion time in Unix seconds. Only present for one-off campaigns.

audience

object[] | null

Audience for a one-off campaign. Only present for one-off campaigns.

Show child attributes

trigger_rules

object

trigger_only_during_business_hours

boolean

created_at

string<date-time>

updated_at

string<date-time>

curl --request POST \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaign": {
    "title": "January announcement",
    "inbox_id": 12,
    "message": "Our January offers are here!",
    "scheduled_at": "2027-01-15T10:00:00Z",
    "audience": [
      {
        "type": "Label",
        "id": 5
      }
    ]
  }
}
'

{
  "id": 123,
  "title": "<string>",
  "description": "<string>",
  "account_id": 123,
  "inbox": {
    "id": 123,
    "name": "<string>",
    "website_url": "<string>",
    "page_id": "<string>",
    "instagram_id": "<string>",
    "business_id": "<string>",
    "provider_name": "<string>",
    "profile_id": "<string>",
    "line_channel_id": "<string>",
    "email": "<string>",
    "bot_name": "<string>",
    "inbox_identifier": "<string>",
    "channel_type": "<string>",
    "avatar_url": "<string>",
    "widget_color": "<string>",
    "website_token": "<string>",
    "enable_auto_assignment": true,
    "web_widget_script": "<string>",
    "welcome_title": "<string>",
    "welcome_tagline": "<string>",
    "greeting_enabled": true,
    "greeting_message": "<string>",
    "channel_id": 123,
    "working_hours_enabled": true,
    "enable_email_collect": true,
    "csat_survey_enabled": true,
    "auto_assignment_config": {},
    "out_of_office_message": "<string>",
    "working_hours": [
      {
        "day_of_week": 123,
        "closed_all_day": true,
        "open_hour": 123,
        "open_minutes": 123,
        "close_hour": 123,
        "close_minutes": 123,
        "open_all_day": true
      }
    ],
    "timezone": "<string>",
    "callback_webhook_url": "<string>",
    "allow_messages_after_resolved": true,
    "lock_to_single_conversation": true,
    "sender_name_type": "<string>",
    "business_name": "<string>",
    "branded_email_layout": "<string>",
    "hmac_mandatory": true,
    "selected_feature_flags": [
      "<string>"
    ],
    "reply_time": "<string>",
    "messaging_service_sid": "<string>",
    "phone_number": "<string>",
    "medium": "<string>",
    "provider": "<string>"
  },
  "sender": {},
  "message": "<string>",
  "template_params": {},
  "campaign_status": "active",
  "campaign_type": "ongoing",
  "enabled": true,
  "scheduled_at": 123,
  "started_at": 123,
  "completed_at": 123,
  "audience": [
    {
      "type": "<string>",
      "id": 123
    }
  ],
  "trigger_rules": {},
  "trigger_only_during_business_hours": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Getting Started

Application APIs

Platform APIs

Client APIs

Other APIs

Create a campaign

Authorizations

Path Parameters

Body

Response