Skip to main content

​
Overview

Communication actions integrate with Messages and FaceTime to send texts and make calls.
ActionDescriptionEnabled by Default
send_messageSend an iMessage or SMS via Messages.app—
facetime_callStart a FaceTime video call—
facetime_audioStart a FaceTime audio call (phone call)—
All communication actions are disabled by default to prevent accidental messages or calls. Enable them individually via the Actions panel (press A in TUI) or CLI.

​
send_message

Send an iMessage or SMS via Messages.app with automatic contact lookup.

​
Parameters

​
to
string
required
Recipient: contact name, phone number, or email address
​
text
string
required
Message content

​
Contact Lookup

The action automatically resolves contact names using the Contacts app:
  • “John” → Searches Contacts for “John”, uses first phone number or email
  • “+1234567890” → Direct phone number (no lookup)
  • “[email protected]” → Direct email (no lookup)
See resolve_contact() in src/actions/communication_actions.cpp:7-34 for implementation details.

​
Examples

rcli listen
# Say: "Send a message to John saying I'll be 10 minutes late"
# Say: "Text Mom that I'm on my way"

​
Implementation Details

The action uses three fallback strategies:
  1. imsg CLI (if installed, fastest)
  2. Buddy-based AppleScript (modern macOS Ventura+): 
    tell application "Messages"
  set targetBuddy to a reference to buddy "<resolved_contact>" of service 1
  send "<text>" to targetBuddy
end tell
  3. Account/participant fallback (older macOS versions): 
    tell application "Messages"
  set targetService to 1st account whose service type = iMessage
  set targetBuddy to participant "<resolved_contact>" of targetService
  send "<text>" to targetBuddy
end tell
Timeout: 15 secondsPermissions: Messages.app may prompt for automation permission on first use.Source: src/actions/messages_actions.cpp:8-55

​
Response

{
  "action": "send_message",
  "to": "John",
  "resolved": "+1234567890",
  "status": "sent"
}

​
facetime_call

Start a FaceTime video call with automatic contact lookup.

​
Parameters

​
contact
string
required
Contact name, phone number, or email address

​
Examples

rcli listen
# Say: "FaceTime John"
# Say: "Video call Mom"

​
Implementation Details

Uses the facetime:// URL scheme:
std::string resolved = resolve_contact(contact); // Contact lookup
std::string url = "facetime://" + url_encode(resolved);
run_shell("open '" + escape_shell(url) + "'");
Note: FaceTime.app will open and initiate the call. The user must confirm the call.Source: src/actions/communication_actions.cpp:36-47

​
Response

{
  "action": "facetime_call",
  "contact": "John",
  "resolved": "[email protected]"
}

​
facetime_audio

Start a FaceTime audio call (phone call) with automatic contact lookup.

​
Parameters

​
contact
string
required
Contact name, phone number, or email address

​
Examples

rcli listen
# Say: "Call Mom"
# Say: "Make a phone call to John"

​
Implementation Details

Uses the facetime-audio:// URL scheme:
std::string resolved = resolve_contact(contact);
std::string url = "facetime-audio://" + url_encode(resolved);
run_shell("open '" + escape_shell(url) + "'");
Note: FaceTime.app will open and initiate the audio call. The user must confirm the call.Source: src/actions/communication_actions.cpp:49-60

​
Response

{
  "action": "facetime_audio",
  "contact": "Mom",
  "resolved": "+1234567890"
}

​
Enabling Communication Actions

Communication actions are disabled by default to prevent accidental messages or calls.

​
Enable via TUI

  1. Press A to open the Actions panel
  2. Navigate to send_message, facetime_call, or facetime_audio
  3. Press Enter to toggle enabled
  4. Changes persist across sessions

​
Enable via CLI

# Enable all communication actions
rcli action send_message --enable
rcli action facetime_call --enable
rcli action facetime_audio --enable

# Verify status
rcli actions | grep communication

​
Voice Examples

You: “Send a message to John saying I’ll be 10 minutes late”RCLI: “Message sent to John.”
You: “FaceTime Mom”RCLI: “Starting FaceTime video call with Mom.”(FaceTime.app opens with call UI)
You: “Call Sarah”RCLI: “Starting FaceTime audio call with Sarah.”(FaceTime.app initiates phone call)

​
Troubleshooting

On first use, macOS will prompt you to grant RCLI permission to control Messages.app.Fix: Click “OK” in the System Settings prompt, then retry the action.
If contact lookup fails, the action uses the raw input (name) as the recipient.Fix: Use the exact contact name from Contacts.app, or provide a phone number/email directly.
FaceTime.app must be installed and the recipient must have FaceTime enabled.Fix: Verify the contact has a valid phone number or email registered with FaceTime.

​
Managing These Actions

See Managing Actions for details on enabling/disabling actions and persisting preferences.

Build docs developers (and LLMs) love

Get started for freeTalk to us