> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clix.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Campaign

> Triggers an API-triggered campaign to send messages to a specific audience

## Overview

Triggers an API-triggered campaign to send messages to a specific audience. This endpoint allows you to send immediate, one-off messages to designated users or broadcast to your entire audience using a pre-configured campaign.

For a comprehensive guide on setting up and using API-triggered campaigns, see the [API-Triggered Campaigns guide](/campaigns/api-triggered).

## Authentication

This endpoint requires authentication via the following HTTP headers:

* `X-Clix-Project-ID`: Your project ID
* `X-Clix-API-Key`: Your Clix Secret API Key

## Path Parameters

| Parameter     | Type   | Required | Description                                      |
| ------------- | ------ | -------- | ------------------------------------------------ |
| `campaign_id` | string | Yes      | The unique identifier of the campaign to trigger |

## Request Body

| Field        | Type   | Required | Description                                                   |
| ------------ | ------ | -------- | ------------------------------------------------------------- |
| `audience`   | object | No       | Defines the target audience for this campaign trigger         |
| `properties` | map    | No       | Custom properties to pass to the campaign for personalization |

### Audience Object

| Field       | Type    | Required | Description                                                                                                                                                  |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `broadcast` | boolean | No       | If `true`, sends to all users matching the campaign's segment definition. Ignores `targets` if set. Default: `false`                                         |
| `targets`   | array   | No       | Array of specific users/devices to target. Only users matching the campaign's segment definition will receive the message. Ignored if `broadcast` is `true`. |

### Target Object

Each target should specify **one** of the following:

| Field             | Type   | Description                             |
| ----------------- | ------ | --------------------------------------- |
| `project_user_id` | string | Target a user by your project's user ID |
| `device_id`       | string | Target a specific device by ID          |

### Properties

Custom properties are passed as key-value pairs and can be used for:

* **Message personalization**: Insert values in message templates using `{{ trigger.property_name }}`
* **Dynamic audience filtering**: Reference values in audience conditions configured in the console

See [Personalization](/personalization/personalization) for template syntax details.

```json theme={null}
{
  "name": "John Doe",
  "age": 40,
  "is_premium_user": true,
  "state": "CA",
  "city": "Mountain View"
}
```

## Example Requests

### Broadcast to All Eligible Users

Send to all users matching the campaign's segment definition:

```json theme={null}
{
  "audience": {
    "broadcast": true
  },
  "properties": {
    "promotion": "Holiday Sale",
    "discount": "30%"
  }
}
```

### Target Specific Users

Send to specific users, but only those who match the campaign's segment definition:

```json theme={null}
{
  "audience": {
    "broadcast": false,
    "targets": [
      {
        "project_user_id": "clix_user_a"
      },
      {
        "project_user_id": "clix_user_b"
      }
    ]
  },
  "properties": {
    "subscription_plan": "premium",
    "message_type": "transactional"
  }
}
```

### Trigger Without Audience (Uses Campaign's Default Audience)

```json theme={null}
{
  "properties": {
    "campaign_variant": "A"
  }
}
```

### Dynamic Filtering and Personalization

This example shows how to use properties for both audience filtering and message content.

**Campaign configuration in console:**

* Audience filter: `user_role == "store_staff" AND store_location == {{ trigger.store_location }}`
* Message title: `New pickup order`
* Message body: `Order #{{ trigger.order_id }} from {{ trigger.customer_name }}. {{ trigger.item_count }} items ready by {{ trigger.pickup_time }}.`

**API request:**

```json theme={null}
{
  "audience": {
    "broadcast": true
  },
  "properties": {
    "store_location": "San Francisco",
    "customer_name": "Sarah Johnson",
    "order_id": "ORD-12345",
    "item_count": "3",
    "pickup_time": "2:30 PM"
  }
}
```

This will:

1. Filter to users where `user_role == "store_staff"` AND `store_location == "San Francisco"`
2. Send a message with title "New pickup order"
3. And body "Order #ORD-12345 from Sarah Johnson. 3 items ready by 2:30 PM."

## Response

### Success Response (200 OK)

Returns a trigger identifier for tracking the campaign send:

```json theme={null}
{
  "trigger_id": "5dbdd10e-6ea6-4ff7-836d-bd30a6d1a521"
}
```

The `trigger_id` can be used to track the status and results of this specific campaign trigger.

### Error Responses

#### 400 Bad Request

Returned when:

* `campaign_id` is missing or invalid
* Request body is malformed
* Failed to send campaign trigger message

Returns a plain text error message:

```
Campaign Id must be provided
```

or

```
Failed to send campaign trigger message
```

#### 401 Unauthorized

Authentication failed or invalid API key.

## Notes

* Campaign must be configured as "API-Triggered" in the dashboard before it can be triggered via this endpoint
* **Segment Filtering**: All messages are filtered by the campaign's segment definition:
  * When `broadcast` is `true`, the campaign sends to all users who match the campaign's segment criteria
  * When `broadcast` is `false` (or omitted) and `targets` are specified, only the targeted users who also match the campaign's segment criteria will receive the message
  * Users who don't match the segment criteria will not receive messages, even if explicitly targeted
* When targeting specific users, you can mix different target types (device\_id, user\_id, project\_user\_id) in the same request
* Properties are optional but highly recommended for personalized messaging
* The `trigger_id` in the response can be used to track delivery results and campaign analytics
* Message delivery is asynchronous - the API returns immediately with a trigger\_id, and messages are processed in the background
* Rate limits apply based on your project plan


## OpenAPI

````yaml POST /api/v1/campaigns/{campaign_id}:trigger
openapi: 3.1.0
info:
  title: clix/external/v1/clix.proto
  version: version not set
servers:
  - url: https://api.clix.so
security:
  - ProjectIdAuth: []
    ApiKeyAuth: []
tags:
  - name: ClixExternalService
paths:
  /api/v1/campaigns/{campaign_id}:trigger:
    post:
      tags:
        - ClixExternalService
      summary: Trigger a campaign
      description: >-
        Triggers an API-triggered campaign to send messages to a specific
        audience
      operationId: ClixExternalService_TriggerCampaign
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: The unique identifier of the campaign to trigger
          schema:
            type: string
      requestBody:
        required: false
        description: Campaign trigger configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1TriggerCampaignRequest'
      responses:
        '200':
          description: Campaign triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1TriggerCampaignResponse'
        '400':
          description: Bad request - invalid parameters or campaign not found
          content:
            text/plain:
              schema:
                type: string
                example: Campaign Id must be provided
components:
  schemas:
    v1TriggerCampaignRequest:
      type: object
      description: Request to trigger a campaign
      properties:
        audience:
          type: object
          description: Target audience for the campaign
          properties:
            broadcast:
              type: boolean
              description: If true, sends to all eligible users
            targets:
              type: array
              description: Specific targets to send to
              items:
                type: object
                properties:
                  project_user_id:
                    type: string
                    description: Target user by project user ID
                  device_id:
                    type: string
                    description: Target specific device
        properties:
          type: object
          description: Custom properties for personalization
          additionalProperties: true
    v1TriggerCampaignResponse:
      type: object
      description: Response containing the trigger ID
      properties:
        trigger_id:
          type: string
          description: Unique identifier for this campaign trigger
  securitySchemes:
    ProjectIdAuth:
      type: apiKey
      in: header
      name: X-Clix-Project-ID
      description: Project ID for authentication
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Clix-API-Key
      description: API Key for authentication

````