State

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.

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.)

Line

The line section contains details about the current line.

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:

Updates are pushed on changes to everything except the call_time field.

Each participant object has fields:

Basic call states are as follows:

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:

Scheduled meeting states are as follows:

Endpoint

The endpoint section details miscellaneous endpoint states.

Audio

The audio section details mute state and volume levels.

Video

The video section details mute state, the state of PC sharing, and video settings.

PC or camera input status is as follows:

Self-view display mode status is as follows:

PC sharing status is as follows:

Locale

The locale section contains the current localization settings.

Network

The network section contains the current IP address and routing settings.

Immediate and delayed state requests

There are two types of state request:

1. State requests that always return immediately with the current state.
2. 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.