Phone API МойСклад связывает виртуальную АТС с интерфейсом системы: показывает всплывающую карточку при входящем звонке, разрешает звонить в один клик по номеру контрагента и хранит историю с записями разговоров. Разберём архитектуру интеграции, события звонков и сопоставление номеров с клиентами.
Что даёт Phone API
Phone API — это контур для провайдеров телефонии, которые хотят интегрироваться с МойСклад в формате приложения. Он закрывает три сценария работы менеджера:
- Входящий звонок — всплывающая карточка с именем контрагента, если номер узнан;
- Click-to-call — исходящий вызов по клику на телефон прямо из карточки клиента или документа;
- История звонков — журнал вызовов со статусами, длительностью и ссылками на записи.
Технически интеграция — это приложение из каталога решений, которое обменивается событиями с платформой и с вашей АТС. Часть логики живёт в iframe (виджет звонка), часть — на сервере провайдера.
Архитектура интеграции
В связке участвуют три стороны: АТС провайдера, сервер интеграции и МойСклад. АТС генерирует события звонков, сервер интеграции их принимает и транслирует в МойСклад, а платформа показывает виджет пользователю.
| Компонент | Ответственность |
|---|---|
| АТС | Установка соединения, медиапоток, запись разговора |
| Сервер интеграции | Приём событий АТС, авторизация, обмен с МойСклад |
| МойСклад | Виджет звонка, карточка контрагента, журнал |
Авторизация идёт через механику приложений: сервер интеграции получает access_token к JSON API 1.2 аккаунта, чтобы искать контрагентов и создавать записи о звонках.
Входящий звонок и всплывающая карточка
Сценарий входящего звонка выглядит так:
- на АТС приходит вызов, событие уходит на сервер интеграции;
- сервер ищет контрагента по номеру в JSON API 1.2;
- интеграция передаёт в МойСклад событие «входящий звонок» с номером и найденным контрагентом;
- у нужного пользователя всплывает карточка вызова.
Поиск контрагента — по телефону через фильтр:
GET /api/remap/1.2/entity/counterparty?filter=phone~+79001234567
+7, 8, с пробелами и скобками). Приводите к единому виду перед поиском, иначе контрагент не найдётся и карточка всплывёт «безымянной».Click-to-call: исходящий вызов
Обратный сценарий — менеджер кликает по номеру телефона в интерфейсе МойСклад, и АТС инициирует вызов. Здесь инициатором выступает платформа: она уведомляет ваше приложение о желании позвонить.
- МойСклад передаёт номер вызываемого абонента и идентификатор оператора;
- сервер интеграции отправляет команду originate на АТС;
- АТС сначала дозванивается до менеджера, затем до клиента;
- статусы соединения возвращаются событиями обратно.
Чтобы связать оператора МойСклад с внутренним номером АТС, ведите маппинг пользователей: сотрудник ↔ SIP-аккаунт/добавочный. Без него система не поймёт, с какого аппарата звонить.
История и записи разговоров
После завершения вызова полезно сохранить его в МойСклад: статус (принят, пропущен, исходящий), длительность и ссылку на запись. Это делает интеграцию ценной — вся история общения видна в карточке клиента.
| Поле события | Значение |
|---|---|
| Тип | входящий / исходящий |
| Статус | принят / пропущен / занято |
| Длительность | секунды разговора |
| Запись | URL аудиофайла на стороне провайдера |
Виджет звонка и контекст оператора
Всплывающая карточка — это iframe-виджет, встроенный в интерфейс МойСклад. В него платформа передаёт контекст: какой пользователь сейчас работает и в каком аккаунте. От качества виджета зависит, насколько удобно менеджеру принять звонок и открыть карточку клиента.
- виджет отдаётся по HTTPS и валидирует переданный контекст на сервере;
- по номеру он подтягивает контрагента, его заказы и задачи, чтобы менеджер видел клиента целиком;
- из виджета удобно сразу создать заказ или задачу по итогам разговора;
- адресуйте событие конкретному оператору — карточка должна всплыть только у того, кому идёт звонок.
Чтобы «поднять» правильного контрагента, связывайте входящий номер с оператором через маппинг и показывайте виджет адресно. Массовая рассылка события всем пользователям аккаунта — антипаттерн: интерфейс будет мигать у тех, кому звонок не предназначен.
Надёжность и обработка событий
Телефония — поток событий в реальном времени, и тут важна устойчивость к сбоям сети и всплескам нагрузки.
- Очередь событий — не обрабатывайте звонки синхронно «в лоб», буферизуйте всплески;
- Идемпотентность — одно событие АТС может прийти дважды, дедуплицируйте по идентификатору вызова;
- Таймауты — если МойСклад недоступен, не блокируйте установку соединения, откладывайте запись в журнал;
- Логи — сохраняйте сырые события АТС для разбора инцидентов.
Разделяйте критичный путь (показ карточки, инициирование вызова) и некритичный (запись истории). Первый должен работать даже при деградации второго.
Итог
Phone API МойСклад — это мост между вашей АТС и интерфейсом системы: всплывающая карточка входящего, click-to-call и журнал звонков с записями. Ключевые технические моменты — нормализация номеров при поиске контрагента, маппинг операторов на SIP-аккаунты и устойчивая обработка потока событий.
Мы разрабатываем интеграции телефонии с учётными системами и сайтами на 1С-Битрикс: приём событий АТС, поиск клиента по номеру, click-to-call и сохранение истории. Спроектируем отказоустойчивую архитектуру, которая не роняет звонки при сбоях внешних сервисов.
Частые вопросы
Что делает Phone API МойСклад?
Связывает телефонию с интерфейсом: показывает карточку при входящем звонке, позволяет звонить по клику на номер и ведёт журнал вызовов со ссылками на записи разговоров.
Phone API заменяет саму АТС?
Нет. Он лишь мост между вашей АТС и МойСклад. Установка соединения, медиапоток и запись остаются на стороне провайдера телефонии.
Как узнать клиента по входящему номеру?
Поиском контрагента через JSON API 1.2 с фильтром по phone. Номер нужно предварительно нормализовать к единому формату, иначе совпадение не найдётся.
Как реализуется click-to-call?
МойСклад уведомляет приложение о клике по номеру, сервер интеграции отправляет команду originate на АТС, та дозванивается до менеджера и затем до клиента, статусы возвращаются событиями.
Зачем нужен маппинг операторов?
Чтобы связать пользователя МойСклад с его внутренним номером или SIP-аккаунтом на АТС. Без этого система не поймёт, с какого аппарата инициировать исходящий вызов.
Как хранить записи разговоров?
Аудио держите на своей стороне с ограничением доступа, а в МойСклад передавайте только защищённую ссылку. Записи — персональные данные и требуют контроля прав.
Почему события звонков стоит буферизовать?
Телефония — поток в реальном времени с всплесками. Очередь и идемпотентная обработка защищают от дублей и потерь при пиковой нагрузке или сбоях сети.
Что делать, если МойСклад временно недоступен?
Не блокировать установку соединения. Критичный путь (звонок) должен работать, а запись истории откладывается в очередь и досылается, когда платформа снова доступна.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.