API Документация
POST https://voksyai.online/api/telephony/public/call

Запуск исходящего звонка

Публичный эндпоинт для запуска исходящих звонков через вашего AI-ассистента. Не требует авторизации — assistant_id служит ключом доступа. Идеально подходит для интеграции с CRM, планировщиками задач и другими внешними системами.

Параметры запроса

Параметр Тип Обязательный Описание
assistant_id string Да
UUID вашего ассистента. Служит ключом доступа к API.
target_phones array Да
Список номеров телефонов для обзвона. Максимум 50 номеров за запрос.
Формат: +79161234567
caller_phone string Нет
Номер для Caller ID (с какого номера звоним).
По умолчанию: первый доступный номер аккаунта
first_phrase string Нет
Первая фраза, которую скажет ассистент.
По умолчанию: приветствие из настроек ассистента
task string Нет
Задача или контекст для звонка. Добавляется в начало промпта ассистента.
mute_duration_ms integer Нет
Время мьюта микрофона клиента в миллисекундах (0-10000).
По умолчанию: 3000

Параметры ответа

Поле Тип Описание
success boolean
Результат операции. true если хотя бы один звонок запущен.
message string
Человекочитаемое сообщение о результате.
started integer
Количество успешно запущенных звонков.
failed integer
Количество неудавшихся звонков.
session_ids array
Список ID сессий запущенных звонков от Voximplant. Используйте для отслеживания статуса и получения записей через GET /call/{id}.

Пример запроса

curl
curl -X POST "https://voksyai.online/api/telephony/public/call" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "target_phones": ["+79161234567"],
    "task": "Напомнить о встрече в 15:00"
  }'

Примеры ответов

JSON
{
  "success": true,
  "message": "Запущено 1 звонков",
  "started": 1,
  "failed": 0,
  "session_ids": ["12345678"]
}
JSON
{
  "detail": "Ассистент не найден"
}
JSON
{
  "detail": "Телефония не подключена для этого ассистента"
}

Тестер API

Внимание! Это отправит реальный запрос и запустит настоящий звонок. Убедитесь, что указан корректный номер телефона и вы готовы принять звонок.
UUID вашего ассистента из личного кабинета
Номер телефона для звонка (с кодом страны)
Контекст или задача для звонка
200 OK 123 мс
Response

              

GET https://voksyai.online/api/telephony/call/{session_history_id}

Получить данные звонка

Публичный эндпоинт для получения данных звонка по Voximplant session_history_id. Не требует авторизации — сам session_history_id служит неявным ключом доступа (генерируется автоматически и недоступен третьим лицам). Возвращает диалог, метаданные звонка, запись и информацию об ассистенте. Используйте session_ids из ответа POST /public/call для отслеживания результатов.

Параметры запроса

Параметр Тип Обязательный Описание
session_history_id string Да
ID сессии звонка от Voximplant. Передаётся в URL-пути.
Пример: 4382022730

Параметры ответа

Поле Тип Описание
success boolean
Результат операции.
call_session_history_id string
ID сессии Voximplant.
session_id string
Внутренний ID сессии.
assistant_id string
UUID ассистента, обработавшего звонок.
assistant_name string
Имя ассистента.
assistant_type string
Тип ассистента.
Значения: openai, gemini
caller_number string | null
Номер звонившего (нормализованный).
call_direction string | null
Направление звонка.
Значения: INBOUND, OUTBOUND
call_cost number | null
Стоимость звонка (в валюте аккаунта).
call_duration number | null
Длительность звонка в секундах.
record_url string | null
URL аудиозаписи звонка.
created_at string
Дата и время звонка (ISO 8601).
dialog array
Массив реплик диалога. Каждая реплика содержит role (user/assistant), text и ts (timestamp).
messages_count integer
Общее количество реплик в диалоге.

Пример запроса

curl
curl "https://voksyai.online/api/telephony/call/4382022730"

Примеры ответов

JSON
{
  "success": true,
  "call_session_history_id": "4382022730",
  "session_id": "abc123-def456",
  "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
  "assistant_name": "Секретарь по звонкам",
  "assistant_type": "gemini",
  "caller_number": "79991234567",
  "call_direction": "OUTBOUND",
  "call_cost": 2.0252,
  "call_duration": 14.0,
  "record_url": "https://records.voximplant.com/...",
  "created_at": "2026-02-12T09:16:46.413463+00:00",
  "dialog": [
    {
      "role": "user",
      "text": "Алло",
      "ts": 1770887803248
    },
    {
      "role": "assistant",
      "text": "Привет Валерий, это ассистент компании...",
      "ts": 1770887804248
    }
  ],
  "messages_count": 2
}
JSON
{
  "detail": "Звонок с session_history_id=9999999999 не найден"
}

Тестер API

Этот запрос только читает данные — он не инициирует звонков и не вносит изменений. Введите session_history_id, полученный из ответа POST /public/call.
ID сессии звонка от Voximplant (из поля session_ids ответа POST /public/call)
200 OK 123 мс
Response

              

POST https://your-server.com/your-webhook

Webhook: завершение диалога

VoksiAI может уведомлять ваш сервер о каждом завершённом диалоге. По событию conversation.completed на указанный вами URL приходит POST-запрос с полным диалогом и метаданными. Событие покрывает и веб-чат, и телефонию — источник различается по полю source. Настроить URL можно в разделе «Диалоги» → кнопка Webhook.

Как это работает

  • Запрос отправляется методом POST с заголовком Content-Type: application/json и User-Agent: VoksiAI-Webhook/1.0.
  • Доставка по принципу «отправили и забыли»: без повторов и без подписи. Таймаут запроса — 10 секунд.
  • Ваш сервер должен вернуть статус 2xx. Любой другой ответ или таймаут не влияет на работу ассистента — просто логируется на нашей стороне.
  • Пустые диалоги (без реплик) не отправляются.

Структура payload

Поле Тип Описание
event string
Тип события.
Всегда: conversation.completed
event_id string
Уникальный UUID события (для дедупликации на вашей стороне).
timestamp string
Время формирования события в формате ISO 8601 (UTC).
data.source string
Источник диалога.
Значения: web_chat, telephony
data.session_id string
ID сессии диалога.
data.assistant_id string
UUID ассистента.
data.assistant_name string
Имя ассистента.
data.assistant_type string
Тип ассистента.
Значения: gemini, openai, fish
data.caller_number string | null
Номер звонившего. null для web_chat.
data.call_direction string | null
Направление звонка. null для web_chat.
Значения: INBOUND, OUTBOUND
data.duration_seconds number | null
Длительность звонка в секундах. null для web_chat.
data.call_cost number | null
Стоимость звонка. null для web_chat.
data.record_url string | null
Ссылка на аудиозапись. null для web_chat.
data.dialog array
Массив реплик. Каждый элемент: role (user | assistant), text (строка), ts (Unix-время в миллисекундах).
data.messages_count integer
Количество реплик в dialog.

Пример payload

JSON
{
  "event": "conversation.completed",
  "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-02-12T09:16:46.413463Z",
  "data": {
    "source": "telephony",
    "session_id": "abc123-def456",
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "assistant_name": "Секретарь по звонкам",
    "assistant_type": "gemini",
    "caller_number": "79991234567",
    "call_direction": "OUTBOUND",
    "duration_seconds": 14.0,
    "call_cost": 2.0252,
    "record_url": "https://records.voximplant.com/...",
    "dialog": [
      {
        "role": "user",
        "text": "Алло",
        "ts": 1770887803248
      },
      {
        "role": "assistant",
        "text": "Привет Валерий, это ассистент компании...",
        "ts": 1770887804248
      }
    ],
    "messages_count": 2
  }
}

Примеры обработки

Python (FastAPI)
from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/voicyfy-webhook")
async def voicyfy_webhook(request: Request):
    payload = await request.json()

    if payload.get("event") != "conversation.completed":
        return {"ok": True}

    data = payload["data"]
    print(f"[{data['source']}] {data['assistant_name']} — {data['messages_count']} реплик")

    for turn in data["dialog"]:
        print(f"  {turn['role']}: {turn['text']}")

    # Всегда отвечаем 2xx, чтобы VoksiAI не считал доставку неуспешной
    return {"ok": True}
Node.js (Express)
const express = require("express");
const app = express();

app.use(express.json());

app.post("/voicyfy-webhook", (req, res) => {
  const payload = req.body;

  if (payload.event !== "conversation.completed") {
    return res.sendStatus(200);
  }

  const { source, assistant_name, messages_count, dialog } = payload.data;
  console.log(`[${source}] ${assistant_name} — ${messages_count} реплик`);

  for (const turn of dialog) {
    console.log(`  ${turn.role}: ${turn.text}`);
  }

  // Всегда отвечаем 2xx
  res.sendStatus(200);
});

app.listen(3000);

Как протестировать

  1. Создайте временный URL на webhook.site.
  2. Откройте раздел «Диалоги», нажмите кнопку Webhook, вставьте URL и включите отправку.
  3. Сделайте тестовый звонок или проведите веб-чат с ассистентом.
  4. На webhook.site появится событие conversation.completed с полем source = telephony или web_chat.