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
| Field | Values |
|---|---|
triggers | Spoken phrases, compared in a case-insensitive way. |
trigger_match | prefix, suffix, exact, inline, selection_intent |
selection_requirement | none, optional, required |
context | include_selection, include_clipboard, include_app, include_url |
delivery | inherit_global, instant_insert, review_window, clipboard_only, silent |
requires_pro | Built-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.
kind | Fields | Result |
|---|---|---|
ai_prompt | system_prompt | Sends the utterance, and the context you included, to the commands language model. |
note | tag or null | Saves 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. |
search | engine, url_template | Opens a browser search. engine may be a named engine or omitted so Default search engine applies. url_template may contain {speech}. |
open_url | url_template | Opens an http or https URL. |
clipboard | none | Copies the remainder. Does not paste. |
key_press | key | enter types, then sends Return. inline_edit is the built-in undo / delete / scratch tool. |
punctuation | none | Inserts a punctuation or edit command. |
webhook | url, method, headers | HTTP 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_action | plugin_id, action | Calls 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_idoractionis 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:
| Delivery | What the person gets |
|---|---|
review_window | The review window, with the string as the result |
clipboard_only | The string on the clipboard |
instant_insert | The string typed into the focused app |
silent, or an empty string | No 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.