Skip to main content
Kalam Documentation

Command actions

A custom or built-in entry on Commands defines a spoken trigger and an action object. When the speaker invokes that trigger, Kalam runs the command's action instead of (or alongside) regular typing. For UI documentation, see Commands and Ask Kalam. This reference documents the action schema exposed to plugins and workspace sync.

Inline Dictation voice commands (period, new line, scratch that) live separately under Dictation → While dictating. See Voice commands reference.

Match​

FieldValues
triggersSpoken phrases, compared in a case-insensitive way.
trigger_matchprefix, suffix, exact, inline, selection_intent
selection_requirementnone, optional, required
contextinclude_selection, include_clipboard, include_app, include_url
deliveryinherit_global, instant_insert, review_window, clipboard_only, silent
requires_proBuilt-in AI and selection tools set this. Capture, search, and typing tools do not.

inherit_global follows Default AI output on the Commands page: Act immediately (instant_insert) or Review window (review_window).

Action kinds​

The JSON tag is kind.

kindFieldsResult
ai_promptsystem_promptSends the utterance, and the context you included, to the commands language model.
notetag or nullSaves a note. Built-in prefixes include new note, save note, remember this, new task, and new reminder. new task and new reminder still save a note.
searchengine, url_templateOpens a browser search. engine may be a named engine or omitted so Default search engine applies. url_template may contain {speech}.
open_urlurl_templateOpens an http or https URL.
clipboardnoneCopies the remainder. Does not paste.
key_presskeyenter types, then sends Return. inline_edit is the built-in undo / delete / scratch tool.
punctuationnoneInserts a punctuation or edit command.
webhookurl, method, headersHTTP request from the host. Disabled while the foreground app is sensitive. Empty method is POST. The URL may contain {speech}, {selection}, {clipboard}, {app}, {app_name}, {url}, or {browser_url}. In an http or https template those values are URL-encoded.
plugin_actionplugin_id, actionCalls that method on the plugin worker.

plugin_action​

Kalam calls action on plugin_id with this JSON body, and waits up to 10 seconds:

{
"command_id": "builtin-or-custom-id",
"command_name": "Stamp",
"speech": "the utterance",
"selection": null,
"clipboard": null,
"app_name": null,
"browser_url": null
}

selection, clipboard, app_name, and browser_url are present when that context flag is on (selection is also included when selection_requirement is not none). They are JSON null when Kalam did not read them.

The call fails, and the take is not handed to the plugin, when:

  • the foreground app is sensitive (Plugin commands are disabled for sensitive apps.)
  • Plugin platform is off
  • plugin_id or action is empty
  • that plugin is not turned on in Labs
  • the worker is missing, or it does not answer in time

Return a JSON object. If text, result, or output is a non-empty string, Kalam delivers that string using the command's delivery mode:

DeliveryWhat the person gets
review_windowThe review window, with the string as the result
clipboard_onlyThe string on the clipboard
instant_insertThe string typed into the focused app
silent, or an empty stringNo insert. status_message still updates the Pill when you set it

status_message is a short Pill line. When the result string is empty, Kalam shows status_message, or <command name>: done.

Register the method in definePlugin({ methods }) under the same name as action. See SDK.