Voxrn 📞

intent

Voxrn registers a browser-native voice and SMS platform as an outbound MCP server in your OpenClaw workspace. Use this skill when the user needs to place outbound phone calls, send text messages, manage contacts, check account balance, or inspect live agent call sessions from any bridged chat (Slack, Telegram, iMessage, WhatsApp, Discord, etc.). The skill bridges those chat platforms directly to the real PSTN, so the agent can execute the full call or message lifecycle on behalf of the user.

inputs

Required environment variables:

• VOXRN_API_KEY (string): API key in format vxk_.... Mint at https://voxrn.com/enterprise/dashboard/agents. Store via env var or use openclaw config secrets set voxrn_api_key vxk_... to avoid exposing the secret in the agent prompt window.

Optional environment variables:

• VOXRN_BASE_URL (string): defaults to https://voxrn.com. Override only if using a self-hosted or staging instance.

External connection:

• Voxrn enterprise workspace with active account and sufficient balance (USD or USDC).
• Outbound calling capability enabled on the workspace API key.
• PSTN routing configured (contacts stored in workspace, or ad-hoc E.164 numbers).

Input context from user:

• Phone numbers in E.164 format (e.g., +1 415 555 0188), or contact names to search.
• Task briefs or call scripts (passed as-is to the agent runtime).
• Contact metadata (name, number, tags, notes) for upsert operations.

procedure

1. Initialize and verify credentials

• Input: VOXRN_API_KEY env var.
• Output: MCP server registration in OpenClaw workspace.
• Action: The skill reads ${VOXRN_API_KEY} at MCP-registration time. Do not echo or log the key. Confirm registration by running any read-only tool (e.g., balance.check).

2. Search for a contact (if user provides a name or partial match)

• Input: User query string (e.g., "plumber", "Atlas", "Mina").
• Tool: contact.search { q: string }
• Output: Array of matching contacts with id, name, number, tags. Returns empty array if no matches.
• Action: Present matches to the user and ask for confirmation before placing a call or sending a message.

3. Check balance (optional but recommended before costly operations)

• Input: None.
• Tool: balance.check {}
• Output: { usd: number } representing workspace balance in USD.
• Action: If balance is low or zero, inform the user and redirect to https://voxrn.com/account → Billing to top up via Stripe or USDC.

4. Place an outbound call

• Input: Destination phone number (E.164), optional task brief, optional voice profile ID.
• Tool: call.place { to: string (E.164), taskBrief?: string, voiceProfileId?: string }
• Output: { callSid: string, reservedUsd: number }
• Action: Pass the user's prose directly into taskBrief without reformatting. The brief travels to the agent runtime. Confirm the destination number and estimated cost with the user before execution. Monitor the call via call.list_active or direct the user to https://voxrn.com/enterprise/dashboard/agents for live view.

5. Send an SMS

• Input: Destination phone number (E.164), message body (string).
• Tool: message.send { to: string (E.164), body: string }
• Output: { messageSid: string, segments: number, billedUsd: number }
• Action: Confirm the recipient and message preview with the user first. Report the message SID and cost after successful send.

6. List active calls

• Input: None.
• Tool: call.list_active {}
• Output: Array of active calls with callSid, to (E.164), durationSeconds, billedUsd, state.
• Action: Use this to show the user which calls are currently live, or to find a call SID before terminating one.

7. End an active call

• Input: Call SID (from call.list_active output).
• Tool: call.end { callSid: string }
• Output: { ok: boolean }
• Action: This is destructive and audit-logged. Always confirm with the user before running unless they explicitly say "kill it now" or "end the call immediately".

8. Stream live captions for a call (optional)

• Input: Call SID.
• Tool: transcript.stream { callSid: string }
• Output: Real-time caption stream for the call.
• Action: Subscribe to see what the agent and the recipient are saying in near real-time. Useful for monitoring or debugging stuck calls.

9. Upsert a contact (save or update)

• Input: name (string), number (E.164), tags (array of strings, optional), notes (string, optional).
• Tool: contact.upsert { name, number, tags?, notes? }
• Output: { id: string, name, number, tags, notes, created_at, updated_at }
• Action: Create a new contact or update an existing one (matched by number). Useful for adding the user's new plumber, client, or frequent contact.

decision points

If the user provides a contact name instead of a phone number:

• Run contact.search { q: name }.
• If one match is found, use it.
• If multiple matches are found, present them and ask the user which one.
• If no matches are found, ask the user to provide the phone number directly, or ask if they want to save it as a new contact.

If the user asks to place a call but the account balance is low (< $0.10):

• Call balance.check first.
• If balance is insufficient, inform the user and direct them to top up. Do not attempt the call.

If the user asks to end a call and does not explicitly say "now" or "immediately":

• Show the active calls via call.list_active.
• Ask the user to confirm the call SID and duration.
• Only run call.end after explicit user approval.

If call.place succeeds but the agent responds with silence or voicemail:

• The destination may have returned caller_audio_failed or hit voicemail. Call call.list_active to inspect the call state.
• Advise the user to check the live monitor at https://voxrn.com/enterprise/dashboard/agents for state and any error logs.

If a Voxrn tool returns 401 Unauthorized:

• The API key is wrong, expired, or the workspace has been deleted.
• Mint a fresh key at https://voxrn.com/enterprise/dashboard/agents → API keys.
• Update the env var and re-register the MCP server.

If balance.check returns 0:

• The workspace has no available balance.
• Direct the user to https://voxrn.com/account → Billing.
• Top up via Stripe or USDC.

If a call or SMS request is to a number outside the workspace's approved regions:

• Voxrn may reject the request with a 403 Forbidden or region-lock error.
• Advise the user to check workspace settings at https://voxrn.com/enterprise/dashboard/agents → Routing.

output contract

For call.place:

• Output: JSON object with callSid (string, unique identifier) and reservedUsd (number, estimated cost).
• File location: none (API response only).
• Success: callSid is non-empty and reservedUsd is >= 0.

For message.send:

• Output: JSON object with messageSid, segments (number of SMS segments), and billedUsd.
• File location: none (API response only).
• Success: messageSid is non-empty and billedUsd matches the reported rate.

For contact.search:

• Output: JSON array of contact objects with id, name, number, tags (array), notes (string).
• File location: none (API response only).
• Success: array may be empty (no matches) or contain one or more objects. Never fails; returns empty on no match.

For contact.upsert:

• Output: JSON object with id, name, number, tags, notes, created_at (ISO 8601), updated_at (ISO 8601).
• File location: none (API response only).
• Success: object includes all input fields plus timestamps.

For call.list_active:

• Output: JSON array of active call objects with callSid, to (E.164), durationSeconds, billedUsd, state (string: "ringing", "in_call", "ended", etc.).
• File location: none (API response only).
• Success: array may be empty (no active calls) or contain one or more active calls.

For balance.check:

• Output: JSON object with usd (number, decimal to 2 places).
• File location: none (API response only).
• Success: usd is a non-negative number.

For call.end:

• Output: JSON object with ok (boolean).
• File location: none (API response only).
• Success: ok is true. Call is terminated immediately and audit-logged.

For transcript.stream:

• Output: Stream of caption events in real-time.
• File location: none (live stream).
• Success: stream opens without error; captions appear within 2-3 seconds of speech.

outcome signal

• Place a call: Agent reports the callSid and reserved cost. User receives confirmation that the outbound call is ringing or in progress. Call appears in the live monitor at https://voxrn.com/enterprise/dashboard/agents within 1-2 seconds.
• Send an SMS: Agent reports the messageSid and billing amount. User can verify delivery via their carrier or the Voxrn live monitor.
• Search contacts: Agent presents a list of matching contacts (or "no matches"). User can then ask to call or message one.
• Check balance: Agent reports the current USD balance. If balance is sufficient (>= $0.10 for a short call), user proceeds. If insufficient, user tops up.
• List active calls: Agent shows all currently live calls with duration and cost so far. User can decide which to monitor or end.
• End a call: Agent confirms the call is terminated. Call disappears from call.list_active within 1-2 seconds and is marked "ended" in audit logs.
• Save a contact: Agent confirms the contact was created or updated with id, name, number, tags. Contact is now searchable via contact.search for future calls and messages.

---

Author: robit-man (clawhub)

Additional references:

• Voxrn docs , MCP overview
• Voxrn docs , OpenClaw integration
• Voxrn API reference
• OpenClaw , outbound MCP servers