Protocol Call

Any given agent can only use the call interfaces on calls directly under the agents control, ie. it is not possible to hangup a call initiated by another agent. If an agent tries to interfere with calls she is not allowed to interfere with, a HTTP 403 Forbidden and a status JSON document is returned:

{
    "status" : "forbidden",
    "description" : "Call|<call_id> belongs to <agent_id>"
}

Call object

The prototype object for a call object will more-or-less, look something like this:

{
    "id": "86c83e07-f020-4c06-9e80-8e9f296fbfe3",
    "state": "queued",
    "b_leg": "<null>",
    "inbound": true,
    "destination": "5900",
    "caller_id": "1001",
    "assigned_to": null,
    "channel": "86c83e07-f020-4c06-9e80-8e9f296fbfe3",
    "organization_id": 1,
    "arrival_time": "1387566878"
}

Interfaces

• Hangup
• List
• Originate
• Park
• Pickup
• Queue
• Transfer

Transfer

GET /call/transfer?source=<call_id>

Bridge (connect) two calls. Implements the transfer functionality. The transfer request connects the currently active call with the call specified in source. When two calls are bridged successfully, the agent channels closes, and the agent is ready to answer a new call. By convention, the transfer can only be completed if the current call held by the agent is outbound.

Condition: Success. Two calls successfully bridged.

HTTP 200 OK

{
    "status" : "success",
    "source_call": {
        "call_id" : 1235,
        "status" : "bridged",
        "type"   : "cm_id",
        "callee" : 4200
    }
    "destination_call": {
        "call_id" : 1234,
        "status" : "bridged",
        "type"   : "cm_id",
        "callee" : 42
    }
}

Condition: Error. The bridge failed.

HTTP 400 Bad Request

{
    "status" : "bridge failed",
    "description" : "Cannot transfer to an inbound call." | "Destination hung up before process could complete | Bad destination | Call on hold hung up | ...."
}

Park

POST /call/park

Put the current call onhold.

Condition: Success. The call is put onhold.

HTTP 200 OK

{
 "status" : "on hold",
 "description" : "<call_id> was put on hold"
}

Condition: Error. No call to put on hold.

HTTP 404 Bad Request

{
 "status" : "not found",
 "description" : "No call available to put on hold"
}

Status

/call/state?call_id=<call_id>

Determine the state of a call.

Condition: Success. The call exists and status is returned.

{
    "call": {
        "call_id" : 1234,
        "status" : "answered",
        "type"   : "cm_id",
        "callee" : 42
    }
}

Condition: Error. <call_id> does not exist.

HTTP 404 Not Found

{
    "status": "not found",
    "description": "<call_id> does not exist."
}