Response body

All response bodies contain text of type application/json encoded in UTF-8. For requests with nontrivial responses, this is a JSON object encoding the requested detail. For requests that do not require a response (most actions), this is the single element null. If the request was not successful, the JSON in the body is usually an object containing the two fields error_code and error_message. Some fundamental errors (malformed requests, for example) have an empty response body.

The response also echoes all elements of the request that are not otherwise used. This can be used to distinguish different requests or streams of requests that arrive out of order.

HTTP header response codes

If you are connecting over IP, the response header includes one of the following codes:

  • 200 OK—Success.
    Note that this does not necessarily mean that the action was valid and was performed, only that it was not determined to be invalid by the endpoint.
  • 400 Bad Request — Request was malformed in some way.
    Includes problems like POSTing invalid JSON and offering invalid arguments to actions.
  • 405 Method Not Allowed— Unsupported HTTP method. Only GET, HEAD, POST and OPTIONS are allowed.
  • 409 Conflict — The request is not valid in the current state.
    For example, trying to hang up a call when not in a call. This may not be returned in all possible cases, because it has to be determined by the endpoint.
  • 413 Request Entity Too Large— The POST request body was too big. The body is limited to 4096 bytes; no valid request should need this much.
  • 414 Request-URI Too Long— The GET or HEAD query string was too long.
  • 500 Internal Server Error— Request was invalid.
  • 503 Service Unavailable— There are too many outstanding requests against this server.

Example responses using IP connection

For example, if the endpoint receives the request:


{
 "id" : 42,
 "request_example" : "one",
 "request"{
  "action" : "dial",
  "number" : "1234"
 }
}
 

It might send the response:


{
  "id":42,
  "request_example":"one",
  "response":null
}

Which indicates success in that the endpoint has received the request and returned a response. For actions, this is usually returned immediately.

State updates work similarly, though may be returned at some point in future. If the endpoint receives a request like:


{
 "id" : 17,
 "request_example" : "two",
 "request" : {
  "action" : "state",
  "filter" : "calls",
  "counter" : 567
 }
}
 

The endpoint does not send a response until the call state updates. If an incoming call arrives, this is updated and the endpoint sends the response:


{
 "id" : 17,
 "request_example" : "text",
 "response" : {
  "counter" : 578,
  "calls" : {
   "counter" : 91,
   "list" : [{
     "id" : 90123,
     "state" : 3,
     "call_time" : 0,
     "start_time" : 0,
     "participants" : [{
       "id" : 90124,
       "state" : 2,
       "name" : "FooBar",
       "number" : "1234"
      }
     ]
    }
   ]
  }
 }
}
 

 

And an example of a failing request:


{
 "id" : 23,
 "request_example" : "three",
 "response" : {
  "error_code" : 7,
  "error_message" : "Invalid state for action hold: no usable default call for action."
 }
}
 }
 

With response:


{
 "id" : 23,
 "request_example" : "three",
 "response" : {
  "error_code" : 7,
  "error_message" : "Invalid state for action hold: no usable default call for action."
 }
}
 

An example IP-connection session

Below is an example session showing a request on the state of the audio and also switching the audio mute on. The example session shows you how you might use unique IDs per request. You can see that this is useful, because in the example the responses are not in the same order as the requests, but are identifiable by the ID. The example session also shows correct usage of the counter.

Send:{“id”: 1,”request”: {“action”: “state”,”filter”: “audio”}}
Receive: {“id” : 1,”response”: {“counter”: 385,”audio”: {“counter”: 10,”mute”: false,”incall_volume”:0,”ringer_volume”: 5,”adjunct_volume”: 6}} }
Send: {“id” : 2,”request”: {“action”: “state”,”filter”: “audio”,”counter”: 385}}
Send: {“id”: 3,”request”: {“action”: “audio_mute”,”off”: true}}
Receive: {“id”: 3,”response”:null}
Send: {“id”: 4,”request”: {“action”: “audio_mute”}}
Receive: {“id”: 4,”response”: null}
Receive: {“id”: 2,”response”: {“counter”: 394,”audio”: {“counter”: 11,”mute”: true,”incall_volume”: 0,”ringer_volume”: 5,”adjunct_volume”: 6}}