Actions are initiated by requests to the path /action.

The argument action is used to determine which action will be run.

Call control

Making a call

The action dial calls a number, URI, favorite, or scheduled conference. Exactly one of those arguments must be provided.

Parameter Data type Description
number string Number or URI to dial.
favorite integer Favorite ID to dial.

scheduled_conference

integer Call the scheduled conference with the given ID.
boolean Call the next scheduled conference.


Examples:

  • action?action=dial&number=1234
    Dial the number 1234.
  • action?action=dial&number=name@example.com
    Dial the URI name@example.com.
  • action?action=dial&number=%c3%b1%c3%a5m%c3%a9@example.com
    Dial the URI ñåmé@example.com.
  • action?action=dial&favorite=567
    Dial the favorite with ID 567.
  • action?action=dial&scheduled_conference
    Dial the next scheduled conference (this implements the Join Now button).
  • action?action=dial&scheduled_conference=890
    Dial the scheduled conference with ID 890.

Ending a call

The action hangup ends a call. If no callid is specified, it hangs up the current foreground call. (In general, unless you are sure that you have exactly one call then always specify the callid to avoid surprises.)

Parameter Data type Description
callid integer ID of call to hang up.

Responding to an incoming call

The actions answer, reject and ignore respond to an incoming call. All take zero (to respond to the first incoming call that has not already been responded to) or one (to respond to a specific call) arguments.

Parameter Data type Description
callid integer ID of call to respond to.

Hold

The actions hold and resume perform hold and resume on calls.

Parameter Data type Description
callid integer ID of call to to hold or resume.

Transfer

The actions start_transfer and complete_transfer perform transfer actions on calls. After the start_transfer action, a new call is immediately created. To proceed with the transfer, use dial to connect that call. Use complete_transfer to finish: if called immediately, the transfer is blind; otherwise, the consultation call connects and the transfer can be completed at any time thereafter. To cancel the transfer, use hangup on the new call (including in the case where it has not yet been dialed).

Parameter Data type Description
callid integer

ID of call being acted on.

Example transfer sequence:

  • action?action=dial&number=1234
    Dial the number 1234.
  • action?action=start_transfer
    Start a transfer.
  • action?action=dial&number=5678
    Dial the number 5678, to make a consultation call.
  • action?action=complete_transfer
    Complete the transfer – both calls end and the remote ends connected to each other.

Conferencing

The actions create_conference and add_to_conference work together in the same way as start_transfer and complete_transfer to create a new ad hoc conference with three participants. When in a conference, dial and add_to_conference can be used to add more participants, again in the same way. A participant can be removed from the conference using kick_participant, and they can be muted and unmuted using mute_participant and unmute_participant.

Parameter Data type Description
callid integer ID of call or conference being acted on.
partid integer ID of participant in the conference to act on.

Example conference sequence:

  1. action?action=dial&number=1234
    Dial the number 1234.
  2. action?action=create_conference
    Promote the call to an ad hoc conference, and make a new call to add.
  3. action?action=dial&number=3456
    Dial the number 3456, to connect the second call.
  4. action?action=add_to_conference
    Add the second call into the conference.
  5. action?action=add_to_conference
    Create a new call to add another participant.
  6. action?action=dial&number=5678
    Dial the number 5678, to connect the third call.
  7. action?action=add_to_conference
    Add the third call into the conference.
  8. action?action=mute_participant&partid=234
    Mute the participant with ID 234 (find the ID numbers in the participants array in the call object).
  9. action?action=kick_participant&partid=456
    Kick the participant with ID 456.
  10. action?action=hangup
    Leave the conference; it continues with the two remaining participants.

Example conference sequence: Answer two incoming calls and escalate one of those to an ad hoc conference

  1. action?action=answer&callid=<1st call id>
    Answer the first incoming call
  2. action?action=answer&callid=<2nd call id>
    Answer the second incoming call, putting the first on hold
  3. action?action=create_conference&callid=<2nd call id>
    Use the second call to create a conference (the first is still on hold)
  4. action?action=add_to_conference&callid=<1st call is>
    Add the first call into the conference.
  5. action?action=hangup
    Leave the conference; it continues with the two remaining participants.

Camera control

Select camera

The camera_select action selects the active camera on systems with multiple cameras. The cameras are zero-indexed (for example, on a system supporting three cameras, the three cameras are 0, 1 and 2).

Parameter Data type Description
index integer Camera index to switch to.

Move camera

The camera_control action is used to move the local active camera or the remote camera (via Far-End Camera Control). Moving local cameras other than the active camera is not supported.

For example:

  • action?action=camera_control&preset=3
    Move the camera to camera preset 3.
Parameter Data type Description
local boolean Move the local camera. This is the default.
remote boolean Move the remote camera.
direction string Direction to move in: one of up, down, left, right, zoom-in or zoom-out.
duration integer Number of milliseconds to continue the move action for. Defaults to 100ms.
preset integer Move the local camera to a camera preset (see below). Note that camera presets must be configured using the StarLeaf Portal.


Camera preset is one of:

Preset Description
0 The default preset from the StarLeaf Portal.
1, 2, 3, 4 Presets 1-4 from the StarLeaf Portal.

Audio

Audio mute

The audio_mute action modifies the audio mute state of the endpoint.

Parameter Data type Description
on boolean Audio muted.
off boolean Audio unmuted.
toggle boolean Toggle. This is the default.

Volume

The volume action controls the volumes of the devices attached to the endpoint. Volume levels are integers 0 to 10 – attempts to move outside this range will saturate.

Parameter Data type Description
device string Device to modify volume on – see below.
absolute integer Set to the given absolute volume.
relative integer Modify the current volume by the (possibly negative) value given.
direction string up or down – equivalent to relative +1 and –1 respectively.

 

  • ringer – The ringer volume.
  • adjunct – The audio or video adjunct. With a GT Mini, this is usually the HDMI/TV output, but could equally be line-out or a Conference Phone 2220.
  • incall– This is usually the HDMI/TV output, but could equally be the audio line-out. It affects whichever audio device is in-use for the call

If no device is specified, then the currently active audio device is used. (When out of call, this is the ringer.)

Video

PC sharing

The share_pc action changes whether the PC is being shared on the currently active call.

Parameter Data type Description
on boolean Switch on.
off boolean Switch off.
toggle boolean Toggle. This is the default.

Video mute

The video_mute action modifies the video mute state of the endpoint.

Parameter Data type Description
on boolean Switch on.
off boolean Switch off.
toggle boolean Toggle. This is the default.

Other actions

Keypad

The keypad action sends digits as if typed on the keypad. This creates DTMF digits while in call. On a StarLeaf endpoint, this opens a new call and starts dialing when the endpoint is not currently in a call.

Parameter Data type Description
digits string Digits to dial.

Do not disturb

The do_not_disturb action sets the ‘do not disturb’ state of the endpoint.

Parameter Data type Description
on boolean Switch on.
off boolean Switch off.
toggle boolean Toggle. This is the default.

Call forwarding

The forward_calls action sets the endpoint to forward calls somewhere else. If the user has no mailbox or mobile number, trying to set the corresponding forwarding target silently fails.

Parameter Data type Description
off boolean Switch off.
target string Forwarding target: off, voicemail, mobile or number.
number string Number to forward to, when target is number.

Help

The help action enumerates the available actions, returning them as a JSON array.