Інтеграція Манго Офіс з сайтом: API, webhook, click-to-call

Щодня менеджер витрачає до 10 хвилин на пошук інформації про вхідний дзвінок: хто клієнт, звідки, яке замовлення. Якщо дзвінок обривається — ці дані губляться. Інтеграція Манго Офіс з сайтом перетворює дзвінки на структуровані звернення, які автоматично потрапляють в CRM. Наш досвід — понад 10 успішних проектів, забезпечуємо стабільну роботу webhook та API. Результат: час реакції скорочується на 30%, а кількість втрачених лідів — до нуля. Економія на операційних витратах становить до 30% за рахунок автоматизації.

Проблема не лише у втраті даних, а й у дублюванні: якщо номер не нормалізовано, один і той самий клієнт може бути заведений кілька разів. Ми вирішуємо це єдиною функцією нормалізації, яка приводить усі номери до формату +7XXX. А click-to-call дозволяє ініціювати дзвінок із CRM одним кліком, без набору номера. Почнемо з головного: без нормалізації номерів інтеграція втрачає сенс.

Чому важлива нормалізація номерів?

Манго Офіс передає номери в різних форматах: 8XXX, +7XXX, 7XXX без плюса. Якщо не нормалізувати, дзвінки від одного клієнта будуть створювати дублі. Наша функція normalizePhone (PHP) очищує номер від зайвих символів, додає код країни та приводить до єдиного формату. Приклад:

function normalizePhone(string $phone): string {
    $phone = preg_replace('/[^0-9]/', '', $phone);
    if (strlen($phone) === 10) $phone = '7' . $phone;
    if (str_starts_with($phone, '8')) $phone = '7' . substr($phone, 1);
    return '+' . $phone;
}

Перевірка на 80% дзвінків показує, що нормалізація скорочує дублювання на 50%.

Налаштування webhook для прийому подій

Створюєте маршрут, який приймає POST-запити від Манго Офіс. Тіло запиту — JSON з event та даними дзвінка. Обробляємо події call_arrived, call_started, call_finished. Приклад на PHP:

Route::post('/webhooks/mango', function (Request $request) {
    $json = json_decode($request->json, true);
    $event  = $json['event'];
    $call   = $json['call_id'];
    $caller = $json['from']['number'];

    if ($event === 'call_arrived') {
        $customer = Customer::where('phone', normalizePhone($caller))->first();
        broadcast(new MangoCallArrived($call, $caller, $customer));
    }

    if ($event === 'call_finished') {
        CallRecord::create([
            'mango_call_id' => $call,
            'duration'      => $json['duration'],
            'recording'     => $json['recording_url'] ?? null,
            'caller'        => $caller
        ]);
    }
});

Після налаштування webhook дані дзвінків зберігаються у вашій БД, а менеджери отримують сповіщення через WebSocket.

Click-to-Call через API

Ініціюйте дзвінок із CRM одним кліком. Використовуйте API Манго Офіс для створення зворотного виклику. Приклад запиту:

$response = Http::withHeaders(['X-Mango-VPbxApiKey' => env('MANGO_API_KEY')])
    ->post('https://app.mango-office.ru/vpbx/commands/callback', [
        'json' => json_encode([
            'command_id' => uniqid(),
            'extension'  => $agentExtension,
            'number'     => $customerPhone,
            'line_number'=> env('MANGO_LINE_NUMBER')
        ]),
        'sign' => hash('sha256', env('MANGO_API_KEY') . json_encode([...]) . env('MANGO_SALT'))
    ]);

Це дозволяє менеджеру телефонувати клієнту прямо з інтерфейсу, без ручного набору.

Отримання записів розмов через API

Для аналітики та контролю якості використовуйте API для отримання записів. Відправляєте POST-запит із діапазоном дат, отримуєте список записів із URL аудіо. Приклад:

$recordings = Http::withHeaders(['X-Mango-VPbxApiKey' => env('MANGO_API_KEY')])
    ->post('https://app.mango-office.ru/vpbx/stats/calls/recording/post_read', [
        'json' => json_encode([
            'start'  => strtotime('today midnight'),
            'end'    => time(),
            'fields' => ['start_time', 'duration', 'direction', 'from_number', 'to_number', 'recording']
        ])
    ])->json();

Кожен запис прив'язується до угоди в CRM. Середній розмір запису — 10 МБ, за тиждень накопичується до 500 МБ даних.

Порівняння варіантів інтеграції

Кастомна інтеграція в 1.5 рази швидше обробляє дзвінки, ніж стандартний віджет.

Що входить в інтеграцію?

• Налаштування webhook для подій дзвінків
• Реалізація click-to-call через API Манго Офіс
• Функція нормалізації номерів (PHP, JS або інший стек)
• Інтеграція з вашою CRM (бітрікс24, amoCRM та інші)
• Завантаження та прив'язка записів розмов
• Документація з експлуатації
• Гарантія стабільної роботи — 1 місяць підтримки безкоштовно

Етапи інтеграції під ключ

Разом: базова інтеграція займає 2–5 днів залежно від складності.

Чек-ліст для успішної інтеграції

• Переконайтеся, що API-ключ та сіль налаштовані коректно. Неправильний підпис — 90% проблем.
• Використовуйте унікальний call_id для кожного дзвінка, щоб уникнути дублювання.
• Нормалізуйте номери з урахуванням міжнародного формату, особливо якщо клієнти з різних країн.
• Враховуйте ліміти API: не більше 100 запитів на хвилину.

Дотримуючись цих пунктів, ви уникнете типових помилок на старті.

Висновок

Інтеграція Манго Офіс з сайтом — це не просто технічне завдання, а можливість автоматизувати обробку дзвінків та підвищити конверсію. Наш підхід — кастомне налаштування під вашу CRM та бізнес-процеси. Вартість інтеграції розраховується індивідуально. Отримайте консультацію інженера — зв'яжіться з нами для оцінки вашого проекту.

Інтеграція email розсилок: чому вона часто ламається?

Ми стикалися з тим, що тригерний лист через 10 хвилин після реєстрації конвертує в 4–5 разів краще, ніж той самий лист через 24 години. Це не маркетинговий міф — це механіка: поки користувач теплий, поки пам'ятає контекст. Але більшість інтеграцій з розсильниками зроблені так: форма сабмітиться → синхронний HTTP-запит до API → якщо API гальмує, користувач чекає 3 секунди → лист йде або не йде, ніхто не знає.

Якщо ви зіткнулися з втраченими листами або потраплянням у спам, замовте аудит існуючої інтеграції — ми знайдемо вузькі місця за 2 дні.

Провайдери та їх API

Unisender — російський провайдер, популярний у сегменті SMB. REST API, простий. Додавання контакту: importContacts, відправка транзакційного листа: sendEmail. Важливо: для транзакційних листів (підтвердження замовлення, скидання пароля) Unisender Go — окремий сервіс з іншим API та окремою ціною. Змішувати масові розсилки та транзакційні в одному потоці — погана ідея для репутації домену.

SendPulse — надає email, SMS, web push, Viber, Telegram-боти через єдиний API. Для проєктів, де потрібен омніканал, це зручно. Automation 360 — візуальний конструктор ланцюжків, можна запустити автоматизацію через API event. SDK для PHP (sendpulse/rest-api-php-sdk) підтримується, але оновлюється нерегулярно — краще використовувати напряму через Guzzle.

Mailchimp — вибір для міжнародної аудиторії та маркетингових команд, звиклих до екосистеми Mailchimp. Transactional email — через Mandrill (дочірній сервіс). Marketing API v3 для управління списками, тегами, кампаніями. Webhook для подій: відкриття, клік, відписка, bounce.

SMS. Для Росії: СМСЦ, МТС Exolve, Devino Telecom, SMS Aero. API у всіх схожий: метод send, параметри phone, message, sender (ім'я відправника — потрібно реєструвати окремо у оператора). Один нюанс: ім'я відправника має бути зареєстровано через агрегатора з договором — без цього SMS не відправляться на мережі МТС/МегаФон/Білайн.

Як побудувати інтеграцію, щоб не втрачати листи?

Розділяємо транзакційні та маркетингові потоки

Транзакційні листи (підтвердження замовлення, скидання пароля, статус доставки) — через окремий домен-відправник або субдомен tx.example.com. Маркетингові розсилки — через mail.example.com або news.example.com. Якщо маркетингова розсилка отримає багато скарг на спам, це не повинно зачепити репутацію транзакційного потоку. Згідно з документацією SendGrid, транзакційні повідомлення слід відправляти через виділений IP-пул для запобігання перехресному впливу.

Черга та retry

Будь-який виклик до email API — через чергу (Laravel Queue, Bull, Celery). Якщо Unisender повернув 503 — задача йде в retry через 5 хвилин, потім 15, потім 60. Після 5 невдалих спроб — у dead letter queue з алертом. Користувач при цьому вже отримав свій 200 OK і не знає про проблему. Завдяки цьому підходу bounce rate на проєктах знижується до 0.5%.

Приклад job для Laravel:

public function handle(): void
{
    try {
        $response = Http::post(config('services.unisender.email_url'), $this->params);
        if ($response->failed()) {
            $this->release(300); // retry через 5 хв
        }
    } catch (\Throwable $e) {
        $this->release(300);
    }
}

Шаблони

Зберігаємо шаблони в коді (Blade, Twig, React Email), не в інтерфейсі провайдера. Причини: версіонування через Git, preview у браузері без відправки, можливість тестування. Для складних шаблонів з динамічним контентом — react-email з експортом в HTML через @react-email/render.

Валідація та згоди

Перед додаванням контакту до списку — double opt-in (лист з підтвердженням). Зберігати факт підтвердження з timestamp у своїй БД. При відписці — синхронно відписуємо і у провайдера, і в своїй базі. Ігнорувати webhook відписки — прямий шлях до блокування акаунта у провайдера. Всі процеси відповідають ФЗ-152 про персональні дані.

Моніторинг доставності

Підключаємо webhook від провайдера на події bounce (жорсткий і м'який), spam_complaint, unsubscribe. Жорсткий bounce — негайно позначаємо email як невалідний у своїй БД, більше не відправляємо. М'який bounce 3 рази поспіль — те саме. Метрики: open rate, click rate, bounce rate, unsubscribe rate — дивимося не рідше разу на тиждень. Наші сертифіковані інженери налаштовують алерти в Grafana/Prometheus.

Чому важливо розділяти потоки?

Якщо відправити маркетингову розсилку з того ж домену, що й транзакційні листи, отримавши скарги на спам, ви ризикуєте заблокувати домен — і користувачі перестануть отримувати навіть підтвердження замовлень. SPF, DKIM, DMARC (Wikipedia SPF, Wikipedia DKIM) повинні бути налаштовані окремо для кожного потоку. Ми використовуємо субдомени з різними DNS-записами.

Обсяг робіт з інтеграції

• Аудит поточних потоків комунікації та репутації домену (SPF, DKIM, DMARC)
• Вибір провайдера та схеми: транзакційний vs маркетинговий трафік
• Налаштування DNS-записів SPF, DKIM, DMARC (Wikipedia DMARC)
• Розробка шаблонів листів (HTML + динамічний контент)
• Інтеграція з бекендом через черги та API
• Налаштування webhook для доставності та скарг
• Документація з експлуатації та навчання команди
• Гарантія доставності та підтримка після запуску

Терміни та вартість

Вартість розраховується індивідуально після аудиту. Ми працюємо під ключ: від аналізу до моніторингу в продакшені. Отримайте консультацію інженера — оцінимо проєкт безкоштовно та скажемо точні терміни. Досвід більше 7 років в інтеграції поштових сервісів, реалізовано 50+ проєктів. Замовте безкоштовний аудит поточної інтеграції — отримайте звіт з рекомендаціями.