speko-calls

name

speko-calls

description

Place and monitor outbound AI phone calls through Speko. This skill dials real telephone numbers and costs real money, so it reads its own environment variable and asks the user to confirm the number and the purpose before every call. Use when explicitly asked to call someone, ring a number, run an outbound voice campaign, or check the status, recording or transcript of a call that was already placed. For transcription, speech synthesis or model routing with no dialing involved, use the speko skill instead.

Speko calls

This skill dials real phones. Treat every call as irreversible: it rings a physical device, it can reach a stranger, it is billed, and it cannot be recalled once connected.

It is deliberately separate from the speko skill. Speech, transcription and model routing place no calls; dialing is irreversible and billed. One Speko key covers both, so the split is enforced by the environment rather than by the credential: this skill reads a second variable that a speech-only setup has no reason to set.

Nothing in Cursor gates this skill on that variable being present. If SPEKO_PLATFORM_API_KEY is not in the environment, every command below has nothing to send and no call is placed. The confirmation steps in the next section are mandatory regardless.

The hosted Speko MCP shipped with this plugin exposes the same telephony surface as tools (sessions.phone_create, calls.get, sessions.transcript_get, phone_numbers.list). The same four confirmations apply to those tools — the guardrail is about dialing, not about which transport reached the API.

Credential

SPEKO_PLATFORM_API_KEY — your Speko key from the dashboard, on the platform host https://api.speko.dev/v1.

It is the same key the speko skill uses on the router host; the second variable name is the gate, so set it only where dialing is approved. Keys are environment-scoped, so a staging key fails against production.

Only supply this key in an environment where dialing is approved, audited and expected. If it is absent, this skill is not eligible and no calling instruction is in play.

Before every call

Do all four. Do not skip one because the request looked explicit.

1. State the number back in full E.164 and get an unambiguous yes. Never dial a number you inferred, completed, or guessed a country code for.
2. State the purpose — what the agent will say and why — and get agreement on it.
3. Check the hour at the destination. Do not cold-call outside normal waking hours.
4. Stop at one call unless the user asked for more, by number, one at a time. Never loop over a list without per-number confirmation.

Refuse, and say plainly why, if the request is to dial an emergency line, a premium-rate number, a number the user does not appear to have a relationship with, or any recipient at volume. Decline impersonation of a real person or organisation on the call.

List the numbers you can call from

curl -s https://api.speko.dev/v1/phone-numbers \
  -H "Authorization: Bearer $SPEKO_PLATFORM_API_KEY" | jq '.[] | {id, e164, direction}'

Returns a bare JSON array, not an object. The path is kebab-case — /v1/phone_numbers 404s. from on a call must be a number the organisation owns. If it owns exactly one outbound number, use it; if several, ask which; if none, say one has to be provisioned first.

Place the call

curl -s https://api.speko.dev/v1/sessions/phone \
  -H "Authorization: Bearer $SPEKO_PLATFORM_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "to": "[phone]",
    "from": "[phone]",
    "intent": { "language": "en" },
    "systemPrompt": "You are calling to confirm a delivery window. Be brief.",
    "firstMessage": "Hi, this is an assistant calling about your delivery."
  }'

Only to is required and it is regex-checked as E.164. Supply either agentId for a pre-built agent or intent for an ad-hoc call — an ad-hoc call needs no agent created in advance. Also accepts voice, telephony, llm, ttsOptions, sttOptions, webhookTags and metadata. Returns {sessionId, callControlId, roomName, status, to, from}.

To prove a request body without ringing anyone, post it with a deliberately invalid to and read the validation error, or with a bogus agentId for a 404 AGENT_NOT_FOUND. Do that first when you are unsure about the shape.

Follow the call

curl -s https://api.speko.dev/v1/calls/$ID \
  -H "Authorization: Bearer $SPEKO_PLATFORM_API_KEY" | jq '{status, duration_seconds, ended_at}'

curl -s https://api.speko.dev/v1/calls/$ID/report \
  -H "Authorization: Bearer $SPEKO_PLATFORM_API_KEY" | jq '{summary, outcome, cost_micro_usd}'

Call ids are UUIDs. /report carries summary, outcome, structured_data, a turn-by-turn transcript.entries[], and cost. structured_data echoes the dialed number back, so anything that redacts phone numbers has to account for it too.

Gotchas

• GET /v1/calls/{unknown-id} returns 500, not 404. A 500 here usually means the id is wrong, not that the platform is down. Re-check the id before escalating.
• Validation errors are uniform: {"error":"Invalid request","code":"VALIDATION_ERROR","issues":[…]}.
• A recording may not exist yet immediately after a call ends; recording_status says so.
• Never paste this key into a shell command that gets logged. Read it from the environment.