Интеграция WhatsApp с Bitrix24: роботы, лиды и таймлайн

Что можно автоматизировать

• Новый клиент написал в WhatsApp — в CRM появляется лид с телефоном и первым сообщением, ответственный видит его в общей очереди.
• Знакомый клиент — его сообщение уходит комментарием в таймлайн лида, менеджер видит переписку рядом со звонками и письмами.
• Стадия «Отгружено» — робот сообщает клиенту, что заказ в пути; время доставки можно подставить из полей сделки.
• Напоминание об оплате — робот на стадии «Счёт выставлен» с отсрочкой выполнения: если сделка через несколько дней всё ещё там, клиенту уходит вежливое напоминание.
• Сообщение не доставлено — по событию message.ack со значением -1 в таймлайн пишется комментарий «WhatsApp не доставлен, позвоните».
• Номер отключился — событие session.status превращается в уведомление ответственному, пока клиенты не начали жаловаться.

Как это устроено

Со стороны Bitrix24 нужны три механизма:

• Входящий вебхук — адрес с секретным кодом для вызова REST: crm.lead.add (создать лид), crm.timeline.comment.add (комментарий в таймлайн), crm.deal.get и crm.contact.get (достать телефон).
• Робот «Webhook» в автоматизации CRM — на нужной стадии отправляет запрос на ваш адрес. В адрес можно вставить поля сделки, например её ID.
• Исходящий вебхук на события (ONCRMDEALADD, ONCRMDEALUPDATE) — альтернатива роботу, если нужна реакция на любое изменение, а не на конкретную стадию.

Со стороны wapi.kz — POST /messages/send для отправки (документация) и вебхук номера с событиями message, message.ack, session.status (документация).

Окно «Открытых линий» требует отдельного приложения-коннектора — у wapi.kz его нет. Поэтому переписку пишем комментариями в таймлайн: менеджер видит её в карточке, а отвечает с телефона или через ваш обработчик.

Настройка по шагам

1. Подключите номер в wapi.kz (как подключить) и выпустите в его карточке ключ номера — с ним не нужно поле from.
2. В Bitrix24 в разделе для разработчиков создайте входящий вебхук с правами на CRM. Адрес вида https://компания.bitrix24.kz/rest/1/код/ — это ключ к вашей CRM, храните его как пароль.
3. Положите обработчик (код ниже) на сервер с PHP 8 и публичным https.
4. В CRM откройте роботы сделок, на стадии «Отгружено» добавьте робота «Webhook» и укажите адрес https://ваш-сервер.kz/b24.php?token=СЕКРЕТ&deal=, а после deal= вставьте поле «ID» сделки.
5. В кабинете wapi.kz на карточке номера задайте вебхук https://ваш-сервер.kz/b24.php?token=СЕКРЕТ.
6. Переведите тестовую сделку на стадию и напишите на номер с другого телефона — проверьте лид и комментарий.

Пример кода

Один файл обслуживает и робота, и вебхук wapi.kz. Адрес входящего вебхука Bitrix24 и ключ wapi.kz — в переменных окружения.

<?php
// b24.php — робот Bitrix24 (?deal=ID) и вебхук wapi.kz (JSON в теле)
if (($_GET['token'] ?? '') !== getenv('HOOK_TOKEN')) { http_response_code(403); exit; }

function b24(string $method, array $params) {
    $ch = curl_init(getenv('B24_HOOK') . $method . '.json'); // https://компания.bitrix24.kz/rest/1/код/
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => http_build_query($params), CURLOPT_TIMEOUT => 15]);
    return json_decode(curl_exec($ch), true)['result'] ?? null;
}

function wapi_send(string $to, string $text): array {
    $ch = curl_init('https://wapi.kz/api/v1/messages/send');
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WAPI_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['to' => $to, 'text' => $text], JSON_UNESCAPED_UNICODE)]);
    return json_decode(curl_exec($ch), true) ?? [];
}

if (isset($_GET['deal'])) {
    // 1. Робот на стадии сделки → WhatsApp клиенту
    $deal = b24('crm.deal.get', ['id' => (int) $_GET['deal']]);
    $contact = b24('crm.contact.get', ['id' => (int) ($deal['CONTACT_ID'] ?? 0)]);
    $phone = preg_replace('/\D/', '', $contact['PHONE'][0]['VALUE'] ?? '');
    if (strlen($phone) === 11 && $phone[0] === '8') $phone = '7' . substr($phone, 1);
    if ($phone === '') exit;
    $r = wapi_send($phone, "Здравствуйте, {$contact['NAME']}! Заказ отгружен, курьер позвонит перед доставкой.");
    b24('crm.timeline.comment.add', ['fields' => ['ENTITY_ID' => $deal['ID'], 'ENTITY_TYPE' => 'deal',
        'COMMENT' => !empty($r['ok']) ? 'WhatsApp отправлен' : 'WhatsApp не отправлен: ' . ($r['code'] ?? '?')]]);
    exit;
}

// 2. Вебхук wapi.kz: входящее → комментарий в лид или новый лид
$e = json_decode(file_get_contents('php://input'), true);
if (($e['event'] ?? '') !== 'message' || !str_ends_with($e['payload']['from'], '@c.us')) exit; // только личные чаты с телефоном (не группы и не скрытые @lid)
http_response_code(200);
if (function_exists('fastcgi_finish_request')) fastcgi_finish_request(); // ответить сразу, работать после

$phone = explode('@', $e['payload']['from'])[0];
$text = $e['payload']['hasMedia'] ? '[клиент прислал файл]' : $e['payload']['body'];
$found = b24('crm.duplicate.findbycomm', ['type' => 'PHONE', 'values' => [$phone], 'entity_type' => 'LEAD']);

if (!empty($found['LEAD'])) {
    b24('crm.timeline.comment.add', ['fields' => ['ENTITY_ID' => $found['LEAD'][0],
        'ENTITY_TYPE' => 'lead', 'COMMENT' => "WhatsApp: $text"]]);
} else {
    b24('crm.lead.add', ['fields' => ['TITLE' => "WhatsApp $phone", 'COMMENTS' => $text,
        'PHONE' => [['VALUE' => '+' . $phone, 'VALUE_TYPE' => 'WORK']]]]);
}

Если CRM работает без лидов, ищите контакт (entity_type = CONTACT) и пишите комментарий в его сделку. Как поиск дублей сопоставляет форматы телефонов, проверьте на своих данных.

Ограничения

• Приложения wapi.kz в маркетплейсе Bitrix24 нет, коннектора к «Открытым линиям» — тоже. Связка — через вебхуки и обработчик.
• Входящие фото и документы в событии не приходят — там hasMedia: true, а сам файл сохраняется у нас и через несколько секунд доступен по ссылке media.url в GET /messages/{id}. В группы через API отправить нельзя.
• Лимиты на каждый номер: 1 сообщение в секунду, первые сообщения новым людям — не чаще раза в 5 секунд и с суточным потолком (лимиты). Робот на стадии, куда массово переносят сотни сделок, — плохая идея: сработает защита от рассылок.
• Вебхуки wapi.kz не повторяются. Если обработчик был недоступен, пропущенное заберите из GET /messages?since=….

Не хотите возиться с кодом? Зарегистрируйтесь, подключите номер и оставьте заявку из кабинета — связку с Bitrix24 настроим, для типового случая это около часа. Тариф — 9 900 ₸ в месяц за номер, сообщения бесплатны (цены).