State
Last updated September 28, 2021 Cloud Endpoint Control API
The state of the endpoint is examined by requesting the path /state.
This returns a JSON object containing one or more subobjects corresponding to each section requested.
Sections
Specific sections can be requested via the filter parameter. This takes a comma-separated list of section names to examine, or the special value all, which requests all sections. If no filter is provided, then a default set of sections is returned (not necessarily all).
Some examples:
- state
Fetch default state sections (time, locale, network, endpoint, line, calls, scheduled conferences, audio, video) - state?filter=line,calls
Fetch the state sections line and calls. - state?filter=all
Fetch all state sections. - state?filter=all&pretty
Fetch all state sections, and pretty-print the output to be more human-readable.
Version
The version section returns version information about the endpoint.
Parameter | Data type | Description |
---|---|---|
version_string | string | String form of the version number. |
Time
The time section shows the current time in universal (UNIX / UTC), local (configured timezone) and system (monotonic) clocks. It pushes an update when the minute changes (sufficient for rendering a HH:MM clock).
Parameter | Data type | Description |
---|---|---|
system_clock | integer | Current system clock time (often seconds since boot). |
unix_clock | integer | Current UNIX time (milliseconds since the start of 1970). |
date_time | object | Current local time, made up of the following fields: |
year | integer | Year. |
month | integer | Month of year (one indexed). |
day | integer | Day of month (one indexed). |
hour | integer | Hours (24-hour). |
minute | integer | Minutes |
second | integer | Seconds. |
dst |
boolean |
Whether DST is currently in effect. |
day_of_week |
integer |
Day of week (Sunday as zero to Saturday as six). |
day_of_year | integer | Day of year (zero indexed). |
Line
The line section contains details about the current line.
Parameter | Data type | Description |
---|---|---|
id | integer | Line ID. |
name | string | Display name. |
number | string | Number. |
uri | string | Global URI. |
legacy_uri | string | Global URI usable with legacy H.323 devices. |
Calls
The calls section contains details of all calls.
The top level object contains the element list, which is an array of call objects. Each call object has fields:
Parameter | Data type | Description |
---|---|---|
id | integer | Unique ID of this call (pass as callid to call-related actions). |
state | integer | API call state. |
call_time | integer | Time since the call was connected, in seconds. |
participants | array | If this is a multiparty call, the array of participant details. |
recording | integer | The recording state of the call. This is only present for organizations that have recording enabled. |
remote_camera_controllable | boolean | Whether the remote / far-end camera is controllable. |
can_start_content_sharing | boolean | Whether content can be shared in the call. |
can_transfer | boolean | Whether the call can be transferred. |
can_add_participant | boolean | Whether a participant can be added to the call. |
audio_muted | boolean | Whether the participant’s audio is muted. |
can_toggle_audio_mute | boolean | Whether using the action “mute_participant” or “umute_participant” on this participant will currently work. |
can_toggle_mute | boolean | Whether using the action “audio_mute” will currently work. |
raised_hand_seq | integer | Self raised hand sequence number. 0 if hand is lowered, non-zero if raised. Only present in Spotlight conference calls. |
can_raise_or_lower_hand | boolean | Whether you are allowed to raise or lower your own hand using the action “raise_hand” in a Spotlight conference call. |
can_participate_in_conference | boolean | Whether a 1-1 call can be escalated into a conference. If true then you must use the action “create_conference” before you can add other people to the conference. |
can_lock_unlock_conference | boolean | Whether you have permission to lock or unlock a conference. |
Updates are pushed on changes to everything except the call_time field.
Each participant object has fields:
Parameter | Data type | Description |
---|---|---|
id | integer | Unique ID of this participant(pass as partid to conference-related actions). |
state | integer | API participant call state. |
name | string | Display name. |
number | string | Number (or URI). |
Basic call states are as follows:
Call state | Description | |
---|---|---|
0 | INACTIVE | Inactive call (ignore, should never be seen). |
1 | DIALING | Call is currently dialing, or offhook about to dial. |
2 | WAITING |
Outgoing call is placed and waiting for the far end. |
3 | RINGING | Incoming call is ringing. |
4 | IN_CALL | In call. |
5 | ON_HOLD | On hold, at the near end. |
6 | ENDED | Call ended. |
Recording state of a call is as follows:
Recording state | Description | |
---|---|---|
0 | UNAVAILABLE | Recording is not available for this call (for example, recording is not available for point-to-point calls). |
1 | DISABLED | This call is not currently being recorded. |
2 | ENABLED | This call is currently being recorded. |
For information about the recording action, refer to the Call action section of Endpoint Control API actions .
Scheduled conferences
The scheduled_conferences section contains details of current and future scheduled conferences. The top level object contains the element list, which is an array of objects:
Parameter | Data type | Description |
---|---|---|
id | integer | Unique ID (pass as scheduled_conference to action dial). |
state | integer | Scheduled conference state. |
name | string | Display name. |
start_time | integer | Conference start time, as UNIX time (may be in the past). |
end_time | integer | Conference end time, as UNIX time. |
Scheduled conference states are as follows:
Schedule conference state | Description | |
---|---|---|
1 | NORMAL | The conference has been created, but is not in any of the other states. |
2 | SOON | The conference can now be called and joined. For example, on the StarLeaf touchscreen controller, the Join Now button displays green. |
3 | NOW |
The conference start time has been reached. For example, on the StarLeaf touchscreen controller, the Join Now button flashes green. On the StarLeaf Phone 2120 and StarLeaf Touch 2020, the message indicator light flashes red. The NOW state continues for five minutes from the start of the conference |
4 | NOW QUIET | The conference has not reached its end time. For example, on the StarLeaf touchscreen controller, the Join Now button displays green, but does not flash. |
Endpoint
The endpoint section details miscellaneous endpoint state.
Parameter | Data type | Description |
---|---|---|
id | integer | Endpoint ID. |
dnd | boolean | Whether Do-Not-Disturb is enabled. |
forwarding_availability |
integer |
Forwarding availability states are listed below. |
forwarding_state | integer | Forwarding states are listed below. |
forwarding_number | string | Number or URI forwarded to. |
missed_calls | integer |
Number of missed calls (cleared when recent calls are opened). |
message_count | integer | Number of messages that have not been listened to. |
standby | boolean | Whether the endpoint is currently in standby. This field is only present where a touchscreen controller is connected to a PT Monitor, PT Mini codec, or a room system codec such as Group Telepresence 3330 or 3351. |
serial | string | The serial number of the touchscreen controller. |
Forwarding availability value is a bitmask of the following (for example, 3 means that calls could be forwarded to either a mobile number or to another number):
Forwarding number | Description | |
---|---|---|
0 | NONE | Calls cannot be forwarded. |
1 | MOBILE | Calls can be forwarded to a mobile number. |
2 | NUMBER | Calls can be forwarded to another number. |
Forwarding state values are as follows:
Forwarding state | Description | |
---|---|---|
0 | OFF | Calls are not forwarded. |
1 | VOICEMAIL | Calls are forwarded to voicemail. |
2 | MOBILE | Calls are forwarded to a mobile number. |
3 | NUMBER | Calls are forwarded to another number. |
Audio
The audio section details mute state and volume levels.
Parameter | Data type | Description |
---|---|---|
mute | boolean | Whether audio mute is enabled. |
ringer_volume | integer | Volume of the ringer. |
adjunct_volume | integer |
Volume of the adjunct processing audio. |
incall_volume | integer |
Volume of the HDMI or line-out audio. This is the volume of whichever audio device is in-use for the call. |
can_toggle_mute | boolean | Whether using the action “audio_mute” will currently work. |
Video
The video section details mute state, the state of PC sharing, and video settings.
Parameter | Data type | Description |
---|---|---|
mute | boolean | Whether video mute is enabled. |
power_line_frequency | integer | Configured power line frequency, in Hz (50 or 60). |
screens | integer | Number of screens attached. |
pc_status | integer | PC input status (see below). |
active_camera | integer | Index of the currently-active camera. |
cameras | array | Array of objects each describing the state of each camera input. |
status | integer | Camera input status (see below). |
pc_share_status | integer | PC sharing status (see below). |
self_view | integer | Self_view display mode status (see below). |
conf_layout | string | Name of the current conference layout. |
active | boolean | Whether the current camera preset is active. |
name | string | Name of the current camera preset. |
Video preset status is as follows:
Parameter | Data type | Description |
---|---|---|
active | boolean | Status of the current camera preset |
name | string | Name of the current camera preset |
PC or camera input status is as follows:
Input status | Description | |
---|---|---|
0 | DISCONNECTED | Nothing is connected to the input |
1 | ACTIVE | Input is connected, active and working. |
2 | ASLEEP | Input is connected, but the source device is asleep or otherwise inactive. |
3 | INVALID | Input is connected and active, but the video mode being used could not be determined or is not supported. |
Self-view display mode status is as follows:
Input status | Description | |
---|---|---|
0 | AUTO | Self view is set to automatic mode. |
1 | ALWAYS OFF | Self view is set to always off. |
2 | ALWAYS ON | Self view is set to always on. |
PC sharing status is as follows:
Sharing status | Description | |
---|---|---|
0 | PC_SHARE_STATUS_NONE | There is no shared PC. |
1 | PC_SHARE_STATUS_LOCAL | A PC is shared at the local end of the call. |
2 | PC_SHARE_STATUS_REMOTE | A PC is shared from the remote end of the call |
Favorites
The favorites section details calling and presence details of the first few favorite contacts.
Parameter | Data type | Description |
---|---|---|
id | integer | Favorite ID (pass as favorite to action dial). |
display_name | string | Display name. |
type | integer | Number type (see Contacts, under contact number types). |
number | string | Number (or URI). |
presence | integer | API presence state. |
The presence states for favorites is as follows:
Presence state | Description | |
---|---|---|
0 | UNKNOWN | Presence state is unknown. |
1 | AVAILABLE | The favorite is available. |
2 | IN CALL | The favorite is currently in a call. |
3 | DO NOT DISTURB | The favorite has set presence to do not disturb. |
4 | CALLS FORWARDED | The favorite has forwarded calls. |
5 | NOT AVAILABLE | The favorite is offline, or the endpoint is not connected. |
6 | MOBILE | The favorite is a signed in iPad user who is not currently looking at StarLeaf. This user can receive notifications of incoming calls and conferences. |
Locale
The locale section contains the current localization settings.
Parameter | Data type | Description |
---|---|---|
lang | string | Language setting, as IETF language tag. |
Network
The network section contains the current IP address and routing settings.
Parameter | Data type | Description |
---|---|---|
ip | string |
IPv4 address of the endpoint. |
hostname | string | Hostname of the endpoint. |
netmask | string | Netmask of the local IPv4 subnet. |
gateway | string | Default gateway for IPv4. |
nameserver | string | IPv4 address of the DNS server. |
Immediate and delayed state requests
There are two types of state request:
- State requests that always return immediately with the current state.
- State requests that delay feedback until the state changes from a particular point in time.
In the response to any state request, within each state section, a counter field can be found. The counter is an integer value, which identifies that particular state snapshot. The counter is incremented whenever any change to the state occurs (Note. there is no maximum value for the counter and it does not return to zero).
If you include this counter in a subsequent state request, the codec only returns the state response when the counter has changed. (HTTP:
Note that state can be returned as if changed without any differences being visible in the response (for example the state may change from A to B and back to A), and that some state differences do not result in a response being pushed (for example, the call timer). Additionally, every section has a local counter for that section (the field counter inside that section object), which is incremented when something in that section changes. There is no way for it to be waited-for directly, but it can be used to determine whether any detail in that section has changed between consecutive requests.
Examples:
1. Without the counter field, you immediately receive the response.
For example, request:
{"id":1,"request":{"action":"state","filter":"endpoint"}}
The response is:
{"id":1,"response":{"counter":33170,"endpoint":{"counter":54,"id":406,
"serial":"SLP1409040","dnd":false,"forwarding_availability"
:2,"forwarding_state":0,"missed_calls":0,"message_count"
:0,"standby":true}}}
2. You can use this feature to wait for an incoming call without repeatedly polling the server.
For example, request:
{"id":2,"request":{"action":"state","filter":"calls","counter":33170}}
There may be no immediate response at this point, but when an incoming call arrives, the response is:
{"id":2,"response":{"counter":33173,"calls":{"counter":95,"list":
[{"id":644,"state":3,"call_time":0,"start_time":0,"participants"
:[{"id":643,"state":2,"name":"John Smith","number":"john.smith
@starleaf.com"}]}]}}}
Requesters
Any state request can specify a requester name with the additional string argument requester. When this is made, all previous outstanding requests from the same requester are canceled and return immediately (with an error message). The intent of this feature is to allow purging of old requests from devices that know they will only ever have one outstanding state request but could be restarted for whatever reason.
If requester is not specified, then multiple outstanding requests are allowed. There is a global limit on the total number of state requests (both anonymous and named) against any API instance (currently 32) – if this is exceeded, the oldest request (the one made earliest in time) is canceled and returns an error message to the user.