Proclaim has many built-in commands that can be executed from third-party devices. This article explains how to use these commands to make HTTP requests against Proclaim’s internal HTTP server.
Did you know? You can control Proclaim with midi input devices.
Enable Local Server
First, ensure Proclaim’s local server is enabled. To do so, open Proclaim and Go to Settings > Remote and click Enable.
Proclaim exposes the API on port 52195. Currently, this port cannot be changed.
Note: If on Windows, you may be prompted to allow Proclaim to make a firewall exception for the port it needs to expose.
Unauthenticated Requests
Proclaim will allow requests unauthenticated if they originate from the same computer. This allows for easy integration with our official Stream Deck plugin.
Authenticated Requests
For calls originating outside your local machine, you will need to authenticate with Proclaim first.
1. Get ProclaimAuthToken.
When making authenticated requests, you’ll need a ProclaimAuthToken. You should only need to do this once.
Locate your IP address and password. Proclaim provides both in the Remote settings. Depending on your network, you may see multiple options (four are visible below). Choose the IP address that corresponds to your current connection. For example, if you are controlling Proclaim over Wi-Fi, use the IP address listed in your Wi-Fi settings (visible in your computer’s network settings).
Note: This password defaults to ‘proclaim’ and can be changed in Proclaim > Settings > Remote > Network Control Password. This password will be passed as plain text over your network, so do not use a password that is important to you.
Make a POST request with your password supplied in the BODY.
Details
Path: /appCommand/authenticate
Method: POST
Port: 52195
Body: JSON object with the following shape:
{
"Password": "proclaim or your own password"
}
CURL example
curl -X POST -d '{"Password": "proclaim"}' "http://192.168.1.15:52195/appCommand/authenticate"
On return, if the correct password was sent, Proclaim will respond with JSON containing the Proclaim Auth Token.
Example Response
{
"proclaimAuthToken":"oxdBKO0NkEyMGj4-UqYVGQ"
}
In all future requests, include this auth token in a header called ProclaimAuthToken.
2. Perform App Commands
To perform an app command, you will need to make a GET request to the /appCommand route, including 1 or 2 parameters.
-
appCommandName
: first and required parameter. -
index
is optional and only available (and required) for a few App Commands.
Full documentation with appCommandName and index details listed below.
Details
Path: /appCommand/perform
Query Params:
appCommandName: A valid, case-insensitive app command name.
index: optional index to provide along with the app command.
Method: GET
Port: 52195
Headers: ProclaimAuthHeader={proclaim auth token}
Example authenticated CURL request
curl -H "ProclaimAuthHeader=oxdBKO0NkEyMGj4-UqYVGQ" http://192.168.1.15:52195/appCommand/perform?appCommandName=nextSlide
Example authenticated CURL request with index
curl -H "ProclaimAuthHeader=oxdBKO0NkEyMGj4-UqYVGQ" http://192.168.1.15:52195/appCommand/perform?appCommandName=goToServiceItem&index=4
List of App Commands
The following are the support app commands today. You can see a similar list in Proclaim when setting up MIDI Input.
Note: Commands requiring an index are annotated with an asterisk (*). The index must be a value between 1–254.
Slide Commands
- NextSlide
- PreviousSlide
- NextServiceItem
- PreviousServiceItem
- StartPreService
- StartWarmUp
- StartService
- StartPostService
- GoToServiceItem*
- GoToSlide*
Audio Video Commands
- NextAudioItem
- PreviousPreviousAudioItem
- VideoRestart
- VideoRewind
- VideoFastForward
- VideoPlay
- VideoPause
QuickScreens Commands
- ShowBlankQuickScreen
- ShowLogoQuickScreen
- ShowNoTextQuickScreen
- ShowFloatingHeartsQuickScreen
- ShowFloatingAmensQuickScreen
- ShowAmenQuickScreen
- ShowHallelujahQuickScreen
- ShowPraiseTheLordQuickScreen
- ShowHeIsRisenQuickScreen
- ShowHeIsRisenWhiteQuickScreen
On/Off Air Commands
- GoOnAir
- GoOffAir
Song Commands
For songs, the index is which part of the song it is. So Verse 1 would be 1. Chorus would be 1, Chorus 2 would be 2, etc. For Chorus, Bridge or other un-index values you can ignore the index parameter.
- ShowSongLyricsVerseByIndex*
- ShowSongLyricsBridgeByIndex*
- ShowSongLyricsChorusByIndex*
- ShowSongLyricsPreChorusByIndex*
- ShowSongLyricsEndingByIndex*
- ShowSongLyricsInterludeByIndex*
- ShowSongLyricsTagByIndex*
Additional OnAir session API
The OnAir session route returns a unique on air session id if Proclaim is On Air and returns nothing if Proclaim is not On Air. The session id is stable for the duration of the On Air session. If Proclaim is taken off air and goes back On Air, it will return a new session id.
This route does not require any authentication.
Details
Path: /onair/session
Method: GET
Port: 52195
CURL example
curl http://192.168.1.15:52195/onair/session