Site Assistant

Create an AI assistant for site visitors. It uses the AI integration of this project, so the key of the chosen provider must be in the vault (openai: openai_api_key, anthropic: aapi_anthropic_key, groq: groq_api_key, openrouter, mistral, cloudflare-workers-ai: see their integration). Visitors can never change the model, instructions or limits. scope sets how broadly it may answer: "strict" (default) only about topic, "related" also briefly about closely related questions, "open" anything. Do NOT put secrets, internal prices or private data in system_prompt: a determined visitor may get the model to reveal it. After creating, call test-assistant once to check it works.

Change an assistant. Only send what changes. Send an empty string for topic or off_topic_reply to clear it. Set is_active false to pause (visitors then see fallback_message).

Delete an assistant permanently. Realtime calls that are still open are ended first (counts in realtime_calls). To pause it instead, use update-assistant with is_active false.

All assistants of this project with their settings, today's number of answers against daily_cap, whether the provider key is in the vault, and the platform limits. realtime holds the voice settings (null when not set up), today's calls against daily_sessions and open_calls (calls not yet closed by the platform; a call the visitor ended counts until its scheduled end).

No input parameters required.

Send one test message with exactly the visitor settings (instructions, scope, limits) and see the answer, or the error from the AI provider. Counts towards daily_cap. Use this after create or update.

Turn on realtime voice (speech-to-speech in the browser) for an assistant, or change its settings. Paid plans only. Uses the OpenAI key of this project (vault: openai_api_key); the key never reaches the browser. The assistant's system_prompt, scope and topic become the voice instructions; the platform adds rules for a spoken conversation (short answers, no made-up details). Spoken answers have their own max_output_tokens (default 1024, about 40 seconds of speech; audio counts as tokens), separate from text chat. The first call needs model; later calls only send what changes. Every call is ended automatically after max_minutes, and daily_sessions caps the number of calls per day (UTC). Once connected, a determined visitor can change the instructions over the browser connection, so never put secrets in system_prompt. For the visitor transcript, transcribe_model and its hints (transcribe_prompt, transcribe_keywords, transcribe_languages, transcribe_delay) set the accuracy; a hint the chosen model does not use is left out of the call and listed in transcription_notes. After setting up, call test-realtime once.

Check that the OpenAI key, model, voice and the other voice settings work for realtime: sends the same session a call gets, without starting a call or using audio. Does not count towards daily_sessions. Returns {ok, model, voice, error, transcription_model, transcription_notes}; transcription_model is null when transcribe_visitor is off.

Emergency stop: end every realtime call of this assistant that is still open. Works on every plan. To stop new calls as well, use set-realtime with enabled false. Returns counts: ended, already_ended, unconfirmed (OpenAI answered 503, which it does for a call the visitor already ended; the call is closed) and failed.

The current visitor asks the assistant a question. Returns {reply, limited, reply_sig}. When limited is true, reply holds the fallback message, reason says why ("daily_limit", "visitor_limit", "network_limit", "inactive", "unavailable") and there is no reply_sig. For a conversation, the page keeps the earlier messages itself and sends them as history; nothing is stored on the server. Keep reply_sig with each answer and send it back as sig in history. With signed_history on, earlier answers without a valid sig are left out, so a visitor cannot make up what the assistant said.

Start a realtime voice call for the current visitor (set up first with set-realtime). The page creates an RTCPeerConnection with the microphone track and a data channel "oai-events", sends its SDP offer here and gets the SDP answer back: {sdp, max_minutes, limited:false}. Audio then flows directly between the browser and OpenAI; the data channel carries the events: the assistant's words as response.output_audio_transcript.delta/done and, with transcribe_visitor on, what the visitor said as conversation.item.input_audio_transcription.completed. When limited is true there is no sdp: message holds the fallback text and reason says why ("daily_limit", "visitor_limit", "network_limit", "busy", "inactive", "not_enabled", "plan", "unavailable"). sapi.execute resolves to {ok, status, data}: the result is in data.result; a refusal has data.success false and data.error. Example: const pc = new RTCPeerConnection(); const audio = new Audio(); audio.autoplay = true; pc.ontrack = e => { audio.srcObject = e.streams[0]; }; const mic = await navigator.mediaDevices.getUserMedia({audio: {echoCancellation: true, noiseSuppression: true}}); pc.addTrack(mic.getTracks()[0]); pc.createDataChannel("oai-events"); await pc.setLocalDescription(await pc.createOffer()); const res = await sapi.execute("site-assistant", "realtime-call", {assistant_key: "tutor", sdp: pc.localDescription.sdp}); const r = res.data && res.data.success ? res.data.result : null; if (!r || r.limited) { pc.close(); /* show r ? r.message : res.data.error */ } else { await pc.setRemoteDescription({type: "answer", sdp: r.sdp}); } Start the call from a user click (browsers require a gesture for the microphone and audio playback).