Настраиваем CRM и доступ
Проверьте, что на портале включён режим CRM с лидами. Создайте входящий вебхук Битрикс24 с доступом к CRM для пользователя, которому разрешено создавать лиды и читать записи, созданные интеграцией. В этом примере используется crm.lead.add из предыдущей версии REST по указанной документации. Битрикс24 помечает эту версию метода как устаревшую и направляет новые интеграции к REST 3.0. Примеры ниже относятся к одному формату REST и используют согласованную пару crm.lead.add и crm.lead.list.
Входящий вебхук Битрикс24 — адрес, по которому ваш сервер вызывает CRM. Обновления Telegram приходят отдельно на ваш сервер. Полный адрес CRM-вебхука содержит секрет. Храните его в серверной конфигурации и исключите из журналов запросов и ошибок. ID ответственного возьмите из Битрикс24 и храните в настройках интеграции.
Бот принимает контакты в личном чате. Проверьте обязательные поля и нормализуйте телефон. Если клиент оставил email, добавьте его как отдельное поле. Telegram username может меняться и не заменяет телефон, email или ID контакта CRM. Сценарий диалога можно собрать по примеру пошаговой анкеты.
Сопоставляем ответы клиента с полями CRM
Перед подключением API проведите одну заявку вручную от анкеты до карточки лида. Выпишите, какие ответы обязательны для менеджера, откуда берётся каждый ответ и в каком поле CRM он должен оказаться. Если в портале обязательны дополнительные поля, добавьте их в анкету или заполните серверным значением до постановки задачи.
Название заявки → TITLE. Используйте понятный шаблон, например «Консультация — подключение команды». Номер локальной заявки можно добавить в название для удобства поиска.
Имя и фамилия → NAME и LAST_NAME. Если клиент ввёл одну строку, можно сохранить её в NAME. Автоматическое разбиение по пробелу часто ошибается на составных именах.
Телефон и email → массивы PHONE и EMAIL. Необязательное поле без значения целиком пропускайте. Проверяйте формат до отправки и сохраняйте исходный ввод для уточнения у клиента.
Тема обращения → COMMENTS. Передавайте текстовое описание и номер заявки. Служебные токены и полный адрес вебхука в комментарии не нужны.
Ответственный → ASSIGNED_BY_ID. Это ID сотрудника портала. Назначайте его по серверному правилу, например по выбранной услуге или подразделению.
Список полей выбранной версии API можно получить через crm.lead.fields. Проверьте коды и типы пользовательских полей в своём портале. Подпись «Город» в интерфейсе может соответствовать техническому коду UF_CRM_…, который отличается между порталами. Сопоставление храните в настройках интеграции.
Покажите клиенту собранную заявку перед финальным подтверждением. Исправление телефона на этом шаге проще, чем поиск неверного контакта уже после передачи менеджеру. После подтверждения зафиксируйте снимок ответов и номер версии, который будет использовать воркер.
Сохраняем заявку и операцию отправки
На финальном шаге анкеты одной транзакцией сохраните заявку с неизменяемым UUID и задание на передачу в CRM. В журнале исходящих операций храните portal_id, request_id, состояние отправки, число попыток, код последней ошибки и crm_lead_id. Добавьте уникальность по (portal_id, request_id). Сохраните версию данных, которую отправляете, чтобы при разборе сбоя видеть исходные поля.
Повтор одного обновления Telegram определяйте по паре «бот, update_id». Повторное нажатие кнопки подтверждения может прийти новым обновлением. Для него используйте тот же ID черновика анкеты и разрешите подтвердить черновик только один раз. Клиент получает номер локальной заявки после фиксации транзакции.
Задание забирает воркер. Атомарно переводите строку из pending в sending, чтобы два воркера не вызвали создание лида одновременно. Если воркер пропал в состоянии sending, переводите запись на сверку по истечении рабочего срока. Старый воркер может ещё завершать запрос, поэтому истечение срока само по себе не разрешает новый POST.
Создаём лид и назначаем ответственного
Отправьте JSON методом POST по адресу вашего входящего вебхука с суффиксом /crm.lead.add.json. Ниже тело запроса с тестовыми значениями. ORIGINATOR_ID — постоянный код источника, ORIGIN_ID — UUID локальной заявки. Храните оба значения неизменными для сверки.
{
"fields": {
"TITLE": "Консультация из Telegram",
"NAME": "Анна",
"PHONE": [{ "VALUE": "+70000000000", "VALUE_TYPE": "MOBILE" }],
"EMAIL": [{ "VALUE": "anna@example.test", "VALUE_TYPE": "WORK" }],
"COMMENTS": "Интересует подключение сервиса для команды.",
"ASSIGNED_BY_ID": 42,
"ORIGINATOR_ID": "telegram_consultations",
"ORIGIN_ID": "ed494b68-b09a-4aa0-b31c-b817a8ad15b0"
}
}
Имя и способы связи в этом примере заполняют поля лида. Для привязки уже известного контакта передавайте проверенный CONTACT_ID. Ищите существующий контакт по своим правилам сопоставления и не выбирайте первую запись при нескольких совпадениях.
Проверьте HTTP-статус и JSON. Успешный ответ содержит ID в result, а ответ с error требует разбора кода и причины. После подтверждённого успеха запишите crm_lead_id и состояние sent в одной локальной транзакции. Дальнейшие операции с лидом адресуйте по этому ID.
Проводим первую заявку от бота до CRM
Начните с тестового пользователя и ответственного сотрудника, который знает о проверке. Подготовьте заявку с вымышленными контактами и убедитесь, что она видна в локальной базе. В карточке операции должны появиться её UUID, портал и состояние pending.
Разрешите воркеру взять одну операцию. Сохраните время начала запроса и номер попытки. После успешного ответа ожидается числовой ID лида в result. Откройте этот лид в CRM и сравните поля с зафиксированным снимком. Затем проверьте, что в локальной операции сохранён именно этот ID.
Проверьте доступ ещё раз после назначения ответственного. Если пользователь вебхука теряет право читать созданный лид, последующая сверка после сбоя может вернуть пустой список. Права интеграции должны позволять находить собственные записи при выбранной схеме назначения.
Для менеджера удобно показывать в списке заявок номер обращения, статус передачи и ID CRM. Клиенту достаточно сообщения «Заявка №142 принята». Обещать, что менеджер уже получил её в CRM, можно после подтверждённого результата передачи.
Восстанавливаем связь после сбоя
Если сервер CRM явно отклонил запрос из-за прав или полей, исправьте причину и только потом возобновите отправку. Таймаут, обрыв соединения, неожиданный ответ или авария воркера после запроса оставляют результат неизвестным. Для таких записей сначала выполните сверку. Не включайте безусловный HTTP-повтор для операции создания.
{
"filter": {
"=ORIGINATOR_ID": "telegram_consultations",
"=ORIGIN_ID": "ed494b68-b09a-4aa0-b31c-b817a8ad15b0"
},
"select": ["ID", "ORIGINATOR_ID", "ORIGIN_ID"]
}
Если найден ровно один лид с этими значениями, запишите его ID и завершите операцию без повторного создания.
Если совпадений несколько, передайте запись на разбор. Сохраните найденные ID и проверьте, с каким лидом уже работает менеджер.
Если совпадений нет, проверьте права чтения, портал и оба значения фильтра. Повторите сверку с паузой. Если после разбора причина осталась неизвестной, оставьте операцию на ручной проверке.
Поля ORIGINATOR_ID и ORIGIN_ID служат для связи и поиска. Уникальность операции в вашей БД защищает от параллельных отправок вашего воркера. Повторное создание в CRM после неясного исхода остаётся отдельным решением оператора.
Организуем повторы и ручной разбор
Состояния операции помогают понять, какое действие сейчас безопасно. pending означает ожидание воркера, sending — выполняющийся запрос, sent — известный ID лида. Для явного отказа заведите состояние failed, а для потерянного результата — unknown. Это состояния вашего приложения.
В списке failed покажите код ошибки и действие, которое её исправляет. Например, оператор уточняет обязательное поле, сохраняет новую версию данных и разрешает повтор. Для unknown показывайте отдельное действие сверки. Такой интерфейс снижает вероятность случайного повторного создания лида.
Если CRM отвечает ограничением частоты, увеличьте паузу и сократите параллелизм отправок на этот портал. Сохраняйте время следующей разрешённой попытки, чтобы перезапуск воркера не обнулял ожидание. Ошибки доступа требуют исправления настройки, поэтому непрерывные повторы здесь бесполезны.
После восстановления интеграции обработайте накопившиеся заявки небольшими порциями. Сначала сверяйте операции с неизвестным исходом, затем возобновляйте ещё не отправленные. Сохраните автора и причину ручного повтора в журнале, чтобы позже объяснить появление каждого лида.
Выполняем запрос и сверку в Laravel
Следующий клиент можно подключить к заданию очереди Laravel. Добавьте в config/services.php настройку 'bitrix' => ['webhook' => env('BITRIX_WEBHOOK_URL')], а в окружение — адрес входящего вебхука вашего портала без имени метода. Он имеет вид https://your-portal.bitrix24.ru/rest/USER_ID/WEBHOOK_SECRET/. Доступ к конфигурации и журналам должен быть ограничен.
<?php
namespace App\Services;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;
final class BitrixLeads
{
private function call(string $method, array $body): array
{
$base = (string) config('services.bitrix.webhook');
if (!str_starts_with($base, 'https://')) {
throw new \LogicException('Настройте HTTPS-вебхук CRM');
}
try {
$response = Http::acceptJson()->connectTimeout(5)->timeout(20)
->withOptions(['allow_redirects' => false])
->post(rtrim($base, '/').'/'.$method.'.json', $body);
} catch (ConnectionException) {
return ['state' => 'unknown', 'code' => 'connection'];
}
$json = $response->json();
if (!is_array($json) || $response->serverError()) {
return ['state' => 'unknown', 'code' => 'unexpected_response'];
}
if (is_string($json['error'] ?? null)) {
// Не пишем error_description и URL в открытые журналы.
return ['state' => 'failed', 'code' => substr($json['error'], 0, 100)];
}
if (!$response->successful() || !array_key_exists('result', $json)) {
return ['state' => 'unknown', 'code' => 'unexpected_response'];
}
return ['state' => 'ok', 'body' => $json];
}
public function create(array $fields): array
{
$reply = $this->call('crm.lead.add', ['fields' => $fields]);
if ($reply['state'] !== 'ok') return $reply;
$id = filter_var($reply['body']['result'], FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
return $id === false ? ['state' => 'unknown', 'code' => 'invalid_id']
: ['state' => 'sent', 'crm_lead_id' => $id, 'code' => null];
}
public function reconcile(string $requestId): array
{
$reply = $this->call('crm.lead.list', [
'filter' => ['=ORIGINATOR_ID' => 'telegram_consultations', '=ORIGIN_ID' => $requestId],
'select' => ['ID', 'ORIGINATOR_ID', 'ORIGIN_ID'], 'start' => 0,
]);
if ($reply['state'] !== 'ok') return ['state' => 'unknown', 'code' => 'lookup_failed'];
$body = $reply['body'];
$rows = $body['result'];
if (!is_array($rows) || count($rows) !== 1 || isset($body['next'])
|| (int) ($body['total'] ?? -1) !== 1) {
return ['state' => 'unknown', 'code' => 'review_required'];
}
$row = array_values($rows)[0];
$id = filter_var($row['ID'] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if ($id === false || ($row['ORIGINATOR_ID'] ?? null) !== 'telegram_consultations'
|| ($row['ORIGIN_ID'] ?? null) !== $requestId) {
return ['state' => 'unknown', 'code' => 'lookup_mismatch'];
}
return ['state' => 'sent', 'crm_lead_id' => $id, 'code' => null];
}
}
Вызов create($fields) принимает содержимое объекта fields из примера выше. Получится один POST с ограниченным временем ожидания. Клиент возвращает sent только с проверенным ID. failed означает полученную ошибку CRM, которую нужно разобрать, а unknown отправляется на сверку. Автоматического повторного создания в HTTP-клиенте нет.
Для небольшого Laravel-приложения заведите таблицу исходящих операций следующей миграцией. Поле fields хранит снимок подготовленной заявки; вставляйте строку одновременно с подтверждением заявки. Время последней попытки нужно для поиска зависших отправок.
\Illuminate\Support\Facades\Schema::create('crm_deliveries', function (\Illuminate\Database\Schema\Blueprint $t) {
$t->id(); $t->string('portal_id'); $t->uuid('request_id');
$t->json('fields'); $t->string('state')->default('pending');
$t->unsignedInteger('attempts')->default(0); $t->timestamp('attempted_at')->nullable();
$t->unsignedBigInteger('crm_lead_id')->nullable(); $t->string('last_error')->nullable();
$t->unique(['portal_id', 'request_id']);
});
Создайте задание командой php artisan make:job SendLeadToBitrix. В созданном классе оставьте ShouldQueue и штатный Queueable, замените конструктор на public function __construct(public int $deliveryId) {} и добавьте свойства public int $tries = 1; public int $timeout = 30; public bool $failOnTimeout = true;. Метод handle() заполните следующим кодом.
$db = \Illuminate\Support\Facades\DB::table('crm_deliveries');
$claimed = (clone $db)->where('id', $this->deliveryId)->where('state', 'pending')->update([
'state' => 'sending', 'attempted_at' => now(),
'attempts' => \Illuminate\Support\Facades\DB::raw('attempts + 1'),
]);
if ($claimed !== 1) return;
$row = (clone $db)->where('id', $this->deliveryId)->first();
$fields = json_decode($row->fields, true, 32, JSON_THROW_ON_ERROR);
$fields['ORIGINATOR_ID'] = 'telegram_consultations';
$fields['ORIGIN_ID'] = $row->request_id;
$outcome = app(\App\Services\BitrixLeads::class)->create($fields);
(clone $db)->where('id', $row->id)->where('state', 'sending')->update([
'state' => $outcome['state'], 'crm_lead_id' => $outcome['crm_lead_id'] ?? null,
'last_error' => $outcome['code'] ?? null,
]);
В примере настроен один портал: используйте один постоянный portal_id при сохранении. Для нескольких порталов выбирайте серверную конфигурацию клиента по этому полю. Задание хранит только deliveryId и имеет одну попытку; повторная доставка задания безопасно остановится на проверке состояния. По расписанию находите давно зависшие sending и передавайте их на сверку, не возвращая в pending.
В routes/console.php подключите подбор pending-операций. Повторно поставленные задания остановятся на атомарном захвате строки. Такой подбор также найдёт заявку, если приложение успело сохранить её, но упало до постановки задания в очередь.
use App\Jobs\SendLeadToBitrix;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;
Schedule::call(function () {
DB::table('crm_deliveries')->where('state', 'pending')->orderBy('id')->limit(100)
->pluck('id')->each(fn ($id) => SendLeadToBitrix::dispatch((int) $id)->onQueue('crm'));
})->everyMinute()->withoutOverlapping();
Для локальной проверки задайте QUEUE_CONNECTION=database и примените миграции таблиц jobs и crm_deliveries. В двух терминалах тестового приложения запустите команды ниже. В рабочем окружении процессы должны обслуживаться вашим планировщиком и менеджером процессов. Интервал retry_after выбранного соединения очереди должен быть больше 30 секунд.
php artisan schedule:work # В другом терминале: php artisan queue:work database --queue=crm --tries=1 --timeout=30
Для сверки вызовите app(\App\Services\BitrixLeads::class)->reconcile($row->request_id) и сохраните найденный crm_lead_id. Если результат unknown, оставьте операцию для разбора. Пустой список не доказывает, что лид не создан: проверьте права, время выполнения первого запроса и портал. На тестовом портале сначала создайте одну заявку и убедитесь, что поиск по двум ORIGIN-полям возвращает тот же ID. Затем вызовите сверку вместо повторного создания — число лидов должно остаться прежним.
Проверяем в тестовом портале
Отправьте одну заявку. Сверьте имя, телефон, email, ответственного и ID лида в локальной базе.
Дважды обработайте одно обновление и отдельно повторите подтверждение черновика новым обновлением. Для обоих сценариев должна остаться одна операция передачи.
Сымитируйте потерю ответа после успешного создания. При сверке должен сохраниться ID найденного лида без второго POST.
Проверьте отказ в чтении и несколько совпадений. В обоих случаях автоматическое повторное создание должно остановиться.
Метод crm.lead.add · Метод crm.lead.list · Как разбирать дубли при отправке из бота