Skip to main content

Automation triggers and limits

An automation (an event flow) is a call flow that does not answer a call: it starts when something happens, such as a missed call, a voicemail, an SMS, a chat message, a website form, an event in your CRM, a timer or a click on Run now. It then runs its steps in the background: send a message, create a CRM task, call a web address, wait, branch.

This page explains what can start an automation, how to narrow it down with a filter, and the limits that keep a busy company from flooding the system. Building the steps themselves is done in the automation designer.

What can start an automation​

Each automation has exactly one trigger. When you need two, make two small automations: their history stays easy to read.

TriggerStarts whenWhat the steps can read (trigger.*)
Missed call (call.missed)An incoming call ended and nobody answered it (no answer, busy, or the caller hung up while it rang). Calls the PBX refused do not count.caller, caller_name, called, did, extension, user, ring_secs, at, call_id
Call ended (call.ended)Any call ended.direction, caller, called, user, users, duration, disposition, has_recording, recording_id, at, call_id
Voicemail left (voicemail.left)A caller left a voicemail. When transcription is on, the automation waits up to two minutes for the transcript and the AI summary.message_id, mailbox, caller, caller_name, duration, urgent, transcript, summary
SMS received (sms.received)An SMS arrived on a company number (not from a sender you silenced).from, to, text, number_id, conversation_id
Team chat message (chat.message)Someone wrote in a team chat room.room_id, sender, text, mentions
Inbox message (inbox.message)A customer wrote on WhatsApp, Telegram, Messenger, Instagram, the website chat or another inbox channel.conversation_id, channel, channel_id, contact, text
Live call trigger (call.trigger_fired)One of your live call triggers fired.call_id, trigger_id, trigger_name, speaker, queue, agent, at, caller (the other party's number, empty when unknown)
Call assistant session (screening.session_ended)A user's call assistant finished screening a call.session_id, user, peer, intent, action_taken, summary
Webhook (webhook)Another system calls the automation's own web address (below).body (the JSON sent), headers
Schedule (schedule)A timer: every N minutes, every day, on weekdays, or on a day of the month.fired_at, tz
Website form (form)A visitor sends the callback form of your website (below).name, number, email, message, page, consent, widget_id
CRM event (crm.event)A connected CRM, helpdesk or shop sends an event (a deal was created, a ticket changed, an order was placed).connector, event, object
Run now (manual)Someone clicks Run now, or an app or script calls the API.inputs (the values you declared), started_by

Each event starts an automation once: if the same event arrives again (a repeated webhook delivery, a corrected call record), nothing new runs.

Filters​

A filter decides which events count. Every condition must hold, and a list of values matches when any of them matches. Text comparisons ignore upper and lower case.

{ "type": "call.missed",
"filter": { "called": { "op": "prefix", "values": ["+5255"] },
"caller_class": ["with_number"] } }
TriggerFilter fields
Missed callcalled, caller, did (text), extension, user (ids), caller_class, min_ring_secs
Call endeddirection (inbound, outbound, internal), disposition (answered, no_answer, busy, cancelled, failed), user, extension, called, caller, min_duration (seconds), has_recording
Voicemail leftmailbox, caller, caller_class, urgent, min_duration
SMS receivedto, from, number_id, text (words it contains), from_class
Team chat messageroom_id, sender, mentions, text, command (for example "/lead": the message starts with that word)
Inbox messagechannel (whatsapp, telegram, messenger, instagram, live_chat, sms, ...), channel_id, text
Live call triggertrigger_id, speaker (caller, agent), queue, agent
Call assistant sessionuser, intent, action_taken
Website formwidget_id (the live chat channel of the website)
CRM eventconnector (for example hubspot), event (for example deal.created)

Text fields take a value, a list, or {"op": "equals" | "prefix" | "contains", "values": [...]}. Number classes are withheld (no number shown), with_number, internal (an extension) and external (a number in international format).

A filter with a field the trigger does not have is refused when you save or publish, so a typing mistake never matches every event.

Schedules​

The schedule is the trigger's filter, exactly one of:

{ "every_minutes": 15 }
{ "daily": "08:30", "tz": "America/Mexico_City" }
{ "weekdays": "08:30", "tz": "Europe/Madrid" }
{ "monthly": { "day": 1, "at": "09:00" }, "tz": "UTC" }

every_minutes is 5 to 1440 and follows the clock (every 15 minutes runs at :00, :15, :30 and :45). Local times follow daylight saving time. Day 31 of monthly means the last day of the month. A schedule that is turned off keeps its place and simply runs nothing until you turn it on again.

Run now and inputs​

An automation on the Run now trigger can declare the inputs it needs:

{ "type": "manual", "filter": { "inputs": { "number": "phone", "note": "string" } } }

Types are string, number, bool, phone, datetime, list and object. A run started by hand gives them; a value of the wrong type, or a name the automation does not declare, is refused:

curl -X POST https://pbx.example.com/api/v1/call-flows/<flow id>/run \
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-H "Idempotency-Key: callback-123" \
-d '{"inputs": {"number": "+525512345678", "note": "Asked for a quote"}}'

The answer is 202 with the run's id. The same Idempotency-Key never starts a second run. You need the permission to change call flows.

The webhook address of an automation​

An automation on the Webhook trigger gets its own address. Create it with PUT /api/v1/call-flows/<flow id>/webhook (an administrator who may change call flows). You get an address such as https://pbx.example.com/hooks/flow/Zm9v... and a signing secret. Store the secret right away: it is shown only once. Creating a new address replaces the old one at once.

The sender signs each call with the secret. With the default hmac_sha256 scheme the signature is the hexadecimal HMAC-SHA256 of the body, in the header X-Hub-Signature-256 (or a header you choose); X-Request-Id (or X-Webhook-Id) identifies a delivery, so a repeated delivery runs nothing new:

BODY='{"order": {"id": 7, "total": 120}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
curl -X POST https://pbx.example.com/hooks/flow/<key> \
-H "Content-Type: application/json" -H "X-Hub-Signature-256: sha256=$SIG" \
-H "X-Request-Id: order-7" -d "$BODY"

Other schemes are standard (Standard Webhooks, as used by many automation platforms), shared_secret and jwt_hs256.

AnswerMeaning
202Accepted; run_id names the run (empty when it was a repeated delivery).
401The signature does not match.
404No such address (or it was removed).
409The automation's live version no longer starts on a webhook, or its trigger is turned off.
413The body is larger than 256 KiB.
429The company's automation limit is reached. Nothing was kept; try again after Retry-After seconds.

The steps read the body as trigger.body, for example {{trigger.body.order.id}}.

The website callback form​

On a website that uses the live chat widget SDK, a page can send its own "call me back" form:

MpbxWidget.requestCallback({ name: 'Ana', number: '+525512345678',
message: 'A quote for 10 users', consent: true });

The visitor must agree to be called back (consent: true) and give a phone number. Automations on the Website form trigger then run: call the visitor back, create a lead in your CRM or post to a team chat. The website always gets the same answer, whether or not an automation listens. Only websites allowed in the chat widget settings can send the form.

CRM and helpdesk events​

When a connected CRM, helpdesk or shop sends events to the PBX (its inbound webhook address under Integrations), each event is also offered to your automations on the CRM event trigger. trigger.event is the vendor's event name and trigger.object the data it sent (very large objects are left out). Filter on connector and event to pick the ones you need.

Limits​

Limits protect the PBX and your telephony when an automation goes wrong, for example one that reacts to its own messages. They refuse new work and alert, they never delete anything.

LimitDefaultWhen it is reached
Automations started per minute120The run is recorded as refused in the run history; a webhook caller gets 429.
Automations running at the same time20Further runs wait their turn.
Automations started per 24 hours10 000 (or your licence's limit when lower)Refused.
Runs waiting on a timer5 000Refused.
Web requests of all automation steps per minute300The step takes its error branch.
Personal automations per user5Creating another one is refused.
Runs of one personal automation per 24 hours2 000Refused.

See and change them with GET and PUT /api/v1/call-flows/quotas (the change needs If-Match and is recorded in the audit log). When a limit refuses work, the alert FlowQuotaReached is raised for an hour and your administrators are told which limit it was. The best fix is usually a filter on the busiest trigger.

To see what an automation did, repeat or test it, read Automation run history, tests and debugging. To start from a ready-made automation, see Automation templates.