PerCL

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. FreeClimb communicates with the application server when events associated with the application occur, so the webserver can instruct FreeClimb how to handle such events using PerCL scripts. For further details on PerCL, visit the PerCL Documentation.

PerCL example generation

import freeclimb

say = freeclimb.Say(text="Hello! This is a message sent using FreeClimb's Python SDK.")
return freeclimb.PerCLCommand.to_json(say.to_dict())

The JSON object below represents the PerCL object generated by the commands above.

[
    {
        "Say" : {
            "text" : "Hello! This is a message sent using FreeClimb's Python SDK."
        }
    }
]

AddToConference

The AddToConference command adds a Participant to a Conference. If this Participant currently is in another Conference, the Participant is first removed from that Conference. Two Call legs can be bridged together by creating a Conference and adding both Call legs to it via AddToConference.

Example:

import freeclimb

addToConference = freeclimb.AddToConference(conference_id='CF_your_conference_id', call_id='CA_your_call_id')
return freeclimb.PerCLCommand.to_json(addToConference.to_dict())

Attributes:

CreateConference

The CreateConference command does exactly what its name implies — it creates an unpopulated Conference (one without any Participants). Once created, a Conference remains in FreeClimb until explicitly terminated by a customer. Once a Conference has been terminated, it can no longer be used.

CreateConference is a terminal command (any actions following it are never executed). When the Conference is successfully created, FreeClimb invokes the provided actionUrl using an HTTP POST with a createConference Webhook as the body. After this request, control picks up using the PerCL code received in the response.

Example:

import freeclimb

conference = freeclimb.CreateConference(action_url='http://example.com/action', status_callback_url='http://example.com/status')
return freeclimb.PerCLCommand.to_json(conference.to_dict())

Attributes:

Dequeue

The Dequeue command transfers control of a Call that is in a Queue so that the waiting caller exits the Queue. Execution continues with the first command in the PerCL script returned by the actionUrl specified in the Enqueue command.

Example:

import freeclimb

dequeue = freeclimb.Dequeue()
return freeclimb.PerCLCommand.to_json(dequeue.to_dict())

Attributes:

Dequeue does not support any attributes

Enqueue

The Enqueue command adds the current Call to a call Queue. If the specified Queue does not exist, it is created and then the Call is added to it. The default maximum length of the queue is 100. This can be modified using the REST API.

Example:

import freeclimb

enqueue = freeclimb.Enqueue(queue_id='QU_your_queue_id', wait_url='http://example.com/wait', action_url='http://example.com/action')
return freeclimb.PerCLCommand.to_json(enqueue.to_dict())

Attributes:

GetDigits

Example:

import freeclimb

get_digits = freeclimb.GetDigits(action_url='http://example.com', max_digits=1, min_digits=1, flush_buffer=True)
return freeclimb.PerCLCommand.to_json(get_digits.to_dict())

Attributes:

GetSpeech

The GetSpeech command enables the Caller to respond to the application using a supported language. Unlike DTMF entry, which implicitly restricts the user to using the available buttons on the phone key pad, speech input allows for flexible audio inputs based on grammar. FreeClimb supports grammars written using GRXML compatible with the Microsoft Speech Platform.

Example:

import freeclimb

get_speech = freeclimb.GetSpeech(action_url='http://example.com/action', grammar_type='BUILTIN', grammar_file='VERSAY_YESNO')
return freeclimb.PerCLCommand.to_json(get_speech.to_dict())

Attributes:

Hangup

The Hangup command terminates a Call. If Hangup is used as the first action in a PerCL response, it does not prevent FreeClimb from answering the Call and billing your account. See the Reject command to hang up at no charge.

Example:

import freeclimb

hangup = freeclimb.Hangup()
return freeclimb.PerCLCommand.to_json(hangup.to_dict())

Attributes:

OutDial

The OutDial command is used to call a phone number.

Example:

import freeclimb

outdial = freeclimb.OutDial(action_url='http://example.com/action', call_connect_url='http://example.com/action', calling_number='+1XXXXXXXXXX', destination='+1XXXXXXXXXX')
return freeclimb.PerCLCommand.to_json(outdial.to_dict())

Attributes:

Pause

The Pause command halts execution of the current PerCL script for a specified number of milliseconds.

Example:

import freeclimb

pause = freeclimb.Pause(length=3500)
return freeclimb.PerCLCommand.to_json(pause.to_dict())

Attributes:

PlayEarlyMedia

PlayEarlyMedia is relevant only when present as the very first command in the PerCL script returned for an incoming Call. In such cases, the command is executed before FreeClimb attempts to connect the call. The audio file it uses can be stored in any location that is accessible via URL.

Example:

import freeclimb

play_early_media = freeclimb.PlayEarlyMedia(file='http://example.com/greeting.wav')
return freeclimb.PerCLCommand.to_json(play_early_media.to_dict())

Attributes:

Play

The Play command plays an audio file back to the caller. The audio file may be located at any location accessible via a URL. Play can exist as a stand-alone command or as a nested command. It does not allow barge-in unless nested within a GetSpeech command. The file will always be played to completion unless nested.

Example:

import freeclimb

play = freeclimb.Play(file='http://example.com/greeting.wav')
return freeclimb.PerCLCommand.to_json(play.to_dict())

Attributes:

RecordUtterance

The RecordUtterance command records the caller’s voice and returns the URL of a file containing the audio recording.

Example:

import freeclimb

record_utterance = freeclimb.RecordUtterance(action_url='http://example.com', play_beep=True, finish_on_key='1')
return freeclimb.PerCLCommand.to_json(record_utterance.to_dict())

Attributes:

Redirect

The Redirect command transfers control of a Call to the PerCL at a different URL.

Example:

import freeclimb

redirect = freeclimb.Redirect(action_url='http://example.com')
return freeclimb.PerCLCommand.to_json(redirect.to_dict())

Attributes:

Reject

The Reject command blocks an incoming Call.

Example:

import freeclimb

reject = freeclimb.Reject()
return freeclimb.PerCLCommand.to_json(reject.to_dict())

Attributes:

RemoveFromConference

The RemoveFromConference command removes a Participant from a Conference but does not hang up.

Example:

import freeclimb

remove_from_conference = freeclimb.RemoveFromConference(call_id='CA_your_call_id')
return freeclimb.PerCLCommand.to_json(remove_from_conference.to_dict())

Attributes:

Say

The Say command provides Text-To-Speech (TTS) support. It converts text to speech and then renders it in a female voice back to the caller. Say is useful in cases where it’s difficult to pre-record a prompt for any reason. Say does not allow barge-in unless nested within a GetSpeech command. The file will always be played to completion unless nested.

Example:

import freeclimb

say = freeclimb.Say(text="Hello! This is a message sent using FreeClimb's Python SDK.")
return freeclimb.PerCLCommand.to_json(say.to_dict())

Attributes:

SendDigits

The SendDigits command plays DTMF tones on a live Call.

Example:

import freeclimb

send_digits = freeclimb.SendDigits(digits='1234#')
return freeclimb.PerCLCommand.to_json(send_digits.to_dict())

Attributes:

SetListen

The SetListen command enables or disables the listen privilege for a Conference Participant provided both calls are in the same conference. The Participant can hear what the other participants are saying only if this privilege is enabled.

Example:

import freeclimb

set_listen = freeclimb.SetListen(call_id='CA-call-id', set_listen=False)
return freeclimb.PerCLCommand.to_json(set_listen.to_dict())

Attributes:

SetTalk

The SetTalk command enables or disables the talk privilege for a Conference Participant provided both calls are in the same conference. If False, no audio from that Participant is shared with the other Participants of the Conference.

Example:

import freeclimb

set_talk = freeclimb.SetTalk(call_id='CA-call-id', set_talk=False)
return freeclimb.PerCLCommand.to_json(set_talk.to_dict())

Attributes:

Sms

The Sms command can be used to send an SMS message to a phone number during a phone call.

Example:

import freeclimb

sms = freeclimb.Sms(to='+1XXXXXXXXXX', from_number='+1XXXXXXXXXX', text='Hello! This is a message sent using FreeClimb's Python SDK.', notification_url='http://example.com/notificationUrl')
return freeclimb.PerCLCommand.to_json(sms.to_dict())

Attributes:

StartRecordCall

The StartRecordCall command records the current call and returns the URL of a file containing the audio recording when recording completes.

Example:

import freeclimb

start_record_call = freeclimb.StartRecordCall()
return freeclimb.PerCLCommand.to_json(start_record_call.to_dict())

Attributes:

StartRecordCall does not support any attributes

TerminateConference

The TerminateConference command terminates an existing Conference. Any active participants are hung up on by FreeClimb. If this is not the desired behavior, use the RemoveFromConference command to unbridge Calls that should not be hung up.

Example:

import freeclimb

terminate_conference = freeclimb.TerminateConference(conference_id='CF-your-conference-id')
return freeclimb.PerCLCommand.to_json(terminate_conference.to_dict())

Attributes: