Broadcast Calls allow you to start outbound calls programmatically, delivering a message to your users — with optional logic, input collection, or integrations. These flows are powerful, scalable, and fully programmable thanks to Callr Actions.

Broadcasting isn’t just about playing a message — it’s about building any voice experience, on your terms.

🚀 Start with the Callr API

You can trigger outbound call flows using the Callr REST API.

This API call will start the api-initiated branch of a Callr Actions scenario, passing in variables like phone numbers, user IDs, or message content.

⚙️ What Can You Do in a Broadcast Flow?

Once the call is answered, you have access to the full power of Callr Actions — just like with inbound calls:

✅ You can...	Example
Play a dynamic or personalized message	Use `say@v2` or `play@v1` with variables
Collect keypad input	Use `gather@v2` to ask questions
Record a message	Use `record@v1`
Make API calls to your backend	Use `fetch@v2` to log or trigger workflows
Run business logic	Use `javascript@v1` or `memcache@v1`
Connect to a real person	Use `dial@v1` to forward the call if needed
Launch a Voice AI Agent	Use `voicebot@v1` for interactive outbound dialogs

Broadcast flows are highly customizable: reminders, alerts, surveys, confirmations, re-engagement campaigns — or even an AI agent calling users on your behalf.

🧪 Example: Voice Reminder with DTMF Confirmation

This basic example shows how to:

Dial a number
Play a message
Ask for confirmation (Press 1 or 2)
Retry up to 3 times if no valid input
Push the result to your server

description: Voice broadcasting

compat:
  version: 2025-09-01

defaults:
  language: en-GB

variables:
  $userID: 0
  $result: "unknown"
  $repeat: 3
  $dial: "unknown"
  $target: "+33639980000"
  $timeout: 30
  $url: "https://api.example.com/call-logs"

branches:
  api-initiated:
    actions:
      - action: dial@v1
        params:
          targets:
            - number: ${{ $target }}
              timeout: ${{ $timeout }}
          answerOnBranch: answered
        result: $dial

      - action: fetch@v2
        params:
          url: ${{ $url }}?userID=${{ $userID }}
          method: POST
          headers:
            Content-Type: application/json
          body: |
            {
              "target": ${{ JSON.stringify($target) }},
              "result": ${{ JSON.stringify($result) }},
              "dial": ${{ JSON.stringify($dial) }}
            }

  answered:
    actions:
      - label: broadcast
        action: say@v2
        params:
          what: Hello there! You have an appointment at 5pm.
        result: $say

      - action: javascript@v1
        params:
          code: $repeat--

      - action: gather@v2
        params:
          maxDigits: 1
          prompt:
            what: Press 1 to confirm, or 2 to cancel.
        result: $dtmf

      - if: $dtmf?.input == '1'
        then:
          - action: javascript@v1
            params:
              code: $result = 'confirmed'
          - action: say@v2
            params:
              what: Thank you! Your appointment is confirmed.
          - action: hangup@v1

      - if: $dtmf?.input == '2'
        then:
          - action: javascript@v1
            params:
              code: $result = 'canceled'
          - action: say@v2
            params:
              what: OK! Your appointment is canceled.
          - action: hangup@v1

      - action: say@v2
        params:
          what: Sorry, I did not get that.

      - if: $repeat == 0
        action: hangup@v1

      - goto:
          label: broadcast

🚀 Trigger the Scenario via API

You can trigger the flow from your app or backend like this:

curl --request POST \
     --url https://api.callr.com/v2.0/actions/<your-scenario-sid>/runs \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your-callr-api-key>' \
     --data '
{
  "variables": {
    "$targetA": "+33639980042",
    "$userID": "1234"
  }
}
'

Replace:

<your-callr-api-key> with your actual API key
<your-scenario-sid> with the scenario SID from the Callr Portal

✅ Use Cases

📅 Appointment Reminders
Confirm or cancel appointments with one key press.
⚠️ Urgent Alerts & Notifications
Instantly deliver time-sensitive messages at scale.
🗳️ Surveys & Polling
Ask questions, collect input, and store responses.
🤖 Outbound AI Agents
Use voicebot@v1 to deliver dynamic conversations with real-time API integration.

🔒
Reminder
If you're in Build Mode, you can only call Testing Numbers — phone numbers you own and have verified.
Make sure to add your personal number as a Testing Number in the Callr Portal.

🚀 Start with the Callr API

⚙️ What Can You Do in a Broadcast Flow?

🧪 Example: Voice Reminder with DTMF Confirmation

🚀 Trigger the Scenario via API

✅ Use Cases

🔒Reminder

🔒
Reminder