Как создать свое приложение для модуля «Телефония»

Документ описывает, что необходимо реализовать внешнему разработчику, чтобы сделать собственное приложение для маркетплейса Аспро.Cloud.

Для разработки приложения ознакомьтесь с библиотекой для приложений Аспро.Cloud (JS SDK).

1. Общая архитектура интеграции

Ваше приложение выступает middleware (прослойкой) между CRM и внешним сервером телефонии:

Зоны ответственности вашего приложения:

1. UI настройки — страница подключения, открываемая внутри CRM в iframe.
2. Бэкенд — хранит интеграцию (связку пользователя CRM ↔ аккаунт CRM ↔ учётка внешнего канала), OAuth-токены.
3. Исходящий канал — принимает webhook от CRM и доставляет события во внешний сервер.
4. Входящий канал — слушает события внешнего сервера, нормализует и отправляет их в CRM.

2. Что нужно реализовать — чеклист

Поля для регистрации канала (telephony/create):

• name — имя конкретной интеграции
• ref_id — ID вашего MiniApp
• active — обязательное значение true
• code — обязательно значение mini_app
• webhook_url — URL, на который CRM будет отправлять запросы
• icon_url — URL на иконку для интеграции
• can_redirect (true/false) — возможность редиректа звонка на другого сотрудника
• manifest_id — ID места встройки

3. Регистрация приложения в маркетплейсе и место встройки

Шаги:

1. Создаёте приложение в https:///module/miniapps/cabinet.
2. В манифесте добавляете место встройки «подключение к сервису телефония».
3. Заполняете поля места встройки:

После сохранения манифеста ваше приложение появляется в списке сервисов телефоний.

4. Данные, передаваемые в iframe

На URL, указанный в iframe (src), CRM отправит POST-запрос с телом:

{
  "domain": ".aspro.cloud",
  "language": "ru",
  "placement": {
    "id": "my_channel_wizard",
    "code": "contactcenter.service.wizard"
  },
  "https": "1",
  "account": { "id": "123456" },
  "app": {
    "id": "",
    "version": "1.0.0"
  },
  "auth": {
    "expires_at": "2026-03-27 17:29:33",
    "access_token": "",
    "refresh_token": ""
  },
  "ratelimit": { "limit": "16" }
}

Ваш endpoint должен:

1. Валидировать payload и извлечь domain, app.id, app.version, account.id, auth.*.
2. Построить base URL CRM: https://{domain} (или http, если https=0 — актуально только для dev-стендов).
3. Идентифицировать пользователя CRM. Рекомендуемый паттерн — «двухпутевый lookup»:
   • Быстрый путь: ищете в своей БД OAuth-клиента по хешу access_token + domain + app.version. Если нашли — пользователь уже известен, API в CRM дёргать не нужно.
   • Медленный путь: если не нашли — делаете GET https://{domain}/api/v1/module/core/user/get с заголовком Authorization: Bearer {access_token} и создаёте у себя запись о пользователе CRM по ответу.
4. Сохранить/обновить OAuth-токены. Ключ уникальности — (user_id, domain, app_version). Токены старых версий приложения имеет смысл вычищать при апдейте, чтобы БД не раздувалась.
5. Отрендерить форму настройки и отдать HTML клиенту.

5. Два потока данных

После подключения интеграции обмен данными идёт в двух направлениях:

Аспро.Cloud -> ваш webhook_url — CRM отправляет POST-запросы на ваш сервер:

• инициация исходящего звонка
• запрос списка звонков и данных конкретного звонка
• запрос списка SIP-сотрудников
• проверка статуса интеграции (health-check)

Ваше приложение -> Аспро.Cloud — вы отправляете POST-запросы с событиями о звонках на endpoint CRM (POST /external/telephony/hook/mini_app/{account_id}/{telephony_uuid}):

• инициализация звонка (для входящих CRM возвращает решение о маршрутизации)
• звонок соединён
• звонок завершён
• информация о записи разговора
• обновление состояния звонка

Подробные контракты (форматы запросов, ответов, коды ошибок) описаны в OpenAPI-спецификациях:

• outgoing_hooks.yaml — запросы от Аспро.Cloud на ваш webhook (файл прикреплен к статье)
• incoming_events.yaml — события от вашего приложения в Аспро.Cloud (файл прикреплен к статье)

6. Порядок подключения интеграции

Пользователь CRM          Аспро.Cloud (CRM)           Ваше приложение
       │                         │                            │
       │  Нажимает «Подключить»  │                            │
       │────────────────────────>│                            │
       │                         │                            │
       │                         │  Открывает iframe (POST    │
       │                         │  с auth-данными)           │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │     Получает OAuth-токены  │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  GET /api/v1/module/       │
       │                         │  core/user/get             │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {id, name, email}         │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │  POST /api/v1/module/      │
       │                         │  telephony/telephony/create│
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {uuid: telephony_uuid}    │
       │                         │───────────────────────────>│
       │                         │                            │
       │     Интеграция готова   │                            │
       │<────────────────────────│                            │
       │                         │                            │

После этого CRM начинает отправлять запросы на webhook_url, а ваше приложение может отправлять события о звонках в CRM.