> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Triggers
> Start conversations automatically from an event: pick what fires it, filter on the payload, and choose what happens
A trigger watches for something to happen and acts on it. A support case is created and an agent calls the customer. A call ends and a webhook posts the outcome to your system. An inbound SMS arrives and a Slack channel hears about it.
Three parts, always: the event that starts it, the conditions that narrow it, and the action.
Searching for automations? That is this page. Automations are Triggers now, and the word is still in the URL inside an agent.
## Prerequisites
* An agent, from [Agent builder](/agents/agent-builder), if the trigger will place a call
* A connected Salesforce or HubSpot account, if the trigger starts from a CRM event
* A connected Slack workspace, if the trigger posts a Slack message
## Where triggers live
Triggers is under Dispatch, in both sidebars. At All agents it lists every trigger in the organization; inside an agent it lists that agent's.
Nothing here is gated by plan, role or permission.
## The list
A grid of cards rather than a table. Each card carries the trigger's name, its event, its action and its status.
Clicking a card opens that trigger's run history, not its settings. To change it, use the **Trigger actions** menu in the card's corner and pick **Edit**. The same menu pauses and activates it without opening anything, and **Edit trigger** in the top bar of Runs gets you there too.
Search runs on the server and covers everything you have. Sort does not. It orders the page you are looking at, so past 50 triggers **Most runs** and **Name A-Z** are sorting a slice.
## Build one
**New trigger** opens a two-pane screen. The canvas on the left, the panel on the right.
The canvas is a picture, not an editor. Three cards, stacked and joined by two lines: Trigger, Conditions, Action. The panel's step tabs carry the same three names.
There is nothing to drag, connect or add. Clicking a card opens that step in the panel, which is where all the work happens.
The panel's header carries those three steps and a **Test** button. They unlock in order: Conditions and Action stay disabled until the event is chosen.
Each card also reports its own state. The Trigger card names its connection, the Conditions card counts what you have set, and the Action card shows where it is pointed, or **Not configured** until it has somewhere to go.
That last one is a destination check, not a completeness check: a call with a number but no agent still shows the number. The **Ready** and **Setup required** badges are the completeness signal, and a step counts as visited only once you have left it, so the card you are working in is the last to flag.
Search, or filter by integration. Bland's own events sort to the top.
| Event | Fires when |
| ---------------------------------------------------- | ------------------------------------------------------- |
| **Post-call webhook** | A call finishes and its summary is ready |
| **Call started**, **Inbound call received** | A call begins, outbound or in |
| **Voicemail detected** | A call reaches voicemail instead of a person |
| **Warm transfer started**, **Cold transfer started** | A call is handed to a human, announced or not |
| **Pathway node reached** | A conversation arrives at a node you name |
| **SMS received**, **Post-SMS webhook** | A message arrives, or a thread closes |
| **Batch completed** | A batch finishes dialing |
| **Eval completed** | An evaluation run finishes |
| **Knowledge gap detected** | An agent is asked something its knowledge did not cover |
| **Tool success**, **Tool failure** | A tool call returns, or does not |
Salesforce adds created and updated for cases, leads and opportunities. HubSpot adds the same pair for companies, contacts, deals, meetings, tasks and tickets.
Picking an event clears any conditions and action settings you had already set, because the fields available depend on the event. Your agent choice survives.
A non-Bland event then asks which connection to use. If you have none, **Connect** opens a panel whose one action takes you to Tools in a new tab, which is where connections are actually made. Create it there, come back, and reopen the step.
**Trigger must meet** is set to **All conditions** and can be **Any condition**.
**Add condition** gives you a row with three controls: **Field**, **Condition**, and **Value**, which disappears for operators that do not take one. A new row starts with no field selected on purpose, so nothing meaningless is filtering for you.
The field list comes from the event, and you can type a path that is not in it.
Every CRM **updated** event needs at least one condition using a change operator, because otherwise it fires on every sync of every record. **Save** will not go through without one.
On a call action, **Timing** is in this step too: **Immediately**, **Business hours**, or **Custom** days and hours with a timezone. A Bland event only offers Immediately.
Five kinds: Call, SMS, **Webhook**, **Slack message**, and **Custom code**. The list shows only the ones your event supports, and if you change the event to one that does not support the action you had picked, it quietly reselects one that fits.
Every CRM event offers Call and SMS and nothing else, because the record it carries is a person to reach. Bland's own events vary. Seven of the fourteen drop at least one action:
| Event | What it cannot do |
| ------------------------------------------------------------------------ | ---------------------- |
| **Warm transfer started**, **Cold transfer started**, **Eval completed** | Call |
| **Batch completed**, **Knowledge gap detected** | Call, SMS |
| **Tool success**, **Tool failure** | Call, SMS, Custom code |
On a Call, the agent picker sits above the action type, because it is the first thing to decide. Below it, **Send from** picks the number the call goes out on, from the numbers in [Dispatch](/agents/dispatch), and **Send to** is the number it dials. Picking the agent fills **Send from** in with that agent's own number, if you have not picked one yourself. If you own no numbers at all the field is replaced by a note saying calls go out from a shared Bland number, which is not an error.
A **Slack message** picks its own workspace and channel, no matter which event started it.
Still in Action. This is the part that makes a trigger worth building: a field can read its value off the event instead of holding something you typed.
On a Call and on an SMS, **Send to** and each **Request data** row carry a **Static** / **Event** switch. **Static** is a value you type, the same on every run. **Event** reads it off the payload that fired the trigger. So **Send to** can be the phone number on the case rather than one number you typed once.
**Request data** is a set of key and value pairs handed to the agent as context. The agent sees both the keys and the values, so name them the way you would say them.
A **Webhook**'s URL carries the same switch with a third option, **Org Default**, which uses the webhook URL from your organization settings. Its headers carry the plain two.
The other two actions reach the event a different way. An SMS or **Slack** message body has no switch: use **Insert field** above the box, which writes a `{{field.path}}` reference into the text. **Custom code** gets the whole payload as `input`.
**Save** lands the trigger **Paused**. That is the intended order: you cannot test a trigger that has never been saved.
If a required field is missing, **Save** does nothing: no message, no error, and the button stays enabled.
What you get instead is the field label turning red, in whichever step you happen to be looking at. So walk Trigger, Conditions and Action in turn and look for it in each.
## Agent attribution
A Call action needs an agent. The field is marked required and **Save** will not go through without it.
No other action has an agent field. A **Webhook** needs a URL, an SMS needs a number and a message, and neither asks who is responsible for it.
Only a Call trigger is ever filed under an agent. A webhook, SMS, Slack or custom code trigger lives at All agents and nowhere else, even when you build it from inside an agent.
Inside an agent, the picker is a locked card rather than a list: the trigger runs on the agent you are editing. If it currently points somewhere else, or nowhere, a warning appears with a **Use this agent** button that repoints it.
Requiring an agent is a dashboard rule. The API is looser, so a trigger built elsewhere may not follow it.
Deleting an agent does not delete the triggers pointed at it. They stay in the list, still trying to run, and the agent picker shows **Unknown agent**.
If you retire an agent, go through Triggers and repoint or pause anything attributed to it.
## Test it
**Test** hands the whole right panel over to the test flow. The steps stay along the top and are how you get back out.
**Conditions only** is on by default.
With it on, pressing **Fire Test Trigger** evaluates your conditions and stops. Nothing is called, sent or posted, and the message you get back says **Conditions evaluated** rather than that the trigger fired.
Turn it off to exercise the action for real. A call action then places a real call to the number in **Send to**, billed like any other, so point it at yourself the first time.
**Conditions only** is forced on, and says so, for a trigger that does not fire immediately.
A test runs the configuration on your screen, including edits you have not saved. So it is a real answer about what you are looking at, and not necessarily about what is live.
For a CRM trigger you can paste a real record ID and Bland fetches it, or switch to **Manual** and type the fields yourself. **Fire Test Trigger** stays disabled until the record comes back, so an ID that does not resolve reads as a dead button.
A Bland event has no record to fetch. It gives you an editable payload instead, and **Fire Test Trigger** waits until that payload is valid JSON.
If your conditions use a change operator, the panel adds **Simulate field changes**, on by default, with a previous value for each field. Without it there is no change for the condition to see.
## Turn it on
The status control at the top switches between Active and **Paused**.
On a trigger that already exists, status and the trigger's name save themselves the moment you change them. Everything else on the screen waits for **Save**.
So flipping to Active and then navigating away leaves it Active. Setting it Active and then pressing **Save** asks you to confirm, and names what it is about to start firing.
While you are building a new trigger neither applies. The status control is greyed out until the trigger exists, and the name rides the first **Save** with everything else.
## Watch it run
Runs in the top bar opens the history for that trigger: when it fired, what happened, and why it stopped if it did.
Failures are not the same on every action. A failed webhook is recorded and never retried. A failed call is retried when the failure looks temporary, up to five attempts in all. The calls themselves land in [Conversations](/agents/conversations) like any others.
## Common failures
A required field is empty. Walk Trigger, Conditions and Action, looking for the red label in each: visiting them is also what makes the canvas badges appear, so the second pass tells you more than the first. A call action needs both an agent and a **Send to** number.
You have not saved yet. Save first, which leaves the trigger Paused, and test from there.
**Conditions only** was on, which is its default. It evaluates the conditions and stops before the action. Turn it off and fire again.
The count on the list card does not fill in for a trigger built here. It is not telling you the conditions are missing, and the conditions themselves work. Clicking the card goes to Runs, so open it from **Trigger actions** then **Edit**, or press **Edit trigger** once you are in Runs.
If it places calls, save it a second time, from the page the first save lands on. The first save writes the trigger and its call settings. The agent it is filed under is written by the update that follows.
If it does anything else, it is not missing. Only call triggers are filed under an agent, so a webhook, SMS, Slack or custom code trigger lives at All agents only.
Expected. Conditions and action settings are specific to an event, so changing it clears them. Pick the event first and build outward.
Bland events are not de-duplicated. Two events for the same call produce two runs and two calls.
A CRM sync is protected against retrying itself, which is not the same thing: one record seen by two separate syncs still fires twice. Narrow the conditions rather than relying on the sync to be quiet.
The server's real message does not reach the screen, so the page cannot tell you which of its rules you broke.
The missing-condition rules are not among the causes: **Save** blocks on those before anything is sent. Check the connection the trigger runs on, then the action's own destination, which are the parts the screen does not validate for you.
## Next steps
Phone numbers, channels, and batches.
Read the calls your triggers placed.
Call an API from inside a conversation rather than from an event.
Build the agent a call trigger will hand its calls to.
Docs for agents: [llms.txt](/llms.txt)