Capybaravoice

Документация Capybaravoice

Как устроен сервис, с чего начать и как подключить его к своей CRM через API, вебхуки и Telegram.

Как работает сервис

Голосовой бот вокруг ваших данных: города, услуги, цены и реплики задаёте вы.

Входящий звонок

Клиент звонит на ваш номер → бот определяет вашу компанию по номеру, здоровается, распознаёт услугу (и модель, если есть дерево номенклатуры), называет цену строго из вашего прайса и предлагает записаться. Возражения и частые вопросы — вашими заготовками; сложный случай — перевод на оператора.

Исходящий обзвон

Кампания: загрузите контакты, задайте окно набора, число попыток и одновременных звонков. Бот сам набирает по вашему сценарию, ведёт статусы дозвона и повторяет недозвоны. Номера из списка «не звонить» пропускаются (152-ФЗ, согласие на обзвон обеспечиваете вы).

Опросы

Кампания-опрос вместо ценового диалога: бот задаёт ваши вопросы и собирает оценки 1–5, «да/нет» и свободные ответы. Результаты — выгрузкой в CSV.

Биллинг и аналитика

Каждый звонок тарифицируется шагом 15 с, видна себестоимость и списание по тарифу. Дашборд показывает звонки по исходам, заявки и расход за период.

Быстрый старт

1

Регистрация

Заведите компанию на странице регистрации — нужен только email.

2

Каталог и цены

Заполните города, услуги и цены. Или примените готовый шаблон сценария.

3

Номер и баланс

Привяжите телефонный номер, выберите тариф и пополните баланс.

4

Интеграции

Создайте ключ API и вебхуки, чтобы данные попадали в вашу CRM.

Публичный API — аутентификация

Доступ к своим данным по токену. Токен создаётся в кабинете: Настройки → Ключи API (показывается один раз).

Передавайте токен в заголовке Authorization:

bash
curl -H "Authorization: Bearer rv_ваш_токен" \
     https://capybaravoice.timergali.ru/api/v1/bookings
Для реального времени не опрашивайте API в цикле — подпишитесь на вебхук call.finished или booking.created.

Эндпоинты

Все запросы — GET, ответ JSON (UTF-8), Bearer-токен обязателен.

GET/api/v1/bookingsзаявки компании
GET/api/v1/callsжурнал звонков
GET/api/v1/campaignsкампании обзвона

Параметров фильтрации сейчас нет: методы отдают свежие записи целиком (/calls — последние 100). Фильтры по периоду и исходу — в планах; для реактивных сценариев используйте вебхуки.

Пример ответа /api/v1/bookings

200 OK · application/json
{
  "bookings": [
    {
      "id": 128,
      "city": "Москва",
      "service": "Замена дисплея",
      "phone": "+79001234567",
      "customer_name": "Иван",
      "status": "new",
      "created_at": "2026-07-25T10:15:00Z"
    }
  ]
}

Пример ответа /api/v1/calls

200 OK · application/json
{
  "calls": [
    {
      "id": 5012,
      "call_id": "1690000000.42",
      "caller": "+79001234567",
      "recognized_city": "Москва",
      "recognized_service": "Замена дисплея",
      "quoted_price": "4490",
      "outcome": "quoted",
      "started_at": "2026-07-25T10:14:30Z"
    }
  ]
}

outcome: quoted (названа цена) · no_city · no_service · transferred · transfer_failed (перевод запрошен, оператор не ответил) · abandoned.

Пример ответа /api/v1/campaigns

200 OK · application/json
{
  "campaigns": [
    { "id": 3, "name": "Весенний обзвон", "status": "active" },
    { "id": 4, "name": "Опрос качества", "status": "paused", "survey_id": 2 }
  ]
}

status: draft · active · paused · done. survey_id есть, если кампания проводит опрос.

Лимиты и ошибки

Специальных лимитов частоты сейчас нет, но не опрашивайте методы в цикле — для событий в реальном времени используйте вебхуки.

КодКогда
200успех
401нет заголовка Authorization или токен неизвестен/отозван
500внутренняя ошибка сервиса

Тело ошибки — JSON вида {"error": "..."}.

Вебхуки

Платформа сама уведомляет вашу систему о событиях. Настраиваются в кабинете: Настройки → Вебхуки.

События

СобытиеКогда
booking.createdСоздана заявка на запись
call.finishedЗвонок завершён (с исходом)

Формат доставки

На указанный URL приходит POST с JSON. Заголовки: X-Capybaravoice-Event — имя события, X-Capybaravoice-Signature: sha256=… — подпись тела HMAC-SHA256 вашим секретом.

POST · application/json
POST https://ваш-адрес.ру/hook
Content-Type: application/json
X-Capybaravoice-Event: booking.created
X-Capybaravoice-Signature: sha256=9f86d0818...

{
  "event": "booking.created",
  "company_id": 42,
  "timestamp": "2026-07-25T10:15:00Z",
  "data": {
    "call_id": "abc-123",
    "phone": "+79001234567",
    "city": "Москва",
    "service": "Замена дисплея",
    "price": "4490"
  }
}

Проверка подписи

Посчитайте HMAC-SHA256 от сырого тела запроса вашим секретом и сравните с X-Capybaravoice-Signature (после sha256=). Пример на Python:

python
import hmac, hashlib
sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert hmac.compare_digest("sha256=" + sig, request.headers["X-Capybaravoice-Signature"])

Отвечайте статусом 2xx — иначе доставка считается неуспешной (виден статус в кабинете).

Уведомления в Telegram

Бот пишет о принятых звонках и новых заявках прямо в ваш чат. Настраивается в кабинете: Настройки → Telegram.

1

Создайте бота

В Telegram напишите @BotFather → /newbot → получите токен.

2

Узнайте chat_id

Напишите боту /start; chat_id подскажет @userinfobot (для группы id начинается с «−»).

3

Включите

Впишите токен и chat_id в кабинете, включите уведомления и нажмите «Отправить тест».

Готовы подключить?

Заведите компанию, настройте бота и получите ключ API за несколько минут.

Начать