Integration of 1C-Bitrix with Usedesk

Integration of 1C-Bitrix with Usedesk

Usedesk is a Russian helpdesk platform providing a unified ticket queue from email, chat, phone, and social media. The primary goal of integrating it with Bitrix is linking tickets to orders. Operators should not have to switch between Usedesk and Bitrix to understand what a customer who contacted support has actually purchased.

Usedesk API

Usedesk REST API: https://api.usedesk.ru/. Authentication — API key in the api_token parameter or the Authorization: Token {api_token} header. Core entities:

• tickets — tickets (requests)
• clients — customers
• comments — messages within a ticket
• custom_fields — custom fields

Webhooks are configured under Settings → Integrations → API in Usedesk.

Customer Synchronization

When a user registers in Bitrix (event OnAfterUserRegister), create or locate the customer in Usedesk:

AddEventHandler('main', 'OnAfterUserRegister', function(&$fields) {
    $email = $fields['LOGIN']; // In Bitrix, login is often the email

    // Look for an existing client by email
    $response = $usedesk->get('/clients', ['email' => $email]);
    if (!empty($response['clients'])) {
        $udClientId = $response['clients'][0]['id'];
    } else {
        // Create a new one
        $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'];
    }

    // Save mapping
    \CUser::SetUserField([], $fields['ID'], 'UF_USEDESK_CLIENT_ID', $udClientId);
});

Passing Order Data to a Ticket

When a new order is created (event OnSaleOrderSaved), write order data to the Usedesk client's custom fields. This enriches the customer card with purchase history:

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;

        // Add a note to the client in Usedesk
        $usedesk->post("/clients/{$udClientId}/comments", [
            'message' => sprintf(
                'New order #%d for %s. Status: %s',
                $order->getId(),
                number_format($order->getPrice(), 2, ',', ' '),
                $order->getField('STATUS_ID')
            ),
            'type' => 'note',
        ]);
    }
});

Usedesk Widget with Personalization

Usedesk provides a JS widget. For personalization, pass the authenticated user's data:

(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);

This allows Usedesk to automatically associate a chat session with the customer card by email.

Handling Webhooks from Usedesk

When a ticket status changes, Usedesk sends a webhook to our handler. A typical use case: when a ticket is closed (status resolved), send the customer an email from Bitrix inviting them to leave a review.

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

// Signature verification
$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']],
        ]);
    }
}

Displaying Tickets in the User Account

Add a "My Requests" section to the Bitrix user account. The component fetches the customer's tickets from the Usedesk API by client_id:

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

The ticket list is cached for 60 seconds (\Bitrix\Main\Data\Cache).

Timeline