To examine the state of the Teamline system, request the path /ecapi/state. This returns a JSON object containing one or more subobjects corresponding to each section requested.
Sections
Specific sections can be requested using the filter parameter. This takes a comma-separated list of section names to examine or the special value all, which requests all sections. If filter is not provided, a default set of sections is returned (not necessarily all.)
Some examples:
- state fetches default state sections (time, locale, network, endpoint, line, calls, scheduled conferences, audio, video)
- state?filter=line,calls fetches the state sections line and calls
- state?filter=all fetches all state sections
- state?filter=all&pretty fetches all state sections, and prints a more readable output (pretty-print)
Version
The version section returns version information about the Teamline system.
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 or not daylight savings time is currently in effect |
day_of_week | integer |
Day of week (Sunday as 0 to Saturday as 6) |
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 |
uri | string | Global URI |
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 |
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 off-hook 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 |
Scheduled meetings
The scheduled_conferences section contains details of current and future scheduled meetings. 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 meeting state |
name | string | Display name |
start_time | integer | Meeting start time, as UNIX time (may be in the past) |
end_time | integer | Meeting end time, as UNIX time |
Scheduled meeting states are as follows:
Schedule conference state | Description | |
---|---|---|
1 | NORMAL | The meeting has been created, but is not in any of the other states |
2 | SOON | The meeting can now be called and joined. On the touchscreen controller, the Join Now tile is displayed |
3 | NOW |
The meeting start time has been reached. On the touchscreen controller, the Join Now tile is displayed. The NOW state continues for five minutes from the start of the meeting |
4 | NOW QUIET | The meeting has not reached its end time. On the touchscreen controller, the Join Now tile is displayed |
Endpoint
The endpoint section details miscellaneous endpoint states.
Parameter | Data type | Description |
---|---|---|
id | integer | Endpoint ID |
missed_calls | integer |
Number of missed calls (cleared when the recent calls list is opened) |
tv_standby | boolean | Whether or not the system is in screen standby mode and not sending any video to the connected display. This is either because the Maestro setting for Display Standby Timeout is enabled or the tv_standby API action has been used |
standby | boolean | Whether or not the room camera is the privacy position and the microphone is muted (that is, in standby mode.) This is either because the Maestro setting for AV Standby Timeout is enabled or the standby API action has been used |
serial | string | The serial number of the Touch |
Audio
The audio section details mute state and volume levels.
Parameter | Data type | Description |
---|---|---|
mute | boolean | Whether or not audio mute is enabled |
ringer_volume | integer | Volume of the ringer |
incall_volume | integer |
Volume of the HDMI or line-out audio. This is the volume of the audio device used for the call |
Video
The video section details mute state, the state of PC sharing, and video settings.
Parameter | Data type | Description |
---|---|---|
mute | boolean | Whether or not video mute is enabled |
power_line_frequency | integer | Configured power line frequency, in Hz (50 or 60) |
screens | integer | Number of displays attached |
pc_status | integer | PC input status |
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 |
pc_share_status | integer | PC sharing status |
self_view | integer | Self-view display mode status |
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 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 |
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 system |
hostname | string | Hostname of the system |
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 when any change to the state occurs. 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 system only returns the state response when the counter has changed. The HTTP connection is held open until a relevant change occurs, then the whole state as requested is returned.
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. It cannot be waited for directly, but it can be used to determine whether or not 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.) This feature allows you to purge old requests from devices that will only ever have one outstanding state request, but could be restarted.
If requester is not specified, multiple outstanding requests are allowed. The global limit on the total number of state requests (both anonymous and named) against any API instance is 32. If this is exceeded, the oldest request (the request made first) is canceled and returns an error message to the user.