Applications

An Application object defines the behaviors for incoming calls to the Sift VOIP API. Each Application encapsulates a callback URL, which will be requested when a new connection is initiated to allow you to control what actions should be taken.

See the guide on setting up Application objects for an example.

The Application Object

Property	Type	Description
app_id	string	Unique ID of the application.
name	string	Short, human readable name for the application.
on_incoming	string	URL which will receive Incoming Connection Callback requests when a phone number bound to this application receives a call, or when a VOIP client bound to this application makes an
default_routine	list	The default routine for incoming calls. Only used if on_incoming is not defined.
script	string	The URL of the hosted script.
phone_numbers	list	A list of phone number strings.

Example

{
    "app_id": "3bb34721cbe2e221",
    "name": "Menu System",
    "on_incoming": "http://myserver.com/menu"
}

Incoming Connection Callback

Each Application may define an on_incoming URL. Sift will send an HTTP POST request to this URL whenever the Application receives a new call.

Request

method:POST content-type:application/json

The request body is a JSON object with the following properties.

Property	Type	Description
account_id	string	ID of the account associated with the Application.
connection	object	The Connection object for the new inbound call.

Example

{
    "account_id": "573e49212d2c62e6",
    "connection": {
        "connection_id": "1994a0ee21b612ee",
        "status": "connected",
        "start_time": "2016-05-06T08:22:22Z",
        "end_time": "2016-05-06T09:22:22Z",
        "from": "+15554443333",
        "to": "+15553322121",
        "direction": "incoming"
    }
}

Reply

The reply should contain a JSON object with the following properties:

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

List Applications

Retrieve a list of Application objects associated with your account.

Request

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

Response

content-type:application/json

The response body contains a JSON object representing a paginated list of Application objects. 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 Application objects.

Example

{
    "previous": null,
    "next": "https://api.gridspace.com/v0/applications?cursor=cE0yMDE2LTA1LTE5KzAxJTNBNDklM0E1MS4xODQ5NjElMkIwMCUzQTAw",
    "results": [
        {
            "app_id": "25fb5f2e6c8fc279",
            "name": "Call Jenny",
            "routine": [
                {
                    "name": "CallPhone",
                    "phone_number": "+15558675309"
                }
            ]
        },
        {
            "app_id": "6de97c5858f56f9f",
            "name": "Tech Support",
            "on_incoming": "http://mysite.com/ontechsupportcall"
        }
        ...
    ]
}

Retrieve an Application

Retrieve a single Application by id.

Request

url:https://api.gridspace.com/v0/applications/:application_id method:GET

Response

Returns a single Application object in JSON format.

Example

{
    "app_id": "6de97c5858f56f9f",
    "name": "Tech Support",
    "on_incoming": "http://mysite.com/ontechsupportcall"
}

Update an Application

Update a single existing Application by id. The application ID is provided in the URL and any fields to be updated are in the JSON of the request body. The application ID cannot be changed.

Request

url:https://api.gridspace.com/v0/applications/:application_id method:POST

Example

{
    "name": "New Name",
    "on_incoming": "http://mysite.com/newcallback"
}

Response

Returns a single Application object in JSON format.

Example

{
    "app_id": "6de97c5858f56f9f",
    "name": "New Name",
    "on_incoming": "http://mysite.com/newcallback"
}

Create an Application

Create a new Application object. See the guide on setting up Application objects for an example.

Request

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

The request body should contain a JSON object with the following properties:

Property	Type	Description
Required Properties
name	string	Human readable short name for the Application.
Optional Properties
on_incoming	string	URL which will receive Incoming Connection Callback requests when a phone number or VOIP client bound to this application receives a call.
default_routine	list	Default list of commands to perform on new inbound connections if on_incoming is not provided. Must be present if on_incoming is omitted.

Response

Returns a JSON object containing the app_id of the created Application.

Example

{
    "app_id": "6de97c5858f56f9f",
}