conference@v1

Put the caller in a conference room. Callers of your account that use the same room are connected together; the room is created when the first caller enters it. The action blocks until the caller leaves the room (by pressing *, automatically as the last participant, or after a failed PIN), then the next action runs.


Version	`conference@v1`
Runs in	`inbound-call` and your own branches

Parameters

Name	Type	Required	Default	Description
`room`	string	yes		Conference room: 1 to 32 letters or digits, not case-sensitive. Rooms are private to your account and separate from real-time apps. Quote an all-digit room in YAML. accepts `${{ }}`
`welcome`	object			Played to the caller before entering the room (and before the PIN prompt). `tts` or `audioFile`, see Voices & Audio
`waiting`	object			Played in a loop while the caller is alone in the room. `tts` or `audioFile`, see Voices & Audio
`pin`	object			If set, the caller must enter this PIN code, followed by #, to enter the room
`pin.code`	string	yes		PIN code: 1 to 10 digits. Quote it in YAML. accepts `${{ }}`
`pin.prompt`	object			Played at each attempt to ask for the PIN code. `tts` or `audioFile`, see Voices & Audio
`pin.error`	object			Played after a wrong PIN code. `tts` or `audioFile`, see Voices & Audio
`pin.valid`	object			Played after the right PIN code, before entering the room. `tts` or `audioFile`, see Voices & Audio
`pin.maxTries`	integer		`3`	Number of attempts: 1..10 accepts `${{ }}`
`pin.timeout`	integer		`10`	Seconds to enter the PIN code at each attempt: 1..30 accepts `${{ }}`
`userJoin`	object			Played to the room when a participant joins. Taken from the caller who opens the room, so use the same value for every caller of a room. `tts` or `audioFile`, see Voices & Audio
`userLeave`	object			Played to the room when a participant leaves. Taken from the caller who opens the room, so use the same value for every caller of a room. `tts` or `audioFile`, see Voices & Audio
`autoLeave`	object			Leave the room automatically when the caller becomes the last participant (when someone else leaves; not while waiting for the first other participant)
`autoLeave.enabled`	boolean	yes	`false`	accepts `${{ }}`
`autoLeave.announce`	object			Played to the caller before leaving the room automatically. `tts` or `audioFile`, see Voices & Audio

Every parameter that accepts ${{ }} can be computed from an expression.

How it works

Callers who run conference@v1 with the same room are connected together. The room is created by the first caller, and it is not case-sensitive: "Sales" and "sales" are the same room. Rooms are private to your account, and separate from the rooms of real-time apps: a real-time call and a conference@v1 call never meet.

The action blocks until the caller leaves the room, then the next action runs. The call is NOT hung up. The result tells why the action ended (see below). The caller can press * at any time to leave the room. With autoLeave enabled, the caller also leaves automatically when they become the last participant (when someone else leaves). After a failed PIN (maxTries attempts), the action ends too.

Every prompt is either an audio file of your library, { audioFile: { sid: 'fdsanjkf' } }, or a text-to-speech prompt, { tts: { text: Welcome } } with an optional voice or language. 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. The SID is the audio file identifier of the REST API v2 (8 lowercase characters) see: https://docs.callr.com/reference/audiofilesget

Examples

Short example

- action: conference@v1
  params:
    room: sales # 1..32 letters or digits
  result: $conference

PIN-protected room, with prompts

The caller types the PIN, followed by the pound key.

- action: conference@v1
  params:
    room: sales
    welcome:
      tts:
        text: Welcome to the sales conference
    waiting:
      audioFile:
        sid: 'fdsanjkf' # played in a loop while the caller is alone in the room
    pin:
      code: '1234' # quote it: digits only (1..10), leading zeros are kept
      prompt:
        tts:
          text: Please enter your PIN code, followed by the pound key
      error:
        tts:
          text: Wrong PIN code
  result: $conference

The call is not hung up after a failed PIN: tell the caller

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

Full example with defaults

Every parameter except room is optional.

- action: conference@v1
  params:
    room: sales # (string) required, 1..32 letters or digits
    welcome: # none by default, played before the PIN and before joining
      tts:
        text: Welcome
        voice: en-US-AvaMultilingual # or language: en-US (not both)
    waiting: # none by default, played in a loop whenever the caller is alone
      audioFile:
        sid: 'fdsanjkf'
    pin: # none by default: no PIN
      code: '1234' # (string) required in pin, digits only (1..10)
      prompt: # none by default, played at each attempt
        tts:
          text: Please enter your PIN code, followed by the pound key
      error: # none by default, played after a wrong PIN (not after a timeout)
        tts:
          text: Wrong PIN code
      valid: # none by default, played after the right PIN
        tts:
          text: PIN code accepted
      maxTries: 3 # (1..10)
      timeout: 10 # seconds per attempt (1..30)
    # userJoin and userLeave are played to the whole room.
    # They are taken from the caller who opens the room:
    # use the same value for every caller of a room.
    userJoin: # none by default
      audioFile:
        sid: 'fdsanjkf'
    userLeave: # none by default
      audioFile:
        sid: 'fdsanjkf'
    autoLeave:
      enabled: false # leave when the caller becomes the last participant
      announce: # none by default, played to the caller before leaving
        tts:
          text: You are the last participant, goodbye
  result: $conference

Result

Set result: $myVariable to keep it. Result of conference@v1. status is left (the caller pressed *), lastParticipant (the caller left automatically, autoLeave), pinError (the PIN was wrong on every attempt), pinTimeout (no PIN was entered in time), hangup (the caller hung up) or failed (the room could not be joined, for example it is full, or it ended unexpectedly)

Field	Type	Description
`ok`	boolean	`true` when the caller entered the room (`left`, `lastParticipant`, or any status with `duration` > 0)
`status`	`left`, `lastParticipant`, `pinError`, `pinTimeout`, `hangup`, `failed`
`duration`	integer	Seconds in the room, after the welcome and the PIN (0 if never entered)

{
  "ok": true,
  "status": "left",
  "duration": 125
}