👍

Bring several callers together in the same audio room with a single action — team bridges, customer calls with multiple stakeholders, on-call hotlines, or any flow where people dial in to talk together.

⚙️ How It Works

1. A participant reaches a Callr Actions scenario that runs conference@v1 with a room name. A participant can be:
   • someone who calls one of your numbers (Inbound Call), or
   • someone you call from the scenario (Outbound Call) to make them join the room.
2. If the room does not exist yet, it is created and the caller hears the waiting prompt (if any) until someone else joins.
3. Every caller of your account who runs conference@v1 with the same room is connected to the others.
4. The action blocks until the caller leaves the room, then the next action of the scenario runs. The call is not hung up.

A caller leaves the room when they:

• press * on their keypad,
• become the last participant and autoLeave is enabled,
• fail the PIN code on every attempt (or don't enter it in time),
• hang up.

📘

Rooms

• A room name is 1 to 32 letters or digits, not case-sensitive: Sales and sales are the same room.
• Rooms are private to your account. They are separate from real-time app rooms: a real-time call and a conference@v1 call never meet.
• Quote an all-digit room name in YAML (room: '1234').

🚀 Basic Conference

Every caller of this number joins the sales room:

description: Conference room for the sales team

branches:
  inbound-call:
    actions:
      - action: conference@v1
        params:
          room: sales
        result: $conference

      - action: hangup@v1

📞 Call Participants Into the Room

Rooms are not limited to inbound callers: you can also call someone and make them join the room. Inbound and outbound participants who use the same room are connected together.

Start the scenario from the REST API (api-initiated branch), dial the participant with dial@v2, and run conference@v1 in the branch named by answerOnBranch. That branch runs on the called participant's leg once they answer.

description: Call a participant and make them join a conference room

variables:
  $participant: "+33639980041" # can be passed when starting the scenario
  $room: sales

branches:
  api-initiated:
    actions:
      - action: dial@v2
        params:
          callerId: "+33199001234" # a number or approved caller ID of your account
          targets:
            - number: ${{ $participant }}
              timeout: 30
          answerOnBranch: join-room
        result: $dial

  join-room:
    actions:
      - action: conference@v1
        params:
          room: ${{ $room }}
          welcome:
            tts:
              text: You are joining the conference.
        result: $conference

      - action: hangup@v1

💡

Start the scenario once per participant to call several people into the same room, and mix them with inbound callers who dial one of your numbers. See Broadcast Calls to trigger a scenario from the API.

🔐 PIN-Protected Room with Prompts

Add a welcome message, hold music while the caller is alone, and a PIN code. The caller types the PIN followed by #.

description: PIN-protected conference room

branches:
  inbound-call:
    actions:
      - action: conference@v1
        params:
          room: board
          welcome:
            tts:
              text: Welcome to the board conference.
          waiting:
            audioFile:
              sid: fdsanjfd # played in a loop while the caller is alone
          pin:
            code: '4321' # quote it: 1 to 10 digits, leading zeros are kept
            maxTries: 3
            timeout: 10
            prompt:
              tts:
                text: Please enter your PIN code, followed by the pound key.
            error:
              tts:
                text: Wrong PIN code.
            valid:
              tts:
                text: Thank you. You are now joining the conference.
          userJoin:
            tts:
              text: A participant has joined.
          userLeave:
            tts:
              text: A participant has left.
        result: $conference

      - if: '!$conference.ok'
        action: play@v3
        params:
          tts:
            text: Sorry, we could not connect you to the conference. Goodbye.

      - action: hangup@v1

🚧

The call is not hung up after a failed PIN

When the PIN is wrong on every attempt (or not entered in time), conference@v1 ends and the next action runs. Check $conference.ok to tell the caller what happened, then hang up.

ℹ️

userJoin and userLeave are taken from the caller who opens the room. Use the same values for every caller of a given room.

🚪 Leaving Automatically

With autoLeave, the caller leaves the room automatically when they become the last participant (when someone else leaves — not while waiting for the first participant). An optional announce prompt is played before leaving.

- action: conference@v1
  params:
    room: support
    autoLeave:
      enabled: true
      announce:
        tts:
          text: Everyone else has left the conference. Goodbye.
  result: $conference

- action: hangup@v1

📊 Result

Store the result with result: $conference to know how and when the caller left the room:

result:
  ok: true      # true when the caller entered the room
  status: left  # left | lastParticipant | pinError | pinTimeout | hangup | failed
  duration: 125 # seconds in the room, after the welcome and the PIN (0 if never entered)

📚 Parameters

An audio source is either a text-to-speech prompt or an audio file of your library:

# Text-to-speech (optional voice or language)
welcome:
  tts:
    text: Welcome
    language: en-US

# Audio file of your library (8-character SID)
waiting:
  audioFile:
    sid: fdsanjfd

No prompt is played by default. Text-to-speech prompts are billed every time the action runs, like play@v3; audio file prompts are free. List your audio file SIDs with GET /v2.0/audio-files.

💡 Ideas

• Dynamic rooms: compute the room from a variable or a fetch@v3 response (for example, a meeting ID typed with gather@v4).
• Analytics: send $conference to your backend with fetch@v3 in the hangup branch.