PHP Voice Quickstart

Hello, World of IVR

In this Voice Quickstart Tutorial, we'll walk you through building a basic sample application in PHP that responds to inbound calls and plays a message to the caller. In other words, we're creating the "Hello, World" of IVR applications. We'll go through the following steps:

1. Sign up for a free trial account with FreeClimb
2. Create an application in your account
3. Configure a FreeClimb number to accept a call
4. Ensure your development machine is ready
5. Install the FreeClimb PHP SDK
6. Write the PHP code to play a message
7. Expose your local web server to the internet with ngrok
8. Connect your application's URL to FreeClimb
9. Test your application by making a call

The whole process should take less than 30 minutes, and our support team will be happy to help if you run into challenges. Let's go!

Sign up for a free trial account with FreeClimb

Go to the FreeClimb account creation page to sign up for an account. You can also sign up using your existing GitHub account credentials.

When you sign up, you'll be prompted to add a verified number. While you're using your free trial account, you'll only be able to make outbound calls to numbers you add as verified numbers. Enter the phone number (US only) of a device you'll be able to access easily while you're working with FreeClimb. You’ll receive a confirmation code by SMS to your device. Enter it in the dashboard, and you'll be ready to move on to the next step.

Create an application in your account

Once you're logged in, you'll be directed to your FreeClimb dashboard. From your dashboard, you can manage your account, add applications, configure phone settings, and review logs. First, we’re going to look at the Applications panel, which you can find in the left sidebar.

FreeClimb applications are the interface between your code and the FreeClimb backend, which handles the transmission of data between the internet and telephone networks. FreeClimb will connect your App ID to a FreeClimb telephone number, so that it can correctly direct incoming and outgoing voice data.

You'll see a list of existing FreeClimb apps in your Applications panel. New trial accounts come with a pre-configured app called "My FreeClimb Application" - use this application or create a new one by clicking on Register New App and entering an alias for it. Each application will have a unique App ID. Keep your App ID handy, either in your browser or on your clipboard. For now, you don't need to enter any URLs into the configuration.

Configure a FreeClimb number to accept a call

FreeClimb numbers are regular phone numbers that you can dial from any mobile or landline phone. When a call is received, FreeClimb picks it up for you and forwards it to an application.

In your FreeClimb dashboard, click on Manage Numbers in the left sidebar to see a list of the numbers you have in your account. You also see their associations with applications. New trial accounts already come with a phone number. You can use that number for the tutorial. If the number is not assigned to the correct application, click the View button next to it, change the "App" drop-down and click Update to confirm.

After completing this tutorial, you can choose a different number when you upgrade your account. For testing purposes, we’ll use the randomly assigned number and your verified outbound number.

First, let’s make sure you’re ready to use PHP from your development environment.

Ensure your development machine is ready

Double-check that your machine has the following prerequisites installed:

• PHP version 7.2 or higher
• Composer

To check your PHP version, open a command prompt and enter:

php -v

If the output shows an older version of PHP or "command not found", you need to fix or upgrade your PHP installation. You can get the latest version for your operating system on the PHP website.
Next, to check that you have Composer installed, enter:

composer -v

You should see a list of Composer commands. Again, if you're seeing "command not found", follow the installation instructions on the Composer website.

Install the FreeClimb PHP SDK

Composer manages dependencies per project. Create a new, empty directory on your computer where you want to store the project. Open a command prompt inside that directory and enter the following command:

composer require freeclimbapi/php-sdk

Composer will warn you if there's any problem with the installation, such as an unmet dependency. If there are no warnings or errors in your console, you're done and have successfully installed the SDK.

Write the PHP code to play a message

In your newly created project directory, create a file named hello.php. Start the file by including Composer's autoload.php, which provides access to the FreeClimb SDK (and all other dependencies):

<?php

require_once __DIR__."/vendor/autoload.php";

The FreeClimb SDK includes support for Performance Command Language, or PerCL scripts. The client-side application in a FreeClimb application is the FreeClimb platform, which handles a different data format than a typical web application. PerCL is a scripting language that converts between JSON-formatted data and audio recordings, and gives the commands to transmit that data back and forth between web applications and the telephone network.

The first step for us to start working with PerCL in our application is to create an instance of the PerclScript class:

$response = new FreeClimb\Api\Model\PerclScript;

A PerCL script is a sequence of commands that control interactions with the call and enable building powerful IVR scenarios. For this QuickStart, we'll use only one: the "Say" command. It instructs the platform to play back a string using text-to-speech (TTS) technology. You need to create the command, set the text to read, and then add it to your response:

$say = new FreeClimb\Api\Model\Say;
$say->setText("Welcome to the FreeClimb SDK!");

$response->addCommand($say);

Great, that's the whole PerCL script we need for a "Hello World" sample. The only thing left is to send the response. As PerCL uses JSON, we set the appropriate Content-Type header for JSON before "echo"-ing our PerCL script:

header("Content-Type: application/json");
echo $response->toPerCLString();

Expose your local web server to the internet with ngrok

FreeClimb requires a public web address to your application. For test projects, you can connect your local machine to a public address using ngrok, a command-line tool to route traffic.

First, start a web server in your project directory with the following command:

php -S 0.0.0.0:8080

The command starts the webserver on port 8080. If that port is blocked or unavailable for any reason, you can try another port number. In that case, make sure to replace 8080 with your custom port throughout this guide.

When your webserver is running, you can go to http://localhost:8080/hello.php in your browser to access the application and see your PerCL script. There's one caveat, though: you're the only one who can access your local web server. The best way to let others on the internet, like the FreeClimb platform (which is obviously outside your local network), access your computer are tunneling services like ngrok. With ngrok, you get a public, shareable URL to your local machine.

Go to the ngrok website and download the tool. You can optionally sign up for a free account to unlock additional functionality, but you should be good to go for this Quickstart even without an account.

To start ngrok and open a tunnel to your HTTP server on port 8080, run the following command:

ngrok http 8080

After establishing the forwarding tunnel, ngrok shows you the public URL in its console output; it typically ends with .ngrok.io. Select and copy that URL, as you'll need it in the next step.

Connect your application's URL to FreeClimb

Go back to your FreeClimb dashboard and click on Applications. Then, go to Edit Config next to the application you assigned to your FreeClimb number.

You only need to fill in the "Voice URL". All other fields can be left blank. Your voice URL is that ngrok forward URL suffixed by the PHP file which contains your application. Combined, your URL should look similar to https://tunnel-id.ngrok.io/hello.php. Save your changes with the Update button.

Congratulations, your application is ready for testing!

📘

How FreeClimb answers voice calls

1. An external call comes in to a registered FreeClimb number.
2. FreeClimb knows the Application associated with that number.
3. FreeClimb makes a POST request to the voiceURL in that App’s configuration.
4. The Application responds with a PerCL script to play a message to the caller.
5. FreeClimb processes the PerCL and plays the message to the caller.

Test your application

To test your application, take your phone and dial your FreeClimb number. Keep your console window where ngrok is running open, and you should see the incoming request.

Your application works if you can hear "Welcome to the FreeClimb SDK!" over the phone. Excellent, you've done it! Feel free to explore our documentation and extend your application.

If you couldn't hear the output but can see the incoming request in the console, there's likely a problem with your PHP implementation. Please double-check your code.

If you couldn't hear the output and you can't even see the incoming request in the console, your configuration on the FreeClimb dashboard isn't accurate. Please double-check that the URL is the correct one and the proper application is associated with the number.

To confirm your requests, you can review the logs within the FreeClimb dashboard.

Reach out to our support if you need additional help in getting the tutorial to work. We’ll be happy to answer your questions.

Explore the possibilities with FreeClimb

FreeClimb apps can be upgraded with a wide range of functionality. A few pointers to help you explore from here:

• FreeClimb meets industry standards for handling sensitive user data, including HIPAA.
• FreeClimb also enables outbound calling, SMS functionality, and conferencing to connect multiple live callers, and we have guides and sample applications covering many use cases.

FreeClimb is highly scalable and reliable, and is built on a proven platform. While setting up a simple voice application is straightforward, it is the first step towards building an application that can reliably handle large volumes of telephone calls and increasingly complex business logic for managing those calls.