The service buttons on your Stream Deck.

Each button sends one web request to Voclyn, and Voclyn does what the sound desk’s own button does. The sound desk page stays open on the computer connected to the mixer, because the sound comes from there; it shows every change a button makes, and its own buttons keep working.

The request carries a booth key: it can press this church’s service buttons and read its rooms, and nothing else. It can’t read your services or transcripts, so it is safe to keep on the booth computer.

• A Voclyn plan with integrations (Chapel, Church or Campus), or the free month.
• A booth key. An owner or admin makes it in Integrations › API keys, choosing “Booth buttons”. It is shown once: paste it straight into Companion or the plug-in.
• Your room’s link word: grace in voclyn.com/grace. Integrations shows each room’s addresses, ready to copy.
• Bitfocus Companion 4.3 or later with its Generic HTTP Requests connection, or the Stream Deck app with the free Web Requests plug-in (Mac and Windows).

Each address follows https://voclyn.com/api/v1. Every request is a POST with the header Authorization: Bearer and your key; the body can be empty or {}.

1. Add the connection. In Connections, add Generic: HTTP Requests (Companion installs it from its module store). Set its Base URL to https://voclyn.com/api/v1.
2. Keep the key in one place. Make a custom variable named voclyn_key holding your booth key, so every button uses it and a new key is one change.
3. Make a button. Give it a POST action. URI: /rooms/grace/worship. Body: {}. Content type: application/json. In header input (JSON): {"Authorization": "Bearer $(custom:voclyn_key)"}
4. Repeat for each button you want: Speech, Break, Private moment, End, Go live.
5. Press it during a rehearsal. The sound desk page shows the change at once. If Companion marks the connection in error, the answer wasn’t a success: see the checks below.

1. Install Web Requests from the Elgato Marketplace (free, by Adrian Mullings).
2. Drag its action to a key. Method: POST. URL: the whole address, such as https://voclyn.com/api/v1/rooms/grace/worship. Content type: application/json. Body: {}.
3. Add the header, one per line: Authorization: Bearer and your key.
4. Press it. The key shows a tick when Voclyn answers with success.

The Stream Deck’s own Website action sends only a GET request, without headers, so it can’t press these buttons.

Go live starts the service from the sound desk page open for that room. Open it on the computer connected to the mixer before the service and check the sound once, so the browser has its microphone: from then on, the Go live button starts the service there, as if its button were held.

If nobody has that page open, the button changes nothing and Voclyn answers desk_closed. Worship, Break, Private moment, Speech and End need a service running in the room, and answer not_live otherwise.

GET /rooms/grace answers with the room’s state: status (idle, starting, live, paused or ended), reason while paused (worship, private or break) and desk_open. Companion can keep that answer in a variable (its JSON Response Data Variable) for a button whose colour follows the service. The API reference has every field; a key may make 120 requests a minute.

• 401 unauthorized. The key was copied only in part, or it was revoked. Make a new booth key and paste it whole.
• 403 plan_required. Your church is on Free: the buttons come with the paid plans.
• 409 desk_closed. Go live needs the room’s sound desk page open. Open Go live on the computer at the mixer.
• 409 not_live. No service is running in that room yet: go live first.
• 404 not_found. The room’s link word changed, or the address has a typo. Copy the addresses again from Integrations.
• Companion says the JSON is invalid. The header field must be one JSON object with straight quotes: {"Authorization": "Bearer …"}.