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: JSONYAML. 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

ActionDescription
amd@v2Detects answering machines.
answer@v1Answers an Inbound Call if autoAnswer is set to false.
bridge@v1Bridges an Outbound Call with the other leg of a dial action.
dial@v1Dials a phone number, initiating an Outbound Call.
dtmf@v1Sends DTMF tones.
email@v1Sends an email.
fetch@v2Communicates with HTTP(s), synchronously or asynchronously.
gather@v2Waits for DTMF input.
googleAnalytics@v1Pushes events to GA4.
hangup@v1Hangs up the call.
javascript@v1Runs JavaScript in a sandbox, useful for data manipulation.
log@v1Logs data.
memcache@v1Stores data in a temporary memory store.
mixpanel@v1Pushes events to MixPanel.
openai@v2Communicates with OpenAI platform.
play@v1Plays an uploaded audio file. See Audio Files.
playRecordingFile@v1Plays a temporary audio recording (record@v1).
saveRecordingFile@v1Saves a temporary audio recording. See Recordings.
recognize@v2Recognizes audio (STT - Speech-to-Text).
record@v1Records audio to a temporary file.
say@v2Uses TTS (Text-to-Speech) to speak.
sms@v1Sends an SMS message.
startRecording@v1Starts recording the call, automatically creating a Recording.
stopRecording@v1Stops the call recording.
voicebot@v1Initiates a Voice AI Agent.
wait@v1Pauses execution for a set duration.
waitForSilence@v1Waits 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.