# List Conversation Messages Source: https://docs.bey.dev/api-reference/agent-conversations/list-conversation-messages /openapi.json get /v1/conversations/{id}/messages List the transcribed messages of a conversation. Returns the conversation transcript in chronological order, with each message attributed to either the agent or the user. # List Conversations Source: https://docs.bey.dev/api-reference/agent-conversations/list-conversations /openapi.json get /v1/conversations List conversations managed by your agents. Returns a cursor-paginated list of conversations across all of your agents, most recent first. # Retrieve Conversation Source: https://docs.bey.dev/api-reference/agent-conversations/retrieve-conversation /openapi.json get /v1/conversations/{id} Retrieve a single conversation by ID, including its status and participants. # Create LiveKit Room Source: https://docs.bey.dev/api-reference/agent-integration/create-livekit-room /openapi.json post /v1/livekit-rooms Create a LiveKit room for one of your agents and return the credentials a LiveKit client needs to join it. Use this only when you are embedding a conversation in your own application via the LiveKit client SDK. Most integrations do not need it: Interacting with Managed Agents through the UI starts a conversation with no API call required. The room is created together with its conversation, whose status and transcript you can then read from `/v1/conversations/{id}`. # Create Knowledge File Source: https://docs.bey.dev/api-reference/agent-knowledge-files/create-knowledge-file /openapi.json post /v1/knowledge-files Create a knowledge file and start its upload. Text files are stored immediately and begin indexing, so they come back as `processing` and are ready to attach to an agent once they read `available`. PDF files begin a chunked upload: use the returned ID to upload each chunk via `PUT /{id}/upload`, then finalize with `POST /{id}/submit`. # Delete Knowledge File Source: https://docs.bey.dev/api-reference/agent-knowledge-files/delete-knowledge-file /openapi.json delete /v1/knowledge-files/{id} Delete a knowledge file. Fails if any of your agents still references the file; detach it from those agents first. # List Knowledge Files Source: https://docs.bey.dev/api-reference/agent-knowledge-files/list-knowledge-files /openapi.json get /v1/knowledge-files List your knowledge files. Returns a cursor-paginated list of the knowledge files you own, along with their processing status. # Retrieve Knowledge File Source: https://docs.bey.dev/api-reference/agent-knowledge-files/retrieve-knowledge-file /openapi.json get /v1/knowledge-files/{id} Retrieve a single knowledge file by ID, including its extracted text. # Submit Knowledge File Source: https://docs.bey.dev/api-reference/agent-knowledge-files/submit-knowledge-file /openapi.json post /v1/knowledge-files/{id}/submit Finalize a chunked knowledge file upload. Assembles the uploaded chunks and starts extracting and indexing them. Returns the file as `processing`; it becomes `available` once that finishes, which takes minutes for a long document. # Upload Knowledge File Chunk Source: https://docs.bey.dev/api-reference/agent-knowledge-files/upload-knowledge-file-chunk /openapi.json put /v1/knowledge-files/{id}/upload Upload a single chunk of a PDF knowledge file. Send the raw chunk bytes as the request body. Chunks are zero-indexed via the `chunk_number` query parameter and can be uploaded in any order. # Create External API Configuration Source: https://docs.bey.dev/api-reference/agents-external-apis/create-external-api-configuration /openapi.json post /v1/external-apis Create an external API configuration. Securely stores credentials for an external service (such as an OpenAI-compatible LLM or your ElevenLabs account) so agents can reference it by ID. The secret itself is never returned in responses. # Delete External API Configuration Source: https://docs.bey.dev/api-reference/agents-external-apis/delete-external-api-configuration /openapi.json delete /v1/external-apis/{id} Delete an external API configuration and its stored secret. Agents still referencing this configuration will fail to use it afterwards. # List External API Configurations Source: https://docs.bey.dev/api-reference/agents-external-apis/list-external-api-configurations /openapi.json get /v1/external-apis List your external API configurations. Returns a cursor-paginated list of configurations you own. Secrets are never included. # Retrieve External API Configuration Source: https://docs.bey.dev/api-reference/agents-external-apis/retrieve-external-api-configuration /openapi.json get /v1/external-apis/{id} Retrieve a single external API configuration by ID (without its secret). # Create Agent Source: https://docs.bey.dev/api-reference/agents/create-agent /openapi.json post /v1/agents Create a new agent. # Delete Agent Source: https://docs.bey.dev/api-reference/agents/delete-agent /openapi.json delete /v1/agents/{id} Delete an agent. Permanently removes the agent. Calls that already ran are unaffected. # List Agents Source: https://docs.bey.dev/api-reference/agents/list-agents /openapi.json get /v1/agents List your agents. Returns a cursor-paginated list of the agents you own, most recent first. # Retrieve Agent Source: https://docs.bey.dev/api-reference/agents/retrieve-agent /openapi.json get /v1/agents/{id} Retrieve a single agent by ID. # Update Agent Source: https://docs.bey.dev/api-reference/agents/update-agent /openapi.json patch /v1/agents/{id} Update an existing agent. Only the fields present in the request body are changed; omitted fields keep their current values. # Verify API Key Source: https://docs.bey.dev/api-reference/authentication/verify-api-key /openapi.json get /v1/auth/verify Check whether the `x-api-key` header contains a valid API key. Returns `204 No Content` when the key is valid and `401 Unauthorized` otherwise. Useful as a lightweight connectivity and credential check. # List Avatars Source: https://docs.bey.dev/api-reference/avatars/list-avatars /openapi.json get /v1/avatars List available avatars. Returns a cursor-paginated list of the avatars you can use in agents: both your own trained avatars and public stock avatars. # Retrieve Avatar Source: https://docs.bey.dev/api-reference/avatars/retrieve-avatar /openapi.json get /v1/avatars/{id} Retrieve a single avatar by ID. # Create Speech-to-Video Session Source: https://docs.bey.dev/api-reference/speech-to-video-sessions/create-speech-to-video-session /openapi.json post /v1/sessions Create a speech-to-video session. Tip: do not use this directly, use the LiveKit plugin instead. See . # List Speech-to-Video Sessions Source: https://docs.bey.dev/api-reference/speech-to-video-sessions/list-speech-to-video-sessions /openapi.json get /v1/sessions List your speech-to-video sessions. Returns a cursor-paginated list of sessions, most recent first. # Retrieve Speech-to-Video Session Source: https://docs.bey.dev/api-reference/speech-to-video-sessions/retrieve-speech-to-video-session /openapi.json get /v1/sessions/{id} Retrieve a single speech-to-video session by ID. # External LLM Source: https://docs.bey.dev/concepts/agents/external-llm Configure Beyond Presence agents to call your own OpenAI-compatible Chat Completions endpoint, including xAI Grok and Google Gemini. Configure agents to use an external LLM instead of our default models. Maintain full control over the language model while leveraging Beyond Presence's optimized avatar and agent management stack. ## Use Cases External LLM configuration is ideal for: * **Custom models**: Use fine-tuned or specialized language models * **Data control**: Route LLM requests through your own infrastructure or preferred providers * **Regulatory compliance**: Meet specific data residency requirements ## Requirements Your external LLM API must implement a single endpoint following the OpenAI-compatible [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) format. At minimum, the endpoint must support: * Standard chat completion requests with `messages` array * Streaming responses with server-sent events Additional features like function calling or vision are optional and only needed if your specific use case requires them. While not strictly required, we recommend supporting token authentication for secure access. ## Using Popular Providers Many LLM providers offer OpenAI-compatible endpoints that work out of the box: **xAI (Grok)**: [Get API key](https://docs.x.ai/docs/tutorial) * Base URL: `https://api.x.ai/v1` * Models: `grok-4`, `grok-3-beta`, `grok-code-fast-1` **Google (Gemini)**: [Get API key](https://aistudio.google.com/app/apikey) * Base URL: `https://generativelanguage.googleapis.com/v1beta/openai` * Models: `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash` Using these providers may incur additional costs based on their pricing models. ## Configuration You can configure external LLMs through our API or the Studio. 1. Register your LLM API with the [Create External API Configuration endpoint](/api-reference/agents-external-apis/create-external-api-configuration) 2. Reference the configuration when creating an agent with the [Create Agent endpoint](/api-reference/agents/create-agent#openaicompatibleagentllm) While we require you to specify a token for the API, you can pass an empty string if your endpoint does not require authentication. ## Complete Example See our external LLM example for full implementation including API registration, agent creation, and optional deployment of a compatible LLM API: Complete implementation with deployment scripts # Extra Capabilities Source: https://docs.bey.dev/concepts/agents/extra-capabilities Enhance Beyond Presence Managed Agents with vision mode that can see the user and wakeup mode that responds only to trigger keywords. Enhance your agents with additional capabilities beyond standard conversational AI. These features enable more immersive and context-aware interactions. ## Available Capabilities ### Webcam Vision Enable your agent to see the user's camera feed for more authentic, context-aware conversations. The agent can respond to visual cues, gestures, and what the user shows on camera. **Use cases:** * **Emotional connection**: Read facial expressions for more empathetic interactions * **Fitness coaching**: Observe form and technique during exercises * **Educational tutors**: Provide feedback on physical work and materials * **Virtual shopping assistants**: Recommend products based on what customers show Webcam vision is currently in preview and available to select customers. Contact [support@beyondpresence.ai](mailto:support@beyondpresence.ai) to discuss access for your use case. ### Wakeup Mode Configure your agent to respond only to specific trigger keywords or phrases (e.g., "jarvis", "hey agent", "computer"). Ideal for assistant-style interactions where the agent should remain passive until explicitly activated. You can specify a list of case-insensitive trigger words or space-separated phrases that will activate the agent. **Use cases:** * **Always-on assistants**: Listen continuously, respond only when called * **Hands-free environments**: Enable voice activation when clicking isn't possible * **Ambient experiences**: Remain present but non-intrusive in the background ## Configuration You can configure capabilities through our API or the Studio. Specify capabilities when creating an agent using the [Create Agent endpoint](/api-reference/agents/create-agent#body-capabilities). Capabilities are additive and agent-specific, allowing you to enable multiple capabilities per agent and configure different capabilities for different agents. ## Learn More Configure capabilities for Managed Agents via API # Conversational Video Agents Source: https://docs.bey.dev/concepts/agents/index How Beyond Presence agents combine LLMs with lifelike avatars, and when to choose Managed Agents versus self-hosted LiveKit Agents. ## What are Agents? Agents are AI systems that can perform tasks and make decisions autonomously. When these agents are designed for real-time dialogue and natural conversation with users, they become **conversational agents** - combining large language models (LLMs) with real-time communication capabilities to create interactive experiences. At Beyond Presence, we focus on conversational agents - and specifically **conversational video agents** powered by our ultra-realistic [avatar models](/concepts/avatars). ### Agent Modalities Agents can operate across different communication channels: * **Text agents**: Traditional chatbots that respond via written messages * **Voice agents**: AI assistants that speak and listen, like Siri or Alexa * **Video agents**: The next evolution - AI that communicates with lifelike visual presence ## Why Video Agents? While text and voice agents are useful, video agents create deeper engagement by: * Establishing human-like connections through visual presence * Conveying emotions and personality through facial expressions * Building trust faster than disembodied voices or text * Providing a more natural interaction paradigm ## Implementation Approaches ### Managed Agents Use Beyond Presence's fully managed infrastructure where agents run on our servers. No framework setup required - just configure your agent through the Studio or our API and deploy instantly. Start building with Beyond Presence Managed Agents ### Self-Hosted Agents Build and manage your own conversational infrastructure using frameworks like [LiveKit Agents](https://github.com/livekit/agents) for real-time audio/video communication. This approach gives you complete control but requires significant engineering effort for media handling, scaling, and infrastructure management. Quickstart for Speech-to-Video API with LiveKit Agents ## Agent Components Understanding agent components helps you optimize performance and customize functionality. Whether you configure Managed Agents or build custom implementations, these components form the foundation of every conversational system. ### Core Intelligence The core reasoning components that power your agent's conversational abilities: * **Language Model**: The "brain" that understands user input and generates intelligent responses. This is the core reasoning engine that makes your agent conversational and context-aware. * **System Prompt**: Instructions that define your agent's behavior, tone, and role. The system prompt contains the guidelines your agent follows during conversations. * **Knowledge Base**: Domain-specific information your agent can reference to provide accurate, relevant responses. Upload documents, FAQs, or data to enhance your agent's expertise. See [Knowledge Base](/concepts/agents/knowledge-base). ### Media Processing Components that handle audio and video processing for real-time interactions: * **Speech-to-Text (STT)**: Converts user speech into text that the language model can process. * **Text-to-Speech (TTS)**: Converts language model responses into natural-sounding speech. * **Turn Detection**: Detects when users finish speaking and when to respond, enabling natural conversation flow. * **Avatar Rendering**: Turns text or speech responses into a lifelike video of a person. ### Transport Manages real-time audio and video streaming between users and agents. Popular transport options in the space include [LiveKit](https://docs.livekit.io). ### External Tools Connections to external systems, APIs, and services that expand your agent's capabilities beyond conversation. ## Learn More Connect your own OpenAI-compatible LLM API to a Managed Agent Enhance agents with webcam vision and wakeup mode Provide conversation-specific context to your agents Receive real-time events for conversations of your Managed Agents Retrieve historical data for conversations of your Managed Agents Connect to agents using LiveKit Client SDK # Just-in-Time Context Source: https://docs.bey.dev/concepts/agents/just-in-time-context Inject session-specific data into a Beyond Presence agent's system prompt at creation time to tailor each conversation to the individual user. Provide context to your agent at creation time just before a conversation. This lets your agent manage the conversation more effectively. ## Use Cases Just-in-time context enables you to: * **Tailored user experience**: Generate unique system prompts based on user data * **Session-specific configuration**: Create specialized agents for individual sessions * **Context augmentation**: Adapt agent behavior based on external data sources ## Implementation You can provide just-in-time context in the system prompt field of the [Create Agent endpoint](/api-reference/agents/create-agent). Since agent creation is a lightweight operation, you can generate agents dynamically just before a conversation to inject just-in-time context. The response includes the agent ID, which you can use to share as a direct link (`https://bey.chat/{agent-id}`) or [embed via iframe](/integrations/web/iframe-embedding). Agents created this way are typically single-use and disposable. To keep your agent collection clean, delete them after use with the [Delete Agent endpoint](/api-reference/agents/delete-agent). Conversations managed by these agents remain in your database. Creating single-use agents for just-in-time context is a simple workaround. We plan to directly support dynamic context injection for agents in the future. ## Complete Example See our just-in-time context example for full implementation including API integration, context injection, and conversation data retrieval: Complete implementation with code examples # Knowledge Base Source: https://docs.bey.dev/concepts/agents/knowledge-base Upload text and PDF knowledge files, wait for them to be indexed, and attach them to a Beyond Presence agent so it can answer domain-specific questions. A knowledge base is the set of knowledge files attached to an agent. The agent uses them to answer questions about your products, policies, or other domain-specific content. You can manage knowledge files in the [Studio](https://bey.studio) or through the [Knowledge Files API](/api-reference/agent-knowledge-files/list-knowledge-files). ## How agents use knowledge Beyond Presence extracts the text of each file page by page, stores it in full, and builds a search index for it. During a conversation, the agent receives your knowledge in one of two ways: * **In the prompt**: If the text of all attached files fits in the agent's prompt, Beyond Presence adds the full text to the agent's instructions. This is the case for most small knowledge bases. * **Through retrieval**: If the text no longer fits in the prompt, the agent gets a `search_knowledge` tool instead. The agent searches the knowledge base before answering, using a hybrid of semantic (vector) and keyword (BM25) search. Results are labelled with the document name and page, so the agent can cite its source. If a search finds nothing relevant, the agent says it does not have that information instead of guessing. Beyond Presence picks the mode for you at the start of each conversation. You don't need to configure it. Realtime LLMs can't use knowledge files. The API rejects creating or updating an agent that combines a realtime model with `knowledge_file_ids`. Use a non-realtime model, or detach the knowledge files from the agent. ## File lifecycle Every knowledge file has a `status`: | Status | Meaning | | - | - | | `to-upload` | A PDF file was created and is waiting for its chunks to be uploaded and submitted. | | `processing` | The file was received and is being extracted and indexed. | | `available` | The file is indexed and ready to attach to an agent. | | `failed` | The file could not be used. The `reason` field explains what is wrong and how to fix it. | Text files and submitted PDF files both come back as `processing`. Indexing a long document can take several minutes. Poll [Retrieve Knowledge File](/api-reference/agent-knowledge-files/retrieve-knowledge-file) until the status is `available` before you attach the file to an agent. Attaching a file that is still `processing` or has `failed` returns an error. ### Create and wait for a text file ```python Python theme={null} import time import requests API_URL = "https://api.bey.dev/v1" HEADERS = {"x-api-key": "sk-your-api-key-here"} response = requests.post( f"{API_URL}/knowledge-files", headers=HEADERS, json={ "name": "Product FAQ", "format": "text", "content": "Q: What is your return policy? A: ...", }, ) response.raise_for_status() knowledge_file = response.json() while knowledge_file["status"] == "processing": time.sleep(5) response = requests.get( f"{API_URL}/knowledge-files/{knowledge_file['id']}", headers=HEADERS ) response.raise_for_status() knowledge_file = response.json() if knowledge_file["status"] == "failed": raise RuntimeError(knowledge_file["reason"]) # The file is available. Attach it to an agent with `knowledge_file_ids`. ``` For PDF files, [create the file](/api-reference/agent-knowledge-files/create-knowledge-file) with `format: "pdf"` and `upload_num_chunks`, upload each chunk with [Upload Knowledge File Chunk](/api-reference/agent-knowledge-files/upload-knowledge-file-chunk), and finish with [Submit Knowledge File](/api-reference/agent-knowledge-files/submit-knowledge-file). Then poll the file the same way. ### Extracted text An `available` file includes the extracted `text` and an `is_text_complete` flag. For large files, `text` contains only the start of the file and `is_text_complete` is `false`. The agent still searches the full file either way. The flag only describes how much text the API returns. ## Failed files When a file has the `failed` status, read its `reason` to find out what to change. Common reasons include: * **Scanned PDF**: No text could be extracted from any page. The PDF is most likely a scan or image-only file. Run it through OCR and upload it again. * **Too many pages**: The PDF has more than 1,500 pages. Split it into smaller files and upload them separately. * **Too large to index**: The file contains more text than one index can hold. Split it into smaller files and upload them separately. * **Unreadable or damaged PDF**: The file is corrupt, is not a PDF, or stopped parsing partway through. Re-export it and upload it again. * **Unexpected error**: Something went wrong during indexing. Upload the file again to retry. ## Limits | Limit | Value | | - | - | | Text file `content` | 250,000 characters. Upload larger content as a PDF. | | PDF pages | 1,500 pages per file | | PDF upload chunks | 1,000 chunks per file | | Knowledge file `name` | 100 characters | | Extracted `text` returned by the API | 250,000 characters. Larger files are searched in full, but `text` is truncated. | The same 250,000-character limit applies in the Studio and the API. # Webhook Events Source: https://docs.bey.dev/concepts/agents/webhook-events Configure a Beyond Presence Managed Agent webhook to receive real-time conversation events, with endpoint, CORS, and Studio setup requirements. Configure webhooks to receive real-time events from agent conversations. Process conversations as they happen in your own systems. ## Use Cases Webhook events are ideal for: * **Real-time monitoring**: Track conversations and agent performance as they happen * **System integration**: Sync conversation data with CRMs, analytics platforms, or internal tools * **Automated workflows**: Trigger actions based on conversation events or sentiment analysis * **Custom analytics**: Build custom dashboards and reporting on top of conversation data ## Requirements Your webhook endpoint must: * Be publicly accessible from the internet * Accept POST requests with JSON payloads * Return a `200` status code to acknowledge receipt The endpoint should also support the following CORS headers: ```http theme={null} Access-Control-Allow-Origin: * Access-Control-Allow-Methods: POST Access-Control-Allow-Headers: Content-Type ``` CORS headers are required because webhook validation currently happens in the browser. This requirement will be removed in a future release. ## Configuration Configure webhooks through the Studio: 1. Navigate to [Your Settings](https://bey.studio/settings) → Webhooks Tab 2. Enter your webhook endpoint URL 3. Save to trigger a test event for validation When you save your webhook URL, Beyond Presence sends a test event to validate your endpoint: ```json theme={null} { "event_type": "test" } ``` Your endpoint must return a `200` status code to confirm it's working correctly. ## Event Types Your webhook endpoint receives POST requests with different event types. We currently do not support retry logic for failed webhook deliveries. Ensure your endpoint is reliable to avoid missing events. ### Message Events Triggered whenever a message is sent during a conversation (by either the user or agent). ```json theme={null} { "event_type": "message", "call_id": "call_abc123", "message": { "sender": "user", // or "agent" "message": "Hello, I need help with my order", "sent_at": "2024-01-15T10:30:45.123Z" }, "call_data": { "userName": "John Doe", "agentId": "agent_xyz789" } } ``` The agent's greeting message marks the start of a conversation and can be used to trigger conversation initialization logic in your webhook handler. ### Call Ended Events Triggered when a conversation concludes. Includes the full transcript and evaluation. ```json theme={null} { "event_type": "call_ended", "call_id": "call_abc123", "user_name": "John Doe", "evaluation": { "topic": "Order status inquiry", "user_sentiment": "positive", // or "neutral", "negative" "duration_minutes": 3.5, "messages_count": 12 }, "messages": [ { "sender": "agent", "message": "Hello, how may I help you today?", "sent_at": "2024-01-15T10:30:30.123Z" }, // ... ] } ``` ## Complete Example See our webhook processor example for full implementation including event handling, CORS configuration, and deployment scripts: Complete implementation with deployment scripts # API Errors Source: https://docs.bey.dev/concepts/api/errors Understand Beyond Presence REST API HTTP status codes and how to debug error responses. This page covers error responses from the REST API only. For known product issues and their resolutions, see [Troubleshooting](/production/troubleshooting), and check [status.bey.dev](https://status.bey.dev/) for ongoing incidents. Every failed request returns the appropriate HTTP status code together with a JSON body describing what went wrong. ## Status Codes | Status | Meaning | Typical cause | | - | - | - | | `400` | Bad Request | An invalid parameter value, file format, or date range was provided. | | `401` | Unauthorized | The `x-api-key` header is missing or the API key is not valid. | | `402` | Payment Required | Your usage limit is reached, see [Quotas](/production/concurrency). Upgrade your plan or enable usage-based billing. | | `403` | Forbidden | The resource is only available to selected customers and not accessible with your API key. | | `404` | Not Found | The resource does not exist, or it is not accessible with your API key. | | `409` | Conflict | A resource with the same ID already exists. | | `410` | Gone | The feature has been permanently removed or retired. | | `422` | Unprocessable Entity | The request body or query parameters are invalid. | | `429` | Too Many Requests | Your concurrency limit has been reached, see [Quotas](/production/concurrency). Upgrade your plan or cancel ongoing sessions. | | `500` | Internal Server Error | An unexpected error occurred on our side. | | `501` | Not Implemented | The requested capability is not available for your account type. | | `503` | Service Unavailable | The service is temporarily at capacity. | ## Handling Errors * Retry `429` and `503` responses with exponential backoff. Both are transient. * Do not retry other `4xx` responses. They indicate a problem with the request itself, and retrying will fail the same way. * Treat `402` and `403` as requiring an account change rather than a retry. Surface them to whoever manages your billing or plan. * Retry `500` responses at most once or twice with backoff. If they persist, check [status.bey.dev](https://status.bey.dev/) and contact [support@beyondpresence.ai](mailto:support@beyondpresence.ai). ## Debugging Authentication Errors Authentication failures always return `401` with one of two messages: * `"API key is required."` when the `x-api-key` header is absent * `"Invalid API key."` when the key is present but not recognized To check a key without side effects, call `GET /v1/auth/verify`. It returns `204 No Content` for a valid key and `401` otherwise. ```sh theme={null} curl --head "https://api.bey.dev/v1/auth/verify" \ --header 'x-api-key: sk-your-api-key-here' ``` ## Error Response Format All errors carry a `detail` field. For most errors, `detail` is a single human-readable message: ```json theme={null} { "detail": "Invalid API key." } ``` Validation errors (`422`) are the exception: `detail` is a list of per-field objects describing each field that failed validation, where it was located, and why. ```json theme={null} { "detail": [ { "type": "missing", "loc": ["body", "name"], "msg": "Field required", "input": {} } ] } ``` Some errors include additional context keys alongside `detail`, such as `avatar_id`, `agent_id`, or `creator_id`. The API does not return machine-readable error codes. Branch your error handling on the HTTP status code, and treat the `detail` message as informational only, as its wording may change without notice. ## Learn More Concurrency and usage limits for your plan Known issues and their resolutions # Beyond Presence REST API Source: https://docs.bey.dev/concepts/api/index Manage avatars, agents, conversations, external APIs, and speech-to-video sessions with the Beyond Presence REST API and x-api-key auth. The Beyond Presence API provides direct programmatic access to our platform, allowing you to build custom video agent experiences and integrate our technology into your applications. ## API Features The API enables you to: * **Manage avatars**: List available avatars and access avatar details * **Control agents**: Create, configure, update, and delete video agents * **Monitor conversations**: Access conversation metadata and transcripts * **Configure integrations**: Set up external API connections and webhooks * **Start speech-to-video sessions**: Initiate real-time speech-to-video sessions Complete documentation for all REST endpoints is available in our [API reference](/api-reference). For speech-to-video sessions, use our [LiveKit plugin](/integrations/voice-agents/livekit) rather than calling the session endpoints directly. ## Authentication Generate API keys in your [Studio settings](https://bey.studio/settings/api-keys). Include your key in the `x-api-key` header with all requests: ```sh theme={null} curl "https://api.bey.dev/v1/avatars" \ --header 'x-api-key: sk-your-api-key-here' ``` ## Learn More Complete documentation for all API endpoints Understand API error responses and status codes API concurrency and usage limits that apply to your plan # Custom Avatars Source: https://docs.bey.dev/concepts/avatars/custom Create an avatar exclusive to your account from a training video or a single image. (New) You can now create custom avatars yourself in the [Studio's Avatars section](https://bey.studio/avatars) 🎉 A custom avatar belongs to your account and can be used for brand representation, product walkthroughs, or a persistent digital persona. There are two ways to create one: * [From a training video](#avatars-from-videos): A few minutes of recorded footage of one person. This produces the highest quality result and is what most of this page covers. * [From a single image](#avatars-from-single-images): A single photograph, with no recording session required. ## Avatars from Videos The quality of a video-trained avatar depends almost entirely on the training video. The sections below cover how to record it, what to send, and what happens next. ### How It Works Follow the setup and recording instructions below to record a good avatar training video. Most people get a good take within two or three attempts. Go to the [Studio's Avatars section](https://bey.studio/avatars), click **"Create Custom Avatar"**, and upload the video. Follow the Studio's prompts to record a consent verification video. Submit your video and wait until the avatar has been created. ### 1. Setup #### Camera and Framing * A good phone camera or laptop webcam works well. Photo Booth or QuickTime Player on a newer Mac are solid options. Even better is a DSLR or mirrorless camera on a tripod, which will give you the sharpest result. * Position the camera at **eye level**. Shooting from below or above distorts the face and degrades the result. * Record at **1080p**. * Frame from mid-chest up, with a small amount of headroom above the head. * Lock focus and exposure if your camera allows it. Auto exposure shifting mid-take causes problems. * Don't zoom, pan, or reframe at any point, and don't move closer to or further from the camera during the take. Record locally to a file. Avoid streaming software or any tool that sends video over an internet connection before saving. The compression artifacts aren't recoverable. #### Lighting * Use a well-lit room with the light coming **from the front**, so your face is evenly lit. * Avoid strong shadows across the face. * Watch what's behind you. A very bright window or lamp behind your head will pull exposure down and darken your face. If you can't move, add light in front of you to compensate. * Keep the lighting consistent for the whole recording. Don't let it change intensity, direction, or colour partway through. #### Background * The background should be **static**. Nothing moving, no one walking behind you. * **Only one person in frame.** No other faces anywhere in the video, including in the background, on a screen, or in a poster or photo on the wall. * Choose a background that contrasts with your hair and clothing. Dark hair against a dark wall is a common failure. * It doesn't have to be a blank wall. A normal room works, as long as it's still and doesn't compete with your face. * Green screen is optional and isn't required for a good result. #### Wardrobe and Hair Anything that moves independently of your body creates artifacts. * Pin down anything loose: open collars, scarves, lanyards, drawstrings, jacket flaps. * No dangling earrings or swinging necklaces. * No hats with brims that shadow the eyes, and no sunglasses. * Keep hair off the forehead and away from the face. Tie long hair back so nothing falls across your face mid-take. * Avoid clothing that matches the background colour. * Wear something that contrasts clearly with your skin tone. Skin-coloured clothing may blur the boundary between neck and clothing. **Long beard?** Wearing a turtleneck or an undershirt in a similar colour to the beard helps the model separate it cleanly from the neck. Long loose hair and full beards are still harder for the model than short hair and clean-shaven faces. The tips above reduce the risk. We are actively working on improving quality across all hair types. #### Glasses Glasses generally work. To reduce risk: * Eliminate reflections of lights or windows in the lenses. Reposition the light rather than tilting your head. * Avoid transparent or very thin wire frames. * Avoid frames that sit close to the eyelid or cut across the eye. If you're unsure, record one take with glasses and one without, and try both. #### Setup Checklist **Room** * [ ] Quiet: HVAC, fans, and notifications off * [ ] No one else in frame or earshot * [ ] Background static, no other faces visible **Camera** * [ ] Eye level, chest-up framing * [ ] 1080p, recording locally to file * [ ] Focus and exposure locked * [ ] Storage and battery for a 5-minute take **Light** * [ ] Lighting from the front, face evenly lit * [ ] No shadow across the face, nothing bright behind your head * [ ] No reflections in glasses **You** * [ ] Clothing contrasts with skin tone and background * [ ] Hair back and off the face * [ ] Nothing loose or dangling * [ ] Hands resting below the neck ### 2. Recording the Video #### Video Specifications | | | | - | - | | **Length** | 2–3 minutes | | **Resolution** | 1080p recommended | | **Format** | MP4 or MOV | | **Structure** | 20s silent opening, 2-3 mins speaking, 5s still ending | | **Camera** | Eye level. Phone, webcam, or DSLR on a tripod | | **Framing** | Chest-up, one person only, hands below the neck | | **Background** | Static, contrasting with hair and clothing | | **Audio** | Clean and quiet, no other voices | #### Recording Structure We recommend structuring the video in three phases: Record in one continuous take. Cuts, trims, and splices anywhere in the video cause problems. Start the recording and stay **silent and still for about 20 seconds** before you speak. * Keep your mouth closed the entire time. Don't open it to speak, yawn, or reset. * Imagine someone is talking to you and you're listening attentively. That's the expression we want. * Gentle, natural movement is welcome: a small smile, slight head nods, subtle shifts of expression. * Avoid large or exaggerated movement. This opening gives us the material we need for a natural-looking avatar when it isn't speaking, so give it the full 20 seconds. **Summary:** silent, mouth closed, listening expression, gentle nods After the 20 seconds of silence, ease into speaking. * Start relaxed. Something like "Hey, my name is ..." works well. * Try not to jump in abruptly with high energy, like "Hey! What's up everyone?!" * Aim for **2–3 minutes** of speech. Shorter recordings give the model less to work with. * Hold steady eye contact with the camera throughout. * Keep your head and body stable. Try not to tilt your head or shift your posture. * Keep your shoulders fixed. Avoid shrugging or lifting them. * Natural micro-expressions are good. Gentle nods and subtle smiles are fine. Large gestures are not. * **Close your mouth completely after each sentence**, with a short natural pause of about half a second. This produces noticeably smoother speech animation. * Aim to be positive and smiling from the inside, while keeping your outward expression neutral, calm, and friendly. * Keep your hands below your neck so they stay out of frame. You don't need a script. Talk about your work, your product, your day, anything you can speak about comfortably for a few minutes without stumbling. Natural speech works better than a formal read. **Summary:** Speaking naturally for 2-3 minutes, eye contact, stable posture, mouth closed between sentences * Wrap up simply. A short sign-off is enough. Don't trail off mid-thought or end on a rushed sentence. * After you finish speaking, stay still and silent for a few seconds in the same position. * Keep your shoulders and head steady through the whole pause. #### Recording Checklist * [ ] 20 seconds silent and still at the start, mouth closed * [ ] Easing in around 0:21 with a relaxed opener * [ ] 2–3 minutes speaking, eye contact, shoulders steady * [ ] There are pauses between sentences * [ ] Simple close, then 3–5 seconds still * [ ] One continuous take, no cuts * [ ] Face is visible at all times and looking directly at the camera * [ ] There were no other faces or voices in the background during the recording ### Best Practices #### Record Clean Audio To obtain an avatar with good lip-synchronization, the audio needs to be audible and clean. * Record in a **quiet space with no background noise**: no air conditioning, traffic, keyboards, fans, or notifications. * Avoid echo. A soft-furnished room is better than an empty hard-walled one. * Speak clearly at a moderate pace. Natural pauses are good. Avoid rushing and filler words. * A lavalier or USB microphone gives the best result, but built-in camera or laptop audio is fine in a quiet room. **No other voices at any point.** If someone else speaks during the recording, your voice won't be captured cleanly and the voice clone will be inaccurate. Don't call "action" or "cut", and don't have anyone feeding you lines. #### Test Setup Before Full Recording Record 30 seconds, stop, and watch it back at full size before doing the real take. Check: * Is the face sharp when you pause on a frame? * Is there a shadow across either side of the face? * Does your hair separate clearly from the background? * Is the audio clean, with no hum, echo, or room noise? * Are your lenses free of reflections? * Are your hands out of frame? Two minutes here saves a full reshoot later. #### Avoid Common Mistakes In rough order of frequency: * Missing or shortened silent opening * Very short recordings * Cuts or trims anywhere in the take * Another voice audible in the recording * Camera above or below eye level * Shadow across one side of the face, or a bright light behind the head * Hair or clothing too close in tone to the background * Another face visible in the background * Hands entering frame * Shoulders shrugging or posture shifting during the read * Loose hair falling across the face partway through * Auto exposure or white balance shifting mid-take ## Avatars from Single Images Custom avatar creation from single images is only available on demand for customers on paid plans. Contact [support@beyondpresence.ai](mailto:support@beyondpresence.ai) with your image. You can also create an avatar from a single photograph, with no recording session required. Quality won't match a video-trained avatar, but it's fast and needs nothing more than a good headshot. The photo does more work here than a single frame does in a video, since everything the avatar produces is derived from it. A neutral, evenly lit, front-facing image gives the model the most room to animate. | Requirement | Details | | - | - | | **Aspect ratio** | 16:9 landscape works well. Square (1:1) or portrait (9:16) is also fine. | | **Head & body position** | Straight and upright, facing the camera directly. Minimal head tilt or rotation, shoulders square to the frame. | | **Framing** | Head-and-shoulders, face centered, with a little headroom. Nothing cropped (full head visible), face not too small and not an extreme close-up. | | **Eyes** | Both eyes fully open and clearly visible, looking toward the camera. Not squinting, mid-blink, or covered by hair. Images with closed or partially closed eyes won't work. | | **Lips** | Closed, or a gentle closed-mouth smile. Avoid open mouths and wide teeth-showing grins. | | **Expression** | Neutral or very lightly smiling, with a relaxed, natural face. Avoid strong or exaggerated expressions. A broad smile, laughter, or raised eyebrows will carry into every frame the avatar produces. | | **Lighting** | Soft and even, lighting the face from the front. Avoid harsh shadows, strong backlight, and heavily coloured or rim lighting. | | **Subject** | One person only. Nothing covering the face or mouth. Glasses are usually fine. | | **Resolution** | Sharp, high-resolution image with the face taking up a good portion of the frame. 1080p or higher preferred. | | **Format** | JPG or PNG. | Avoid heavily filtered or retouched photos, and images that have been upscaled from a small original. Both tend to produce soft or unstable results. ## Consent and Ethics Every avatar requires the explicit, informed consent of the person being replicated, whether it's created from video or from a single image. We verify this during review. If the subject is a paid performer or an employee, make sure your agreement with them covers the creation and ongoing use of an AI likeness, the scope and duration of that use, and what happens if they leave. We don't create avatars of public figures, or of anyone who hasn't personally consented. # Beyond Presence Avatar Models Source: https://docs.bey.dev/concepts/avatars/index How Beyond Presence avatar models bring AI agents to life, and how stock and custom avatars differ. ## What are Avatars? Avatars are AI-generated digital humans that transform agents into lifelike video experiences. They deliver natural facial expressions, synchronized lip movements, and authentic human gestures that create genuine connections with users. Beyond Presence creates these digital representations using proprietary AI models trained on real-life footage, allowing them to authentically replicate a person's voice, appearance, and natural movement patterns. You can use avatars in two ways: * **With our platform**: Avatars power all agents that run on our infrastructure * **With your voice agents**: Avatars give any existing voice agent a lifelike visual presence ## Stock Avatars We provide a curated selection of high-quality [stock avatars](/concepts/avatars/stock) featuring professional models filmed in studio settings. These avatars offer excellent quality and are immediately available for your projects. ## Custom Avatars For personalized solutions, you can create [custom avatars](/concepts/avatars/custom) that only you can use. Custom avatars allow you to represent your brand, team members, or create unique digital personas tailored to your specific needs. ## Learn More Browse our professional avatar collection and start building immediately Create custom avatars exclusive to your account # Stock Avatars Source: https://docs.bey.dev/concepts/avatars/stock Beyond Presence Stock Avatars that are available to every account for immediate use. All accounts include access to these professional avatars, ready for immediate use in your video agents. To use an avatar in [API calls](/api-reference), set the `avatar_id` field to one of the IDs listed below. Browse all available avatars and preview them in action in your [Studio avatars tab](https://bey.studio/avatars). ID: `694c83e2-8895-4a98-bd16-56332ca3f449` ID: `b63ba4e6-d346-45d0-ad28-5ddffaac0bd0_v2` ID: `70b1b917-ed16-4531-bb6c-b0bdb79449b4` ID: `7c9ca52f-d4f7-46e1-a4b8-0c8655857cc3` # Studio Source: https://docs.bey.dev/concepts/studio Manage avatars, agents, API keys, analytics, and billing in the Beyond Presence Studio. The [Beyond Presence Studio](https://bey.studio) is where you'll create your account and manage video agents that run on our infrastructure. All video agents and custom avatars you create are tied to your account. The Studio is ideal for builders who prefer a low-code approach, though many developers find it sufficient for their use cases. For more programmatic control and flexibility, you can also integrate directly via the [Beyond Presence API](/concepts/api). ## Key Studio Features ### Avatar Management Access your avatar collection including both stock avatars provided by us and custom avatars you own. Browse, preview, and select avatars for your video agents. ### Agent Management Manage all Conversational Video Agents you have created in the Studio: * View your complete agent collection * Create new agents with custom configurations * Delete agents you no longer need * Review detailed agent settings and performance * Test agents through demo conversations * Export agents as shareable links or HTML-embeddable code snippets ### Knowledge Base Set up a centralized knowledge base of files that your agents can reference during conversations. See [Knowledge Base](/concepts/agents/knowledge-base) for how agents use knowledge files, file statuses, and size limits. ### Conversation Analytics Access detailed logs of conversations between users and your agents, plus AI-powered analysis providing insights into user interactions and agent performance. ### Billing Management Monitor your credit balance, review usage, and manage your subscription plan to ensure uninterrupted service. ### API Key Management Generate and manage API keys for authenticating requests when using the [Beyond Presence API](/concepts/api). ### Webhook Configuration Configure a webhook URL to receive real-time events from your agent conversations, including conversation initiation and message exchanges. # Choose Path Source: https://docs.bey.dev/get-started/choose-path Choose between Beyond Presence Managed Agents for zero-infrastructure deployment and the Speech-to-Video API for full control over STT, LLM, and TTS. Beyond Presence offers two main products: * A modular [Speech-to-Video API](/get-started/quickstart/speech-to-video) that receives audio via WebRTC and turns it into lifelike avatar video in real-time, * [Managed Agents](/get-started/quickstart/managed-agent) which provide a full end-to-end AI video conversation experience, with LLM, STT, TTS also fully managed by Beyond Presence. **Zero-infrastructure deployment** - Production-ready video agents in minutes with full pipeline management, 1-second end-to-end response times, and built-in optimizations. Supports no-code workflow automation via n8n. **Best for**: Quick deployment, no maintenance overhead, built-in scaling **Maximum control** - Add avatar video streams to existing voice agents with 250 ms response times while maintaining full control over STT, LLM, and TTS components. Supports LiveKit. **Best for**: Technical flexibility, custom components, existing voice pipelines ## Decision Guide | If you... | ... then use: | | - | - | | want the fastest go-live | [Managed Agents](/get-started/quickstart/managed-agent) - zero infrastructure, built-in optimizations, auto-scaling | | want total programmatic control | [Speech-to-Video](/get-started/quickstart/speech-to-video) - control every component in your agent pipeline | | have an existing voice agent | [Speech-to-Video](/get-started/quickstart/speech-to-video) - keep your current STT, LLM, and TTS stack | | need custom LLM control | Either [Managed Agents](/get-started/quickstart/managed-agent) with a [custom LLM](/concepts/agents/external-llm), or [Speech-to-Video](/get-started/quickstart/speech-to-video) if you want to manage the full LLM, STT, and TTS stack yourself. | | need workflow automation | [Managed Agents](/get-started/quickstart/managed-agent) with [n8n Workflows](/integrations/n8n) - automate conversation management and webhook processing | ## Get Started Start building with Beyond Presence Speech-to-Video API and LiveKit Agents. Start building with Beyond Presence Managed Agents - fully no-code! # Introduction Source: https://docs.bey.dev/get-started/index Beyond Presence is an enterprise-ready developer platform for hyper-realistic AI Avatars and Conversational Video Agents. ## What is Beyond Presence? Beyond Presence is a developer platform for **Conversational Video Agents** that look and feel like real people. ## Why Beyond Presence? Traditional chatbots feel robotic. Video calls require human availability. Beyond Presence bridges this gap with AI that maintains human connection at machine scale. Our proprietary real-time avatar models deliver hyper-realistic, multilingual, low-latency interactions. Built in Europe, for Enterprise scale. ### Key Features Powered by our proprietary AI research in computer vision and generative modeling. Our avatars deliver lifelike facial expressions, natural lip-sync, and human-like micro-movements that create genuine emotional connections with users. Industry-leading performance with 250 ms speech-to-video latency and 1-second end-to-end response times. Real-time conversations feel natural and fluid, eliminating the awkward delays that plague traditional video chat solutions. Handle hundreds of simultaneous video calls without performance degradation. Our distributed infrastructure automatically scales to meet demand, ensuring consistent quality whether you're serving one user or thousands. Visit our [Enterprise page](https://www.beyondpresence.ai/enterprise) for more information on Enterprise support. Choose your level of control: from fully managed Studio solutions to custom API components. Whether you need plug-and-play widgets or granular programmatic control, our platform adapts to your technical requirements and timeline. Built by ML engineers who understand your workflow. Clean APIs, comprehensive documentation, and thoughtful abstractions that let you focus on your product instead of wrestling with infrastructure complexity. We also have a [Discord community](https://bey.dev/community) where you can ask questions and get help from our team and other developers. ## Get Started Learn about our integration options and find the right path for you. Jump right into our Python Speech-to-Video Quickstart with LiveKit Agents ## Learn More LLM-powered AI assistants that can operate across text, voice, or video modalities. They understand context, maintain dialogue flow, and tailor responses to your use case and knowledge base. Digital human models that transform text or voice agents into video agents, complete with natural expressions, lip-sync, and human-like gestures. Web-based management interface for creating, configuring, and monitoring your video agents - upload knowledge bases, test conversations, and deploy without code. Direct programmatic access to our platform. Embed video agents into your applications and control agent behavior dynamically via our REST API. # Managed Agent Quickstart Source: https://docs.bey.dev/get-started/quickstart/managed-agent Create a no-code Managed Agent in the Beyond Presence Studio, embed it on your site with an iframe, and analyze conversations in the Studio. Managed Agents are ideal for quick prototyping and for zero-infrastructure deployments. If you already have a voice agent, or need full control over infrastructure and conversation data, use [Speech-to-Video](/get-started/quickstart/speech-to-video) instead. ## Part 1: Setup & Create Agent Create your first agent through the [Studio](/concepts/studio) for quick and simple prototyping: Go to the [Beyond Presence Studio](https://bey.studio) and sign up with either your email or your Google account. Go to the [Agents tab](https://bey.studio/agents) and click ["Create Agent"](https://bey.studio/agents/create). Select an avatar, give your agent a name, objective, and starting script, and click **"Generate Agent"**. Your agent is ready for deployment immediately. Once your agent is created, click on it in the [Agents tab](https://bey.studio/agents) and have a chat with it in the window that opens up. You can also share the link with your team or customers for initial feedback. To tweak the conversation settings of your agent, go to the [Agents tab](https://bey.studio/agents), hover your agent, and click **"... > Edit"**. ## Part 2: Integrate Agent Go to the [Agents tab](https://bey.studio/agents), hover your agent, and click **"... > Embed"**. Configure the settings as you see fit, then copy the Embed Code by clicking **"Copy"**. Paste the iframe Embed Code into your website or your product HTML section. That's it, your agent is now live in your web app! If iframe web embedding is not suitable for your use-case, check out our [other integration options](/integrations)! ## Part 3: Analyze Conversations Go to the Studio [Conversations tab](https://bey.studio/conversations) to see all conversations your agents have had. Alternatively, to see conversations of a specific agent, go to the [Agents tab](https://bey.studio/agents), hover your agent, and click **"... > Conversations"**. Click on a conversation entry to see an AI summary, AI insights, and suggested next steps. In the **"Conversation Transcript"** tab, you can find the full transcript, and also ask our AI for help with custom analyses. Go to the Studio [Analytics tab](https://bey.studio/analytics) to monitor the usage of your agents. ## Learn More Learn more about how to embed agents into your website or application using iframes ## Next Steps Use these advanced features to enhance your agents and automate workflows: Connect your own OpenAI-compatible LLM API to a Managed Agent Provide conversation-specific context to your agents Receive real-time events for conversations of your Managed Agents Enhance agents with webcam vision and wakeup mode Retrieve historical data for conversations of your Managed Agents Connect to agents using LiveKit Client SDK # Speech-to-Video Quickstart Source: https://docs.bey.dev/get-started/quickstart/speech-to-video Start building with Beyond Presence Speech-to-Video API and LiveKit Agents. Speech-to-Video API is ideal if you have an existing voice agent or need full control over your infrastructure and user data. For zero-infrastructure no-code deployment, use [Managed Agents](/get-started/quickstart/managed-agent) instead. ## Part 1: Set Up Beyond Presence Go to the [Beyond Presence Studio](https://bey.studio) and sign up with either your email or your Google account. Go to the [API Keys tab](https://bey.studio/settings/api-keys) in your account settings, create a new API key, and save it somewhere. Learn more about how to use API keys for using the Beyond Presence API. Go to the [Avatars tab](https://bey.studio/avatars) in the Studio and select an avatar you want to use in your application. Then hover the avatar, open the **"..."** menu, click **"Copy ID"**, and save it. Explore our stock avatars that can be used immediately. ## Part 2: Create a LiveKit Agent with Beyond Presence Avatar If you already have a functional LiveKit voice agent, skip to **Step 5**. Sign up to LiveKit at [https://cloud.livekit.io/](https://cloud.livekit.io/) and create a new project. In your LiveKit Cloud project, go to **"Settings" > "API Keys"**, generate a new LiveKit API key, and save the resulting code snippet. Set your Beyond Presence and LiveKit secrets as environment variables: ```bash theme={null} export BEY_API_KEY="..." # Your Beyond Presence API key from Step 1.2 export BEY_AVATAR_ID="..." # Your Beyond Presence Avatar ID from Step 1.3 export LIVEKIT_API_KEY="..." # From LiveKit API key setup (Step 2.2) export LIVEKIT_API_SECRET="..." # From LiveKit API key setup (Step 2.2) export LIVEKIT_URL="..." # From LiveKit API key setup (Step 2.2) ``` Clone the [LiveKit Agents Python Quickstart](https://github.com/livekit-examples/agent-starter-python/tree/7c0af539fe065e262f31942715f5f97e1579fd78) and follow the README to set up and run your first voice agent in a matter of minutes. Install the Beyond Presence LiveKit plugin `livekit-plugins-bey`: ```bash theme={null} pip install livekit-plugins-bey ``` Edit `src/agent.py` and add the Beyond Presence avatar to your voice agent: ```python theme={null} # session = AgentSession(...) from livekit.plugins import bey avatar = bey.AvatarSession(avatar_id=os.environ["BEY_AVATAR_ID"]) await avatar.start(session, room=ctx.room) # await session.start(...) ``` Note that Beyond Presence supports [several ways of technical integration](/integrations), but if you are familiar with Python, we recommend using our LiveKit Agents plugin as shown in this guide. ## Learn More Learn more about how Beyond Presence's LiveKit Agents plugin works. Learn how to create your own Beyond Presence avatar. # n8n Workflows Source: https://docs.bey.dev/integrations/n8n Automate Beyond Presence Managed Agent creation and webhook processing with the official n8n node. Beyond Presence provides an [official n8n node](https://n8n.io/integrations/beyond-presence/) for no-code workflow automation. Use the node to create agents that manage conversations and to process webhook events. See the [n8n node documentation](https://github.com/bey-dev/n8n-nodes-beyondpresence#readme) for setup instructions and features overview. ## Ready-Made Templates Explore these free templates to build your workflow automation: Analyze conversations with GPT-4 and save insights to Google Sheets Real-time lead scoring from conversation data Automated interview processing and scoring ## Other Integration Options Add Beyond Presence Managed Agents to your website or web app. Add avatar video to your existing LiveKit voice pipeline # Speech-to-Video Integration for Voice Agents Source: https://docs.bey.dev/integrations/voice-agents/index Add Beyond Presence avatars to your existing voice agent pipeline to maintain full control over turn detection, STT, LLM, and TTS. Most modular solution for technical teams. Send audio from your voice agent, receive avatar video streams with **250 ms response times** from audio input to HD avatar video output. The Speech-to-Video API expects the **agent's spoken response audio** (typically your TTS output) as input, not the user's raw microphone audio. To create your own Conversational Video Agent, run the user audio through your own STT → LLM → TTS pipeline first, then forward the TTS output to the Speech-to-Video API. ## When to Use This Choose Speech-to-Video when you need: * **Component-level control**: Complete management of turn detection, STT, LLM, and TTS components * **Complex tool calling**: Flexible LLM integrations with external APIs and databases * **Voice infrastructure migration**: Seamless upgrade path for existing voice agent infrastructure For zero-infrastructure deployment, use [Managed Agents](/get-started/quickstart/managed-agent) instead. ## Pipeline Overview You manage media transport, turn detection, STT, LLM, and TTS components Receives audio input from your pipeline Beyond Presence manages avatar generation and video streaming ## Supported Frameworks We support integration with popular voice agent frameworks including **LiveKit**, allowing you to add avatar video to your existing voice pipelines. Add avatars to your LiveKit agents with our plugin ## Other Integration Options Add Beyond Presence Managed Agents to your website or web app. No-code workflow automation for managing conversations with Beyond Presence Managed Agents. # LiveKit Plugin Source: https://docs.bey.dev/integrations/voice-agents/livekit Install the livekit-plugins-bey plugin for Python or JavaScript to add Beyond Presence avatars to your existing LiveKit Agents pipeline. Integrate Beyond Presence avatars with [LiveKit Agents](https://docs.livekit.io/agents) using our official plugin. ## Installation ```sh Python theme={null} pip install livekit-plugins-bey ``` ```sh JavaScript theme={null} pnpm add @livekit/agents-plugin-bey ``` ## Quickstart Get started quickly with Beyond Presence and LiveKit Agents following our Speech-to-Video Quickstart: Quickstart for Speech-to-Video API with LiveKit Agents ## Complete Example See our LiveKit agent example for full implementation in both Python and JavaScript, including environment setup, voice processing, avatar integration, and client configuration: Complete implementation example with setup instructions # iframe Embedding Source: https://docs.bey.dev/integrations/web/iframe-embedding Embed a Beyond Presence Managed Agent in any webpage via iframe. Embed your agents into any webpage using a simple iframe element. The agent appears as an interactive video call interface within your existing UI. ## Use Cases iframe embedding is ideal for: * **Seamless experience**: Keep users on your platform without redirecting to external pages * **Custom branding**: Maintain your own branding instead of Beyond Presence's default interface * **Conversion optimization**: Reduce friction by embedding agents directly in your sales funnel * **Unified interface**: Integrate AI assistance alongside your existing features and content ## Configuration Embed your agent using this HTML snippet: ```html theme={null} ``` Replace `{agent-id}` with your agent's ID and adjust the iframe dimensions as needed. Extract the agent ID from the direct conversation link - it's the string after `bey.chat/`. Get the iframe code directly from [the Studio](https://bey.studio/agents) by clicking **Embed** in the agent card's options menu. # Web & Mobile Integration Source: https://docs.bey.dev/integrations/web/index Add Beyond Presence Managed Agents to a web or mobile app with iframe embedding for a ready-made call UI or the LiveKit Client SDK for a custom interface. Beyond Presence [Managed Agents](/get-started/quickstart/managed-agent) can be added to any web or mobile app - either embedded as a ready-made widget or wired into a fully custom interface you build yourself. ## Choose Your Integration Path **Just need an agent on your site?** Use [iframe Embedding](/integrations/web/iframe-embedding) to drop in a fully managed video call UI with a single `