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

# How to start and steer mission runs with events

> Decide what starts a run, and what changes one while it's going.

A signal is something that happens to a person. Your product sends an event, a contact gets created, they open a support ticket, or they say something in a chat. Rules on the mission decide what each signal does.

| Rule | Where it lives | What it does |
| - | - | - |
| **Start rule** | Who and when | Starts a run, or adds the person to their company's run. |
| **Run rule** | During a run and when it ends, under **While a run is going** | Wakes the agent, tells it something, or ends the run. |
| **Stop or hold rule** | During a run and when it ends, under **Stop or hold the run** | Holds or stops the run. |

A mission can have up to 50 rules.

## Add a rule

Click **Add rule** in the card.

![The Add rule dialog](https://mintcdn.com/chatbase/J9oopG46WMTX3-j2/user-guides/missions/images/add-rule.png?fit=max\&auto=format\&n=J9oopG46WMTX3-j2\&q=85\&s=dc9658e03d4e425442b1c9ace87e992a)

1. Give it a **Name** if you like. The run timeline shows it.
2. Pick **What happened**.
3. For run and stop rules, pick what to do under **Then**.
4. Add conditions if it should apply to some people only.
5. Click **Add rule**, then **Save changes**.

### What happened

| Signal | Fires when |
| - | - |
| **Event received** | Your product sends an event with this name, like `signed_up`. |
| **Contact created** | A contact is added, from anywhere. |
| **Contact updated** | A contact's details change. |
| **Attribute changed** | A custom attribute changes. |
| **Something comes up in a conversation** | They say something that matches what you describe, like "Asks about pricing for a team". Checked after each reply on web, email, and WhatsApp. |
| **Support ticket opened** or **closed** | Their ticket opens or closes. |
| **Teammate takes over** | A teammate takes over their conversation. |
| **On a schedule** | Every hour, day, or week, at a time you set. |

A scheduled start rule checks your contacts and starts a run for each match, up to 500 at a time. People already in the mission are skipped. A scheduled run rule checks active runs instead, and skips runs waiting on you.

### Then

* Start rules always start a run.
* Run rules can **Check in now**, **Add to what the agent knows** for its next check-in, **Mark goal reached** with an outcome, or **Mark as failed**.
* Stop rules can **Hold the run** until a teammate resumes it, or **Stop the run**.

### Conditions

Conditions narrow who a rule applies to. Under **Only if all of these match**, every condition must be true. Under **And at least one of these matches**, one is enough.

You can match a contact field, a custom attribute, work or personal email, an event property, what changed, or how long since the last activity. For example, a start rule on **Contact created** with **Email type is Work** and **company\_size is more than 50** only starts runs for work emails at bigger companies.

## How replies wake a run

Your AI agent answers every reply right away. Chatbase then decides if the reply should wake the mission agent now, or wait for its next check-in.

Questions, answers, a proposed time, a new person brought in, a complaint, or a request to stop wake it. Out-of-office replies and "I'll get back to you" wait. The run timeline shows which one happened and why.

## Send events to Chatbase

Event rules need your product to send the event. Click **How to send this event** on the rule for ready-to-copy code.

### From your site

Call `sendEvent` on a page with the Chatbase embed script:

```javascript theme={null}
window.chatbase('sendEvent', 'trial_started', {
  plan: 'pro'
})
```

The person must be signed in and identified with [identity verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md). The event is saved as that person.

* Names can use letters, numbers, `_`, `.`, and `-`, up to 100 characters.
* Properties are optional, up to 8 KB. Add anything the agent should know, like the plan.
* Each visitor can send 60 events a minute.

To avoid sending the same event twice, add a key: `window.chatbase('sendEvent', 'trial_started', { plan: 'pro' }, { idempotencyKey: 'trial-123' })`.

### From your server

Use API v2 when your backend knows first, or when the person isn't on your site. Authenticate with an API key from **Workspace settings > API keys**. A scoped key needs the `events:write` permission.

```bash theme={null}
curl -X POST https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/missions/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "trial_started",
    "subject": { "email": "sarah.lee@brightwave.io" },
    "properties": { "plan": "pro" },
    "idempotency_key": "trial-123"
  }'
```

| Field | Required | Description |
| - | - | - |
| `type` | Yes | The event name, same rules as above. `trial_started` and `custom.trial_started` are the same event. |
| `subject` | Yes | Who it's about. Send exactly one of `email`, `phone`, `external_id`, or `run_id`. A new email, phone, or external ID creates the contact. |
| `properties` | No | Anything the agent should know, up to 8 KB. |
| `effect` | With `run_id` | What to do to that run: `wake` it now, add to its `context`, or `end_run` as a success. |
| `details` | No | A short note for a run, up to 500 characters. Only with `run_id`. |
| `idempotency_key` | No | Sending the same key again does nothing. Up to 200 characters. |

A successful call returns `202` with the event `id`. It returns `404` when the run doesn't exist or your plan doesn't include Missions, `409` when the run already ended, and `429` when you send too fast.

Use `run_id` to steer a run you already know about, for example to end it when a payment clears in your billing system.

## Log an event by hand

If something happened that Chatbase didn't see, like a call booked by phone, [log it on the run](https://chatbase.co/docs/user-guides/missions/runs.md#log-an-event).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.