Speko

View saved version →

---
name: speko-phone-call
description: Place a real outbound phone call through Speko and read back what was said. Use when the user wants someone actually called on the telephone — booking, confirming, chasing, asking a business a question — or wants to rehearse such a call first, or wants to review a call that already happened.
---

# Placing a phone call with Speko

Speko dials a real phone number with a voice agent, stays on the line, and returns a transcript and
a recording when the call ends. This skill covers the whole loop: decide who to call, rehearse,
confirm, dial, watch, read back.

## When this applies

Use it when the user wants a real telephone call made or reviewed. Phrases that mean this: "call
them", "ring the clinic", "book me a table", "chase the quote", "find out if they're open", "what
did they say on that call", "rehearse this call first".

Do **not** use it to send a message, an email or a text — Speko is voice on the telephone network.

## Before you dial: three things, every time

**1. Read the number back.** Say the full E.164 number out loud in your reply — `+14155550142`, not
"the dentist". A wrong digit means a stranger's phone rings.

**2. Say what the call is for.** One sentence, in the user's words, so they can catch a
misunderstanding before it is spoken to a person.

**3. Get an explicit yes.** One confirmation, one call. Never batch. If the user asks for several
numbers, take them one at a time with a separate confirmation each, and say that is what you are
doing.

If the user has not given a number — only a business name — ask for it. Do not guess a number and
do not look one up and dial it without showing it first.

## Rehearsing first

When the call matters, or the user seems unsure what the agent should say, offer
`agents.test_call` before `sessions.phone.create`. It runs the whole conversation between the agent
and a synthesized caller inside Speko, with **no phone leg at all** — nobody's phone rings. Pass
the user's goal as `objective`.

It returns session ids immediately and the conversation runs in the background. Poll `calls.get`
with the agent session id until it ends, then read `sessions.transcript.get`. Show the user that
transcript and ask whether to make the real call.

## Making the call

Use `sessions.phone.create`. The body needs `to` in E.164 form, plus either an `agentId` from
`agents.list` or an `intent` naming the language — for example
`{"to": "+14155550142", "intent": {"language": "en"}}`. Put what the agent should accomplish in
`systemPrompt`.

The call opens by disclosing it is an AI. That is applied server-side and is not yours to remove or
soften; if the user asks you to hide it, say plainly that Speko always discloses.

If the account owns more than one number, `phone_numbers.list` shows which ones can be used as
`from`. Leave it unset to use the default.

Calls are recorded by default, and `sessions.recording.get` returns the audio afterwards. Say so
when you confirm the call — "this will be recorded" — because many places require everyone on a
call to know. If the user would rather not have a recording, say that recording is controlled in
the Speko dashboard rather than from here.

## Watching and reading back

`sessions.phone.create` returns a session id and comes back before the call is over. Poll
`sessions.get` with that id. When it has ended:

- `sessions.transcript.get` — what was actually said, both sides
- `sessions.recording.get` — a signed URL to the audio

Summarise the outcome first — did the thing the user wanted happen? — then offer the transcript.
Do not paraphrase a commitment the other party did not make; quote them.

`sessions.list` finds earlier calls when the user asks about one that already happened.

## Building an agent for a repeated call

For a one-off, pass `systemPrompt` straight to `sessions.phone.create` — no agent needed. When the
user will make the same kind of call repeatedly, create one:

Call `agents.preview_stacks` with a one-l

Preview of the first 4,000 characters. Read full instructions →