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 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --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

api_access_token

string

header

required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

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 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --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