03.0 Check State

Owned by PeterF (Deactivated)
Sept 06, 2016
7 min read

DEPRECATED: use the new 05.0 Subscribe method

Check the current state of a call. This method is typically used to track the progress of a call after having initiated the call using the dial method.

All responses include:

  • Code - a numeric status code - 0 for sucess, non-zero for error conditions
  • Message - a clarification messages, most common for error conditions
  • State - a collection of extension state resources.
    Each item in the collection is mapped to the relevant extension number.
    Each state resource has a code and a message.
    The code is zero for sucess and non-zero for error conditions.
    For successful calls the message is a call state, one of:
  • Ringing Agent
  • Ringing Client
  • On Call
  • Hung Up
  • On Hold
    NOTE: To receive On Hold events for SIP channels "callevents = yes" must be set in sip.conf.

Entry point:

http://<server host>/servicemanager/rest/CallManagementAPI/checkState

Parameters:

extenOrUniqueId - a comma separated list of internal or agent extensions.
timeOut - the poll timeout in seconds (default is 10 if this parameter is omitted)
timeStamp - the authentication timestamp.
hash - the authentication signature or hash.

UniqueID:

To facilitate synchronisation with 05.0 Subscribe calls, the checkState response includes the call unique ID. The uniqueCallId property in the checkState response (see below) matches the uniqueCallId in the subscribe response.

{"State":
  {"102":
    {"uniqueCallId":"1412221587.51",
     "Message":"Ringing Client",
     "Code":0},
   "101":
    {"Code":0}},
  "Code":0}
{"State":
  {"102":
    {"uniqueCallId":"1412221590.52",
     "Message":"On Call",
     "Code":0},
    "101":
     {"Code":0}},
   "Code":0}
{"State":
  {"102":
    {"uniqueCallId":"1412221587.51",
     "Message":"Hung Up",
     "Code":0},
   "101":
    {"Code":0}},
  "Code":0}

Timeouts:

There are conditions that may cause the system to timeout while waiting for status updates. When these timeouts occur the server will respond with status updates however those statuses may not be accurate. When timeouts occur the server will add a warning message in the response to this effect. Example:

{"State":
  {"115":
    {"Message":"Session automatically created by checkState","Code":0},
   "101":
    {"Message":"Session automatically created by checkState","Code":0},
   "100":
    {"Message":"Session automatically created by checkState","Code":0}},
  "Message":"WARNING: Timeout while waiting for status updates. Results may be incomplete.","Code":1}

Notice the "WARNING:" message. If these warnings are persistent the server must be configured with an extended timeout period to ensure accurate status is returned. Notice also that that response code is "1" - indicating a warning.

 

Sample Scenarios

In these scenarios three extensions are monitored (100, 101 and 115).

Scenario 1

A simple internal call from one extension to another. Ext 100 dials 101.

1. Ext 100 is Ringing Agent, i.e. ext 100 is ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Agent","Code":0}},
  "Code":0}

2. Ext 100 is Ringing Client, i.e. the agent has answered ext 100 and ext 101 is now ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Client","Code":0}},
  "Code":0}

3. Ext 101 has been answered. Both ext 100 and 101 are now On Call.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"On Call","Code":0},
   "100":
    {"Message":"On Call","Code":0}},
  "Code":0}

4. Ext 101 hung up. Both extensions are now Hung Up.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"Hung Up","Code":0},
   "100":
    {"Message":"Hung Up","Code":0}},
  "Code":0}

5. No further events are found.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}
Scenario 2

An internal call from ext 100 to 101. The call is then blind transferred from ext 101 to ext 115. Ext 115 hangs up.

1. Typical startup sequence - ext 100 is Ringing Agent.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Agent","Code":0}},
  "Code":0}

2. Continued startup sequence with ext 100 Ringing Client. Ext 101 is now ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Client","Code":0}},
  "Code":0}

3. No new events found. Ext 101 is still ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

4. Ext 101 has been answered. Both ext 100 and 101 are now On Call.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"On Call","Code":0},
   "100":
    {"Message":"On Call","Code":0}},
  "Code":0}

5. No new events found. Ext 100 and 101 are still On Call.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

6. Ext 101 has put the call On Hold (in order to transfer)

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"On Hold","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

7. Ext 101 has hung up. No new events on ext 100 so it is still On Call.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"Hung Up","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

8. Ext 100 has gone to Ringing Client state. (The call has been transferred to ext 115. The event does not at this stage identify the ringing extension but the Ringing Client state following from On Call state indicates a transfer)

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Client","Code":0}},
  "Message":"WARNING: Timeout while waiting for status updates. Results may be incomplete.",
  "Code":1}

9. Ext 115 has been answered. Ext 115 and ext 100 are On Call. Notice the WARNING message. This indicates the server timeout configuration must be adjusted. In this particular case the result is known to be accurate however the timeouts can cause inaccurate results.

{"State":
  {"115":
    {"Message":"On Call","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"On Call","Code":0}},
  "Message":"WARNING: Timeout while waiting for status updates. Results may be incomplete.",
  "Code":1}

10. Ext 115 hung up. Both ext 115 and 100 go to Hung Up state.

{"State":
  {"115":
    {"Message":"Hung Up","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Hung Up","Code":0}},
  "Code":0}

11. No new events detected.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}
Scenario 3

An internal call from ext 100 to 101. The call is then blind transferred from ext 101 to ext 115. Ext 115 then does an attended transfer back to 101. Ext 101 then hangs up.

1. Ext 100 is Ringing Agent, i.e. ext 100 is ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Agent","Code":0}},
  "Code":0}

2. Ext 100 is Ringing Client. The agent has answered ext 100 and ext 101 is ringing.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Client","Code":0}},
  "Code":0}

3. Ext 101 has been answered. Both exts 100 and 101 are On Call.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"On Call","Code":0},
   "100":
    {"Message":"On Call","Code":0}},
  "Code":0}

4. Ext 100 and 101 are still on call. No new events have been detected.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

5. Ext 101 is On Hold - preparing to blind transfer to ext 115.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"On Hold","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

6. Ext 101 has now hung up. Ext 100 is still On Call as no new events have e=been reported for that extension.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"Hung Up","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

7. Ext 100 is now Ringing Client. The blind transfer is in progress.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Ringing Client","Code":0}},
  "Code":0}

8. Exts 100 and 115 are now On Call. The blind transfer has been completed.

{"State":
  {"115":
    {"Message":"On Call","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"On Call","Code":0}},
  "Code":0}

9. Ext 115 is On Hold - preparing for an attended transfer to ext 101.

{"State":
  {"115":
    {"Message":"On Hold","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

10. Ext 115 and 101 are now On Call. Ext 115 is discussing the transfer with ext 101. Ext 100 is still On Call.

{"State":
  {"115":
    {"Message":"On Call","Code":0},
   "101":
    {"Message":"On Call","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

11. Ext 115 hangs up. Exts 100 and 101 are still On Call. The transfer has been completed.

{"State":
  {"115":
    {"Message":"Hung Up","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

12. Ext 101 is now Hung Up.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"Hung Up","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}

13. Ext 100 is now Hung Up. The call has been completed.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"Hung Up","Code":0}},
  "Code":0}

14. No new events have been detected.

{"State":
  {"115":
    {"Message":"No events found","Code":0},
   "101":
    {"Message":"No events found","Code":0},
   "100":
    {"Message":"No events found","Code":0}},
  "Code":0}