Snag help

Voice commands

A command is something you say to Snag that isn't for an agent: a phrase, an action, and a reply. "log 42 miles" runs an n8n workflow and Snag says the workflow's answer back.

Voice commands live under Control > Voice commands: "Things you can say to Snag that aren't for an agent." They are part of Snag Control, which is Pro (see Plans).

"Say it hands-free or in the car. The in-app mic saves a capture instead." The capture card's mic always saves a capture; a command is heard in Siri's "Snag this", Go hands-free, AirPods and CarPlay.

The page has four sections: Packs, Yours, Repos (once a repo is linked) and Recent runs (once a command has run).

How a command is matched

Commands are checked before agent names and captures, in any hands-free capture and on the car screen.

• The phrase must match everything said, words in order.
• A slot in braces, such as {miles}, takes one or more words: "log {miles} miles" matches "log 42 miles".
• A leading "snag" and a trailing "please" are ignored.
• When several match, the one with the most fixed words wins.
• Your own commands and repo commands come before packs. A pack command with the same id as one of yours is dropped.

Packs

Built-in sets of commands, each with a switch. Packs are off by default, except Agents, which turns on once an agent is connected (until you turn it off). A pack command only runs when what it needs is connected.

Make your own command

1. Open Control > Voice commands > New command.
2. Pick what it runs: "n8n workflow", "Zapier Zap", "Make scenario" or "Any webhook".
3. Follow the steps below. The step count shows at the top ("1 of 4").

1. The URL

"Paste" fills the field from the clipboard. The address must be https; plain http works only on your own network ("Use an https address. Plain http works only on your own network.").

2. The signing secret

"Snag signs every call, so your workflow can tell it's really Snag."

Each command gets its own secret, made when the flow opens: whsec_ and 24 random bytes. Tap Copy secret and paste it into the workflow. The secret is kept in this iPhone's Keychain, never in the command itself.

"How to check it in n8n" (or "How to check it") lists the steps: read the raw body and the webhook-id, webhook-timestamp and webhook-signature headers, check the signature (HMAC-SHA256 of id.timestamp.body with the secret), and refuse the call if it doesn't match. In n8n, turn on Raw Body on the Webhook node and check it in a Code node.

Zapier doesn't check signatures, so the Zapier flow skips this step. Its calls are still signed.

The signing format, with examples, is in Webhooks.

3. Test it

Snag sends one real, signed call with sample values: 42 for each slot (25 for a slot with "minute" in its name).

The result card shows what was sent ({"miles": 42}), how long the workflow took ("n8n replied in 0.4 s"), its reply, and "Worked" or "Failed". When it worked, "Snag will say" shows the line Snag would speak. "Send again" repeats the test.

For Zapier: "Zapier replies straight away, so there's no answer to read back yet." Snag says "Sent." right away.

4. What do you say?

Type the phrase. "Braces make a slot: log {miles} miles." With slots, the line below shows what Snag sends, for example {"miles": 42}. "That phrase can't be used: check the braces." means the braces don't pair.

Then choose what Snag says back:

• Say the workflow's reply (on): Snag reads the spoken field of the workflow's JSON reply (or say, when there is no spoken), or a plain text reply as it is. With nothing to read, Snag says "Sent.".
• Off: write your own line, for example "Logged it." Keep it to 8 words or fewer for the car.

Tap Save command.

Edit a command

Tap a command under Yours.

Tap Save at the top to keep changes. A command from a linked repo is read only: "From you/snag-commands, main. Change it in the file and Snag picks it up."

Import commands

Control > Voice commands > Import commands has three ways in:

Before anything is imported, each command shows the address it calls ("Calls n8n.example.net") and a tag: "New", or "Already have" for a phrase you already use. Tap Import 2 to add the new ones; the ones you already have are left alone. If any imported command signs its calls, add each one's secret on the command afterwards.

Share links

A snag://commands link adds a commands file:

• snag://commands?data=... carries the file in the link.
• snag://commands?url=https://... points at a file on the web.

Opening one switches to Control > Voice commands. The file is added under Repos with "Changes waiting", and nothing runs until you accept it in the "Changes to your commands" sheet.

Recent runs

Each time a webhook command runs, Snag records it. Recent runs shows the latest 10 (Snag keeps 50): what Snag said back, when ("07:58, in the car" or "in the app"), and "Failed" if it failed.

Tap a run to see:

• HEARD: what you said.
• SAID BACK: what Snag said.
• Sent: the slot values sent.
• Workflow: the address and "answered in 0.4 s", with "Worked" or "Failed".
• Run again: sends the same values as a test. Edit opens the command.

What commands can do

Commands made in the app call a webhook. Commands from a file or a repo can also:

A command can also carry an approval class (it asks "approve or hold" or for a confirm phrase before it runs, as agent approvals do) and a privacy level (a Private reply asks "Say it out loud?" first). The file format is in Commands in a repo.

Commands from a repo

Keep your commands in a file in a GitHub or GitLab repo. Snag reads .snag/commands.yaml on the chosen branch and writes nothing back.

Open Control > Voice commands > Commands from a repo ("GitHub or GitLab"), or Import commands > Repo.

GitLab

1. Pick GitLab ("gitlab.com or your own") and tap Continue with GitLab.
2. Enter your GitLab address, or leave it as gitlab.com.
3. If Snag isn't registered on that GitLab yet, the screen asks for an Application ID: in GitLab, add an application named Snag with redirect URI snag://oauth/gitlab, not confidential, scope read_repository, and paste its Application ID.
4. Tap Sign in to GitLab and approve on GitLab's own page ("Authorize Snag to use your account?", read_repository).
5. Pick the project and branch ("Which project?").
6. Check the preview and tap Accept.

A pasted address (GitHub, GitLab or a file)

1. Pick GitHub or GitLab and tap Paste a repo or file address. In this version GitHub sign-in isn't set up, so Continue with GitHub opens this step too ("GitHub sign-in isn't available in this version.").
2. Paste the repo's address, or a commands file's. Add /tree/<branch> to pick a branch.
3. For a private repo, add an Access token (read-only is enough: a fine-grained GitHub token with Contents read, or a GitLab project or personal token). A public repo needs none. The token stays in this iPhone's Keychain.
4. Turn on It's on my own GitLab for a self-hosted GitLab.
5. Tap Continue, check the preview and accept.

The preview

The preview lists what was found ("Found .snag/commands.yaml: 3 commands"), each command with the address it calls, and any agents the repo defines. "Each address is shown before you accept." Tap Accept 3 commands. Nothing runs before that tap.

Checks each time Snag opens

Snag fetches every linked repo each time it opens, and on "Check now".

• A change that calls no new address (a changed phrase or reply) is taken straight away.
• A change that calls a new address waits. The Voice commands chip shows a count, the repo shows "Changes waiting", and the "Changes to your commands" sheet opens on the Voice commands page.
• Until you accept, the old version keeps working.
• A failed check keeps the last accepted version working.

The repo row shows the command count and when it was last checked, or why the last check failed:

Tap a repo for Review changes (when something waits), Check now and Unlink.

Changes to your commands

The sheet names the repo and the number of changes. Each line is tagged "New", "Changed" or "Removed", with the phrase and the address it calls. A changed command that now calls somewhere else shows "Now calls example.net, a new address". Agents the repo adds or changes are counted too ("1 agent changes too.").

"Until you accept, the old version keeps working and the new one waits." Tap Accept 2 changes, or Not now.

Advanced settings

Settings > Advanced. Turn on Use my own infrastructure ("For people who run their own servers.") to show:

Keys go in the Keychain by name: "Keys stay in this iPhone's Keychain. Saving an empty value removes the key." Details are in Bring your own stack.

Related

• Snag Control
• Webhooks: the signed request, the reply, and async answers.
• Commands in a repo: the file format.

Next: CarPlay