Parliant HomepageSearch

How To Write AppleScripts for PhoneValet

Detailed information on writing AppleScripts that PhoneValet will run for you when events occur on your telephone line. In addition to reading this document you may be interested in our downloadable scripts page.


Introduction: Why PhoneValet Needs Special Scripts

Writing AppleScripts for PhoneValet is not difficult, but there are a few things you need to know to ensure your scripts are reliably called by PhoneValet.

Generally, an AppleScript sets commands (and their parameters) to applications. You decide when to run a script, and the script orders the applications appropriately. With PhoneValet scripts, it is the opposite: PhoneValet decides when it is appropriate to call your scripts and provides information (like caller's name, etc.) to you. With the provided information, you then decide your action.

This means your script must be set up to anticipate that PhoneValet will send you a particular message (with parameters like caller's name and number). Your script must be able to get the information it may require from PhoneValet. Doing this is easy, you just define an AppleScript Handler by adding two lines to your script.


How to Create Handlers

Setting your script up is very simple. You define an AppleScript handler within your script, which PhoneValet will call when necessary. Handlers define a named message and an order of parameters. Within the handler you can make use of the parameters passed by PhoneValet (examples: sending them to other applications or changing the behavior of the script depending on the caller's number).

Here is a simple remote control script that simply returns the caller's name as a string. This script tells you the Caller ID name of the line you are calling from, whenever you call into the system and activate the remote control.

on perform_remote_control(
        secretCode,
        argument,
        callerName,
        callerNumber,
        callTime,
        lineName,
        domesticAreaCode,
        domesticNumber)

    -- your AppleScript goes here --
    return callerName

end perform_remote_control

This trivial script consists of three parts. The first part marks the start of the handler and specifies the names of the parameters (variables) that PhoneValet will make available to you for use in your script. The last part marks the end of the handler. Between these lines are the contents of your script, which can be whatever is appropriate in your situation, and, in this case, consists of simply returning the caller's name provided by PhoneValet. If you have configured this script in your remote control settings with 'text to be spoken' as the feedback option, then running this script will play you the name when you call in.


Different Handlers for Different Types of Script

PhoneValet always presents the same information in the same order when calling a remote control — so you can simply copy the example above to get started on your own scripts. Or, you can copy one of the examples shipped in your
    /Library/Application Support/Parliant/AppleScripts/RemoteControl
folder to start making your own scripts. Alternatively, you can download templates for each script type below.

Each type of script (Remote Control, Hook Status, Voice Mail, etc.) expects to pass information to your handler which is specific to that type of message. For example, Hook Status scripts (which are run when extension telephones are picked up and hung up) pass information relating to lines and extensions, while Remote Control passes secret codes and calling numbers. That translates into a different handler line for each type of script — so be sure you start with the right template depending on when you expect your script to be run.

Note, Recording, Remote Control, and Hook Status scripts are available in PhoneValet Message Center only.


Parliant-Provided Templates

If you do not want to start with one of the provided examples, you can download a template appropriate to each script type from the following list. Simply download and expand the zip file provided, and you'll find a script with the appropriate handler lines and a comment indicating where you should place your own AppleScript statements. Just one more way Parliant aims to help you make the most of your PhoneValet Message Center.

Script Type Template Description
Caller ID download run when Caller ID information is received
Hook Status download Also called Line in Use, run whenever the telephone line becomes active, and whenever it becomes inactive (Message Center only)
Voice Mail download run when a caller has left a voice mail message
Call Recording download run when a call recorded call has completed (Message Center only)
Remote Control download run when a caller has requested your configured remote control (Message Center only)

For further information on PhoneValet's AppleScript support, click here.