Make a call

Two objects and one command. Create an agent — the configuration that decides how the conversation goes — then place a call that runs it. Everything below assumes $SPHORO_API_KEY is set from step 1.

Step 1 · Create an agent

An agent is long-lived: create it once and place as many calls with it as you like. The only two things it insists on are a name and one language carrying the instructions it follows.

AGENT_ID=$(curl -s -X POST https://voice.sphoro.com/v1/agents \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Clinic reception",
    "languages": [{
      "code": "en-IN",
      "system_prompt": "You are a receptionist for Acme Clinic. Answer questions about opening hours and appointments. Keep answers to one or two sentences.",
      "greeting": "Thanks for calling Acme Clinic. How can I help?"
    }]
  }' | jq -r .id)

echo $AGENT_ID
# agt_7f3ab2c19e4d

const res = await fetch("https://voice.sphoro.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPHORO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Clinic reception",
    languages: [{
      code: "en-IN",
      system_prompt:
        "You are a warm, efficient receptionist for Acme Clinic. Answer questions about " +
        "opening hours and appointments. Keep every answer to one or two sentences.",
      greeting: "Thanks for calling Acme Clinic. How can I help?",
    }],
  }),
});

const agent = await res.json();
console.log(agent.id); // agt_7f3ab2c19e4d

import os, json, urllib.request

body = json.dumps({
    "name": "Acme Clinic reception",
    "languages": [{
        "code": "en-IN",
        "system_prompt": (
            "You are a warm, efficient receptionist for Acme Clinic. Answer questions "
            "about opening hours and appointments. Keep every answer to one or two sentences."
        ),
        "greeting": "Thanks for calling Acme Clinic. How can I help?",
    }],
}).encode()

req = urllib.request.Request(
    "https://voice.sphoro.com/v1/agents",
    data=body,
    headers={
        "Authorization": "Bearer " + os.environ["SPHORO_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as res:
    agent = json.load(res)

print(agent["id"])  # agt_7f3ab2c19e4d

{
  "id": "agt_7f3ab2c19e4d",
  "object": "agent",
  "name": "Acme Clinic reception",
  "languages": [{
    "code": "en-IN",
    "system_prompt": "You are a receptionist for Acme Clinic. Answer questions...",
    "greeting": "Thanks for calling Acme Clinic. How can I help?"
  }],
  "model": "claude-sonnet-5",
  "temperature": 0.6,
  "max_tokens": 512,
  "speed": 1,
  "pitch": 1,
  "created_at": "2026-08-18T09:12:44Z"
}

Keep the id. It is the one thing every call needs.

Every field an agent takes

Two are required. The rest have the defaults shown above, and every one of them can be changed later with PATCH /v1/agents/{id} without touching the others.

Step 2 · Place the call

One request. It returns immediately with a queued call — dialling, ringing and answering happen after the response, and you hear about them through events or webhooks.

CALL_ID=$(curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"to\": \"+919876543210\"
  }" | jq -r .id)

echo $CALL_ID
# call_1d8e4c7b9a02

import { randomUUID } from "node:crypto";

const res = await fetch("https://voice.sphoro.com/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPHORO_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: agent.id,
    to: "+919876543210",
  }),
});

const call = await res.json();
console.log(call.id, call.status); // call_1d8e4c7b9a02 queued

import os, json, uuid, urllib.request

body = json.dumps({"agent_id": agent["id"], "to": "+919876543210"}).encode()

req = urllib.request.Request(
    "https://voice.sphoro.com/v1/calls",
    data=body,
    headers={
        "Authorization": "Bearer " + os.environ["SPHORO_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as res:
    call = json.load(res)

print(call["id"], call["status"])  # call_1d8e4c7b9a02 queued

{
  "id": "call_1d8e4c7b9a02",
  "object": "call",
  "agent_id": "agt_7f3ab2c19e4d",
  "status": "queued",
  "direction": "outbound",
  "from": "+911140848000",
  "to": "+919876543210",
  "language": "en-IN",
  "source": "sdk",
  "source_client": "sphoro-voice-node/1.0.0",
  "created_at": "2026-08-18T09:14:02Z",
  "started_at": "2026-08-18T09:14:02Z"
}

Every field a call takes

Where a call came from

Every call comes back with a source, and it is not a field you send. It is derived from the endpoint you reached and the credential you used, so nothing can file itself under the wrong one:

direction tells you which way the audio went; this tells you which of your integrations produced the call, which stops being the same question the moment you have more than one. source_client is free text and is absent when nothing named itself — read it, do not branch on it. Both are absent on calls placed before we recorded this, which is not the same as api.

Step 3 · Follow the call as it happens

Open a stream and read events as they occur — transcript turns, transfers, the end reason. It is Server-Sent Events, so curl can read it and browsers reconnect to it automatically.

curl -N https://voice.sphoro.com/v1/calls/$CALL_ID/events \
  -H "Authorization: Bearer $SPHORO_API_KEY"

id: evt_01
event: call.started
data: {"id":"evt_01","type":"call.started","call_id":"call_1d8e4c7b9a02","created_at":"2026-08-18T09:14:02Z","data":{"agent_id":"agt_7f3ab2c19e4d","direction":"outbound","to":"+919876543210","from":"+911140848000"}}

id: evt_02
event: call.transcript.updated
data: {"id":"evt_02","type":"call.transcript.updated","call_id":"call_1d8e4c7b9a02","created_at":"2026-08-18T09:14:19Z","data":{"role":"user","text":"are you open on Sunday?"}}

id: evt_03
event: call.ended
data: {"id":"evt_03","type":"call.ended","call_id":"call_1d8e4c7b9a02","created_at":"2026-08-18T09:15:31Z","data":{"duration_seconds":89.2,"turns":6,"end_reason":"completed"}}

event: done
data: {}

Three things about this stream are worth knowing before you build on it:

• It ends with an event: done frame after call.ended, so a client knows the difference between "finished" and "the connection dropped".
• Every frame carries an id. Reconnect with Last-Event-ID set to the last one you saw and you get everything you missed, rather than a gap.
• A comment line arrives every 15 seconds during a quiet call, which is what stops a proxy idling the connection out.

This stream is for watching one call you are already holding open — a live UI, or a terminal while you test. For a server that needs to know about every call without holding a connection per call, use webhooks instead.

Step 4 · Read the result

Once the call is over, fetch it. The record carries how it ended, how long it lasted, and the whole conversation.

curl -s https://voice.sphoro.com/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $SPHORO_API_KEY"

{
  "id": "call_1d8e4c7b9a02",
  "object": "call",
  "agent_id": "agt_7f3ab2c19e4d",
  "status": "completed",
  "direction": "outbound",
  "from": "+911140848000",
  "to": "+919876543210",
  "language": "en-IN",
  "started_at": "2026-08-18T09:14:02Z",
  "ended_at": "2026-08-18T09:15:31Z",
  "duration_seconds": 89.2,
  "end_reason": "completed",
  "source": "sdk",
  "source_client": "sphoro-voice-node/1.0.0",
  "turns": 6,
  "transcript": [
    { "role": "agent", "text": "Thanks for calling Acme Clinic. How can I help?", "at": "2026-08-18T09:14:11Z" },
    { "role": "user",  "text": "are you open on Sunday?", "at": "2026-08-18T09:14:19Z", "latency_ms": 640 }
  ],
  "recording_url": "https://voice.sphoro.com/v1/calls/call_1d8e4c7b9a02/recording"
}

Just the transcript

The same conversation without the rest of the record, which is what you want if you are rendering it in a UI:

curl -s https://voice.sphoro.com/v1/calls/$CALL_ID/transcript \
  -H "Authorization: Bearer $SPHORO_API_KEY"

{
  "object": "transcript",
  "call_id": "call_1d8e4c7b9a02",
  "status": "completed",
  "turns": 6,
  "entries": [ ... ]
}

Each entry carries a role of user, agent or tool; the text; when it was said; and, on the caller's turns, latency_ms — how long the agent took to start answering. An entry with "source": "keypad" was typed on the keypad rather than spoken, which matters because "1" pressed and "one" said arrive as the same string.

The recording

Only if the agent was created with record_calls: true. The endpoint streams the audio itself, authenticated the same way as everything else:

curl -s https://voice.sphoro.com/v1/calls/$CALL_ID/recording \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -o call.wav

A call with no recording answers 404 and not_found rather than an empty file.

What each call status means

And why it ended

end_reason is the field to branch on, not status. Reaching voicemail and reaching the customer both end a call the same way.

Ending a call early

Hangs up the phone leg as well as closing the conversation. Both matter: closing only our side leaves a carrier leg up, and you are billed for every minute of it.

curl -s -X POST https://voice.sphoro.com/v1/calls/$CALL_ID/end \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"customer_requested"}'

reason is optional and is stored as the call's end_reason; omit it and you get ended_by_api.

Listing calls

Newest first, cursor-paginated like every list on the API. Two filters, applied before pagination — so ?status=failed pages through failures rather than through the first page of everything.

curl -s "https://voice.sphoro.com/v1/calls?status=failed&limit=20" \
  -H "Authorization: Bearer $SPHORO_API_KEY"

curl -s "https://voice.sphoro.com/v1/calls?agent_id=$AGENT_ID" \
  -H "Authorization: Bearer $SPHORO_API_KEY"

List responses omit transcripts — fetch a single call for those. Paging is covered in step 2.

Calling on somebody’s behalf

One agent serves your whole team. That is the point of it — fifty people who make the same kind of call share one prompt, one voice and one set of documents, and you maintain one thing instead of fifty. But an agent is a configuration, not a person, so a call placed through it says nothing about who made it.

If your own system dials on a colleague’s behalf — a CRM with a click-to-call button, a collections queue, a callback worker — send member_id:

curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"to\": \"+919876543210\",
    \"member_id\": \"$MEMBER_ID\"
  }"

Two things follow, and both are what the console already does for somebody signed in:

• The caller ID becomes their own number — whichever of your numbers is assigned to them on the Phone numbers page. So when the person they rang calls back, it reaches them and not a colleague. Without this the call goes out on the agent’s rotation, and the callback lands wherever that rotation pointed.
• The call is attributed to them — member_id comes back on the call and on every webhook, and the call appears in that person’s own history rather than the account’s.

An explicit from still wins over both. If your system has already decided which number to present, that decision is not overruled by a seat it does not know about — and the call is still attributed.

Personalising a single call

Write {{placeholders}} into a language's prompt or greeting, then fill them per call. This is how one agent serves every customer without a prompt per customer.

{
  "languages": [
    {
      "code": "en-IN",
      "system_prompt": "You are confirming an appointment for {{first_name}} on {{date}} at {{time}}.",
      "greeting": "Hello {{first_name}}, this is Acme Clinic calling about your appointment on {{date}}."
    }
  ]
}

curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"to\": \"+919876543210\",
    \"variables\": {
      \"first_name\": \"Priya\",
      \"date\": \"Thursday the 21st\",
      \"time\": \"4:30 in the afternoon\"
    }
  }"

Write values the way they should be spoken. "4:30 in the afternoon" is read back correctly; "16:30" is a coin toss. The same goes for dates, amounts and reference numbers.

Variables the platform fills

Eight placeholders are not yours to supply. The platform already knows them, fills them when the call is answered, and never refuses a call for their absence — so a prompt may use them freely and a campaign spreadsheet needs no column for them.

Sending one of these in variables yourself is not an error and is not overridden: your value wins. An agent that has always filled {{current_date}} from its own spreadsheet column keeps doing exactly that.

Calling from a browser

Leave to out and you get a web call instead of a phone call: no carrier, no number, no per-minute charge, and the response carries a WebSocket URL to connect a browser to. It is the fastest way to hear an agent before a phone number is provisioned.

curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\":\"$AGENT_ID\"}"

{
  "id": "call_1d8e4c7b9a02",
  "status": "in_progress",
  "direction": "web",
  "realtime_url": "wss://voice.sphoro.com/v1/realtime?call_id=call_1d8e4c7b9a02"
}

Connect to realtime_url and exchange JSON frames. Audio travels base64-encoded in both directions.

The audio is G.711 µ-law at 8 kHz, each way. Read it off session.created rather than assuming it — that message carries input_audio_format, output_audio_format and sample_rate, and a client that hardcodes them plays noise the day a deployment negotiates something else.

Two more things a client has to get right, and both fail quietly. Pace the playback — queue the arriving frames and let the audio clock drain them, because writing a long buffer out as fast as it arrives ends the agent’s turn early and takes barge-in with it. And when the caller talks over the agent, send interrupt and empty your own buffer: the message stops the server generating, and only the flush stops the sound.

When a call will not go out

Every code above is explained in full in step 2.

Check it before you move on

• The call connected, and end_reason was completed.
• The transcript shows both sides of the conversation.
• You are sending an Idempotency-Key on every POST that dials.

Next: step 4 makes it speak the right language in the right voice.