Integration of 1C-Bitrix with Omnidesk

Integration of 1C-Bitrix with Omnidesk

Omnidesk is a helpdesk focused on omnichannel communication: email, chat, Telegram, VKontakte, Facebook, and Viber in a single window. Integrating it with Bitrix gives the Omnidesk operator customer context without switching tabs — order numbers, amounts, statuses, and history directly in the case card.

Omnidesk API

REST API: https://{account}.omnidesk.ru/api/. Authentication — HTTP Basic Auth: {user_email}:{api_token}. Core resources: cases (cases = tickets), users (customers), staff (operators), labels (tags).

Rate limit: 60 requests per minute.

Synchronizing Bitrix Users → Omnidesk

On user registration and profile update, synchronize data to Omnidesk via POST /api/users.json or PUT /api/users/{id}.json:

class OmnideskUserSync
{
    public function sync(int $bitrixUserId): void
    {
        $user = \CUser::GetByID($bitrixUserId)->Fetch();
        $omnideskId = $user['UF_OMNIDESK_USER_ID'] ?? null;

        $data = [
            'user' => [
                'full_name'    => trim($user['NAME'] . ' ' . $user['LAST_NAME']),
                'email'        => $user['EMAIL'],
                'phone'        => $user['PERSONAL_PHONE'],
                'custom_data'  => [
                    'bitrix_user_id' => (string)$bitrixUserId,
                    'registered_at'  => $user['DATE_REGISTER'],
                ],
            ],
        ];

        if ($omnideskId) {
            $response = $this->client->put("/api/users/{$omnideskId}.json", $data);
        } else {
            // Search by email first
            $existing = $this->client->get('/api/users.json', ['email' => $user['EMAIL']]);
            if (!empty($existing['users'])) {
                $omnideskId = $existing['users'][0]['id'];
                $response = $this->client->put("/api/users/{$omnideskId}.json", $data);
            } else {
                $response = $this->client->post('/api/users.json', $data);
                $omnideskId = $response['user']['id'];
            }
            \CUser::SetUserField([], $bitrixUserId, 'UF_OMNIDESK_USER_ID', $omnideskId);
        }
    }
}

Enriching the Customer Card with Order Data

Omnidesk supports custom fields (custom_data) in the user profile. In addition to static enrichment at registration, configure a dynamic widget in Omnidesk via an iframe.

In the Omnidesk settings under Integrations → Widgets, specify the widget URL on the Bitrix side:

https://myshop.ru/personal/omnidesk-widget/?email={user.email}

The {user.email} placeholder is substituted by Omnidesk with the customer's email from the case.

The Bitrix widget page receives the email, locates the user, and outputs their orders:

$email = htmlspecialchars($_GET['email'] ?? '');
if (!$email) exit;

$user = \CUser::GetByLogin($email)->Fetch();
if (!$user) {
    echo 'Customer not found in the system';
    exit;
}

$orders = \Bitrix\Sale\Order::getList([
    'filter' => ['USER_ID' => $user['ID']],
    'order'  => ['DATE_INSERT' => 'DESC'],
    'limit'  => 10,
    'select' => ['ID', 'ACCOUNT_NUMBER', 'DATE_INSERT', 'PRICE', 'STATUS_ID', 'CURRENCY'],
])->fetchAll();

// Render orders table

The iframe shows the operator the customer's last 10 orders with amounts and statuses directly in the Omnidesk interface.

Automatic Ticket Creation on a Problematic Order

When an order is moved to the "Return" or "Complaint" status (a custom status), create a ticket in Omnidesk via POST /api/cases.json:

AddEventHandler('sale', 'OnSaleStatusOrderChange', function(\Bitrix\Main\Event $event) {
    $order  = $event->getParameter('ENTITY');
    $status = $order->getField('STATUS_ID');

    if (!in_array($status, ['RETURN', 'COMPLAINT'])) return;

    $userId     = $order->getUserId();
    $omnideskId = \CUser::GetByID($userId)->Fetch()['UF_OMNIDESK_USER_ID'] ?? null;

    $omnidesk->post('/api/cases.json', [
        'case' => [
            'subject'     => 'Order #' . $order->getId() . ': ' . ($status === 'RETURN' ? 'return request' : 'complaint'),
            'content'     => 'Automatically created on order status change',
            'user_id'     => $omnideskId,
            'label_names' => [$status === 'RETURN' ? 'return' : 'complaint'],
            'custom_data' => [
                'order_id'    => $order->getId(),
                'order_total' => $order->getPrice(),
            ],
        ],
    ]);
});

Webhooks from Omnidesk

Omnidesk sends webhooks (POST to your URL) on events: case_created, case_updated, case_resolved, message_created.

The handler verifies the request via the X-Omnidesk-Signature header (HMAC-SHA1 of the body) and performs the required action. For example, on case_resolved — send an email from Bitrix requesting a support quality rating.

Timeline