Інтеграція 1С-Бітрікс з Usedesk

Інтеграція 1С-Бітрікс з Usedesk

Usedesk — російський хелпдеск: єдина черга тікетів із email, чату, телефону, соцмереж. Інтеграція з Бітрікс потрібна насамперед для зв'язку тікетів із замовленнями. Оператор не повинен перемикатися між Usedesk і Бітрікс, щоб зрозуміти, що саме купив клієнт, який написав у підтримку.

API Usedesk

REST API Usedesk: https://api.usedesk.ru/. Авторизація — API-ключ у параметрі api_token або заголовку Authorization: Token {api_token}. Основні сутності:

• tickets — тікети (звернення)
• clients — клієнти
• comments — повідомлення у тікеті
• custom_fields — кастомні поля

Webhooks налаштовуються в розділі «Налаштування → Інтеграції → API» Usedesk.

Синхронізація клієнтів

При реєстрації користувача у Бітрікс (подія OnAfterUserRegister) створюємо або знаходимо клієнта у Usedesk:

AddEventHandler('main', 'OnAfterUserRegister', function(&$fields) {
    $email = $fields['LOGIN']; // У Бітрікс логін часто = email

    // Шукаємо існуючого клієнта за email
    $response = $usedesk->get('/clients', ['email' => $email]);
    if (!empty($response['clients'])) {
        $udClientId = $response['clients'][0]['id'];
    } else {
        // Створюємо нового
        $response = $usedesk->post('/clients', [
            'name'  => $fields['NAME'] . ' ' . $fields['LAST_NAME'],
            'email' => $email,
            'phone' => $fields['PERSONAL_PHONE'] ?? '',
            'custom_fields' => [
                ['id' => USEDESK_CF_BITRIX_USER_ID, 'value' => $fields['ID']],
            ],
        ]);
        $udClientId = $response['client']['id'];
    }

    // Зберігаємо маппінг
    \CUser::SetUserField([], $fields['ID'], 'UF_USEDESK_CLIENT_ID', $udClientId);
});

Передача даних замовлення у тікет

При створенні нового замовлення (подія OnSaleOrderSaved) записуємо дані в кастомні поля клієнта Usedesk. Це збагачує картку клієнта історією покупок:

AddEventHandler('sale', 'OnSaleOrderSaved', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    if ($order->isNew()) {
        $userId = $order->getUserId();
        $udClientId = \CUser::GetByID($userId)->Fetch()['UF_USEDESK_CLIENT_ID'] ?? null;
        if (!$udClientId) return;

        // Додаємо нотатку до клієнта у Usedesk
        $usedesk->post("/clients/{$udClientId}/comments", [
            'message' => sprintf(
                'Нове замовлення #%d на суму %s грн. Статус: %s',
                $order->getId(),
                number_format($order->getPrice(), 2, ',', ' '),
                $order->getField('STATUS_ID')
            ),
            'type' => 'note',
        ]);
    }
});

Віджет Usedesk на сайті з персоналізацією

Usedesk надає JS-віджет. Для персоналізації при авторизованому користувачеві передаємо його дані:

(function(d, w, c) {
    w.usedeskSettings = {
        company_id: "<?= USEDESK_COMPANY_ID ?>",
        <?php if ($USER->IsAuthorized()): ?>
        user: {
            name: "<?= htmlspecialchars($USER->GetFullName()) ?>",
            email: "<?= htmlspecialchars($USER->GetEmail()) ?>",
            fields: {
                custom_id: "<?= $USER->GetID() ?>"
            }
        },
        <?php endif; ?>
    };
    var s = d.createElement("script");
    s.type = "text/javascript"; s.async = true;
    s.src = "https://secure.usedesk.ru/widget.js";
    d.getElementsByTagName("head")[0].appendChild(s);
})(document, window);

Це дозволяє Usedesk автоматично пов'язати чат-сесію з карткою клієнта за email.

Обробка webhooks із Usedesk

При зміні статусу тікета Usedesk надсилає webhook на наш обробник. Типове застосування: при закритті тікета (статус resolved) надіслати клієнту email із Бітрікс із пропозицією залишити відгук.

// /api/usedesk-webhook.php
$payload = json_decode(file_get_contents('php://input'), true);

// Верифікація підпису
$sig = hash_hmac('sha256', file_get_contents('php://input'), USEDESK_WEBHOOK_SECRET);
if (!hash_equals($sig, $_SERVER['HTTP_X_USEDESK_SIGNATURE'] ?? '')) {
    http_response_code(403); exit;
}

if ($payload['event'] === 'ticket.resolved') {
    $email = $payload['ticket']['client']['email'] ?? '';
    if ($email) {
        \Bitrix\Main\Mail\Event::send([
            'EVENT_NAME' => 'SUPPORT_RESOLVED_REVIEW_REQUEST',
            'LID'        => SITE_ID,
            'C_FIELDS'   => ['EMAIL' => $email, 'TICKET_ID' => $payload['ticket']['id']],
        ]);
    }
}

Відображення тікетів у особистому кабінеті

У ЛК Бітрікс додаємо розділ «Мої звернення». Компонент запитує тікети клієнта через Usedesk API за client_id:

$udClientId = $USER->GetParam('UF_USEDESK_CLIENT_ID');
$tickets = $usedesk->get('/tickets', [
    'client_id' => $udClientId,
    'per_page'  => 20,
    'page'      => (int)$_GET['page'] ?: 1,
]);

Список тікетів кешується на 60 секунд (\Bitrix\Main\Data\Cache).

Терміни