PerCL Overview

The Performance Command Language (PerCL) defines a set of instructions, written in JSON format, that express telephony actions to be performed in response to an event on the FreeClimb platform related to a call. FreeClimb communicates with the application server when events associated with a call for the application occur, so the webserver can instruct FreeClimb how to handle such events using PerCL scripts.

The FreeClimb API reference and PerCL reference define all of the events for which FreeClimb will contact the application when it needs instructions, sending an HTTP request and accepting a PerCL script in response. This is referred to as a Webhook. Examples of such events include:

• An inbound call being received from the Public Switched Telephone Network (PSTN)
• End of digit collection (from the caller)
• Completion of recording

A PerCL script consists of a sequence of commands for that call, and therefore it is represented as an array. Every command in the PerCL script is represented as a JSON object. There can only be one PerCL command in each JSON object.

For example, the Say command needs a string to render, because this contains the input data that the command requires. The language in which the speech is to be rendered can be system default or another specified language — these would the attributes of the command. Attributes generally have default values defined within the system and are typically optional. Inputs, on the other hand, do not have default values — these must _always _be specified.

Example

The following PerCL script tells FreeClimb to say a short message, and then record the caller’s voice for up to one minute:

[
	{
		"Say": {
			"text": "Please leave a brief message after the tone."
		}
	},
	{
		"RecordUtterance": {
			"actionUrl": "http://example.com/recordingComplete",
			"maxLengthSec": 60
		}
	}
]

These PerCL commands are executed sequentially. There are no branching or looping constructs. However, individual commands may consist of _implied _branching or looping actions in how those specific commands are to be executed. Depending on the complexity of a command, we can categorize PerCL commands as follows:

• Simple – The command is atomic and executes by itself. The Enqueue command is an example of a Simple command.
• Compound – The command may contain child commands nested within it. The child commands are executed within the overall context of the parent command, which may affect their behavior. Child commands can be expressed as distinct commands within the parent command. The GetSpeech command is an example of a Compound command. Its prompts property allows including a collection of commands to execute while waiting for speech to be detected.

FreeClimb automatically hangs up a Call when it has reached the end of a PerCL script and there is no other PerCL script to be executed. For example, a PerCL script in response to a callback URL request. At any one time, only one PerCL script is executed within a given Call context. However, many scripts can be linked together via callback URL requests to your server to build complex interactive applications.

Another way to have FreeClimb automatically hang up a call is to not specify a callback URL where one is expected. This can be useful, for example, in having all calls get hung up when a conference terminates -- see the AddToConference command.

Debugging

Unlike a REST API, PerCL cannot return HTTP response codes. Instead, PerCL scripts can be debugged using logs. You can access these logs in your dashboard, or using the Logs API endpoint. For more information about specific error codes, reference the Error and Warning Dictionary.

JSON syntax makes extensive uses of curly braces, square braces, and commas as delimiters with a lot of nesting of these constructs. It is easy to introduce syntactical errors in your JSON PerCL commands by missing things like },{ or ],[ between keys or objects. FreeClimb will detect many of these errors but due the syntax, it may not be able to determine exactly what the application was intending to do and its error messages will be its best attempt to diagnose the problem. If errors logged by FreeClimb suggest a possible formatting issue, using an online JSON formatting tool to examine a PerCL command string may help identify the cause. Entering 'JSON Formatter' into a search engine will show many online tools that can be used to quickly format a JSON string in your web browser to make it easily readable.