# Як налаштувати Ringostat

Швидко налаштуйте інтеграцію з Ringostat через preset конфігурацію. Preset містить готові налаштування маппінгу полів, які підходять для більшості випадків використання Ringostat.

## Передумови

- Доступ до налаштувань бота в ConnectiveOne
- Аккаунт Ringostat з налаштованим webhook

## Коли знадобиться

- Використовуєте Ringostat як провайдера телефонії
- Потрібно швидко налаштувати інтеграцію без ручного введення маппінгу полів

## Крок 1: Відкрити налаштування каналу

1. Перейдіть в **Налаштування** → **Боти**
2. Оберіть потрібного бота
3. Перейдіть на вкладку **Телефонія**
4. Створіть новий канал або відкрийте існуючий для редагування

## Крок 2: Завантажити Ringostat preset

1. В формі налаштування каналу знайдіть кнопку **Завантажити Ringostat preset**
2. Натисніть на неї — preset конфігурація автоматично заповнить поле Advanced Config

## Крок 3: Налаштувати webhook у Ringostat (Webhooks 2.0)

У ConnectiveOne на каналі вже має бути **Webhook URL** і **Webhook Token** (кроки 1–2). Далі налаштуйте відправку подій у Ringostat.

### Де відкрити

1. У кабінеті Ringostat: **Налаштування** → **Інтеграція** → **Webhooks 2.0**
2. Створіть або відкрийте сповіщення в блоці **Сповіщення зовнішніх систем**

### Основні поля сповіщення

| Поле в Ringostat | Значення |
|------------------|----------|
| **Назва** | Будь-яка зрозуміла назва, наприклад `ConnectiveOne` |
| **Подія** | **Після дзвінка** (завершений дзвінок — те, що обробляє ConnectiveOne v1.1) |
| **Активна** | Увімкнено |

### Вкладка HTTP → підвкладка «Дані»

| Поле | Значення |
|------|----------|
| **HTTP метод** | `POST` |
| **Напрямок (URL)** | Повний **Webhook URL** з ConnectiveOne, включно з параметром `token`, наприклад: `https://<ваш-домен>/kw/telephony/webhook/<id_каналу>?token=<webhook_token>` |
| **Заголовки** | `Content-Type` = `application/json` |
| **Формат відправки даних** | `raw` |
| **Формат дати** | **Стандартна дата** (`2023-01-20 15:00:00`) |
| **Тіло запиту** | Режим **Json** — вставте JSON нижче (одним рядком або з переносами) |

> Токен має бути **в URL** (`?token=...`), як у згенерованому посиланні каналу ConnectiveOne. Не змінюйте шлях `/kw/telephony/webhook/...`.

### Приклад тіла запиту (Json)

Скопіюйте в поле **Тіло запиту**. Змінні з `$` — параметри Ringostat; підставляються при кожному дзвінку.

```json
{"call_id":"$cdr_id","caller":"$userfield","callee":"$dst","status":"$disposition","date":"$calldate","call_duration":"$duration","type":"$call_type","waiting":"$duration-billsec","dialog":"$billsec","manager_id":"$staffid","record_link":"$recording_wav","project_id":"$project_id"}
```

Що означають ключі для ConnectiveOne (після **Ringostat preset** у каналі):

| Ключ у JSON webhook | Змінна Ringostat | Поле в ConnectiveOne |
|---------------------|------------------|----------------------|
| `call_id` | `$cdr_id` | ID дзвінка |
| `caller` | `$userfield` | Номер абонента (вхідний) |
| `callee` | `$dst` | Номер, на який дзвонили |
| `status` | `$disposition` | Статус (PROPER / MISSED тощо) |
| `date` | `$calldate` | Час дзвінка |
| `call_duration` | `$duration` | Тривалість |
| `type` | `$call_type` | Напрямок (in / out) |
| `waiting` | `$duration-billsec` | Час очікування |
| `dialog` | `$billsec` | Час розмови |
| `manager_id` | `$staffid` | ID співробітника в Ringostat |
| `record_link` | `$recording_wav` | Посилання на запис |
| `project_id` | `$project_id` | ID проєкту Ringostat |

Якщо в **Advanced Config** каналу ConnectiveOne інші назви полів — змініть ключі в JSON або оновіть `field_mapping` у preset.

### Перевірка в ConnectiveOne

1. У формі каналу: **Формат webhook** = **JSON**
2. Завантажте **Ringostat preset** (крок 2), якщо ще не зробили
3. Збережіть канал і зробіть тестовий дзвінок або **Тест** webhook у ConnectiveOne

## Де взяти Auth-key і Project id (Ringostat API)

Ці значення потрібні, якщо ConnectiveOne **звертається до API Ringostat** — зокрема для [збагачення webhook](/uk/telephony/how-to/configure-webhook-enrich.md) (email оператора, статус лінії, тематика).

### Де відкрити

1. У кабінеті Ringostat: **Налаштування** → **Інтеграція** → **Ringostat API**
2. На сторінці знайдіть блок з обліковими даними (зазвичай зверху, перед списком «Опис Api»)

### Що скопіювати

| Поле в Ringostat | Для чого в ConnectiveOne |
|------------------|---------------------------|
| **Auth-key** | Ключ авторизації API (у Action Jail — параметр на кшталт `ringostat_api_key`) |
| **Project id** | ID проєкту Ringostat (у Action Jail — `ringostat_project_id`; має збігатися з `project_id` у webhook, якщо ви його передаєте) |

> **Auth-key** — секрет. Не публікуйте його в чатах і не вставляйте в публічні інструкції. Передавайте лише відповідальній особі, яка налаштовує Action Jail.

На тій самій сторінці нижче є **Опис Api** (Callback, експорт дзвінків, SIP-статуси тощо) — для базового webhook і preset ConnectiveOne ці URL **не потрібні**; достатньо **Webhooks 2.0** (крок 3).

## Крок 4: Збагачення webhook (опційно, Ringostat)

Якщо в webhook Ringostat **немає email оператора** або потрібно автоматично визначати тему (Онлайн / Оффлайн):

1. Скопіюйте **Auth-key** і **Project id** з розділу [Ringostat API](#де-взяти-auth-key-і-project-id-ringostat-api)
2. Налаштуйте action в Action Jail з цими параметрами — зазвичай це робить команда впровадження
3. У формі каналу ConnectiveOne вкажіть action в **Webhook enrich action**

Покроково: [Як налаштувати збагачення webhook](/uk/telephony/how-to/configure-webhook-enrich.md).

## Крок 5: Зберегти та протестувати

1. Натисніть **Зберегти**
2. Натисніть **Тест** для перевірки роботи webhook
3. Перевірте, що тестовий діалог створено успішно

## Що включає preset

Ringostat preset включає:

- **Field mapping** — маппінг стандартних полів Ringostat
- **Status mapping** — маппінг статусів дзвінків
- **Direction mapping** — маппінг напрямку дзвінків
- **Налаштування записів** — якщо Ringostat надає записи
- **Налаштування транскриптів** — якщо Ringostat надає транскрипти

## Додаткові налаштування

Після завантаження preset ви можете:

- Змінити маппінг полів, якщо ваш Ringostat використовує інші назви полів
- Додати додаткові поля, якщо потрібно
- Налаштувати нормалізацію номерів (код країни за замовчуванням)

## Промокод Ringostat

Підключайте будь-який продукт Ringostat та отримайте на рахунок компанії $50.

**Промокод на $50**\*: `Ringostat_ConnectiveOne`

Щоб скористатися пропозицією:

1. Зареєструйтесь на сайті [ringostat.com](https://ringostat.com/uk/).
2. Повідомте менеджеру Ringostat промокод: **Ringostat_ConnectiveOne**.
3. Почніть користуватися рішеннями Ringostat.

\* Пропозиція діє для нових клієнтів та не сумується з іншими вигодами.

[Отримати $50 на рахунок Ringostat](https://ringostat.com/uk/?utm_campaign=partner&utm_medium=referral&utm_source=connectiveone&utm_term=partner-connectiveone-promocode)

## Пов'язані статті

- [Налаштувати збагачення webhook](/uk/telephony/how-to/configure-webhook-enrich.md)
- [Налаштувати канал телефонії](/uk/telephony/how-to/configure-telephony-channel.md)
- [Протестувати webhook](/uk/telephony/how-to/test-telephony-webhook.md)