spiiksi
Log ind
Documentation menu

Reference

Calls

Calls

Voice and video calls in which the agent and the customer each speak their own language and hear the other interpreted live.

A call has two sides, the agent and the customer. Each speaks their own language and hears the other interpreted into it, a couple of seconds behind, both ways at once. With video they also see each other.

Start a call#

Shell
curl https://api.spiiksi.fi/v1/calls \
  -H "Authorization: Bearer $SPIIKSI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_language": "fi", "agent_name": "Acme Support",
       "customer_language": "es", "customer_name": "Lucía",
       "video": true, "external_id": "ticket-1234",
       "metadata": {"queue": "billing"}}'
JSON
{"id": "6f0c…", "status": "open", "livemode": true,
 "agent_name": "Acme Support", "agent_language": "fi",
 "customer_name": "Lucía", "customer_language": "es", "video": true,
 "external_id": "ticket-1234", "metadata": {"queue": "billing"},
 "agent_url": "https://spiiksi.fi/call/6f0c…#k=…",
 "customer_url": "https://spiiksi.fi/call/6f0c…#k=…",
 "created_at": "2026-10-08T09:00:00", "ended_at": null}
FieldNotes
agent_languageRequired. The language the agent speaks and hears, such as en, fi or pt-BR.
customer_languageLeave it out and the customer chooses theirs when they open the link.
videoWhether the two may see each other. The voices are interpreted either way.
external_id, metadataYour references, handed back with every webhook about the call.

The two links#

agent_url and customer_url open each side's call page. They are only in this answer: keep them, or make new ones later with POST /v1/calls/{id}/link.

  • Send customer_url to the customer: a text message, an email, your chat, your app.
  • Open agent_url for the agent, in a new tab or inside your own page with the JavaScript SDK.

Each link carries its side's key after #k=. The fragment isn't sent to servers or put in referrers. Anyone with a link speaks for that side, so treat links like passwords. A new link replaces the old one, and its microphone goes off the air.

The call page needs no account and no app: a browser with a microphone (and a camera, for video). The customer picks their language if it wasn't set, then starts a voice or video call. The call starts as soon as both sides are there.

During the call#

  • Interpretation runs both ways at once. Each side hears only the other's interpretation, never their original voice, with live captions.
  • Echo. On loudspeakers, the interpretation a person hears could reach their microphone. Unless they say they wear headphones, their microphone sends silence while the interpretation plays, so they speak in turns.
  • Video goes straight between the two browsers, without the voices. On strict networks it may not connect; the interpreted voice still does.
  • Quiet. A side that is silent for a minute stops being interpreted, and billed, until it speaks again.

End a call#

Shell
curl -X POST https://api.spiiksi.fi/v1/calls/$CALL_ID/end -H "Authorization: Bearer $SPIIKSI_KEY"

Both pages say the call has ended, the links stop working, and interpretation and billing stop. The agent can end it from their page too. A customer who leaves can come back with the same link until the call ends.

Find calls#

Shell
curl "https://api.spiiksi.fi/v1/calls?status=open&external_id=ticket-1234" \
  -H "Authorization: Bearer $SPIIKSI_KEY"

Calls are listed newest first, up to 100 at a time.

Other ways in#

Pricing#

A call is billed like live interpretation: per minute for each side while that side's interpretation runs, at your organization's prices. Languages served by the Default engine cost less than those that need the Plus engine. A quiet side pauses after a minute and isn't billed until it speaks again.