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

# Campaigns

> Multi-step outreach with AI, branching, stop conditions, and smart follow-ups. Built into Tuco AI iMessage automation — works with HubSpot, Salesforce.

## Campaign Lifecycle

1. **Select leads** — pick a list, import from HubSpot, or use API-only mode (leads added via API/webhooks)
2. **Compose steps** — each step is a message with optional wait, stop conditions, and branching
3. **Assign lines** — select sending lines, Tuco spreads across them within limits
4. **Launch** — Tuco sends step 1, then advances through the sequence

### What happens when a lead replies

By default, when a lead replies:

* The campaign **pauses** for that lead
* Your **Knowledge Base** takes over and handles the conversation (copilot or autopilot mode)
* The campaign does NOT continue to the next step

You can change this with **"Continue + KB in parallel"** mode — the campaign continues to the next step on schedule while the KB handles the reply independently.

## Message Variables

Use variables in your messages to personalize:

| Variable        | Example                                 | Description                 |
| --------------- | --------------------------------------- | --------------------------- |
| `{firstName}`   | Sarah                                   | Lead's first name           |
| `{lastName}`    | Lane                                    | Lead's last name            |
| `{companyName}` | Acme Corp                               | Lead's company              |
| `{email}`       | [sarah@acme.com](mailto:sarah@acme.com) | Lead's email                |
| `{phone}`       | +1234567890                             | Lead's phone                |
| `{line_name}`   | John Smith                              | Sending line's display name |

### Fallback syntax

If a variable is empty, provide a fallback after the pipe:

```
Hey {firstName|there}, this is {line_name}
```

If `firstName` is empty, the message becomes: "Hey there, this is John Smith"

### API tool variables

Use workspace API tools as variables:

```
Hey {firstName}, your account status is {api_check_status|active}
```

The `api_check_status` tool is called before sending. If the API fails, "active" is used as fallback.

## Stop Conditions

Stop conditions prevent a step from sending if a condition is met:

| Condition                                | Description                                     |
| ---------------------------------------- | ----------------------------------------------- |
| Lead replied                             | Lead sent any reply                             |
| Lead replied (keyword)                   | Lead replied with a specific keyword            |
| Tag exists/not exists                    | Lead has or doesn't have a tag                  |
| HubSpot property                         | Check a HubSpot contact property                |
| GHL tag                                  | Check a GoHighLevel contact tag                 |
| Custom API                               | Call a workspace API tool and check the result  |
| Lead was contacted before                | Tuco has previously sent to this lead           |
| Lead was contacted before (any campaign) | Tuco has sent to this lead in any past campaign |
| Unsubscribed/DNC                         | Lead is on the Do Not Contact list              |

Stop conditions are evaluated **live** — HubSpot and GHL checks call the real APIs, not stale cached data.

<Note>Stop conditions only apply from step 2 onward. Step 1 always sends (it's the entry point).</Note>

### Condition Operators

When comparing property values in stop conditions and branches, the following operators are available:

| Operator       | Label                 | Use case              |
| -------------- | --------------------- | --------------------- |
| `eq`           | equals                | Exact match           |
| `neq`          | not equals            | Exclude a value       |
| `contains`     | contains              | Partial text match    |
| `not_contains` | does not contain      | Exclude partial match |
| `starts_with`  | starts with           | Prefix match          |
| `gt`           | greater than          | Numeric comparison    |
| `gte`          | greater than or equal | Numeric comparison    |
| `lt`           | less than             | Numeric comparison    |
| `lte`          | less than or equal    | Numeric comparison    |
| `gt_date`      | after date            | Date comparison       |
| `lt_date`      | before date           | Date comparison       |
| `exists`       | exists                | Field has a value     |
| `not_exists`   | is missing            | Field is empty        |

## Reply Behavior

Control what happens when a lead replies to your campaign:

### Pause & AI Responder (default)

Campaign pauses for this lead. The AI Responder handles the conversation.

### Continue + AI Responder in parallel

Campaign continues to the next step on schedule. AI Responder handles the reply independently. Use for multi-touch drips where follow-ups must go out regardless.

Toggle this in the campaign builder on step 1 under "Reply Behavior."

## Branching

Branch steps split leads into different paths based on conditions:

* **Lead replied** — did the lead respond?
* **No reply for X hours/days** — silence after a set time
* **Tag added** — was a specific tag added?
* **HubSpot property** — check a CRM property value
* **GHL has tag** — check a GoHighLevel tag
* **Custom API** — call an API and branch on the result
* **Lead was contacted before** — has Tuco sent to this lead before?
* **Default** — fallback path if no other condition matches

## SMS Fallback

Each step can have an SMS fallback. If iMessage is unavailable for a lead, the SMS version is sent via Twilio instead. Configure the fallback message per step or use the same text as the iMessage.

## AI-Powered Steps

Steps can be AI-driven instead of using a fixed template:

* Set a **prompt** describing what the AI should say
* The AI generates a personalized message for each lead using their data
* If AI generation fails, the **manual fallback** message is sent instead
* AI usage is tracked and logged for billing

## Testing Campaigns

Use the **Test Conversation** panel to simulate the full campaign flow for a real lead:

1. **Select a lead** — uses their real data (name, phone, tags, CRM properties)
2. **See each step** — AI-generated messages use real AI calls (billed to your usage)
3. **Reply as the lead** — type what the lead would say to test reply handling
4. **See stop conditions** — green/red pills show which conditions passed or triggered
5. **See branches** — click "Evaluate live" to check real HubSpot properties, GHL tags, and custom API calls
6. **Fast-forward waits** — skip "3 days later" to see what happens next
7. **Path simulation** — visual timeline showing every step, wait, branch, and the delivery method (iMessage vs SMS fallback)
8. **CRM links** — open the lead in HubSpot or GHL to change data mid-test, then restart from the header

<Note>AI-generated test messages count toward your AI usage. Use sparingly on expensive models.</Note>

## API-Only Campaigns

Create campaigns with no initial list — leads are added via the API:

```bash theme={null}
POST /api/campaigns/{id}/enroll
{
  "leadId": "lead_123"
}
```

Useful for event-driven enrollment (form submissions, webhook triggers, CRM automations).