Proclaim App Command API

Print Friendly and PDF

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.

Remote Settings In Proclaim With Enable Remote Control Over Local Wifi Highlighted

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).

Remote Settings In Proclaim Showing IP 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
Was this article helpful?
Suggest an improvement or request a feature

Can't find what you need? Give us a call!