Інтеграція Vonage (Nexmo) для голосового AI: WebSocket, NCCO

Інтеграція Vonage (Nexmo) для голосового AI

При розробці голосового AI-асистента ключова складність — організація real-time аудіостріму з мінімальною затримкою. Дзвінок має оброблятися в реальному часі: кожна зайва мілісекунда призводить до втрати контексту та погіршення користувацького досвіду. Vonage Voice API (колишній Nexmo) пропонує інтерфейс на основі WebSocket для прямої передачі аудіо, але налаштування вимагає глибокого розуміння NCCO та протоколів потокової передачі. Ми, як інтегратори з багаторічним досвідом, реалізували десятки проєктів на цьому стеку — від простих IVR до мультимовних асистентів із перекладом. Наші клієнти отримують стабільне з'єднання з latency p99 менше 500 мс і гарантованим uptime 99,9%.

Чому Vonage краще Twilio для голосового AI?

Vonage виграє за трьома параметрами. SIP-інтеграція на рівні API — не потрібні додаткові шлюзи. Покриття номерів у Європі щільніше: 70+ країн проти 50 у Twilio. Тарифи на вихідні дзвінки в середньому нижчі при обсягах >1000 хвилин/міс, що дає відчутну економію бюджету — до 35% на великих проєктах.

Основні NCCO дії для голосового AI

Налаштування WebSocket-обробника для низької затримки

База — FastAPI + WebSocket. Приймаємо NCCO через /answer, стрімимо аудіо на /voice-stream/. Всередині — конвеєр: VAD (напр. Silero VAD) → ASR (Whisper або власний) → NLP (RAG / LLM) → TTS. Весь трафік залишається на вашому сервері, що важливо для безпеки та дотримання специфікації WebSocket.

from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app = FastAPI() @app.get("/answer") async def answer_call(uuid: str, conversation_uuid: str): """NCCO для вхідного дзвінка""" return JSONResponse([ { "action": "talk", "text": "Вітаю! Я голосовий асистент.", "language": "uk-UA", "style": 4 }, { "action": "connect", "endpoint": [{ "type": "websocket", "uri": f"wss://api.yourapp.com/voice-stream/{uuid}", "content-type": "audio/l16;rate=16000", "headers": {"call_id": uuid} }] } ]) @app.post("/events") async def call_events(request: Request): data = await request.json() status = data.get("status") if status in ["completed", "failed"]: await cleanup_session(data.get("uuid")) return JSONResponse({"status": "ok"}) 

WebSocket обробник

from fastapi import WebSocket @app.websocket("/voice-stream/{call_id}") async def voice_stream(websocket: WebSocket, call_id: str): await websocket.accept() session = VoiceSession(call_id) try: async for message in websocket.iter_bytes(): # Vonage надсилає PCM 16-bit 16kHz pcm_audio = message # Обробляємо аудіо через наш AI pipeline response_text = await process_audio(pcm_audio, session) if response_text: audio_response = await synthesize(response_text) await websocket.send_bytes(audio_response) except Exception as e: logger.error(f"WebSocket error: {e}") finally: await session.finalize() 

Надсилання подій та керування дзвінком

import vonage client = vonage.Client(key=VONAGE_KEY, secret=VONAGE_SECRET) voice = vonage.Voice(client) def transfer_to_agent(call_uuid: str, agent_number: str): """Переведення на оператора""" voice.update_call(call_uuid, { "action": "transfer", "destination": { "type": "ncco", "ncco": [{ "action": "connect", "endpoint": [{"type": "phone", "number": agent_number}] }] } }) 

Як забезпечити відмовостійкість WebSocket?

При падінні з'єднання контекст діалогу може бути втрачено. Використовуємо Redis для зберігання стану сесії — при перепідключенні відновлюємо історію. Експоненційна затримка реконнекту (1,2,4,8 сек) знижує навантаження на API. Такий підхід застосовується в проєктах з критичним SLA. Додатково налаштовуємо keepalive з інтервалом 10 секунд, щоб уникнути розриву від Vonage. NCCO documentation рекомендує завжди задавати timeout для дій, щоб дзвінок не завис при тривалій обробці.

Процес роботи: від ідеї до продакшену

1. Аналітика — аудит вашої телефонії, узгодження сценаріїв (IVR, outbound, голосовий бот).
2. Проєктування — схема дзвінків, вибір AI-моделей, навантажувальне тестування.
3. Реалізація — пишемо NCCO, WebSocket-обробник, підключаємо ML-компоненти.
4. Тестування — симуляція дзвінків, перевірка latency (p99 <300 мс), стрес-тест до 100 одночасних з'єднань.
5. Деплой — контейнеризація, моніторинг (Prometheus + Grafana), налаштування будь-якої хмари або bare-metal.
6. Підтримка — оновлення моделей, ротація ключів, цілодобовий моніторинг, SLA на відновлення 4 години.

Що входить в роботу

• Документація: NCCO-конфіги, архітектура рішення, інструкції для операторів.
• Код інтеграції (FastAPI + WebSocket + AI-пайплайн) на ваш репозиторій.
• Тестові сценарії: 20+ кейсів (зайнято, немає відповіді, переведення, DTMF).
• Навчання вашої команди: 2–3 сесії по 2 години.
• Моніторинг та алертинг (Uptime 99.99%, latency p99, error rate).

Типові помилки при інтеграції Vonage

• NCCO без timeout — якщо AI довго відповідає, дзвінок зависає. Завжди ставте timeout: 15.
• Ігнорування event-колбеків — Vonage надсилає події ringing, answered, completed. Якщо не обробляти failed, не очистите сесію.
• Один WebSocket на всі дзвінки — для кожного uuid створюйте окреме з'єднання. Використовуйте asyncio або multiprocessing.
• Відсутність keepalive — Vonage розриває WebSocket через 30 секунд бездіяльності. Відправляйте ping кожні 10 секунд.

Для відновлення контексту при розриві WebSocket використовуйте механізм перепідключення з експоненційною затримкою. При розриві зберігайте стан сесії в Redis, щоб при новому з'єднанні відновити діалог. Це особливо важливо для проєктів з вимогою zero downtime.

Строки та вартість

Базова інтеграція (один сценарій, одна мова) — від 2 тижнів. Повноцінний production (мультимовний, з навантаженням, моніторингом) — 1.5–2 місяці. Вартість розраховується індивідуально і залежить від складності сценаріїв, кількості мов та вимог до продуктивності. Ми гарантуємо прозорий кошторис після безкоштовного аудиту вашої поточної телефонії. Замовте аудит — оцінимо проєкт за 2 робочі дні, ви отримаєте детальний план і розрахунок строків. Отримайте консультацію, щоб обговорити ваш сценарій використання Vonage Voice API.

Досвід: понад 30 успішних інтеграцій, сертифіковані інженери з Vonage та Twilio, гарантія SLA на всі проєкти.