Reference

API reference

Every public endpoint, its parameters, request body and answer, generated from the API itself. The base URL is https://api.spiiksi.fi.

Authenticate every request with Authorization: Bearer <key or token>; see Authentication. The same reference as an OpenAPI document, for code generators and API clients: openapi.json.

Account

get/v1/account

Account

The key's organization, its balance and prices. A cheap way to check a key works.

Response 200

AccountOut

Calls

get/v1/calls

List Calls

Parameters

Name	Type	Description
`status`query	"open" \| "ended" \| null
`external_id`query	string \| null	max 200 characters
`limit`query	integer	min 1 · max 100 · default 50

Response 200

array of CallOut

post/v1/calls

Create Call

Start a voice or video call in which the agent and the customer each hear the other in their own language. agent_url and customer_url open the call in a browser; given only now.

A machine client (a phone bridge, a contact center) takes part instead of a browser: GET /calls/public/{id} with the key from its link's fragment (#k=) in X-Call-Key returns the WebSockets to send that side's voice to and to hear the other side on.

Request body application/json

Name	Type	Description
`agent_language`required	string	The language the agent speaks and hears: a code such as en or fi.min 2 characters · max 12 characters
`agent_name`	string \| null	Who the customer talks to: "Acme Support", or the agent's name.max 80 characters
`customer_language`	string \| null	Leave out for the customer to pick when they join.min 2 characters · max 12 characters
`customer_name`	string \| null	The customer's name, shown to the agent.max 80 characters
`external_id`	string \| null	A note of the agent's own: the ticket, the order.max 200 characters
`metadata`	object of string \| integer \| number \| boolean \| null \| null	Handed back with every event about the call.
`video`	boolean	Whether the two may see each other; the voices are translated either way.default true

Response 201

CallCreated

get/v1/calls/{call_id}

Get Call

Parameters

Name	Type	Description
`call_id`requiredpath	string

Response 200

CallOut

post/v1/calls/{call_id}/dial

Dial

Ring a phone from the organization's Twilio number; when it is answered, the line plays side of the call. Needs the Twilio connector.

Parameters

Name	Type	Description
`call_id`requiredpath	string

Request body application/json

Name	Type	Description
`side`	"agent" \| "customer"	Which side the phone plays; usually the customer.default "customer"
`to`required	string	The phone number to ring, in international form: +358401234567.

Response 200

DialOut

post/v1/calls/{call_id}/end

End Call

End the call for both sides; translation and billing stop.

Parameters

Name	Type	Description
`call_id`requiredpath	string

Response 200

CallOut

post/v1/calls/{call_id}/link

New Call Link

A new link for one side; their old one, and its microphone, stop working.

Parameters

Name	Type	Description
`call_id`requiredpath	string

Request body application/json

Name	Type	Description
`side`required	"agent" \| "customer"	Which side's link to replace.

Response 200

CallLinkOut

post/v1/calls/{call_id}/phone-line

Phone Line

A line id for a PBX to join side through Asterisk AudioSocket. A new id replaces the side's old one.

Parameters

Name	Type	Description
`call_id`requiredpath	string

Request body application/json

Name	Type	Description
`side`	"agent" \| "customer"	default "customer"

Response 200

PhoneLineOut

Joining a call

get/calls/public/{call_id}

Join

Who the call is with, and once both languages are known, where to send this side's voice and where to hear the other side.

Parameters

Name	Type	Description
`call_id`requiredpath	string
`x-call-key`header	string \| null

Response 200

app__schemas__call__JoinOut

post/calls/public/{call_id}/end

Hang Up

The agent ends the call for both. A customer who hangs up only leaves, and can come back with the same link.

Parameters

Name	Type	Description
`call_id`requiredpath	string
`x-call-key`header	string \| null

Response 200

app__schemas__call__JoinOut

patch/calls/public/{call_id}/me

My Settings

This side's language, or name. The other side's page hears to reconnect, so its voice is translated into the new language.

Parameters

Name	Type	Description
`call_id`requiredpath	string
`x-call-key`header	string \| null

Request body application/json

Name	Type	Description
`language`	string \| null	min 2 characters · max 12 characters
`name`	string \| null	min 1 characters · max 80 characters

Response 200

app__schemas__call__JoinOut

Support chats

get/v1/sessions

List Sessions

Sessions, newest first; by your own reference with external_id.

Parameters

Name	Type	Description
`status`query	"open" \| "closed" \| null
`external_id`query	string \| null	max 200 characters
`limit`query	integer	min 1 · max 100 · default 50

Response 200

array of SessionOut

post/v1/sessions

Create Session

Open a session. customer_url is the customer's link to the chat; it is given only now.

Request body application/json

Name	Type	Description
`agent_language`required	string	The language the agents read and write.min 2 characters · max 12 characters
`agent_name`	string \| null	Shown to the customer as who they talk to: "Acme Support".max 80 characters
`customer_language`	string \| null	Leave out to learn it from the customer's first message.min 2 characters · max 12 characters
`customer_name`	string \| null	The customer's name, shown to the agents.max 80 characters
`external_id`	string \| null	Your own reference: a ticket, chat or call id.max 200 characters
`metadata`	object of string \| integer \| number \| boolean \| null \| null	Handed back with every event about the session.
`retention_days`	integer \| null	Days the messages are kept.min 1 · max 365

Response 201

SessionOut

get/v1/sessions/{session_id}

Get Session

Parameters

Name	Type	Description
`session_id`requiredpath	string

Response 200

SessionOut

delete/v1/sessions/{session_id}

Delete Session

Erase a session and everything said in it, for good.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Response 204

No content.

post/v1/sessions/{session_id}/close

Close Session

End the session: nobody can post, and the customer's page says so. The messages are kept their retention days.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Response 200

SessionOut

post/v1/sessions/{session_id}/customer-link

New Customer Link

A new link for the customer; the one given before stops working.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Response 200

SessionOut

get/v1/sessions/{session_id}/messages

List Messages

Messages after the id after, oldest first; the latest ones when after is 0.

Parameters

Name	Type	Description
`session_id`requiredpath	string
`after`query	integer	min 0 · default 0
`limit`query	integer	min 1 · max 200 · default 100

Response 200

ApiMessagesOut

post/v1/sessions/{session_id}/messages

Post Message

Post what an agent or the customer wrote. It comes back translated for the other side: customer_text for the customer, agent_text for the agents.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Request body application/json

Name	Type	Description
`author_name`	string \| null	Who wrote it, shown to the other side: the agent's own name.max 80 characters
`language`	string \| null	The language it is written in, when you know; detected otherwise.min 2 characters · max 12 characters
`sender`required	"agent" \| "customer"	Who wrote it: an agent or the customer.
`text`required	string	The message, as written (up to 4,000 characters).min 1 characters · max 4000 characters

Response 201

ApiMessageOut

get/v1/sessions/{session_id}/stream

Session Stream

The session's events as they happen (server-sent events).

Parameters

Name	Type	Description
`session_id`requiredpath	string

Response 200

A stream of server-sent events (text/event-stream).

post/v1/sessions/{session_id}/typing

Typing

Show the other side that someone is writing.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Request body application/json

Name	Type	Description
`author_name`	string \| null	max 80 characters
`sender`required	"agent" \| "customer"	Who is typing.

Response 204

No content.

post/v1/sessions/{session_id}/voice

Post Voice

Post a recording of what an agent or the customer said (up to two minutes: WebM, Ogg, MP4/M4A, MP3 or WAV). Billed per minute.

Parameters

Name	Type	Description
`session_id`requiredpath	string

Request body multipart/form-data

Name	Type	Description
`audio`required	string
`author_name`	string \| null	max 80 characters
`sender`required	"agent" \| "customer"

Response 201

ApiMessageOut

Text translation

post/v1/translate

Translate

Translate one text, or up to 100 in one go, into target. Billed per character actually translated: text already in the target language is free.

Request body application/json

Name	Type	Description
`context`	string \| null	A sentence on where the text comes from, to steer the wording: "Replies from a bicycle shop's support team".max 500 characters
`glossary`	object of string \| null	Your own terms and how to render them: {"Spiiksi": "Spiiksi"}.
`source`	string \| null	Leave out to have it detected.min 2 characters · max 12 characters
`target`required	string	The language to translate into: a code such as en, fi or pt-BR.min 2 characters · max 12 characters
`text`required	string \| array of string	One text, or a list of up to 100, each up to 10,000 characters (50,000 in all).

Response 200

TranslateOut

Live events

get/v1/events

Org Stream

Response 200

A stream of server-sent events (text/event-stream).

OAuth

get/.well-known/oauth-authorization-server

Metadata

Where everything is (RFC 8414).

Response 200

JSON.

post/oauth2/revoke

Revoke

Revoke an access or refresh token, and with it the app's connection (RFC 7009). Answers 200 whatever the token was.

Request body application/x-www-form-urlencoded

Name	Type	Description
`token`required	string

Response 200

JSON.

post/oauth2/token

Token

Trade a code, or a refresh token, for tokens (RFC 6749). The app authenticates with its secret (Basic or in the form), or, for a code with a PKCE challenge, with the verifier alone.

Request body application/x-www-form-urlencoded

Name	Type	Description
`client_id`	string \| null
`client_secret`	string \| null
`code`	string \| null
`code_verifier`	string \| null
`grant_type`required	string
`redirect_uri`	string \| null
`refresh_token`	string \| null

Response 200

JSON.

Schemas

AccountOut

Name	Type	Description
`balance`	number \| null	Prepaid organizations pay from this; null for the invoiced.
`currency`required	string
`mode`	string	"live" or "test": the mode of the key (an app is always live).default "live"
`org_id`required	string
`org_name`required	string
`scopes`	array of string	What the key or app may do.
`text_rate_per_million_characters`required	number	Excluding VAT.
`voice_rate_per_minute`required	number

ApiCallCreate

Name	Type	Description
`agent_language`required	string	The language the agent speaks and hears: a code such as en or fi.min 2 characters · max 12 characters
`agent_name`	string \| null	Who the customer talks to: "Acme Support", or the agent's name.max 80 characters
`customer_language`	string \| null	Leave out for the customer to pick when they join.min 2 characters · max 12 characters
`customer_name`	string \| null	The customer's name, shown to the agent.max 80 characters
`external_id`	string \| null	A note of the agent's own: the ticket, the order.max 200 characters
`metadata`	object of string \| integer \| number \| boolean \| null \| null	Handed back with every event about the call.
`video`	boolean	Whether the two may see each other; the voices are translated either way.default true

ApiMessageIn

Name	Type	Description
`author_name`	string \| null	Who wrote it, shown to the other side: the agent's own name.max 80 characters
`language`	string \| null	The language it is written in, when you know; detected otherwise.min 2 characters · max 12 characters
`sender`required	"agent" \| "customer"	Who wrote it: an agent or the customer.
`text`required	string	The message, as written (up to 4,000 characters).min 1 characters · max 4000 characters

ApiMessageOut

Name	Type	Description
`agent_text`required	string	What each side reads.
`author_name`required	string
`created_at`required	date-time
`customer_text`required	string
`id`required	integer
`kind`required	string
`language`	string \| null	The language it was written or spoken in.
`sender`required	"agent" \| "customer"
`session_id`required	string
`text`required	string	As written or said.
`translations`	object of string	By base language code.

ApiMessagesOut

Name	Type	Description
`cursor`required	integer	The last message's id: ask for what comes after it.
`messages`required	array of ApiMessageOut

CallCreated

Name	Type	Description
`agent_language`required	string
`agent_name`required	string
`agent_url`required	string	Each side's own link. Shown only now: keep them.
`created_at`required	date-time
`customer_language`	string \| null	Null until the customer picks it.
`customer_name`	string \| null
`customer_url`required	string
`ended_at`	date-time \| null
`external_id`	string \| null
`id`required	string
`livemode`	boolean	False for a call made in test mode.default true
`metadata`	object
`status`required	string	'open', or 'ended' once the agent or the API ended it.
`support_session_id`	string \| null
`video`required	boolean

CallLinkIn

Name	Type	Description
`side`required	"agent" \| "customer"	Which side's link to replace.

CallLinkOut

Name	Type	Description
`url`required	string	The side's new link; their old one stops working.

CallOut

Name	Type	Description
`agent_language`required	string
`agent_name`required	string
`created_at`required	date-time
`customer_language`	string \| null	Null until the customer picks it.
`customer_name`	string \| null
`ended_at`	date-time \| null
`external_id`	string \| null
`id`required	string
`livemode`	boolean	False for a call made in test mode.default true
`metadata`	object
`status`required	string	'open', or 'ended' once the agent or the API ended it.
`support_session_id`	string \| null
`video`required	boolean

CallSettingsIn

Name	Type	Description
`language`	string \| null	min 2 characters · max 12 characters
`name`	string \| null	min 1 characters · max 80 characters

DialIn

Name	Type	Description
`side`	"agent" \| "customer"	Which side the phone plays; usually the customer.default "customer"
`to`required	string	The phone number to ring, in international form: +358401234567.

DialOut

Name	Type	Description
`twilio_call_sid`required	string

ListenOut

Where this side hears the other, translated: a WebSocket at {path}?unlock={unlock}, sending WAV chunks (24 kHz mono PCM16) as binary frames and JSON text frames (captions, provenance).

Name	Type	Description
`channel_id`required	string
`path`required	string
`unlock`required	string

PhoneLineIn

Name	Type	Description
`side`	"agent" \| "customer"	default "customer"

PhoneLineOut

Name	Type	Description
`audiosocket_id`required	string	Pass this to AudioSocket in the PBX's dialplan: AudioSocket(<audiosocket_id>,<host>:<port>)
`host`required	string
`port`required	integer

SessionCreate

Name	Type	Description
`agent_language`required	string	The language the agents read and write.min 2 characters · max 12 characters
`agent_name`	string \| null	Shown to the customer as who they talk to: "Acme Support".max 80 characters
`customer_language`	string \| null	Leave out to learn it from the customer's first message.min 2 characters · max 12 characters
`customer_name`	string \| null	The customer's name, shown to the agents.max 80 characters
`external_id`	string \| null	Your own reference: a ticket, chat or call id.max 200 characters
`metadata`	object of string \| integer \| number \| boolean \| null \| null	Handed back with every event about the session.
`retention_days`	integer \| null	Days the messages are kept.min 1 · max 365

SessionOut

Name	Type	Description
`agent_language`required	string
`agent_name`required	string
`closed_at`	date-time \| null
`created_at`required	date-time
`customer_language`	string \| null	Null until the customer's language is known.
`customer_last_seen_at`	date-time \| null
`customer_name`	string \| null
`customer_url`	string \| null	The link that opens the chat for the customer. Only when a link is made: keep it, it can't be read back.
`external_id`	string \| null
`id`required	string
`livemode`	boolean	False for a session made in test mode.default true
`metadata`	object
`retention_days`	integer \| null
`status`required	string

StreamOut

Where this side sends its voice: a WebSocket on the API's address, {path}?token={token}&source_id={source_id}, taking binary frames of mono 16-bit little-endian PCM at 24 kHz.

Name	Type	Description
`channel_id`required	string
`path`required	string
`source_id`required	string
`token`required	string

TranslateIn

One text, or a list translated in the same order.

Name	Type	Description
`context`	string \| null	A sentence on where the text comes from, to steer the wording: "Replies from a bicycle shop's support team".max 500 characters
`glossary`	object of string \| null	Your own terms and how to render them: {"Spiiksi": "Spiiksi"}.
`source`	string \| null	Leave out to have it detected.min 2 characters · max 12 characters
`target`required	string	The language to translate into: a code such as en, fi or pt-BR.min 2 characters · max 12 characters
`text`required	string \| array of string	One text, or a list of up to 100, each up to 10,000 characters (50,000 in all).

TranslateOut

Name	Type	Description
`characters_billed`required	integer	Characters of source text a model translated (and that were billed).
`charged`required	number	What the request cost, in `currency`, excluding VAT.
`currency`required	string
`target`required	string
`translations`required	array of TranslationOut

TranslationOut

Name	Type	Description
`detected_source_language`	string \| null	The language the text was written in.
`text`required	string	The translation, or the text itself when it was already in the target language.
`translated`required	boolean	False when it was already in the target language (and cost nothing).

TypingIn

Name	Type	Description
`author_name`	string \| null	max 80 characters
`sender`required	"agent" \| "customer"	Who is typing.

appschemascall__JoinOut

Name	Type	Description
`company`required	string	The organization the call is with.
`ice_servers`	array of object	RTCIceServer entries for the video connection.
`id`required	string
`listen`	ListenOut \| null
`my_language`	string \| null
`my_name`	string \| null
`other_language`	string \| null
`other_name`	string \| null
`ready`required	boolean	Both languages are known and the call is open: `stream` and `listen` are given.
`role`required	"agent" \| "customer"	Which side this key opens.
`status`required	string
`stream`	StreamOut \| null
`video`required	boolean