EPTIONIST

 THE RECEPTIONIST

MORE THAN A SIMPLE PHONE PAGING PLUGIN!

 

Introducing The Receptionist - a powerful Q-SYS plugin that allows you to interact with your Q-SYS environment over the phone. It can easily create menus and submenus and navigate through them via simple keypad operations. Whether you need to make a live paging announcement, send pre-recorded messages, or manage an emergency system in a public building, The Receptionist is the solution you've been looking for.

This plugin is particularly useful in emergency situations where you need to quickly convey important information to people in a building or facility.

Security being a priority, you can lock menus behind a password to ensure only authorized users have access.

The Receptionist also lets you, amongst other things:

1. Start a paging
2. Play a pre-recorded message
3. Record calls
4. Load and save snapshots
5. Write to the Core’s log
6. Access all the controls in your Q-SYS design
7. Sequence any of the above and more.
   

This makes it easy to integrate The Receptionist into your existing Q-SYS design and create a truly seamless user experience, allowing you to customize the plugin to your specific needs.

Overall, The Receptionist is more than a simple phone paging plugin. It's a comprehensive solution for managing communication and information delivery in a variety of settings, from public buildings to corporate offices. Try it out today and experience its power of for yourself.

1.3.0.1	2023-04-02	Small bugs fix about exporting Purge Log Day value with the Wizard.
1.3.0.0	2023-03-16	Introduction of the Wizard. This function help you to build your first phone menu.
1.2.0.1	2023-02-10	Minor UI bug fixe after configuration import and with VPS action type.
1.2.0.0	2023-02-01	Add the CONDITION Action Type. Add the Write to Log Action Type. Ability to disable internal recorder via plugin’s properties. Rebuild the backup section. No need to be live on a core to save/load a configuration file anymore. Add VARIABLES, allow user to access to external data in the plugin. Remove global Virtual Paging Station to allow user to select a different component for each action’s call.
1.1.0.0	2022-12-01	Add another row of action’s parameter for supplemental controls. Minor bug fixe related to Inactivity Timer.
1.0.0.1	2022.04-10	Minor bug fixe related to Delay Action
1.0.0.0	2022-03-01	Initial release.

Design Requirements

The plugin requires that any Softphone, Virtual Paging Station, and Snapshot Controller are named.

How to rename a component
Q-SYS Designer 9.4 and lower: While in offline mode, simply rename the actual component block.

Q-SYS Designer 9.5 and upper: While in offline mode, go to the Properties pane and change “Code Name” to the desired name and make sure “Script Access” is at “Script” or “All”.

Softphone component (REQUIRED)

To connect the Softphone, you need to rename the Status/Control component.

Virtual Paging Station Component

To connect an external Virtual Paging Station, you need to rename the component and activate <ROBOT CONTROLS> properties.

Snapshot Controller Component

To connect a Snapshot Controller, you need to rename the component.

Except the Variables, none of these controls are meant to be used externally by activation of pins or naming the component.

Menus

Menu.List	List of all created menu items
Menu.Add	Create a new menu
Menu.Delete	Delete the currently selected menu
Menu.Up	Move the item up in the list
Menu.Down	Move the item down in the list
Global.RootMenu	The first menu a user will encounter when calling
Menu.Name	The menu name
Menu.ConfirmationKey	A drop-down list that allows to choose if The Receptionist will look for a match option after each keypress or after the user presses # or *
Menu.PlayAudioFile	The audio file that will be played when entering the current menu.
Menu.PlayAudioRepeat	Choose if the audio file loops or not (If you do so, we recommend you leave at least 4 seconds of silence at the end of the audio file.)
Menu.EntryAction	You can select an option ( available in the current menu options list ) to be trigger when the user entered into this menu
Menu.InactivityAction	You can select an option ( available in the current menu options list ) to be trigger after X seconds of inactivity (keypress)
Menu.InactivityTimeout	The amount of time it takes to trigger the Inactivity Action

Options

 

Option.List	List of all created options items under the selected menu
Option.Add	Create a new option
Option.Delete	Delete the currently selected option
Option.Up	Move the item up in the list
Option.Down	Move the item down in the list
Option.Test	Test the currently selected option
Option.Name	The option name. If a number, it can be triggered by the user via the keypad. If alphanumeric, it can only be used internally. A CATCHALL option can also be defined if required.
Option.ActionType	The type of action that this option will be trigger. A complete list is available bellow
Option.EventTopic	When used in conjunction with the ADDA Event Receiver plugin, the topic of the event that will be transmitted.
Option.EventPayload	When used in conjunction with the ADDA Event Receiver plugin, the payload of the event that will be transmitted.
Option.SecondAction	If selected, the second action will be triggered after the current one is finished. If a new action starts before the second action is triggered, it will be canceled.
Option.*ACTION PARAMETERS*	Each action has its own set of parameters (it also might not have any) which may be used to further specify what The Receptionist should do as an action.

 

Variables

The variables controls are the only controls accessible via pins.

Useful to import data in The Receptionist available thru templating.

Can be use in Event Topic, Event Payload, Condition Value and Write to Log Message.

Eg. {{VAR1}} {{VAR24}}

 

Log

Log files are stored in the /media/The Receptionist/Logs

Enable	Enables the “Save log to file” feature
Auto Purge	Toggles auto-deletion of older events
# of days	Defines how long events should be kept for when auto purge is enabled.
Clear Live Log	Clears the live log. This does not clear the log files.
Live log view	This list auto-updates with log events happening in real time.

Settings

Softphone Component	Selection of the softphone the plugin will use.
Virtual Page Station selection	Selection of the Virtual Page Station that will be used by the plugin when paging.
Current Configuration	The configuration that The Receptionist is currently running. Can be copied and stored.
Import New Configuration	Paste another Configuration string and press the button to import it.

 

This included plugin allow The Receptionist to interact with externals components in your design. The Payload controls count can be changed via the plugin’s properties.

Topic	The topic the Receiver will listen on.
Catchall	Gets triggered on any event matching the topic, the payload gets read and is accessible via the output pin..
Payload 1-4	If the event payload matches this field, LED and Trigger gets activated.

 

 

Action types

Nothing	Do nothing (Default value)
Delay	Add a delay before performing the <SECOND ACTION>.
Navigation	Navigate to another <MENU>.
End Call	End the current call.
Load Snapshot	Load a Snapshot.
Save Snapshot	Save a Snapshot.
Start Recorder	Start the internal Audio Recorder. *Available according to the plugin’s properties.
Stop Recorder	Stop the internal Audio Recorder. The recorder will also automatically stop when the user hangs up the call. *Available according to the plugin’s properties.
Play Audio	Play an audio file into the internal <ACTION AUDIO PLAYER>. This will duck the <MENU AUDIO PLAYER>. (Note: the second action field will be triggered after the player is done with playing the audio file.)
Start Live Page	Start the Virtual Page Station selected into the plugin's configuration page in Live mode.
Start Auto Page	Start the Virtual Page Station selected into the plugin's configuration page in Auto mode.
Start Delayed Page	Start the Virtual Page Station selected into the plugin's configuration page in Delayed mode.
Play Message	Start the Virtual Page Station selected into the plugin's configuration page in Message mode. Select Directory and File.
Play Loop Message	Start the Virtual Page Station selected into the plugin's configuration page in Loop Message mode. Select Directory and File.
Stop Page	Stop the Virtual Page Station selected into the plugin's configuration page. It also stops Message or Loop Message.
Cancel Page	Cancel the Virtual Page Station selected into the plugin's configuration page. It also cancels Message or Loop Message.
Condition	Validate if either of not the selected variable equal a custom input. The Value user input accept templates. (see templates section)
Write to Log	Write either a Message or an Error to the Core log.

Note: whatever action type you use, you must fill in any required parameters. Otherwise, the action will not trigger!

 

 

Menu Inactivity and entry actions

1-     Inactivity action allows you to automatically trigger an action after a certain time when the user isn’t reacting anymore. It can be useful in multiple scenarios, but as an example, you could have an action that hangs up the call to make sure the line stays free. The inactivity delay can be defined in the Inactivity Timeout field.

2-    The entry action simply gets triggered whenever the user enters a menu.

Options with alphanumeric names/second actions

While only options named with numbers can be called by the user from their phone, you can name options with alphanumeric name for internal use. A great example of this is when you want to prepare a VPS before starting a paging message. You would first recall a snapshot of the configuration needed to properly route the message to the desired zone(s) and then use the second action field to trigger a second action that would be named “start paging” that would have the action type of that very same name, thus starting a page in the right zone(s) in a single step as far as the user is concerned.

CATCHALL

The CATCHALL action name will make an action catch any keypress that is selected by the user. It can be used in two ways:

1-     If you put a CATCHALL before other actions, the catchall will catch any entry, and then execute a specific option if one matches.

2-    If you put a CATCHALL after other specific actions, the catchall will only run if no action matched the user input.

The CATCHALLs are the only options for which the order matters.

 

How to setup a password protected menu

Setting up a password protected menu is just a matter of using a menu with a single option that has the PIN as a name and asking for a confirmation. For example, you could setup a menu named “password” as a root menu, and as its only action have an option named “1234”. You then would set the menu up so that it asks for the pound key as a confirmation key. The 1234 action simply navigates to another menu name “main menu” where the actual actions would be.

To handle wrong passwords, simply add a CATCHALL after the good pin option so that it catches ONLY wrong passwords as explained in the previous section.

 

A word on events

Events are very similar to MQTT. They allow The Receptionist to be used with control pins and to be accessed in a control script. In a nutshell, they have a topic (mandatory) and a payload (technically optional). The Event Receiver will receive any event that matches the selected topic and automatically trigger the catchall, passing on the payload. It will then start comparing the payload(s) defined in the plugin to the actual payload and will trigger any of them that matches with the event payload. The number of payloads the plugin will compare it to can be set in its properties.

Each time an action is triggered, an event can be sent. To do so, simply fill the Topic field of the action. The payload will be sent in this event, but it is optional.

Working with snapshots

The Receptionist can work with your pre-existing snapshots. Using the action types “load snapshot” and “save snapshots” will trigger a load or save snapshots controller in your design.

However, it is required that you rename your controller before you can select it in the options parameters.

About the “Nothing” action type

This action type has been implemented to allow notably for sending events to The Event Receiver plugin that is bundled with The Receptionist without executing any other action. It can also be used to create dead ends.

Template

---

{{CID_NAME}}	Caller’s name
{{CID_NUMBER}}	Caller’s phone number
{{KEYPRESS}}	Last key(s) pressed (Option Name or actual key(s) when CATCHALL)
{{CALL_DETAILS}}	All information about the current call: Call-Direction Codec-Name Codec-Rate Caller-ID-Name Caller-ID-Number
{{DATE_TIME}}	Date Time. Format: %Y-%m-%d %H:%M:%S
{{DATE}}	Date. Format: %Y-%m-%d
{{TIME}}	Time. Format: %H:%M:%S
{{VARn}}	n as a number from 1 to 24. Get the current value of the selected variable field.

File Structure

THE RECEPTIONIST will create directories into the \media folder of your Core:

\media\The Receptionist	Root folder of the plugin
\media\The Receptionist\Audio	Where the TTS files should be stored
\media\The Receptionist\Recording	Target directory for the output of the recording action types.
\media\The Receptionist\Logs	Where the logs are stored when “Save log to file” is enabled.

 

1.      First, you must drag few components into your design:

a.     The Receptionist

b.     Softphone or POTS Component

2.     Then you should rename it. You will have to specify to The Receptionist which Softphone component to use. You can do so by going to the settings tab of the plugin when in the runtime.

3.     The Receptionist will take care of making your Softphone automatically answer after 0 rings, but you still must make sure it can handle a call. Please refer to its own documentation for that part.

4.     Each Virtual Page Station that you want to be accessible for The Receptionist must be set to allow robot controls. To do so, please go in its properties (in offline mode) and set that option to “Yes”

5.     At this point, you need to start getting some content into The Receptionist.

a.     Get your TTS audio files into your design via Core Manager. Go to the File section and upload them into /The Receptionist/Audio.

b.     Let’s create a menu under the Menu Builder Tab. Give it a meaningful name. This will be automatically assigned as the Root Menu which means this is the first menu a user will encounter when calling. It can be changed later if you so desire.

c.     Create some options in the bottom section. Anything that contains only numbers can be triggered directly by the far end when in this menu using the keypad. If you have more than 10 options or you need a specific number (like a zone number or employee ID), you can set a confirmation key in the menu section to allow users to enter multiple digits as an option. You can also use the CATCHALL option which is explained in the “how to use” section.

d.     It is then up to you to choose what your actions will do but remember to keep it simple for any user to use in a rush.

Use Cases

---

1.      Schools

This system is a great use case for The Receptionist as it allows handling of paging, playback of pre-recorded messages for emergency response and much more.

2.     Offices and corporate buildings

Forgot to lock the office because you thought someone was still there? Just call The Receptionist and let it handle locking your doors! It will allow paging in your office with selective zones, let you and your employees change the volume of the music in the elevator and many more customisation options from a single phone number!

3.     Restaurants

With The Receptionist, your employees can handle the volume of the music and call out a customer's birthday without physically interacting with any hardware devices. They can simply call in and use their personal PIN to make these adjustments. This eliminates the need for a complicated sound board installation for simple tasks.

 

Resources usage

The Receptionist uses 2 audio player tracks and 1 audio recorder channel*. Those will count towards the limit imposed by your license.

*The internal audio recorder can be disabled via the plugin’s properties.

 

License

License keys can be added, while in Offline mode, in the right side Properties pane.

To purchase a license, go to https://ad-da.ca

The plugin can be emulated for free, allowing you to prepare menus and automation without access to a core. However, once you run your design on a core, you will need a licence to run the plugin more than 1 hour.

If you use a backup Q-SYS Core and the main one fails, the backup one technically does not need a license to work. However, from the moment the backup one loses power, it will not be able to boot back up without a license. That is what the “Backup License” field is for. If the main license does not work because you are now running on a backup device and had to reboot it, The Receptionist will try and use the backup license instead.