Q-SYS PA Remote API (PARAPI)

The Q-SYS Public Address Remote API, or PARAPI, is a TCP/IP command protocol intended to allow third-party systems to programmatically issue and monitor pages using the PA features of Q-SYS. The command and response syntax is based on JSON-RPC version 2.0 (see http://jsonrpc.org/wiki/specification). The PA.PageSubmit command allows the client to issue a page, either voice or message play. PA.ZoneStatusConfigure allows the client to monitor the activity of the PA Router output zones.

JSON-RPC Error Codes

The following PARAPI error codes can be returned as the code value in a JSONRPC error object.

Example: {"id":"2235","jsonrpc":"2.0","error":{"message":"Message file does not exist","code":4}}

Code	Description
1	Bad Parameters – one or more of the parameters is bogus.
2	Bad PageID – the PageID refers to a Page Request which does not exist.
3	Bad Request – could not create requested Page Request.
4	Bad File – Message file doesn't exist.

Parameters

PA.PageSubmit

Parameter	Type	Value	Notes	Overrides Global Setting	Parameter Required	Parameter Applies to Mode
Mode	string	"message" or "live" or "delay" or "auto"	Specifies the type of page. “live”, “delay”, and “auto” are all voice pages.	-	Y	live	delay/auto	message
Description	string		Appended to the completion event generated for the page (events appear in the Q-SYS Core Manager Event Log).	-	N	Y	Y	Y
Zones	integer or string array		Array of integers and/or strings that represent zone numbers or literal zone name strings specified in Q-SYS Administrator.	-	Y (and/or ZoneTags)	Y	Y	Y
ZoneTags	string array		Array of zone tag strings.	-	Y (and/or Zones)	Y	Y	Y
Priority	integer	1-n	1 is highest priority.	-	Y	Y	Y	Y
Preamble	url string	audio file path	The preamble to play preceding the voice page or message.	-	N	Y	Y	Y
Message	url string	audio file path	The message to play, located in the Messages directory.	-	Y, if Mode == message	N	N	Y
MessageDelete	boolean		The message file will be deleted on page completion.	-	N	N	N	Y
Station	integer	1-n	n is the number of PA Router Page Station inputs.	-	Y, if Mode != message	Y	Y	N
Start	boolean		Start the Page after Submitting it (otherwise, the client must issue a PA.PageStart).	-	N	Y	Y	Y
QueueTimeout	integer	seconds	Time before delayed page times out, 0 means infinite, 1 means no queuing (i.e. page will fail if zones are not ready).	Y	N	N	Y	Y
Archive	boolean		Archive the page on completion.	Y	N	Y	Y	Y
Split	boolean		Allow partial page.	Y	N	Y	Y	Y
RetryCount	integer	0-n	Number of retries when page is interrupted on one or more zones.	Y	N	N	Y	Y
MaxPageTime	integer	seconds	Time before a voice page times out.	Y	N	Y	Y	N
CancelDelay	integer	seconds	Time during which delayed pages and messages are held for possible cancellation.	Y	N	N	Y	Y
Originator	string		Optional string used for logging. Default value is "QRAPI".	-	-	-	-	-

PA.PageStart

Parameter	Type	Value	Notes
PageID	integer		Starts a page.

PA.PageStop

Parameter	Type	Value	Notes
PageID	integer		End a voice page (when the announcer is finished talking).

PA.PageCancel

Parameter	Type	Value	Notes
PageID	integer		Cancel a page.

PA.ZoneStatusConfigure

Parameter	Type	Value	Notes
Enabled	boolean		Configure zone status change notifications.

PA.PageProceed

Parameter	Type	Value	Notes
PageID	integer		Starts a remote page.

PA.SourceWatchdog

Parameter	Type	Value	Notes
RemoteSystem (name of the system)	string		Starts a watchdog on a remote system.

Parameter

Type

Value

Notes

RemoteSystem

(name of the system)

string

Starts a watchdog on a remote system.

PA.PageStatus

State	SubState	Count	Message
			Mode=live	Mode=delay	Mode=message
ready	queued		Busy¹		Message not ready²
	immediate		Ready to Page	Ready to Record	Ready to play message
wait	preamble		Playing Preamble
	zones		Please wait	Waiting to playback	Waiting to playback
	system			Waiting to playback
	cancel	Y		Waiting to playback³	Waiting to playback³
input	live	Y	Paging³
	record	Y		Recording³
output	output			Playing message⁴	Playing message⁴
done	success		Page complete	Playback complete	Playback complete
	cancel		Page canceled	Playback canceled	Playback canceled
	timeout		Page timeout	Queue timeout, playback canceled	Queue timeout, playback canceled
	interrupt		Page interrupted	Playback interrupted	Playback interrupted
	fail		?	?	Message failed²

1. Zones are busy.

2. Issued if system hasn't moved file into buffer yet, or if message file doesn't exist. But, state will move from “Message not ready” to “Ready to play message” if file comes into existence. If a Start is issued while file doesn't exist, status will move to done.fail: “Message failed”.

3. input.cancel, input.live and input.record are issued once per second, with a Count parameter that counts down from CancelDelay or MaxPageTime to zero.

4. Includes optional Preamble playback.

Note: After a Page is submitted with PA.PageSubmit, it moves to the ready.queued or ready.immediate state. When PA.PageStart is issued on that Page, it will move to the wait.x or input.x state. Mode = delay or message type Pages will then move to the output.output state. Finally, the Page will move to the done.x state.

Examples

Get PA Configuration

Retrieve the configured Zones, Tags, and Priorities.

Request

{
    "method": "PA.GetConfig",
    "params": {},
    "id": "1"
}

Response

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "Priorities": [
            {
                "Archive": false,
                "Color": "#FFFF7F80",
                "Guid": "4e055259-34a4-45df-84c1-8e96faa9926f",
                "Name": "Emergency Pages",
                "Retry": false,
                "Split": false
            },
            {
                "Archive": false,
                "Color": "#FFFFB280",
                "Guid": "39f9f05f-ad2f-4b83-92fb-5a2ce8ae11e7",
                "Name": "Emergency Messages",
                "Retry": false,
                "Split": false
            },
            {
                "Archive": false,
                "Color": "#FFFFE580",
                "Guid": "5522845e-8536-4140-9c3e-7afc4d3d50d3",
                "Name": "Terminal Pages",
                "Retry": false,
                "Split": false
            },
            {
                "Archive": false,
                "Color": "#FFE6FF80",
                "Guid": "9f405daa-a03a-45ad-8800-7a3f2fd29cd0",
                "Name": "Terminal Messages",
                "Retry": false,
                "Split": false
            },
            {
                "Archive": false,
                "Color": "#FF80FF80",
                "Guid": "59767f61-7e1e-47dd-b54c-1d6f874534e5",
                "Name": "Background",
                "Retry": false,
                "Split": false
            }
        ],
        "Tags": [
            {
                "Guid": "9aebb5f2-566a-4682-a068-85842f206e79",
                "Name": "tag1"
            },
            {
                "Guid": "1bb9fb07-513c-4419-bab7-e24ae36f4cf9",
                "Name": "tag2"
            },
            {
                "Guid": "6ea9a718-e177-4dbf-8834-569283c02c57",
                "Name": "tag3"
            },
            {
                "Guid": "939f7575-9d1e-4a88-86a4-47c43596d12c",
                "Name": "tag4"
            }
        ],
        "Zones": [
            {
                "Group": "Local",
                "Index": "1",
                "IsLocal": true,
                "Name": "Zone 1",
                "Tags": [
                    {
                        "Guid": "9aebb5f2-566a-4682-a068-85842f206e79",
                        "Name": "tag1"
                    },
                    {
                        "Guid": "6ea9a718-e177-4dbf-8834-569283c02c57",
                        "Name": "tag3"
                    }
                ]
            },
            {
                "Group": "Local",
                "Index": "2",
                "IsLocal": true,
                "Name": "Zone 2",
                "Tags": [
                    {
                        "Guid": "939f7575-9d1e-4a88-86a4-47c43596d12c",
                        "Name": "tag4"
                    },
                    {
                        "Guid": "6ea9a718-e177-4dbf-8834-569283c02c57",
                        "Name": "tag3"
                    }
                ]
            },
            {
                "Group": "Local",
                "Index": "3",
                "IsLocal": true,
                "Name": "Zone 3",
                "Tags": [
                    {
                        "Guid": "1bb9fb07-513c-4419-bab7-e24ae36f4cf9",
                        "Name": "tag2"
                    }
                ]
            }
        ]
    }
}

Q-SYS PA Remote API (PARAPI)

Commands (to Q-SYS)

Notifications (from Q-SYS)