Volt AI Avatar Integration Guide

Overview

The Volt AI Avatar API allows you to create interactive AI avatars with custom knowledge bases, enabling rich conversational experiences for your users. This API generates secure, token-based URLs that can be embedded in your application via iframes.

Key Features

Secure Authentication: API key-based authentication with token generation

Custom Knowledge Bases: Train avatars with your specific content and data

Multi-Language Support: Support for English, Indonesian, Chinese, and Arabic

Easy Integration: Simple iframe embedding in any web application

How It Works

Authenticate: Send a POST request with your API key to create a media URL

Receive Token: Get a secure token and complete embed URL in the response

Embed: Use the URL in an iframe to display the interactive avatar

Authentication

The Volt AI Avatar API uses API key authentication. Include your API key in the request header to authenticate your requests.

Authentication Header

Include the following header in all API requests:

X-API-KEY: your_api_key_here

Security Best Practices

Store API keys in environment variables, not in code

Make API calls from your backend server, not client-side JavaScript

Rotate API keys periodically for enhanced security

Use HTTPS for all API requests to ensure data encryption

Monitor API usage and set up alerts for unusual activity

Security Warning: Never expose your API key in client-side code or public repositories. Always store it securely in environment variables or secure backend services.

API Reference

Endpoint

POST http://mamba.getvolt.io/api/auth/create-media-url

Creates a secure token and URL for embedding an AI avatar

Request Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes
`X-API-KEY`	`your_api_key`	Yes

Request Body Parameters

Parameter	Type	Required	Description
`email`	string	Yes	User's email address for session tracking
`name`	string	Yes	User's display name for personalization
`origin`	string	Yes	Your application's domain URL for CORS validation
`avatar_id`	integer	Conditional	ID of the avatar to use (required if not using voice_id)
`voice_id`	integer	Conditional	ID of the voice to use (required if not using avatar_id)
`knowledge_base_id`	string	Yes	ID of the knowledge base for avatar responses
`lang_id`	string	Yes	Language code (en-US, id-ID, zh-CN, ar-AE, ar-SA)

Success Response (200 OK)

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.url`	string	Base URL for embedding
`data.token`	string	JWT token for authentication (expires in 24 hours)
`data.complete_url`	string	Ready-to-use URL with token included

Example Response:

{
  "success": true,
  "data": {
    "url": "https://avatar.getvolt.io/v2/stream-embed",
    "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
    "complete_url": "https://avatar.getvolt.io/v2/stream-embed?token=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
  }
}

Error Responses

401 Unauthorized

Invalid or missing API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

400 Bad Request

Missing or invalid request parameters

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: knowledge_base_id"
  }
}

404 Not Found

Avatar or knowledge base not found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Avatar not found"
  }
}

429 Too Many Requests

Rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later"
  }
}

Code Examples

cURL

JavaScript/Node.js

React

Python

Direct iFrame Embedding

Use the complete_url from the API response:

Integration Guide

Step 1: Set Up Your Environment

Store your API key securely in environment variables. Never hardcode it in your source code.

Step 2: Create Backend Endpoint

Create a server-side endpoint that calls the Volt API. This protects your API key from exposure.

Security Best Practice: Always make API calls from your backend server, never directly from client-side JavaScript.

Step 3: Make the API Request

Call the create-media-url endpoint with required parameters:

User email and name for personalization

Your application's origin URL

Avatar ID or Voice ID

Knowledge base ID

Preferred language code

Step 4: Handle the Response

Extract the complete_url from the successful response. This URL contains the embedded token and is ready to use.

Step 5: Embed the Avatar

Use an iframe element to embed the avatar in your application:

Step 6: Test Your Integration

Verify that:

✓ The avatar loads correctly

✓ Camera and microphone permissions work

✓ The avatar responds with knowledge base content

✓ Error handling works for invalid requests

Troubleshooting & FAQ

Getting 401 Unauthorized error

Possible causes:

API key is incorrect or missing

API key is not included in the X-API-KEY header

API key has been revoked or expired

Solutions:

Verify your API key is correct

Ensure the header name is exactly "X-API-KEY" (case-sensitive)

Check that you're not accidentally including extra whitespace in the API key

Avatar not loading in iframe

Possible causes:

CORS policy blocking the iframe

Invalid or expired token

Missing required iframe attributes

Solutions:

Ensure the 'origin' parameter in your API request matches your actual domain

Include all required iframe attributes: allow="clipboard-read; clipboard-write; camera; microphone"

Check browser console for specific error messages

Verify the token hasn't expired (tokens are valid for 24 hours)

Camera/microphone permissions not working

Solutions:

Ensure the iframe has the allow attribute: allow="clipboard-read; clipboard-write; camera; microphone"

Your site must be served over HTTPS (camera/microphone require secure context)

User must grant permission when prompted by the browser

Check browser settings to ensure camera/microphone are not blocked for your domain

Getting 404 Not Found error

Possible causes:

Invalid avatar_id or knowledge_base_id

Using an ID that doesn't belong to your account

Resource has been deleted

Solutions:

Verify the avatar_id exists in your avatar list

Verify the knowledge_base_id exists and is accessible

Double-check for typos in the IDs

Ensure you're using numeric IDs for avatar_id, string IDs for knowledge_base_id

Avatar responses are not using my knowledge base

Possible causes:

Knowledge base is empty or not properly indexed

Incorrect knowledge_base_id provided

Knowledge base content is still being processed

Solutions:

Navigate to the Knowledge Base section and verify content exists

Ensure the knowledge base status is "Active" or "Ready"

Wait a few minutes if you just uploaded new content

Try asking questions directly related to your knowledge base content

Rate limit errors (429)

Solutions:

Implement exponential backoff in your retry logic

Cache the media URL and reuse it for the same user session

Tokens are valid for 24 hours - don't request a new one for every page load

Contact support if you need higher rate limits for production use

How long is a token valid?

Tokens are valid for 24 hours from the time of creation. After expiration, you'll need to request a new token by calling the create-media-url endpoint again.

Best practice: Implement token refresh logic in your application to request a new token before the current one expires, ensuring uninterrupted service for your users.

Can I use this in a mobile app?

Yes, you can embed the avatar in mobile apps using WebView components:

React Native: Use the WebView component from react-native-webview

iOS: Use WKWebView and grant necessary permissions

Android: Use WebView with camera/microphone permissions enabled

Ensure your WebView configuration allows camera and microphone access for full functionality.

Support

If you're still experiencing issues, check your browser console for detailed error messages. These often provide specific information about what went wrong.

Volt AI Avatar Integration Guide

Overview#

Key Features#

How It Works#

Authentication#

Authentication Header#

Security Best Practices#

API Reference#

Endpoint#

Request Headers#

Request Body Parameters#

Success Response (200 OK)#

Error Responses#

401 Unauthorized#

400 Bad Request#

404 Not Found#

429 Too Many Requests#

Code Examples#

cURL#

JavaScript/Node.js#

React#

Python#

Direct iFrame Embedding#

Integration Guide#

Step 1: Set Up Your Environment#

Step 2: Create Backend Endpoint#

Step 3: Make the API Request#

Step 4: Handle the Response#

Step 5: Embed the Avatar#

Step 6: Test Your Integration#

Troubleshooting & FAQ#

Getting 401 Unauthorized error#

Avatar not loading in iframe#

Camera/microphone permissions not working#

Getting 404 Not Found error#

Avatar responses are not using my knowledge base#

Rate limit errors (429)#

How long is a token valid?#

Can I use this in a mobile app?#

Support#

Overview

Key Features

How It Works

Authentication

Authentication Header

Security Best Practices

API Reference

Endpoint

Request Headers

Request Body Parameters

Success Response (200 OK)

Error Responses

401 Unauthorized

400 Bad Request

404 Not Found

429 Too Many Requests

Code Examples

cURL

JavaScript/Node.js

React

Python

Direct iFrame Embedding

Integration Guide

Step 1: Set Up Your Environment

Step 2: Create Backend Endpoint

Step 3: Make the API Request

Step 4: Handle the Response

Step 5: Embed the Avatar

Step 6: Test Your Integration

Troubleshooting & FAQ

Getting 401 Unauthorized error

Avatar not loading in iframe

Camera/microphone permissions not working

Getting 404 Not Found error

Avatar responses are not using my knowledge base

Rate limit errors (429)

How long is a token valid?

Can I use this in a mobile app?

Support