Understanding Applications

FreeClimb applications

An application is a set of URLs, along with configuration data, that uses FreeClimb’s RESTful API or Performance Command Language (PerCL) to tell FreeClimb what to do. The Applications resource represents all of the applications registered with a single FreeClimb account.

How applications work

FreeClimb maintains constant interaction with your client applications using HTTP. From the perspective of the client application, FreeClimb looks like a browser when it makes requests.

There are 2 modes of operation on FreeClimb's platform:

1. Application-initiated actions using the RESTful API
2. Actions using PerCL that are in response to external events

Application-initiated actions using the RESTful API

The client application (or the end user) can explicitly initiate an action, such as issuing an HTTP request using a command-line interface. FreeClimb authenticates the request using basic authentication over HTTPS before processing the request.

If a synchronous request is made, then FreeClimb fully processes the request and returns a response to the client application. If the request is asynchronous, it is added to a job queue and FreeClimb will return a response code. Potential response codes include:

• 202 ACCEPTED (FreeClimb was able to add the request to the job queue)
• 500 INTERNAL SERVER ERROR (FreeClimb was unable to add the request to the job queue)

The status codes indicate whether FreeClimb has acknowledged the request, but do not indicate that FreeClimb completed the task.

The FreeClimb dashboard is an example of an application using the RESTful API to initiate actions using FreeClimb's platform. The features correspond to REST API counterparts. This means that the sequence of actions a customer takes to purchase an incoming phone number via the dashboard results in the same under the hood behavior as the sequence of actions required when making HTTP POST calls to the API’s Available numbers resource to provision an incoming phone number.

See the RESTful API reference documentation for more details on communicating with FreeClimb via API.

Actions using PerCL in response to external events

FreeClimb can respond to external events that were not triggered by the client application or the end user. FreeClimb’s responses are sent to the client application using the HTTP protocol in the form of a POST request.

The client application, in response to FreeClimb’s request, can provide a response that contains the call control logic written as commands. These commands use the Performance Command Language (PerCL).

FreeClimb defines the execution points during the call. These execution points include, but aren't limited to:

• Inbound call received from the Public Switched Telephone Network (PSTN)
• End of digit collection from the caller
• Completion of message recording

For these events, FreeClimb describes the data that is included in the HTTP POST request to the client.

For information on using Performance Command Language commands to communicate with FreeClimb, see the PerCL Overview.

Standard HTTP requests to a FreeClimb application

FreeClimb makes a synchronous HTTP Request to a FreeClimb application whenever an event, like receiving a call, occurs.

The application profile, RESTful API requests, and PerCL commands all contain URLs that communicate to FreeClimb where specific requests should be sent.

Application URLs can use either the HTTP or HTTPS protocols, but the request from FreeClimb to the application always uses the HTTP POST method.

The data that FreeClimb provides to the client application in the request includes the following standard request parameters that appear in the message body.