Zadarma (телефония)

Zadarma — IP-телефония + виртуальная АТС. OPORA подключается к Zadarma API для:

• Входящих звонков — webhook’и NOTIFY_START / NOTIFY_ANSWER / NOTIFY_END для CRM-sync’а (карточка лида открывается менеджеру до снятия трубки)
• Исходящих — click-to-call из CRM (OPORA zadarma.call.originate)
• SMS — через REST API

1. Credentials

В Zadarma: «Мой Zadarma» → «API и интеграции»:

• User key (public)
• Secret (private)

2. Сохраните в OPORA

Settings → Secrets:

• zadarma-user-key: User key
• zadarma-secret: Secret

3. Webhook для входящих

1. Zadarma → «Настройки PBX» → «Настройки уведомлений»
2. URL для уведомлений: https://app.opora.example/webhook/<uuid> (после publish’а workflow’а с zadarma.webhook.trigger)
3. События: отметьте все нужные (NOTIFY_START, ANSWER, END, RECORD, INTERNAL, IVR)

Zadarma подписывает webhook’и MD5’ом (signature в query-param) — OPORA валидирует автоматически.

4. Ноды

Нода	Что делает
zadarma.webhook.trigger	Incoming call events (MD5-signed)
zadarma.call.originate	Click-to-call — инициирует звонок с SIP-внутреннего на внешний номер
zadarma.sms.send	Отправка SMS (через SIP-номер как sender)

5. Пример: входящий звонок → создание лида в amoCRM

zadarma.webhook.trigger (event: NOTIFY_START)
    ↓
amocrm.crm.list
  entity = "contacts"
  filter = {custom_fields_values: [{field_code: "PHONE", value: "{{trigger.caller_id}}"}]}
    ↓
control.switch
  ├─ list.results.length > 0 → существующий контакт
  │   ↓
  │   telegram.message.send (chat_id = {{manager_tg}}, text = "📞 Звонок от существующего: {{list.results.0.name}}")
  │
  └─ list.results.length == 0 → новый
      ↓
      amocrm.lead.create
        name = "Входящий звонок {{trigger.caller_id}}"
        custom_fields = [{field_code: "PHONE", values: [{value: "{{trigger.caller_id}}"}]}]
      ↓
      telegram.message.send (chat_id = {{manager_tg}}, text = "🔥 Новый лид со звонка: {{trigger.caller_id}}")

6. Click-to-call

# Из CRM: менеджер жмёт «Позвонить» на карточке лида →
# фронт дёргает какой-то OPORA-endpoint / запускает agent
zadarma.call.originate
  from = "100"              # SIP-внутренний менеджера
  to = "{{lead.phone}}"     # внешний номер
  predicted = true          # сначала дозваниваемся менеджеру,
                            # потом лиду — чтобы менеджер не ждал

7. SMS

zadarma.sms.send
  from = "MyCompany"        # sender id (зарегистрирован в Zadarma)
  to = "+79991234567"
  text = "Ваш заказ #{{order_id}} принят. Ссылка: {{url}}"

Troubleshooting

Webhook подпись не сходится

• zadarma-user-key / zadarma-secret перепутаны (частая ошибка). Проверьте в Zadarma cabinet’е.
• Zadarma иногда меняет формат signature’а — при issue’ax проверьте их changelog.

call.originate возвращает OK, но звонок не идёт

• SIP-внутренний from не зарегистрирован / offline. Проверьте в Zadarma PBX → Мои SIP → статус линии.
• Баланс Zadarma закончился (они отключают outbound’ы).

SMS не доходит

• from не зарегистрирован как sender-id (нужна ручная регистрация в Zadarma, занимает 1-3 дня). На период регистрации используйте дефолтный Zadarma.
• Абонент в «чёрном списке» Zadarma или заблокировал короткие номера.

Другие провайдеры телефонии

Zadarma — flagship, но тот же pattern работает для:

• Mango Office — аналогичный REST + HMAC webhook
• UIS / Телфин / Novofon — аналогично

Dedicated-ноды этих провайдеров не написаны, добавим по demand’у. Пока можно использовать external.http ноду с auth-preset’ом HMAC если нужно что-то нестандартное.

Связанное

• Cookbook «Inbound call to lead» — полный пример «входящий звонок → открыть карточку амо менеджеру → SMS-follow-up» — в cookbook (добавляется в следующей итерации). Пока см. Refund coordinator как reference-паттерн с similar shape’ом (webhook → CRM lookup → cross-system action).