---
title: "Подключение из Five9"
description: "Направляйте звонки Five9 голосовому агенту ThunderPhone по SIP с помощью AI Agent Connect и получайте их обратно с заголовками маршрутизации, которые читает ваш сценарий IVR."
---

Ваш IVR-сценарий Five9 передаёт звонящего агенту вместе с данными вызова Five9. Когда агент завершает работу, он кладёт трубку, добавляя заголовки маршрутизации в SIP `BYE`, которые сценарий считывает в переменные вызова для маршрутизации звонящего.

## Перед началом работы

- Агент ThunderPhone и [API-ключ](/ru/guides/api-keys) организации.
- Дополнение Five9 **Подключение ИИ-агента**. Five9 ограничивает его поставщиками ИИ, которых она аккредитовала, а команда внедрения Five9 настраивает его: импортирует шаблон IVR-сценария поставщика, создаёт переменные вызова и направляет модуль сценария **Передача стороннему сервису** к поставщику. ThunderPhone пока нет в списке аккредитованных Five9: уточните у вашей команды по работе с аккаунтом Five9 или в поддержке ThunderPhone, прежде чем учитывать это в планах.

## 1. Создайте SIP-эндпоинт

Модуль Five9 «Передача стороннему сервису» набирает номер телефона, а не SIP-адрес, и интеграции Five9 других поставщиков аутентифицируют Five9 по адресу источника, а не по паролю. Поэтому создайте эндпоинт `ip_allowlist` с номером, который будет набирать Five9, в качестве номера для входящего набора (см.
[Платформы, набирающие номер телефона](/ru/guides/sip-addresses)):

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Five9",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["FIVE9_SIGNALLING_RANGE_1", "FIVE9_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["+14155550188"]
  }'
```

- `allowed_source_cidrs`: диапазоны SIP-сигнализации ваших дата-центров Five9, предоставленные Five9. Каждый должен быть общедоступным диапазоном IPv4 с префиксом `/16` или длиннее (IPv6 `/48` или длиннее).
- `dial_in_numbers`: номер, который будет набирать сценарий Five9, записанный в формате, в котором его отправляет Five9. Это необязательно должен быть реальный номер телефона. Он не должен уже использоваться в ThunderPhone — как номер телефона или на другом эндпоинте: в этом случае возвращается `409`.

Адреса Five9 используются всеми её клиентами, поэтому любой другой клиент Five9, набравший этот номер, попадёт к вашему агенту. При выборе номера используйте длинный номер, который никто не угадает (до 15 цифр), убедитесь, что Five9 отправляет его в ThunderPhone, а не в телефонную сеть, и не публикуйте его.

## 2. Передавайте вызовы с контекстом

Попросите команду внедрения Five9:

- Отправлять вызов из модуля **Передача стороннему сервису** на
  `sip:+14155550188@sip.thunderphone.com`, указывая номер и в URI запроса, и в заголовке `To`. Модуль принимает номер, а SIP-домен поставщика указывается в заголовке.
- Передавать его по TLS (порт 5061) или TCP (порт 5060). Эндпоинт отклоняет UDP, а Five9 не публикует сведения об используемом транспорте, поэтому убедитесь, что это не UDP.
- Включить **Возврат после вызова стороннего сервиса**, чтобы сценарий продолжался, когда агент кладёт трубку (Five9 допускает до 3 600 секунд для вызова стороннему сервису).

В руководстве Five9 перечислены значения, которые она отправляет (`call.ANI`, `call.DNIS`,
`call.call_id`, `call.session_id`, `call.campaign_name` и другие), но не названия их
заголовков. Интеграции Five9 других поставщиков ИИ документируют их при передаче как `X-CallANI`, `X-CallDNIS`, `X-CallID`, `X-CallSessionID`, `X-CallCampaign`
и `X-AgentID`; проверьте их при первом тестовом вызове. Каждое значение попадает в промпт как переменная, например
`{{sip_x_callcampaign}}`. `X-CallID` сохраняется как
`external_call_id` вызова.

## 3. Верните вызов

Агент возвращает вызов: прощается и завершает его, а `BYE` содержит четыре
заголовка, которые читает скрипт Five9. Добавьте этот номер для перевода (см.
[Добавление номера для перевода](/ru/guides/contact-centers/overview)):

```json
{
  "name": "Five9 agent",
  "action": "return",
  "headers": {
    "X-RouteType": "SkillTransfer",
    "X-RouteValue": "Support",
    "X-RouteReason": "{{handoff_intent}}",
    "X-CustomMetaData": "handoff_id={{handoff_id}}"
  }
}
```

- `X-RouteType` и `X-RouteValue` указывают скрипту, куда направить звонящего,
  в данном случае — на навык Support. Другие значения `X-RouteType`, которые
  документируют другие провайдеры, включают `SkillTransfer`, `PhoneTransfer`,
  `Hangup` и `DispositionOnly`; согласуйте значения с тем, кто поддерживает
  скрипт. Для нескольких направлений добавьте по одному возврату для каждого
  направления с разными именами и значениями `X-RouteValue`.
- `X-RouteReason` содержит метку намерения агента, например `billing_dispute`.
- `X-CustomMetaData` содержит идентификатор передачи. `BYE` также содержит его
  как `X-TP-Handoff-Id`, который Five9 не читает.

Скрипт Five9 сопоставляет четыре заголовка с переменными вызова. Чтобы получить
сводку агента, настройте скрипт на вызов поиска передачи через модуль IVR
**Запрос**: `GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=` с последующим
`call.call_id`, используя профиль авторизации, который отправляет
`Authorization: Bearer` и ваш API-ключ. См.
[Поиск переданного вызова](/api-reference/calls#look-up-a-handed-off-call).

## Проверьте работу

Позвоните в скрипт IVR, попросите агента соединить вас с человеком и убедитесь,
что скрипт направляет звонящего с заполненными переменными вызова. Если вызов
никогда не поступает агенту, проверьте, что номер в URI запроса и заголовке
`To` совпадает с номером дозвона, что исходный адрес Five9 указан в
`allowed_source_cidrs`, а вызов поступил по TCP или TLS. Затем откройте вызов с
помощью `GET /v1/calls/{call_id}`: в `sip_headers` должен быть указан
`x-callid`, а `external_call_id` должен совпадать с `call.call_id` в Five9.

## Ограничения

- В руководстве Five9 описываются данные маршрутизации в `BYE`, но не
  упоминается приём `REFER`, поэтому обратная передача — это холодный перевод
  скриптом.
- Five9 читает `X-RouteType`, `X-RouteValue`, `X-RouteReason` и
  `X-CustomMetaData`, но не `User-to-User`. ThunderPhone отправляет значение
  каждого заголовка длиной не более 256 байт.
- Five9 рекомендует использовать около десяти пользовательских заголовков,
  чтобы избежать фрагментации пакетов.
