How FreeClimb Works

What you can do with FreeClimb

FreeClimb is a cloud-based application programming interface (API) that puts the power of Vail's platform in your hands. FreeClimb simplifies the process of creating applications that can use a full range of telephony features without requiring specialized or on-site telephony equipment. FreeClimb gives application developers access to features including:

How FreeClimb reaches your web server

FreeClimb uses HTTP requests and webhooks to communicate with your web server application. FreeClimb relies on 2 resources to communicate with your application: Incoming Numbers and Applications.

Incoming Numbers

Incoming Numbers represent phone numbers and connect users to your applications. You can use an Incoming Number to make and receive calls or send and receive messages. Learn more about the Incoming Numbers API and how to Buy and Configure a FreeClimb Number in the FreeClimb dashboard.

Applications

To FreeClimb, an Application is simply a set of configuration data. You can configure the following data on an Application:

Webhook	Description
voiceUrl	URL that FreeClimb will request when an inbound call arrives on a phone number assigned to this Application.
voiceFallbackUrl	URL that FreeClimb will request if it times out waiting for a response from the voiceUrl.
smsUrl	URL that FreeClimb will request when a phone number assigned to this Application receives an incoming SMS message.
smsFallbackUrl	URL that FreeClimb will request if it times out waiting for a response from the smsUrl.
callConnectUrl	URL that FreeClimb will request when an outbound call request is complete.
statusCallbackUrl	URL that FreeClimb will request to pass call status (such as call ended) to the application.

When a call or message lands on the platform for one of your Numbers, these URLs work as the initial link between FreeClimb and your web server. Learn more about how to Register and Configure an Application.

Connecting Numbers to Applications

Assigning your Number to an Application means that when a call or message comes through to that phone number, FreeClimb can use the Application's configuration data for instructions on what to do.

For all of this to work, your webhooks need to be configured with publicly available URLs.

How your web server interacts with FreeClimb

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

Actions using the Performance Command Language (PerCL) that are in response to external events
Application-initiated actions using the RESTful API

API actions happen through HTTP requests to FreeClimb endpoints. When an external event happens, like a call or message coming in, FreeClimb will make a POST request to one of your Application's webhooks. Some of these POST requests expect a set of instructions in the response, like what to do with the call, and that's where PerCL comes in. PerCL is a scripting language that FreeClimb developers can use to control events within the context of a call.

Let's look at a couple of examples to see how it all comes together.

Incoming voice call

1600 — Using PerCL to respond to an external event

A call for your Incoming Number lands on the platform.
FreeClimb looks for an Application associated with the phone number.
FreeClimb makes a POST request to the voiceUrl of the Application.
Your web server returns a PerCL script with instructions for how FreeClimb should handle the call.
FreeClimb processes the instructions, and takes some action on the call (for example, playing audio to the caller).

Outgoing SMS

Your web server makes a POST request to the FreeClimb /Messages endpoint containing the details of the message (the text of the message, the number it's going to, and the FreeClimb number it's coming from) and the URL of a notificationUrl.
FreeClimb sends your message.
FreeClimb makes a POST request to the notificationUrl you provided with status updates about your message.

What's next

Now that you've got an idea of how FreeClimb works, you're ready to start building. A great place to start is the Voice Quickstart or SMS Quickstart. If you're ready for something more complex, we also offer voice and SMS tutorials as well as sample apps.