Developer

Talk to Voila from your app

This page explains how to interact with Voila from another app: send cards, dates, numbers and keywords with a voila:// link or a shortcut, or let Voila fetch data from your API.

Last updated:

URL scheme

You can send data to Voila using the Voila URL scheme. URLs use this format: voila://[action]?[params]

Possible actions

[action] can be replaced with any action from this list:

Possible parameters

[params] depends on the [action] you are calling. Each action lists its own parameters below.

The input action

Here are the parameters you can use with the input action:

Parameter Sends Value
card A card 2 characters: rank + suit
position A card, by its position in the user's stacked deck Integer from 1 to 52
date A date Unix timestamp, in seconds
number A number Non-negative integer
keyword A keyword URL-encoded string

Examples

Here are some examples of URLs that work with the input action:

Parameter reference

card

rank + suit

Sends a card to Voila. The value must be 2 characters long: the first one is the card's rank and the second one its suit.

Ranks

  • 1Ace
  • 2Two
  • 3Three
  • 4Four
  • 5Five
  • 6Six
  • 7Seven
  • 8Eight
  • 9Nine
  • 0Ten
  • JJack
  • QQueen
  • KKing

Suits

  • S Spades
  • H Hearts
  • C Clubs
  • D Diamonds

Joker

  • JJJoker

The Joker can't be sent at the moment.

Examples

  • 1CAce of Clubs
  • 3DThree of Diamonds
  • 0STen of Spades
  • KHKing of Hearts
  • JJJoker

position

integer · 1–52

Sends a card to Voila using its position in the user's stacked deck. The value must be an integer between 1 and 52.

Examples, using Juan Tamariz's Mnemonica stack

  • 1Four of Clubs
  • 52Nine of Diamonds

date

Unix timestamp · seconds

Sends a date to Voila. The value must be a Unix timestamp, in seconds.

Examples

  • 601302600January 20th, 1989
  • 1604349590November 2nd, 2020

number

integer · 0 or more

Sends a number to Voila. The value must be a non-negative integer.

Examples

  • 123
  • 1234567890

keyword

URL-encoded string

Sends a keyword to Voila. The value must be a URL-encoded string.

Examples

  • Steve%20Jobs
  • Daft%20Punk
  • tiger

Shortcuts

Since version 7.0

Voila adds two actions to the Shortcuts app as soon as it is installed, with no setup: Setup keyword fills a keyword with any value from your shortcut, and Open Voila opens the app. Any app or automation that works with Shortcuts can send data to Voila this way.

Actions

Action What it does Siri
Setup keyword Fills one keyword, without opening Voila. Add one per keyword you want to fill. “Setup a Voila keyword”, “Fill a Voila keyword”
Open Voila Opens Voila. Add it after your Setup keyword actions so Voila opens with those keywords already filled. “Open Voila”, “Launch Voila”

If Voila isn't ready yet when a Setup keyword action runs, its value is kept and applied as soon as Voila opens.

Setup keyword parameters

Parameter Value
Keyword The Voila keyword to fill: pick it from the list, or type its name (or pass it as text), such as [card]
Value Any text or shortcut variable. It is converted to text, and leading and trailing spaces are ignored.

Keywords and values

The values accepted are the same as the input action's, plus a few forms that are easier to get from a shortcut:

Keyword Fills Value
[card] The card: also fills [the card], [position] and [position's number] A card code such as QH or 0S, or a position from 1 to 52 in the user's stacked deck
[date] The date A Unix timestamp in seconds, such as 601302600, or a written date (a Shortcuts date variable works)
[number] The number A whole number of 0 or more, such as 456
[note] The keyword sent with the keyword parameter Any text. URL-encoded text such as Steve%20Jobs is decoded.
[white], [black], [red] A Mental Dice die The die's value. Listed only when Mental Dice is enabled.
Connectivity keywords The user's own OCR, SR and DK keywords Any text. Requires Voila Pro.

Keyword names work in English whatever language Voila is set to. You can also use your own language's names if you prefer, as shown in Voila: [carte] and [card] both work when Voila is in French.

API keywords can't be filled from a shortcut: the next fetch from the user's API would overwrite them.

If a value can't be used, Voila shows a notification with the format it expects.

Examples

  • Set [card] to QH → Open Voila
    Sends the Queen of Hearts to Voila.

  • Set [card] to 12 → Set [number] to 456 → Open Voila
    Sends the Three of Diamonds (12th card in Mnemonica) and 456 to Voila.

  • Set [note] to Clipboard → Open Voila
    Sends the clipboard's text to Voila.

API fetching

Since version 5.4

Voila can fetch data from any API URL.

Users can map any key from a JSON dictionary, or any plain string, to a Voila keyword. Keywords can then be used in Voila tricks.

Anything else?

Please contact us if you'd like to talk about connecting your product with Voila.

[email protected]