Connections

A connection object represents a single media connection between an end user and the Sift service.

For examples of how Connections are created and used, see the guide on making calls.

The Connection object

Property	Type	Description
connection_id	string	Unique string identifier for this connection.
status	string	Current status of the connection. Possible values are connecting, connected, failed, finished.
start_time	string	Time that the connection was established.
end_time	string	If the connection has terminated, the time at which it was terminated. Present only if status is finished.
from	string	String reperesentation of the endpoint that that initiated the connection. May be a phone number or webrtc name.
to	string	String representation of the endpoint that received a call.
direction	string	If the call was initiated by Sift to an external endpoint value is incoming, otherwise value is outgoing.
Optional Properties
client_data	Any	If the connection is an inbound call from a VOIP client, contains any data passed to the connect() function on the client.

Example

{
    "connection_id": "1994a0ee21b612ee",
    "status": "finished",
    "start_time": "2016-05-10T02:28:17Z",
    "end_time": "2016-05-10T05:38:22Z",
    "from": "+15554443333",
    "to": "webrtc:jimmy"
    "direction": "incoming"
    "client_data": {
        "username": "jimmy"
    }
}

List Connections

Retrieve a list of Connection objects associated with your account.

Request

url:https://api.gridspace.com/v0/connections method:GET

Response

content-type:application/json

The response body contains a JSON object representing a paginated list of Connections. See See Paginated Results for more information.

Property	Type	Description
Required Properties
next	string	URL of the next page of results, or null if this is the last page.
previous	string	URL of the previous page of results, or null if this is the first page.
results	list	A list of Connection objects.

Example

{
    "next": "https://api.gridspace.com/v0/connections?cursor=cE0yMDE2LTA1LTE5KzAxJTNBNDklM0E1MS4xODQ5NjElMkIwMCUzQTAw",
    "previous": null,
    "results": [
        {
            "connection_id": "1994a0ee21b612ee",
            "status": "finished",
            "start_time": "2016-05-10T02:28:17Z",
            "end_time": "2016-05-10T05:38:22Z",
            "from": "+15554443333",
            "to": "webrtc:jimmy"
        },
        {
            "connection_id": "bb09c6c4e1b34275",
            "status": "finished",
            "start_time": "2016-05-10T02:28:17Z",
            "end_time": "2016-05-10T05:38:22Z",
            "from": "+15554443333",
            "to": "webrtc:jimmy"
        }
        ...
    ]
}

Retrieve a Connection

Retrieve a single connection object by id

Request

url:https://api.gridspace.com/v0/connections/:connection_id method:GET

Response

Returns a single Connection object in JSON format.

Example

{
    "connection_id": "bb09c6c4e1b34275",
    "status": "finished",
    "start_time": "2016-05-10T02:28:17Z",
    "end_time": "2016-05-10T05:38:22Z",
    "from": "+15554443333",
    "to": "webrtc:jimmy"
}

Create a Connection

Creates a new outbound connection to a client either by phone_number or client_name.

url:https://api.gridspace.com/v0/connections method:POST content-type:application/json

Property	Type	Description
Required Properties
status_url	string	Sift will POST to this URL when the connection is created and anytime the connection’s status changes. The response should contain a routine telling Sift what to do with the connection.
phone_number	string	Phone number to call. One of phone_number and client_name must be provided.
client_name	string	A client identifier. This should be unique among all clients that are using capability tokens generated from the same API account. See the Helper Libraries for details. One of phone_number and client_name must be provided.

Set the routine for a connection

Stop the currently executing routine for a given connection and start a new one.

Request

url:https://api.gridspace.com/v0/connections/:connection_id method:POST content-type:application/json

Property	Type	Description
Required Properties
routine	list	A list of commands to run sequentially on the connection with the given id. It will immediately stop any previously executing routine for that connection id. The structure of the objects in this list is defined in Routines

Example

{
    "routine": [
        {
            "name": "HangUp"
        }
    ]
}

Response

If the request is accepted, the reply will have a status of 200 and an empty body.

In a failure case, the reply JSON describes the error.

Property	Type	Description
error	string	A description of the error.