Callr Actions Reference
Design communication flows with Callr Actions — a declarative, YAML-based framework inspired by GitHub Actions.
Whether you're routing calls, triggering events, or integrating with external services, Callr Actions lets you compose complex voice logic with simple building blocks.
Tip
We recommend using the Callr Portal to create your Callr Actions scenarios. It features a built-in code editor with autocomplete, inline documentation, and live testing to help you build faster.
Architecture
Call flows in Callr Actions are organized around branches – sequences of actions that determine your call’s behavior. There are four special branches:
inbound-call
: The entry point for an Inbound Call.inbound-sms
: The entry point for an Inbound SMS.api-initiated
: The entry point for actions triggered via the API.hangup
: Executed for Inbound Calls once the call is hung up.
You can also create additional branches to organize your logic. To jump between branches, use the built-in goto
statement:
branches:
inbound-call:
actions:
- # your initial actions...
- if: '!$dial.ok'
goto:
branch: voicemail
voicemail:
actions:
- action: say@v2
params:
what: Sorry, we are not available at the moment.
JSON Schema Reference
Callr Actions are defined by a JSON Schema, available here: JSON – YAML. You can use the schema to enable validation and auto-completion in your favorite code editor.
💡 Tip: The Callr Portal includes a built-in code editor with autocomplete and live validation – no setup required.
Expressions
Expressions, enclosed in double curly braces ${{ expression }}
, can be used in any params
object. They are evaluated at runtime using a modern JavaScript engine.
- action: say@v2
params:
what: Hello! Your number is ${{ call.fromNumber }}.
- action: say@v2
params:
what: >
I know that 1 + 1 equals ${{ 1+1 }}
- action: say@v2
params:
what: >
Your ticket ID is ${{ $ticketID.split('').join(' ') }}
User-defined variables
You can define your own variables to use in expressions. These variables must start with a dollar sign and be valid JavaScript identifiers. The variable type is inferred from the value and preserved when used in expressions.
variables:
$errorCode: 0 # an int
$pi: 3.14159265359 # a float
$user: # an object
name: John # a string
age: 42 # an int
$list: # an array
- apples
- oranges
For example, you can reference these variables in a branch:
branches:
inbound-call:
actions:
- action: say@v2
params:
what: >
Hello ${{ $user.name }}!
You look like you are ${{ $user.age/2 }} years old!
Conditions
Use the if
statement to conditionally execute actions. Conditions are expressions evaluated with a modern JavaScript engine.
- if: call.fromNumber.match(/^+33/)
action: say@v2
params:
what: Bonjour. Comment allez-vous?
language: fr-FR
For multiple actions under one condition, use the if
-then
structure:
- if: call.fromNumber == '+33199004242'
then:
- action: say@v2
params:
what: Hello boss!
- action: say@v2
params:
what: How are you today?
- action: say@v2
params:
what: See you later!
- action: hangup@v1
Goto & Labels
The goto
lets you jump to another branch or a specific label within a branch. This is useful for looping or branching logic.
branches:
inbound-call:
actions:
- label: gather # Define a label
action: gather@v2
params:
maxDigits: 1
prompt:
what: Hello! Press 1 to accept the call
result: $digits
- if: $digits.input == '1'
goto:
branch: accept # Jump to a different branch
- action: say@v2
params:
what: >
Sorry, I didn't get your answer.
- goto:
label: gather # Jump back to the label
accept: # New branch defined here
actions:
- action: say@v2
params:
what: >
OK! I'm going to connect you to the other party.
- action: bridge@v1
Defaults
Defaults allow you to define common behavior at the top level of your scenario or for specific branches. These values can be overridden by branch-level defaults.
defaults:
language: en-US # Default language for speech (TTS/STT)
voice: en-US-Aria # Default voice for TTS
autoAnswer: true # If false, you need to use answer@v1
branches:
voicemail:
defaults:
language: en-GB # the voicemail uses a British accent
actions:
- action: say@v2
params:
what: Sorry, we are not available at the moment.
List of actions
Action | Description |
---|---|
amd@v2 | Detects answering machines. |
answer@v1 | Answers an Inbound Call if autoAnswer is set to false. |
bridge@v1 | Bridges an Outbound Call with the other leg of a dial action. |
dial@v1 | Dials a phone number, initiating an Outbound Call. |
dtmf@v1 | Sends DTMF tones. |
email@v1 | Sends an email. |
fetch@v2 | Communicates with HTTP(s), synchronously or asynchronously. |
gather@v2 | Waits for DTMF input. |
googleAnalytics@v1 | Pushes events to GA4. |
hangup@v1 | Hangs up the call. |
javascript@v1 | Runs JavaScript in a sandbox, useful for data manipulation. |
log@v1 | Logs data. |
memcache@v1 | Stores data in a temporary memory store. |
mixpanel@v1 | Pushes events to MixPanel. |
openai@v2 | Communicates with OpenAI platform. |
play@v1 | Plays an uploaded audio file. See Audio Files. |
playRecordingFile@v1 | Plays a temporary audio recording (record@v1 ). |
saveRecordingFile@v1 | Saves a temporary audio recording. See Recordings. |
recognize@v2 | Recognizes audio (STT - Speech-to-Text). |
record@v1 | Records audio to a temporary file. |
say@v2 | Uses TTS (Text-to-Speech) to speak. |
sms@v1 | Sends an SMS message. |
startRecording@v1 | Starts recording the call, automatically creating a Recording. |
stopRecording@v1 | Stops the call recording. |
voicebot@v1 | Initiates a Voice AI Agent. |
wait@v1 | Pauses execution for a set duration. |
waitForSilence@v1 | Waits until silence is silence. |
Templates
Explore our Callr Portal for a variety of ready-to-use templates, such as:
- Transparent Call Forwarding
- Call forwarding with recording and transcription
- Call forwarding with voicemail
- Call forwarding with AI ✨
- Voice broadcasting
- AI Agent with OpenAI
- Fetch and push data
- Call Screening
- Voicemail With Transcription
- Advanced Call Tracking
- Smart IVR
- Two Outbound Calls
- Two Outbound Calls with AI ✨
- Voicemail with AI ✨
Prefer working programmatically?
You can also create and manage your scenarios using our API.
Updated 14 days ago