Кейсы
Звоним с сайта с помощью SDK
Интеграция агента в веб-приложение через SDK
Итак, вы хотите добавить агента в свое веб-приложение. Для этого вам понадобится 2 наших SDK:
- Клиент - браузер пользователя, с которого он обращается к Серверу аутенфикации и console. На клиенте используем JavaScript SDK (aiva-client-js-sdk)
- Сервер аутенфикации - ваш сервер, который будет выдавать Клиенту токены авторизации. На нем используем Python SDK (aiva)
🔑 1. Получите API ключ
- Зайдите на https://app.aiva.chat
- Зарегистрируйтесь или войдите в аккаунт
- Нажмите на свою аватарку -> API ключи
- Создайте новый API ключ
- Сохраните ключ в безопасном месте
🖥️ 2. Создайте сервер аутенфикации на Питоне
Ваш API-ключ нельзя показывать браузерам, ведь тогда пользователи смогут его украсть. Поэтому console авторизует взаимодействия одноразовым токеном, который действует 30 секунд. Этот токен выдает API console. Python SDK упрощает взаимодействие с этим API
2.1. Установите пакет
pip install aiva
2.2. Создайте простой сервер аутенфикации
Создайте файл token_server.py:
from aiva import aivaTokenServer
def main():
# Настройка сервера токенов
server = aivaTokenServer(
tos_base_url="https://app.aiva.chat", # URL бэкенда TOS
api_key="your-api-key", # Ваш API ключ
host="0.0.0.0", # Хост сервера
port=8001 # Порт сервера
)
print("🚀 Запуск токен-сервера на http://localhost:8001")
print("📖 Документация доступна на http://localhost:8001/docs")
# Запуск сервера (блокирующий)
server.run()
if __name__ == "__main__":
main()
2.3. Проверьте сервер аутенфикации
# Запуск сервера
python token_server.py
# В другом терминале - тест токена
curl -X POST http://localhost:8001/token
# Ответ:
# {
# "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
# }
NB: вы можете добавить свою логику аутенфикации на сервер. В руководстве показан сервер, который примет любый входящий запрос.
🌐 3. Настройка клиента на Джаваскрипте
3.1. Установите клиентский SDK
npm install aiva-client-js-sdk
3.2. Сконфигурируйте обязательные параметры
import { aivaWebClient } from "aiva-client-js-sdk";
// Создание клиента с аутентификацией по токену
const client = new aivaWebClient({
serverUrl: "https://your-runtime-server.com", // Сервер выполнения (/run/voice/offer)
tokenServerUrl: "http://localhost:8001", // Токен-сервер (/token)
});
3.3. Обрабатывайте получаемые события
// Начало звонка
client.on("call_started", () => {
console.log("🚀 Звонок начался");
updateUI("connected");
});
// Конец звонка
client.on("call_ended", () => {
console.log("📞 Звонок завершен");
updateUI("disconnected");
});
// Агент начал говорить
client.on("agent_start_talking", () => {
console.log("🎤 Агент начал говорить");
showSpeakingIndicator(true);
});
// Агент закончил говорить
client.on("agent_stop_talking", () => {
console.log("🔇 Агент закончил говорить");
showSpeakingIndicator(false);
});
// Получение сообщений
client.on("update", (message) => {
console.log("📨 Получено сообщение:", message);
displayMessage(message);
});
// Обработка ошибок
client.on("error", (error) => {
console.error("❌ Ошибка:", error);
showError(error.message);
});
// Изменение состояния соединения
client.on("connection_state_change", (state) => {
console.log("🔗 Состояние соединения:", state);
updateConnectionStatus(state);
});
3.4. Начните звонок
async function startCall() {
try {
await client.startCall({
agentUuid: "your-agent-uuid", // UUID агента
allowedResponses: ["text", "voice"], // Разрешенные типы ответов
sampleRate: 24000, // Частота дискретизации аудио
emitRawAudioSamples: true, // Эмиссия сырых аудио данных
dataInput: {
// Начальные данные для агента
userId: "user123",
context: "support_call",
},
messages: [
// Начальные сообщения
{
type: "system",
content: "Вы помощник службы поддержки",
},
],
});
console.log("✅ Звонок успешно начат");
} catch (error) {
console.error("❌ Ошибка при начале звонка:", error);
}
}
3.5. Отправляйте аудио
// Включение эмиссии сырых аудио данных
client.on("audio", (audioData) => {
console.log("🎵 Получены аудио данные:", audioData.length, "сэмплов");
// audioData - это Float32Array с PCM данными
// Можно обработать, сохранить или передать дальше
processAudioData(audioData);
});
function processAudioData(float32Audio) {
// Пример: конвертация в другой формат
const uint8Audio = convertFloat32ToUnsigned8(float32Audio);
// Или анализ громкости
const volume = calculateVolume(float32Audio);
updateVolumeIndicator(volume);
}
3.6. Отправляйте текстовые сообщения
function sendMessage(text) {
const success = client.sendMessage(text);
if (success) {
console.log("📤 Сообщение отправлено:", text);
addMessageToChat("user", text);
} else {
console.error("❌ Не удалось отправить сообщение");
}
}
// Пример использования
sendMessage("Привет, мне нужна помощь с заказом");
3.7. Завершите звонок
function stopCall() {
client.stopCall();
console.log("📞 Звонок остановлен");
}
🧪 4. Все слишком сложно, ничего не понятно
Вы можете воспрользоваться demo.py и test-browser.js в наших SDK, чтобы попробовать минимальные примеры
# В корневой папке python SDK
python demo.py
# В корневой папке javascript SDK
npm run build
# Запуск тест-сервера
npm run demo
# Откройте http://localhost:3000
Начните с простых примеров и постепенно добавляйте функциональность по мере необходимости. Удачи в разработке! Присоединяйтесь к нашему tg-каналу и чату для обсуждения и поддержки.