Realtime API

Realtime transport pro agenty Siesta AI

Realtime API umožňuje externí aplikaci vytvořit krátkodobou relaci agenta Siesta AI, otevřít WebSocket a streamovat události poskytovatele prostřednictvím Siesta AI. Použijte to pro zážitky ve stylu hlasu, živé rozhraní agentů, veřejné widgety a klienty, kteří potřebují reagovat na přepisy, provádění nástrojů, stavy schválení a trvalé události konverzace, jakmile se stanou.

Odkaz na veřejné API v1

POST

/api/v1/Agent/{agentId}/realtime-sessionVytvořte jednorázovou relaci v reálném čase.

GET

/api/v1/Agent/{agentId}/realtimeOtevřete WebSocket s conversationId a sessionId.

Serverová smlouvaRelace vytvořená na backenduPoužijte X-Api-Key a X-Org-Id pouze na důvěryhodném serveru.

Životní cyklus relaceJednorázový tokenVrácený sessionId je krátkodobý a je spotřebován, když se socket připojí.

Výchozí hodnoty v reálném časeModel a audioRelace v reálném čase mají jako výchozí hodnotu gpt-realtime-2 a pcm16.

Co tato API dělá

API vytváří relaci v reálném čase pro konkrétní konverzaci agenta Siesta AI a zprostředkovává provoz mezi vaším klientem a nakonfigurovaným poskytovatelem v reálném čase. Siesta AI vkládá systémové pokyny agenta, backendové nástroje, volitelné klientské nástroje, nastavení zvuku, nastavení přepisu a trvalost konverzace.

Konverzace v reálném čase: streamujte audio a události poskytovatele přes WebSocket po vytvoření jednorázové relace.
Backendové nástroje: nástroje nakonfigurované na agentovi Siesta AI jsou prováděny Siesta AI a hlášeny prostřednictvím vlastních událostí.
Klientské nástroje: vaše aplikace může vystavit místní funkce modelu a provádět je uvnitř klienta.
Trvalost konverzace: přepisy, odpovědi asistenta, stav nástrojů a stav sub-agenta mohou být trvale uloženy zpět do konverzace Siesta AI.

Token relace v reálném čase je krátkodobý a jednorázový. Vytvořte relaci ihned před otevřením WebSocketu.

Rychlý start

Vytvořte relaci v reálném čase pomocí POST /api/v1/Agent/{agentId}/realtime-session.
Připojte se k wss://{api-host}{webSocketPath}.
Odesílejte standardní události klienta poskytovatele v reálném čase.
Směrujte příchozí zprávy podle nejvyššího type.
Provádějte deklarované klientské nástroje lokálně.
Pro schválení backendových nástrojů odešlete approval.approve nebo approval.reject.
Pokud relace vyprší, je spotřebována nebo se odpojí, vytvořte novou relaci.

Autentizace

Udržujte externí API klíč na serverové straně.Vytvářejte relace v reálném čase ze svého backendu a vraťte pouze webSocketPath do prohlížeče.

Endpoint pro vytváření HTTP relací je autentizován pomocí externích API hlaviček:

X-Api-Key: <externí-api-klíč>
X-Org-Id: <organizace-id>

Endpoint WebSocket nepoužívá X-Api-Key. Je autorizován krátkodobým jednorázovým sessionId, který je vložen do vráceného webSocketPath.

Nedávejte X-Api-Key do kódu prohlížeče. Klientské prohlížeče by měly volat důvěryhodný backend, a ten by měl vytvořit relaci v reálném čase. Prohlížeč by měl přijímat pouze vrácený webSocketPath.

Vytvoření relace v reálném čase

POST

/api/v1/Agent/{agentId}/realtime-sessionVrací sessionId, conversationId, metadata vypršení, podporované formáty a webSocketPath.

POST /api/v1/Agent/{agentId}/realtime-session
Content-Type: application/json
X-Api-Key: <externí-api-klíč>
X-Org-Id: <organizace-id>

Pokud je conversationId vynecháno, Siesta AI vytvoří novou konverzaci pro agenta. Pokud je poskytnuto, musí patřit stejnému agentovi.

Tělo požadavku

Vlastnost	Typ	Výchozí	Popis
`conversationId`	`uuid \| null`	`null`	Existující id konverzace. Vynechte pro vytvoření nové konverzace.
`inputAudioFormat`	`string`	`pcm16`	Požadovaný formát vstupního audia.
`outputAudioFormat`	`string`	`pcm16`	Požadovaný formát výstupního audia.
`voice`	`string`	`alloy`	Hlas poskytovatele používaný pro výstupní audio.
`additionalInstructions`	`string \| null`	`null`	Další pokyny připojené po systémové zprávě agenta pro tuto relaci.
`clientTools`	`array`	`[]`	Nástroje prováděné vaším klientem, nikoli Siesta AI.

Příklad požadavku

POST /api/v1/Agent/3f67ef24-3f96-4c20-a3b3-5fd0abef15a1/realtime-session HTTP/1.1
Host: api.siesta.ai
Content-Type: application/json
X-Api-Key: VÁŠ_EXTERNÍ_API_KLÍČ
X-Org-Id: 4bdaed95-19f8-47c2-bbf0-8a476cf0a527

{
  "inputAudioFormat": "pcm16",
  "outputAudioFormat": "pcm16",
  "voice": "alloy",
  "additionalInstructions": "Udržujte odpovědi krátké a pokládejte jednu otázku najednou.",
  "clientTools": [
    {
      "name": "open_booking_calendar",
      "description": "Otevřete rezervační kalendář pro požadovaný datum.",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Datum ve formátu YYYY-MM-DD."
          }
        },
        "required": ["date"]
      }
    }
  ]
}

Tělo odpovědi

Vlastnost	Typ	Popis
`sessionId`	`string`	Jednorázový token použitý k připojení k WebSocketu v reálném čase.
`conversationId`	`uuid`	Id konverzace používané touto relací v reálném čase.
`expiresAt`	`datetime`	UTC čas vypršení pro otevření WebSocketu. Výchozí TTL je 60 sekund.
`webSocketPath`	`string`	Relativní cesta WebSocketu pro připojení.
`supportedInputAudioFormats`	`string[]`	Vstupní formáty podporované nasazením.
`supportedOutputAudioFormats`	`string[]`	Výstupní formáty podporované nasazením.
`maxSessionSeconds`	`number`	Maximální doba trvání relace v reálném čase vrácená klientům. Výchozí: `1800`.
`idleTimeoutSeconds`	`number`	Časový limit nečinnosti vrácený klientům. Výchozí: `60`.
`providerModelName`	`string`	Název modelu poskytovatele v reálném čase, obvykle `gpt-realtime-2`.

{
  "sessionId": "15f3c5c7b61c4a16893621b3ec969962",
  "conversationId": "6ad53918-7055-4f10-bd81-b06f8fcfae2a",
  "expiresAt": "2026-06-09T12:00:45.1234567Z",
  "webSocketPath": "/api/v1/Agent/3f67ef24-3f96-4c20-a3b3-5fd0abef15a1/realtime?conversationId=6ad53918-7055-4f10-bd81-b06f8fcfae2a&sessionId=15f3c5c7b61c4a16893621b3ec969962",
  "supportedInputAudioFormats": ["pcm16"],
  "supportedOutputAudioFormats": ["pcm16"],
  "maxSessionSeconds": 1800,
  "idleTimeoutSeconds": 60,
  "providerModelName": "gpt-realtime-2"
}

Vytvořená relace je spotřebována, když se WebSocket připojí. V nasazeních s více instancemi použijte sticky routing nebo sdílené úložiště relací.

Realtime WebSocket

GET

/api/v1/Agent/{agentId}/realtime?conversationId={conversationId}&sessionId={sessionId}Aktualizujte na WebSocket na stejném hostiteli API pomocí vráceného jednorázového tokenu relace.

Připojte se k vrácenému webSocketPath na stejném hostiteli API:

wss://{api-host}{webSocketPath}

Cesta má tento tvar:

GET /api/v1/Agent/{agentId}/realtime?conversationId={conversationId}&sessionId={sessionId}

Jakmile je socket přijat, Siesta AI se připojí k poskytovateli, odešle session.update a začne obousměrné zprostředkování. Váš klient přijímá události poskytovatele a vlastní události Siesta AI na stejném socketu.

Směrujte příchozí rámce podle type.Raw události poskytovatele a vlastní události Siesta AI sdílejí stejný socket, takže udržujte směrování událostí explicitní.

Konfigurace relace na backendu

Klienti tuto konfiguraci neposílají. Siesta AI ji odesílá interně po připojení k poskytovateli:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2",
    "output_modalities": ["audio"],
    "instructions": "{systémová zpráva agenta}\n\n{další pokyny}",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "gpt-realtime-whisper"
        },
        "turn_detection": {
          "type": "semantic_vad"
        }
      },
      "output": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "voice": "alloy"
      }
    },
    "tools": [
      "{nástroje backendového agenta}",
      "{klientské nástroje z požadavku relace v reálném čase}"
    ],
    "tool_choice": "auto"
  }
}

Zprávy od klienta k serveru

Backend přeposílá většinu zpráv WebSocket klienta k poskytovateli beze změny. Použijte standardní tvary událostí klienta poskytovatele v reálném čase.

Zpráva	Chování
Standardní události klienta v reálném čase	Přeposílány k poskytovateli beze změny.
Binární rámce	Přeposílány k poskytovateli beze změny, podléhající maximální velikosti rámce.
`{ "type": "approval.approve", "callId": "..." }`	Spotřebováno Siesta AI, pokud je hovor čekající na schválení.
`{ "type": "approval.reject", "call_id": "..." }`	Spotřebováno Siesta AI, pokud je hovor čekající na schválení. Obě `callId` a `call_id` jsou akceptovány.

Příchozí události

Váš klient přijímá dvě kategorie zpráv:

raw události poskytovatele,
vlastní události Siesta AI.

Směrujte podle nejvyššího vlastnosti type.

Raw události poskytovatele

Zprávy poskytovatele jsou přeposílány jako první a beze změny. Příklady zahrnují:

response.created
response.done
response.audio.delta
response.audio_transcript.done
response.output_audio_transcript.done
response.output_text.done
response.content.done
conversation.item.input_audio_transcription.completed
input_audio.transcript.done
response.function_call_arguments.done
error

Siesta AI naslouchá některým událostem poskytovatele, aby trvale ukládala zprávy konverzace a prováděla backendové nástroje, ale raw události stále dosahují vašeho klienta.

Události spouštějící trvalost

Událost poskytovatele	Uložená role	Vlastní události
`conversation.item.input_audio_transcription.completed`	Uživatel	`message.created`
`input_audio.transcript.done`	Uživatel	`message.created`
`response.audio_transcript.done`	Asistent	`response.id`, poté `response.completed`
`response.output_audio_transcript.done`	Asistent	`response.id`, poté `response.completed`
`response.output_text.done`	Asistent	`response.id`, poté `response.completed`
`response.content.done`	Asistent	`response.id`, poté `response.completed`

Obálka vlastní události Siesta AI

{
  "type": "event.name",
  "data": {
    "property": "value"
  }
}

Reference vlastní události

Událost	Data	Kdy je odeslána
`message.created`	`{ chatbotId, id, role, content, createdAt }`	Přepis uživatele byl trvale uložen jako zpráva konverzace.
`response.id`	`{ chatbotId, id }`	Přepis asistenta byl trvale uložen.
`response.completed`	`{ chatbotId }`	Trvalé uložení odpovědi asistenta dokončeno.
`response.function_invocation.start`	`{ id, callId, title, imageUrl, chatbotId, arguments, approvalRequired, functionName }`	Spuštění provádění backendového nástroje nebo čekání na schválení.
`response.function_invocation.done`	`{ id, callId, text, title, imageUrl, button, buttonLabel, buttonLink, chatbotId, status, executionTimeSeconds }`	Provádění backendového nástroje dokončeno, selhalo, bylo odmítnuto nebo vypršelo.
`approval.waiting`	`{ callId, messageId, timeoutSeconds }`	Backendový nástroj vyžaduje schválení uživatele před provedením.
`approval.approved`	`{ callId, messageId }`	Schválení bylo přijato a backend provádí nástroj.
`approval.expired`	`{ callId, messageId }`	Časový limit schválení uplynul.
`subagent.start`	`{ id, name, icon, iconColor, callId }`	Spuštění invokace sub-agenta.
`subagent.done`	`{ chatbotId }`	Dokončení invokace sub-agenta.

Stav provádění nástroje je serializován jako číslo aktuálním vlastním serializerem WebSocketu:

Stav	Význam
`0`	Čekající
`1`	Úspěch
`2`	Neúspěch
`3`	Čekající na schválení

Klientské nástroje

Klientské nástroje jsou funkce deklarované vaším klientem během vytváření relace. Model je vidí jako funkční nástroje, ale Siesta AI je neprovádí ani neukládá. Vaše aplikace musí naslouchat voláním nástrojů, provádět místní funkci, odesílat výstup funkce poskytovateli a požadovat další odpověď.

Deklarace

{
  "clientTools": [
    {
      "name": "open_booking_calendar",
      "description": "Otevřete rezervační kalendář pro požadovaný datum.",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Datum ve formátu YYYY-MM-DD."
          },
          "durationMinutes": {
            "type": "integer",
            "description": "Požadovaná délka schůzky v minutách."
          }
        },
        "required": ["date"]
      }
    }
  ]
}

Pravidla

name a description jsou povinné a nemohou být prázdné.
Názvy nástrojů jsou citlivé na velikost písmen.
Názvy klientských nástrojů musí být jedinečné.
Názvy klientských nástrojů nesmí kolidovat s názvy nástrojů backendového agenta.
parameters musí být objektem. Pokud je vynecháno, použije se prázdná schéma objektu.
Provádění klientských nástrojů není Siesta AI trvale ukládáno.
Klientské nástroje nevydávají vlastní události response.function_invocation.*.

Zpracování volání klientského nástroje

Když poskytovatel zavolá klientský nástroj, váš klient obdrží raw událost poskytovatele:

{
  "type": "response.function_call_arguments.done",
  "call_id": "call_open_calendar_01",
  "name": "open_booking_calendar",
  "arguments": "{\"date\":\"2026-06-10\",\"durationMinutes\":30}"
}

Pokud name odpovídá nástroji, který jste deklarovali, proveďte ho lokálně a odešlete výstup funkce:

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_open_calendar_01",
    "output": "{\"status\":\"success\",\"result\":\"Kalendář otevřen pro 2026-06-10.\"}"
  }
}

Poté požádejte model, aby pokračoval:

{
  "type": "response.create"
}

Pokud je volání funkce jiný váš deklarovaný klientský nástroj, počkejte na vlastní události backendového nástroje Siesta AI.

Schvalovací tok pro backendové nástroje

Některé backendové nástroje mohou vyžadovat schválení uživatele. Model volá backendový nástroj, Siesta AI trvale ukládá čekající schválení a váš klient musí požádat uživatele, aby je schválil nebo odmítl.

Klient obdrží response.function_invocation.start s approvalRequired: true.
Klient obdrží approval.waiting s callId, messageId a timeoutSeconds.
Uživatel schválí nebo odmítne.
Klient odešle approval.approve nebo approval.reject se stejným callId.
Schválené nástroje vydávají approval.approved a response.function_invocation.done.
Časově omezená schválení vydávají approval.expired.

{
  "type": "approval.waiting",
  "data": {
    "callId": "call_send_email_01",
    "messageId": "da3ba88e-22f5-49de-8421-e4f43834ba42",
    "timeoutSeconds": 300
  }
}

Schválit:

{
  "type": "approval.approve",
  "callId": "call_send_email_01"
}

Odmítnout:

{
  "type": "approval.reject",
  "call_id": "call_send_email_01"
}

Výchozí časový limit schválení je 300 sekund. Pokud schválení vyprší, Siesta AI vrátí modelu chybu vypršení časového limitu.

Audio a transport

Nastavení	Výchozí	Poznámky
Vstupní formát	`pcm16`	Mapováno na poskytovatele `audio/pcm` s vzorkovací frekvencí `24000`.
Výstupní formát	`pcm16`	Mapováno na poskytovatele `audio/pcm` s vzorkovací frekvencí `24000`.
Hlas	`alloy`	Předáno konfiguraci relace poskytovatele.
Detekce přepnutí	`semantic_vad`	Nakonfigurováno backendem v `session.update`.
Model přepisu vstupu	`gpt-realtime-whisper`	Nakonfigurováno backendem v `session.update`.
Max velikost zprávy WebSocket	`65536` bajtů	Větší zprávy mohou zavřít cílový socket s `MessageTooBig`.

Siesta AI neprovádí transcoding klientského audia. Použijte události payloady poskytovatele kompatibilní s vybraným formátem.

Příklad implementace

V produkci vytvářejte relaci na důvěryhodném backendu, aby váš externí API klíč nebyl vystaven v prohlížeči.

const apiBaseUrl = "https://api.siesta.ai";
const agentId = "3f67ef24-3f96-4c20-a3b3-5fd0abef15a1";

async function createRealtimeSession() {
  const response = await fetch(`${apiBaseUrl}/api/v1/Agent/${agentId}/realtime-session`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "VÁŠ_EXTERNÍ_API_KLÍČ",
      "X-Org-Id": "4bdaed95-19f8-47c2-bbf0-8a476cf0a527"
    },
    body: JSON.stringify({
      inputAudioFormat: "pcm16",
      outputAudioFormat: "pcm16",
      voice: "alloy",
      clientTools: [
        {
          name: "open_booking_calendar",
          description: "Otevřete rezervační kalendář pro požadovaný datum.",
          parameters: {
            type: "object",
            properties: {
              date: { type: "string" }
            },
            required: ["date"]
          }
        }
      ]
    })
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}

function openRealtimeSocket(session) {
  const wsUrl = new URL(session.webSocketPath, apiBaseUrl.replace(/^http/, "ws"));
  const socket = new WebSocket(wsUrl);

  socket.addEventListener("message", async event => {
    const message = JSON.parse(event.data);

    if (message.type === "response.function_call_arguments.done") {
      await maybeHandleClientTool(socket, message);
      return;
    }

    if (message.type === "approval.waiting") {
      showApprovalDialog(socket, message.data);
      return;
    }

    handleRealtimeEvent(message);
  });

  return socket;
}

async function maybeHandleClientTool(socket, event) {
  if (event.name !== "open_booking_calendar") {
    return;
  }

  const args = JSON.parse(event.arguments || "{}");
  const result = await openBookingCalendar(args.date);

  socket.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: event.call_id,
      output: JSON.stringify({ status: "success", result })
    }
  }));

  socket.send(JSON.stringify({ type: "response.create" }));
}

function approve(socket, callId) {
  socket.send(JSON.stringify({ type: "approval.approve", callId }));
}

function reject(socket, callId) {
  socket.send(JSON.stringify({ type: "approval.reject", callId }));
}

const session = await createRealtimeSession();
const socket = openRealtimeSocket(session);

Odesílání audia nebo textu

Použijte formát události poskytovatele v reálném čase. Siesta AI tyto události přeposílá beze změny.

{
  "type": "input_audio_buffer.append",
  "audio": "BASE64_PCM16_AUDIO_CHUNK"
}

{
  "type": "input_audio_buffer.commit"
}

{
  "type": "response.create"
}

Chyby a limity

Chyby v doméně v reálném čase vracejí HTTP 400 s tímto tvarem:

{
  "status": 400,
  "detail": "Relace v reálném čase vypršela.",
  "errorCode": "RealtimeSessionExpired"
}

Kódy chyb

Kód chyby	Význam	Akce klienta
`RealtimeNotEnabled`	Realtime je zakázáno pro nasazení nebo režim přístupu.	Zakázat uživatelské rozhraní v reálném čase nebo kontaktovat vlastníka API.
`RealtimeUnsupportedConnection`	Připojení agenta nepodporuje audio v reálném čase nebo je zakázáno vládou.	Použijte agenta s podporovaným připojením OpenAI.
`RealtimeUnsupportedModel`	Vybraný model agenta nepodporuje audio v reálném čase nebo neodpovídá nakonfigurovanému modelu poskytovatele.	Použijte agenta nakonfigurovaného s modelem schopným v reálném čase.
`RealtimeAudioFormatUnsupported`	Požadovaný vstupní nebo výstupní formát audia není podporován.	Použijte formát vrácený při vytváření relace, obvykle `pcm16`.
`RealtimeSessionInvalid`	Chybějící, neznámý, nesouladný nebo jinak neplatný token relace.	Vytvořte novou relaci v reálném čase a znovu se připojte.
`RealtimeSessionExpired`	Token relace vypršel před připojením WebSocketu.	Vytvořte novou relaci v reálném čase a okamžitě se připojte.
`RealtimeSessionAlreadyUsed`	Jednorázový token relace již byl spotřebován.	Vytvořte novou relaci v reálném čase. Nepokoušejte se znovu použít stejný token.

Výchozí limity

Limit	Výchozí
TTL relace před připojením WebSocketu	60 sekund
Maximální doba trvání relace	1800 sekund
Časový limit nečinnosti	60 sekund
Časový limit schválení	300 sekund
Maximální velikost zprávy WebSocket	65536 bajtů
Časový limit připojení poskytovatele	15 sekund

Pokud je WebSocket otevřen s nesprávným agentId, může být jednorázová relace již spotřebována, než je nesoulad hlášen. Vytvořte novou relaci místo pokusu o opakování stejného tokenu.

Kontrolní seznam implementace

Uložte apiBaseUrl, agentId a organizační údaje do důvěryhodné serverové konfigurace.
Zavolejte POST /api/v1/Agent/{agentId}/realtime-session ihned před otevřením WebSocketu.
Vytvořte URL WebSocketu jako wss://{host}{webSocketPath}.
Neposílejte X-Api-Key do WebSocketu.
Zpracovávejte každý příchozí textový rámec jako JSON a směrujte podle nejvyššího type.
Zpracovávejte raw audio poskytovatele a události odpovědí podle protokolu poskytovatele v reálném čase.
Zpracovávejte vlastní události Siesta AI s obálkou { type, data }.
U událostí backendových nástrojů aktualizujte stav uživatelského rozhraní, ale neodesílejte výstupy funkcí sami.
U deklarovaných klientských nástrojů naslouchejte response.function_call_arguments.done, provádějte lokálně, odešlete conversation.item.create, poté odešlete response.create.
U approval.waiting zobrazte uživatelské rozhraní pro schválení a odešlete approval.approve nebo approval.reject se stejným callId.
Při RealtimeSessionExpired nebo RealtimeSessionAlreadyUsed vytvořte novou relaci místo pokusu o opakování staré.
Udržujte jednotlivé zprávy WebSocket pod 65536 bajty, pokud vaše konfigurační nasazení neříká jinak.

Co tato API dělá​

Rychlý start​

Autentizace​

Vytvoření relace v reálném čase​

Tělo požadavku​

Příklad požadavku​

Tělo odpovědi​

Realtime WebSocket​

Konfigurace relace na backendu​

Zprávy od klienta k serveru​

Příchozí události​

Raw události poskytovatele​

Události spouštějící trvalost​

Obálka vlastní události Siesta AI​

Reference vlastní události​

Klientské nástroje​

Deklarace​

Pravidla​

Zpracování volání klientského nástroje​

Schvalovací tok pro backendové nástroje​

Audio a transport​

Příklad implementace​

Odesílání audia nebo textu​

Chyby a limity​

Kódy chyb​

Výchozí limity​

Kontrolní seznam implementace​