Getting Started with Velora!

Build and deploy your first AI agent in under 5 minutes.

1. Create an account

2. Create an agent

From the dashboard, click "+ New Agent" or pick a template. Give your agent a name, type, and personality.

3. Train with documents

Go to Knowledge Base and upload PDFs, DOCX, TXT, CSV files or add URLs. Your agent learns from them automatically using hybrid vector search (semantic + keyword).

4. Test in the playground

Open the Playground tab and chat with your agent. Test questions, check sources, and refine the personality.

5. Deploy

Go to Deploy, generate an API key, and choose your deployment method: website widget, mobile PWA, Telegram bot, or API.

API Reference

Authenticate with an API key using the X-API-Key header.

POST/api/widget/{agent_id}/chat

Send a message and receive a streaming response (SSE).

Request

curl -X POST "https://your-backend.com/api/widget/{agent_id}/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vk_your_api_key" \
  -d '{
    "message": "What is your return policy?",
    "conversation_id": null
  }'

Response (SSE stream)

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "metadata", "conversation_id": "uuid", "sources": ["faq.pdf"], "response_time_ms": 1234}
data: [DONE]

GET/api/widget/{agent_id}/config

Get agent configuration (name, greeting, color). Requires API key.

curl "https://your-backend.com/api/widget/{agent_id}/config" \
  -H "X-API-Key: vk_your_api_key"

Response

{
  "agent_name": "Support Bot",
  "greeting_message": "Hi! How can I help?",
  "widget_color": "#6366f1",
  "widget_position": "bottom-right",
  "enable_voice": false,
  "enable_vision": false
}

GET/api/widget/{agent_id}/public-config

Get minimal public info (no API key required). Used by the PWA landing page.

curl "https://your-backend.com/api/widget/{agent_id}/public-config"

Website Widget

Embed a chat bubble on any website with a single script tag.

Installation

Add this script before the closing </body> tag:

<script
  src="https://your-backend.com/widget/widget.js"
  data-agent-id="your-agent-id"
  data-api-key="vk_your_api_key"
  data-host="https://your-backend.com"
></script>

Customization

The widget automatically uses your agent's configured color and position. Change these in Settings → Widget tab in the dashboard.

Supported options

widget_color: Hex color for the chat bubble and header

widget_position — bottom-right or bottom-left

Mobile App (PWA)

Share your agent as a standalone mobile app. No app store needed.

How it works

Each agent gets a unique shareable URL:

https://your-app.com/a/{agent_id}?key=vk_your_api_key

When users open this on mobile:

1. They see a full-screen chat interface with your agent's branding

2. They can tap "Add to Home Screen" in the browser menu

3. The agent installs as a standalone app with its own icon and name

4. Each agent installs as a separate app — completely isolated

Note on HTTPS

The automatic install prompt only appears on HTTPS. On localhost, users need to manually use "Add to Home Screen" from the browser menu.

Telegram Bot

Deploy your agent as a Telegram bot.

1. Create a bot

Open Telegram, search for @BotFather, send /newbot, and follow the instructions.

2. Connect to Velora!

Go to your agent's Deploy page, scroll to Telegram Bot, paste the token from BotFather, and click Connect.

3. Start the bot

Click Start on the dashboard. Your bot is now live and uses the same RAG pipeline, tools, and personality as your agent.

Commands

/start: Start the conversation

/help: Show help message

/new: Start a new conversation

Integrations

Connect external services so your agent can read and act on real data.

📧

Gmail

Read, search, draft, and send emails

Read (auto), Send (approval required)

📅

Google Calendar

Read events, find free time, create events

Read (auto), Create (approval required)

📁

Google Drive

Search and list files

Read-only (auto)

🎬

YouTube

Search videos, get video details

Read-only (auto)

💬

Slack

List channels, read history, send messages

Read (auto), Send (approval required)

🟠

HubSpot

Search contacts and deals, create records

Read (auto), Create (approval required)

All integrations use OAuth 2.0. Connect from your agent's Integrations tab. Tokens are encrypted at rest using Fernet symmetric encryption.

Agent Tools

Every agent has access to built-in tools. The AI decides when to use them.

web_search

Search the web using DuckDuckGo

AUTO

calculator

Evaluate math expressions

AUTO

get_datetime

Get current date, time, and timezone

AUTO

read_emails

Read recent emails from Gmail

AUTO

send_email

Send an email via Gmail

APPROVAL

read_events

Read calendar events

AUTO

create_event

Create a calendar event

APPROVAL

search_drive

Search Google Drive files

AUTO

search_youtube

Search YouTube videos

AUTO

send_slack_message

Send a Slack message

APPROVAL

create_hubspot_contact

Create a HubSpot contact

APPROVAL

Permission levels

AUTO: Agent uses the tool automatically without asking.

APPROVAL: Agent asks the user for permission before executing.

Custom APIs

Connect any REST API as an agent tool - your CRM, internal services, or third-party APIs.

How to add a custom API

Go to your agent's Integrations page, scroll to Custom APIs, and click "+ Add API".

Configuration fields

Tool Name: Unique identifier (e.g., get_weather). No spaces.

Description: What the API does. The AI reads this to decide when to use it.

Method: GET, POST, PUT, or DELETE.

URL: Full endpoint URL. Use {param} placeholders for dynamic values.

Parameters: JSON array defining what inputs the AI should provide.

Headers: JSON object for auth headers, API keys, etc.

Body Template: JSON template for POST/PUT requests.

Response Path: JSONPath to extract useful data from the response.

Example: Weather API

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "method": "GET",
  "url": "https://api.weather.com/v1/current?city={city}",
  "parameters": [
    {
      "name": "city",
      "type": "string",
      "description": "City name",
      "required": true
    }
  ],
  "headers": {
    "X-Api-Key": "your-weather-api-key"
  }
}