Operations agent: triggers

A trigger is the first box on the board: it decides when the flow runs and what data it starts with. Each kind of trigger can appear once on a board, and a board can hold several kinds (for example a PBX call and a manual run). Triggers only start runs while the agent is enabled; a test run from the designer works either way.

Call ended (PBX)#

Every call the project's PBX journals starts the flow. The PBX is connected once for the whole project under Integrations (see Contacts and PBX integration). The trigger gives the steps:

• caller_number, caller_name, callee_number, callee_name, direction (inbound, outbound, internal)
• duration_sec, status (answered, missed, and so on), subject, extension (the extension user's name)
• recording_url (the PBX download link) and recording_ref (the recording's file name)
• call_id, contact_id, contact_number

A missed call has no recording. The steps that need one (download, transcribe, summarise, report) mark themselves Skipped: nothing to do and the run still completes, so a missed call never leaves a run waiting for retries.

Keep recording_url inside the flow: it carries the PBX's download secret. To identify a recording in another system send recording_ref instead.

One PBX call can start several agents: every enabled agent with this trigger runs on it.

Webhook received#

Anything that can post JSON can start the agent: the board shows the agent's own URL in the inspector (also under Settings). The request body becomes the trigger data, so a field order_id in the body is {{trigger.order_id}} in the steps.

Runs on a schedule#

Starts the flow every hour, every day at 09:00, on weekdays at 09:00, every Monday at 09:00, on the first of the month at 09:00, or on your own cron expression, in the timezone you choose, at most once every five minutes. Two choices:

• If the previous run is still going: skip this one, or queue it.
• Fires missed while the service was down: skip them, or run once.

After you save, the designer shows the estimated runs and cost per month, because every run is billed for the time it works. The Overview shows the next scheduled run. The trigger gives scheduled_for, fired_at, cron, timezone and missed_by_s.

Called by another agent#

Another operations agent of the project hands data to this one, with Call another agent or the Dispatcher. The data it sent is the trigger data; caller_agent and caller_run_id say who called. Use it for agents that do one job for several others.

Manual run#

Starts the flow from the console or the API with data you type. Useful for boards you run on demand, such as transcribing one recording by its URL.

WhatsApp message received#

A customer wrote to one of the project's WhatsApp numbers (see WhatsApp: your agent on your business number). Customer messages only: your team's replies have their own trigger. Narrow it with Number (empty: every number of the project), Message type, Which messages (every message, the first message of a conversation, or a message after 24 hours of silence, which opens a new 24-hour window) and Text contains, which also searches a caption or a voice note's transcript. The trigger gives the steps:

• from (the customer's phone number, empty when they hide it), user_id (their WhatsApp user id, always there), username, profile_name
• text (for a voice note, its transcript), type, caption, media, location
• conversation_id, wamid, timestamp, number_id, number, contact_id, window_open_until, window_opened, first_in_conversation
• answered_by: who answers this message under the number's answer settings (agent, team_then_agent or team), so a board can act only when people will answer

Use event_id (the same as wamid) when the system you send to needs a key that never repeats.

Your team replied on WhatsApp#

Someone of your team answered a WhatsApp customer, from the console or from the WhatsApp Business app on the phone. Narrow it with Number, Sent from (the console or the phone app) and Text contains. It gives the reply's text, sent_by, rep_name (who replied, from the console), agent_paused_until, conversation_id and wamid, and the customer's from and user_id. A typical use: log your team's replies to your CRM.

Listen for the real event#

The Webhook received, Call ended (PBX), Called by another agent, WhatsApp message received and Your team replied on WhatsApp triggers have a Listen button in the inspector. Press it, then make the event happen: send the webhook from the other system, make and hang up a call on the PBX, run the board that calls this one, write to the WhatsApp number from a phone, or reply to a customer from the console or the WhatsApp Business app. The next event is shown in the inspector exactly as the trigger would receive it, formatted, and it is not run, even while the agent is disabled. Listening lasts ten minutes. Press Use as test payload to run the board with that exact data.

This is the quickest way to learn the real field names a system sends, instead of guessing them.