AIVAАйва
Консоль

API

WebRTC, WebSocket и REST

Варианты API

console поддерживает 3 способа запуска агентов через API:

  1. WebRTC - Для клиент-серверного взаимодействия (в приложении или на сайте)
  2. WebSocket - Для сервер-серверного взаимодействия (в телефонии, через прокси-сервер)
  3. REST - Клиент-серверное или сервер-серверное взаимодействие (только для чата)
ФункцияWebRTCWebSocketREST
Реализовано✅✅❌
Поддержка чата✅✅✅
Стриминг✅✅❌
Аудио✅✅❌
Стейт✅ На сервере✅ На сервере❌ Клиент должен хранить 'interaction_id'
АвторизацияВременный token или API keyВременный token или API keyВременный token или API key

Аутентификация и авторизация

Все API ключи следуют формату sk_ за которым следуют 32 случайных буквенно-цифровых символа. Ключи могут иметь опциональные даты истечения.

Создание ключа

API ключи можно создать через веб-интерфейс или API:

Через API (требует JWT аутентификацию):

POST /api/keys
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "My API Key",
  "expiry_secs": 2592000  // Optional: 30 days, null = immortal
}

Ответ:

{
  "id": 123,
  "name": "My API Key",
  "key": "sk_AbC123...", // Only returned once!
  "created_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-31T00:00:00Z",
  "revoked": false,
  "revocation_reason": null
}

⚠️ Важно: Значение API ключа возвращается только один раз при создании. Сохраните его.

Использование ключей

Authorization: Bearer sk_your_api_key_here

Эта форма принимается всеми REST / WebSocket / WebRTC эндпоинтами.

Управление ключами

Список API ключей:

GET /api/keys
Authorization: Bearer <jwt_token>

Отзыв API ключа:

DELETE /api/keys/{key_id}
Authorization: Bearer <jwt_token>

Ответы с ошибками

StatusErrorОписание
401"Invalid API key"Ключ не найден или неверный формат
401"API key revoked: expired"Срок действия ключа истек
401"API key revoked: banned"Вы нарушили условия использования ключа

Временные токены

В клиентских приложениях нужно генерировать недолговечные токены (30 секунд) вместо прямого использования статических API ключей:

Генерация временного токена с API ключом:

POST /api/token/generate
Authorization: Bearer sk_your_api_key_here
Content-Type: application/json

Генерация временного токена без API ключа (с ограничением частоты):

POST /api/token/generate
Content-Type: application/json

Ответ:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Использование токена в соединениях:

// Use ephemeral token instead of API key
{
  "agent_uuid": "your-agent-uuid",
  "api_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",  // ephemeral token
  "response_medium": "chat"
}

Общие элементы

Инициализация

И WebRTC, и WebSocket соединения используют одинаковую структуру инициализации:

{
  "agent_uuid": "<uuid or b-number>",
  "api_key": "sk_your_api_key_here",
  "response_medium": "chat|voice|both",
  "response_format": "raw|base64",
  "messages": [{ "role": "user", "content": "initial message" }],
  "data_input": {},
  "vendor": "default|voximplant|jivo"
}

Обязательные параметры:

  • agent_uuid: UUID агента (или маппинг B-номера)
  • api_key: Ваш API ключ для аутентификации (формат: sk_ + 32 символа) или токен. Обязателен для всех соединений.

Опциональные параметры:

  • response_medium: Как агент будет отвечать ("chat", "voice", или "both"). По умолчанию: "both"
  • response_format: Только WebSockets Будут ли аудиоданные предоставлены как байты или base64-кодированная строка ("raw" или "base64"). По умолчанию: "raw"
  • messages: Начальная история разговора. Должна чередоваться между пользователем и ассистентом, заканчиваясь пользователем. Может быть пустой
  • data_input: Входные данные для агента. Любые входные данные разрешены, но будут обработаны только ключи, определенные в агенте
  • vendor: Поставщик клиента для специальной обработки данных. В большинстве случаев используйте значение по умолчанию: "default"

Методы аутентификации:

  • Статические API Keys: Долгоживущие ключи, начинающиеся с sk_, созданные через веб-интерфейс или API
  • Временные токены (Рекомендуется): Недолговечные токены (30 секунд), генерируемые через endpoint /api/token/generate

⚠️ Примечание по безопасности: WebRTC обязаны должны использовать временные токены, в то время как WebSocket соединения могут использовать любой метод.

Типы ответов

Все ответы от сервера (независимо от типа соединения) используют эти типы ответов:

  1. Content: Обычное текстовое содержимое от агента. Содержимое поступает частями.
{
  "emission_type": "content",
  "content": "message text here"
}
  1. Completion: Сигнализирует о завершении взаимодействия или передаче. Сервер разорвет соединение после этой эмиссии.
{
  "emission_type": "completion",
  "completion_type": "turn|termination|transfer",
  "target": "optional target for transfer"
}
  1. Error: Сообщения об ошибках сервера.
{
  "emission_type": "error",
  "error_message": "error details"
}
  1. Tool Call: Агент использует инструмент
{
  "emission_type": "tool_call",
  "call": {
    "tool_name": "name of tool",
    "tool_type": "tool type",
    "call_reason": "reason for call",
    "arguments": {}
  }
}
  1. Tool Response: Ответ от вызова инструмента. Может содержать ошибки.
{
  "emission_type": "tool_response",
  "response": {
    "tool_name": "name of tool",
    "tool_type": "tool type",
    "content": "response content"
  }
}
  1. опционально Recognized Speech: Результаты распознавания речи. Примечание: предоставляется только если аудио отправляется от клиента
{
  "emission_type": "recognized_speech",
  "content": "recognized text"
}

WebSocket API

Инициализация агента по вебсокету происходит по адресу:

wss://app.aiva.chat/run/ws

Поток соединения

  1. Начальное соединение: Подключение к WebSocket endpoint
  2. Инициализация сессии: Отправка AgentStartRequest как первого сообщения
  3. Ответ на handshake: Сервер отвечает со статусом и interaction ID
json
{
  "status": "ready",
  "message": "Ready to receive messages",
  "interaction_id": "<interaction_id>"
}

Отправка сообщений

  1. Текстовые сообщения
{
  "text": "your message here"
}
  1. Аудио сообщения
  • Бинарный формат: Необработанные аудио байты
  • Base64 формат: 
    json
{
"audio": "<base64-encoded-audio>",
"timestamp": "<optional-timestamp>"
}

Получение ответов

Все ответы используют общие типы ответов, описанные выше. Аудио отправляется как:

  • Необработанные бинарные данные, если response_format равен "raw"
  • Base64 кодированные в JSON сообщении, если response_format равен "base64" 
    json
{
  "audio": "<base64-encoded-audio>"
}

Минимальный пример

Начните работу с websockets, запустив этот минимальный пример кода Python для командной строки:

import asyncio, json, websockets
from prompt_toolkit import PromptSession
from prompt_toolkit.patch_stdout import patch_stdout

URL = "wss://app.aiva.chat/run/ws"
UUID = "YOUR_AGENT_UUID" # возьмите uuid с URL страницы агента /talk
KEY = "YOUR_API_KEY" # ваш api key доступен в настройках аккаунта

async def main():
    async with websockets.connect(URL) as ws:
        # Отправка инициализационного сообщения с API ключом
        await ws.send(json.dumps({
            "agent_uuid": UUID,
            "api_key": KEY,  # API ключ для аутентификации
            "messages": [],
            "data_input": {},
            "response_medium": "chat"
        }))

        # Ожидание ответа на handshake
        handshake = json.loads(await ws.recv())
        print(f"Подключено: {handshake.get('message', 'Ready')}")

        session = PromptSession()

        async def send():
            while True:
                msg = await session.prompt_async("You: ")
                if msg.strip():
                    await ws.send(json.dumps({"text": msg.strip()}))

        async def recv():
            async for raw in ws:
                data = json.loads(raw)
                if data.get("emission_type") == "content":
                    print(f"Bot: {data.get('content', '')}", end='', flush=True)
                elif data.get("emission_type") == "completion":
                    print(f"\n[Session ended: {data.get('completion_type')}]")
                    break

        with patch_stdout():
            await asyncio.gather(send(), recv())

asyncio.run(main())

Примеры аутентификации

Использование Authorization Header с curl:

# WebSocket соединение с API ключом
curl -H "Authorization: Bearer your_api_key_here" \
     -H "Upgrade: websocket" \
     -H "Connection: Upgrade" \
     "wss://app.aiva.chat/run/ws"

# REST API вызов с API ключом
curl -X POST "https://app.aiva.chat/api/agents/start" \
     -H "Authorization: Bearer your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"agent_uuid": "your-uuid", "message": "Hello"}'

Пример JavaScript/Node.js:

const WebSocket = require("ws");

const ws = new WebSocket("wss://app.aiva.chat/run/ws", {
  headers: {
    Authorization: "Bearer your_api_key_here",
  },
});

ws.on("open", function () {
  // Отправка инициализации
  ws.send(
    JSON.stringify({
      agent_uuid: "your-agent-uuid",
      api_key: "your_api_key_here",
      response_medium: "chat",
      messages: [],
    })
  );
});

ws.on("message", function (data) {
  const message = JSON.parse(data);
  if (message.emission_type === "content") {
    console.log("Bot:", message.content);
  }
});

WebRTC API

Детали соединения

WebRTC endpoint доступен по адресу:

POST https://<your-server>/offer

Поток соединения

  1. Создание Offer: Создание WebRTC offer на стороне клиента
  2. Отправка Offer: Отправка offer вместе с данными инициализации агента
{
  "sdp": "<session-description>",
  "type": "offer",
  "agent_uuid": "<uuid>",
  "api_key": "<api-key>",
  "response_medium": "both",
  ...other initialization parameters
}
  1. Обработка Answer: Получение и обработка SDP answer от сервера
{
  "sdp": "<session-description>",
  "type": "answer"
}

Каналы данных

WebRTC использует канал данных с названием "messages" со следующими параметрами:

  • id: 0
  • ordered: true
  • negotiated: true

Отправка сообщений

  1. Текстовые сообщения: Отправка JSON через канал данных
{
  "text": "your message here"
}
  1. Аудио сообщения: Аудио автоматически отправляется через аудио трек

Получение ответов

  1. Текстовые/контрольные сообщения: Получаются через канал данных используя общие типы ответов
  2. Аудио: Получается через WebRTC аудио трек

Завершение соединения

Соединение может быть завершено:

  1. Отключением клиента
  2. Сервером, отправляющим completion emission с типом "termination"
  3. Выключением сервера Восстановление соединения в случае отключения со стороны сервера невозможно.

Tools

Integrations and functions for agents

Звоним с сайта с помощью SDK

Интеграция агента в веб-приложение через SDK