Writing the prompt

A prompt that works in a chat window frequently fails on a telephone, and it fails in ways that look like platform bugs: the agent talks for forty seconds, reads a URL out loud, or answers a question it should have refused. This page is what to write instead.

Where the prompt lives

On the first language entry, as system_prompt — not on the agent. An agent that speaks three languages has up to three prompts; the first entry's is the one everything else derives from, and a later entry that leaves its prompt empty gets one derived from the first rather than nothing.

JSON

{
  "languages": [
    { "code": "en-IN", "system_prompt": "You are …", "greeting": "Thanks for calling Acme." },
    { "code": "hi",    "voice_id": "hindi-voice",    "greeting": "नमस्ते, एक्मे।" }
  ]
}

Max 100,000 characters, which is far more than you should use. Time to first token grows faster than linearly with prompt length, so a prompt twice as long is more than twice as slow to start — see latency.

The shape that works

Five sections, in this order. The order matters more than the wording: a model reads the top of a prompt more reliably than the middle, so the constraint you cannot afford to have ignored goes early, not in a list of twenty at the bottom.

1. WHO YOU ARE      one or two sentences. Company, role, what you handle.
2. WHAT YOU DO      the task, in the order it should happen.
3. WHAT YOU NEVER DO   the refusals, stated as refusals, with the alternative.
4. HOW YOU SPEAK    length, register, what to do with numbers and spellings.
5. WHEN TO STOP     what finishing looks like, and what to do if you cannot.

You are the receptionist for Acme Clinic in Pune. You book, move and cancel
appointments, and you tell people the opening hours.

Work in this order: find out what they want, then take their name and
telephone number, then offer the two nearest free slots, then confirm
the one they choose by reading it back.

Never give medical advice, never guess at a price, and never confirm a
slot you have not read back. If you are asked something medical, say you
will take a message for the doctor and offer to do that.

Speak in short sentences — one or two at a time, never a paragraph. Read
telephone numbers back in pairs of digits. Read dates as "Tuesday the
fourteenth", not "14/10".

You are finished when the caller has a confirmed slot or has said they do
not want one. If you cannot help, offer to transfer and say who to.

Rules that only matter on a telephone

Write this	Because
"One or two sentences at a time."	A caller interrupts a long answer, which arms barge-in, which throws away the rest — so the useful half of a long reply is often the half nobody heard. Cap `max_tokens` as well; the two together are what actually keep replies short.
"Never read out a URL, an email address or a reference code unless asked twice."	They are unlistenable, and callers ask again, and now the call is ninety seconds longer.
How to say numbers.	"Read telephone numbers back in pairs" and "say amounts as rupees and paise" are the two that come up constantly. Without instruction a model will read `9876543210` as one enormous number.
"Ask one question at a time."	Two questions in one breath gets one answer, and you cannot tell which.
"If you did not understand, say so and ask them to repeat."	The alternative is a model answering the question it guessed at. On a bad line this is most turns.
What to do when it cannot help.	Unstated, a model improvises — and the improvisation is usually a promise somebody has to keep.

Refusals

Write a refusal as three things: what not to do, what to do instead, and what to say. A refusal with only the first is a model that stops and leaves a silence.

Never quote a price for anything not on the price list. Instead, say
"I do not want to quote you the wrong figure — let me have someone call
you back with an exact price," and take their number.

Using the caller's data

Anything in {{double braces}} is filled in per call, so one agent can greet ten thousand people by name. Eight are filled by the platform and never have to be sent — {{current_date}}, {{from_number}} and friends. See variables.

A call missing a variable the prompt uses is refused. That is deliberate and it is better than the alternative: an agent that says "Hello {{first_name}}" out loud to a customer. Refusals happen at POST /v1/calls, before anything is dialled.

When the prompt is not the answer

Symptom	Reach for
Confidently wrong about your own products, prices or policies	A knowledge base. No prompt fixes this — you are asking the model to remember something it never knew.
Does the steps out of order, or skips one when the caller is impatient	A flow. Each step becomes a node, and the model is only ever asked to do one step's worth of work.
Needs a fact only your systems have — an order status, a balance	A function.
You want a specific field out of every call afterwards	An extraction, not an instruction to "remember to note the budget".
Every reply is fine but the whole call is too slow	The model, then the prompt length. See latency.

Changing a prompt safely

Duplicate the agent, change the copy, place a browser call to it, and only then patch the live one. The duplicate costs nothing and takes one request.

POST/v1/agents/{id}/duplicate

Shell

curl -s -X POST https://voice.sphoro.com/v1/agents/$AGENT_ID/duplicate \
  -H "Authorization: Bearer $SPHORO_API_KEY"

Prompts are also the thing a coding assistant is genuinely good at drafting against a real schema — build with AI covers pointing one at this API.