Realtime API

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 ji pro hlasové zážitky, rozhraní živých agentů, veřejné widgety a klienty, kteří potřebují reagovat na přepisy, provádění nástrojů, stavy schválení a přetrvávající události konverzace, jakmile se stanou.

Podívejte se na referenci Public API v1 pro úplné schéma.

Koncové body

Metoda	Koncový bod	Účel
`POST`	`/api/v1/Agent/{agentId}/realtime-session`	Vytvořit jednorázovou relaci v reálném čase.
`GET`	`/api/v1/Agent/{agentId}/realtime`	Otevřít WebSocket s `conversationId` a `sessionId`.

Přehled

Téma	Detail
Smlouva serveru	Vytvářejte relace z důvěryhodného serveru. `X-Api-Key` a `X-Org-Id` se používají pouze pro volání backendu pro vytvoření relace.
Životní cyklus relace	Vrácený `sessionId` je krátkodobý, jednorázový token, který se spotřebuje při připojení socketu.
Výchozí hodnoty v reálném čase	Relace mají ve výchozím nastavení model `gpt-realtime-2` a zvuk `pcm16`.

Živý příklad

cmd.siesta.ai je živý případ použití postavený na Siesta AI. Použijte jej jako referenci pro to, jak se cítí workflow v reálném čase poháněný agentem, když je integrace již zapojena.

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é instrukce agenta, backendové nástroje, volitelné klientské nástroje, nastavení zvuku, nastavení přepisu a přetrvávání konverzace.

Konverzace v reálném čase: streamujte zvuk 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.
Přetrvávání konverzace: přepisy, odpovědi asistenta, stav nástrojů a stav sub-agentů mohou být přetrvávány 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 s 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šší úrovně type.
Lokálně provádějte deklarované klientské nástroje.
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

Uchovávejte externí API klíč na straně serveru

Vytvářejte relace v reálném čase z vašeho backendu a vracejte pouze webSocketPath do prohlížeče.

Koncový bod pro vytvoření HTTP relace je autentizován pomocí externích API hlaviček:

X-Api-Key: <external-api-key>
X-Org-Id: <organization-id>

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

Nevystavujte X-Api-Key v kódu prohlížeče. Klienti prohlížeče by měli volat důvěryhodný backend a tento backend by měl vytvořit relaci v reálném čase. Prohlížeč by měl obdržet pouze vrácený webSocketPath.

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

POST /api/v1/Agent/{agentId}/realtime-session

Vrací sessionId, conversationId, metadata vypršení, podporované formáty a webSocketPath.

POST /api/v1/Agent/{agentId}/realtime-session
Content-Type: application/json
X-Api-Key: <external-api-key>
X-Org-Id: <organization-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`	ID existující konverzace. Vynechejte pro vytvoření nové konverzace.
`inputAudioFormat`	`string`	`pcm16`	Požadovaný vstupní formát zvuku.
`outputAudioFormat`	`string`	`pcm16`	Požadovaný výstupní formát zvuku.
`voice`	`string`	`alloy`	Hlas poskytovatele použitý pro výstupní zvuk.
`additionalInstructions`	`string \| null`	`null`	Další instrukce připojené za systémovou zprávu agenta pro tuto relaci.
`clientTools`	`array`	`[]`	Nástroje prováděné vaším klientem, ne 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: YOUR_EXTERNAL_API_KEY
X-Org-Id: 4bdaed95-19f8-47c2-bbf0-8a476cf0a527

{
  "inputAudioFormat": "pcm16",
  "outputAudioFormat": "pcm16",
  "voice": "alloy",
  "additionalInstructions": "Keep answers short and ask one question at a time.",
  "clientTools": [
    {
      "name": "open_booking_calendar",
      "description": "Open the booking calendar for a requested date.",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Date in YYYY-MM-DD format."
          }
        },
        "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žité touto relací v reálném čase.
`expiresAt`	`datetime`	Čas vypršení platnosti UTC pro otevření WebSocketu. Výchozí TTL je 60 sekund.
`webSocketPath`	`string`	Relativní cesta WebSocketu k 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"
}

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

Realtime WebSocket

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

Povýšení na WebSocket na stejném API hostiteli pomocí vráceného jednorázového tokenu relace.

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

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

Cesta má tento tvar:

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

Po přijetí socketu se Siesta AI připojí k poskytovateli, odešle session.update a zahájí obousměrné proxy. 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

Surové události poskytovatele a vlastní události Siesta AI sdílejí stejný socket, takže udržujte směrování událostí explicitní.

Konfigurace backendové relace

Klienti tuto konfiguraci neodesí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": "{agent system message}\n\n{additionalInstructions}",
    "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": [
      "{backend agent tools}",
      "{client tools from realtime-session request}"
    ],
    "tool_choice": "auto"
  }
}

Zprávy od klienta k serveru

Backend přeposílá většinu zpráv klienta WebSocketu 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 poskytovateli beze změny.
Binární rámce	Přeposílány poskytovateli beze změny, s ohledem na maximální velikost rámce.
`{ "type": "approval.approve", "callId": "..." }`	Spotřebováno Siesta AI, pokud volání čeká na schválení.
`{ "type": "approval.reject", "call_id": "..." }`	Spotřebováno Siesta AI, pokud volání čeká na schválení. Oba `callId` a `call_id` jsou přijímány.

Příchozí události

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

surové události poskytovatele,
vlastní události Siesta AI.

Směrujte podle nejvyšší úrovně vlastnosti type.

Surové 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 poslouchá některé události poskytovatele, aby přetrvávala zprávy konverzace a prováděla backendové nástroje, ale surové události stále dosahují vašeho klienta.

Události spouštěče přetrvávání

Událost poskytovatele	Přetrvávající 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`, pak `response.completed`
`response.output_audio_transcript.done`	Asistent	`response.id`, pak `response.completed`
`response.output_text.done`	Asistent	`response.id`, pak `response.completed`
`response.content.done`	Asistent	`response.id`, pak `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 přetrván jako zpráva konverzace.
`response.id`	`{ chatbotId, id }`	Přepis asistenta byl přetrván.
`response.completed`	`{ chatbotId }`	Dokončení přetrvání odpovědi asistenta.
`response.function_invocation.start`	`{ id, callId, title, imageUrl, chatbotId, arguments, approvalRequired, functionName }`	Spuště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 }`	Dokončení, selhání, odmítnutí nebo vypršení časového limitu provedení backendového nástroje.
`approval.waiting`	`{ callId, messageId, timeoutSeconds }`	Backendový nástroj vyžaduje schválení uživatelem 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í vypršel.
`subagent.start`	`{ id, name, icon, iconColor, callId }`	Spuštění sub-agentního volání.
`subagent.done`	`{ chatbotId }`	Dokončení sub-agentního volání.

Stav provedení nástroje je serializován jako číslo aktuálním vlastním WebSocket serializátorem:

Stav	Význam
`0`	Čeká
`1`	Úspěch
`2`	Selhání
`3`	Čeká 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 nepřetrvává. Vaše aplikace musí poslouchat volání 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": "Open the booking calendar for a requested date.",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Date in YYYY-MM-DD format."
          },
          "durationMinutes": {
            "type": "integer",
            "description": "Requested meeting duration in minutes."
          }
        },
        "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 backendových agentních nástrojů.
parameters musí být objekt. Pokud je vynechán, použije se prázdné schéma objektu.
Provedení klientského nástroje není přetrváváno Siesta AI.
Klientské nástroje nevydávají vlastní události response.function_invocation.*.

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

Když poskytovatel volá klientský nástroj, váš klient obdrží surovou 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 jej 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\":\"Calendar opened for 2026-06-10.\"}"
  }
}

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

{
  "type": "response.create"
}

Pokud volání funkce není vaším deklarovaným klientským nástrojem, 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živatelem. Model volá backendový nástroj, Siesta AI přetrvává čekající schválení a váš klient musí požádat uživatele o schválení nebo odmítnutí.

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 výsledek chyby časového limitu.

Zvuk a přenos

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

Siesta AI nepřekóduje zvuk klienta. Použijte poskytovatelem kompatibilní payloady událostí v reálném čase pro vybraný formát.

Příklad implementace

V produkci vytvořte 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": "YOUR_EXTERNAL_API_KEY",
      "X-Org-Id": "4bdaed95-19f8-47c2-bbf0-8a476cf0a527"
    },
    body: JSON.stringify({
      inputAudioFormat: "pcm16",
      outputAudioFormat: "pcm16",
      voice: "alloy",
      clientTools: [
        {
          name: "open_booking_calendar",
          description: "Open the booking calendar for a requested date.",
          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í zvuku nebo textu

Použijte formát událostí 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": "Realtime session has expired.",
  "errorCode": "RealtimeSessionExpired"
}

Kódy chyb

Kód chyby	Význam	Akce klienta
`RealtimeNotEnabled`	Realtime je zakázán pro nasazení nebo přístupový režim.	Zakázat uživatelské rozhraní v reálném čase nebo kontaktovat vlastníka API.
`RealtimeUnsupportedConnection`	Připojení agenta nepodporuje zvuk v reálném čase nebo je zakázáno správou.	Použijte agenta s podporovaným připojením OpenAI.
`RealtimeUnsupportedModel`	Vybraný model agenta nepodporuje zvuk v reálném čase nebo neodpovídá nakonfigurovanému modelu poskytovatele.	Použijte agenta nakonfigurovaného s modelem schopným pracovat v reálném čase.
`RealtimeAudioFormatUnsupported`	Požadovaný vstupní nebo výstupní formát zvuku není podporován.	Použijte formát vrácený při vytváření relace, obvykle `pcm16`.
`RealtimeSessionInvalid`	Chybějící, neznámý, nesouhlasný 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 připojte se ihned.
`RealtimeSessionAlreadyUsed`	Jednorázový token relace byl již 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, jednorázová relace může být již spotřebována před tím, než je nahlášena nesrovnalost. Vytvořte novou relaci místo pokusu o opětovné použití stejného tokenu.

Kontrolní seznam implementace

Uložte apiBaseUrl, agentId a organizační přihlašovací údaje v důvěryhodné serverové konfiguraci.
Zavolejte POST /api/v1/Agent/{agentId}/realtime-session ihned před otevřením WebSocketu.
Sestavte URL WebSocketu jako wss://{host}{webSocketPath}.
Neposílejte X-Api-Key do WebSocketu.
Analyzujte každý příchozí textový rámec jako JSON a směrujte podle nejvyšší úrovně type.
Zpracovávejte surové události poskytovatele zvuku a odpovědi podle protokolu poskytovatele v reálném čase.
Zpracovávejte vlastní události Siesta AI s obálkou { type, data }.
Pro události backendových nástrojů aktualizujte stav uživatelského rozhraní, ale neposílejte výstupy funkcí sami.
Pro deklarované klientské nástroje poslouchejte response.function_call_arguments.done, proveďte lokálně, odešlete conversation.item.create, pak odešlete response.create.
Pro approval.waiting zobrazte schvalovací uživatelské rozhraní 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 opětovné použití staré.
Udržujte jednotlivé zprávy WebSocket pod 65536 bajtů, pokud vaše nasazení neříká jinak.

Koncové body​

Přehled​

Živý příklad​

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 backendové relace​

Zprávy od klienta k serveru​

Příchozí události​

Surové události poskytovatele​

Události spouštěče přetrvávání​

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​

Zvuk a přenos​

Příklad implementace​

Odesílání zvuku nebo textu​

Chyby a limity​

Kódy chyb​

Výchozí limity​

Kontrolní seznam implementace​