Как найти CRM-объект, созданный из диалога открытой линии
Scope:
imopenlines,crmКто может выполнять методы:
imconnector.send.messages— приложение с доступом к открытым линиямimopenlines.dialog.get— пользователь с правом на доступ к диалогуcrm.item.list— пользователь с правом на чтение элементов CRM
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Коннектор открытой линии передает в Битрикс24 сообщения клиента из внешнего канала: мессенджера, чата на сайте или сервиса поддержки. Если CRM-трекер создает лид, контакт или компанию по обращению, интеграции часто нужно получить идентификатор созданного CRM-объекта.
Не передавайте технические идентификаторы в поле email метода imconnector.send.messages. В CRM это поле используется как адрес электронной почты клиента. Невалидное значение может попасть в контакт или компанию и помешать сценариям, где нужен настоящий email, например отправке чека клиенту.
Как получить идентификатор связанного CRM-объекта
Чтобы найти лид, контакт или компанию, которые CRM-трекер связал с диалогом открытой линии, последовательно выполним методы:
-
imconnector.send.messages — отправим сообщение клиента в открытую линию и получим идентификатор чата
-
imopenlines.dialog.get — получим данные диалога и код пользователя открытой линии
-
crm.item.list — найдем лид, контакт или компанию по точному значению поля мессенджера
Что понадобится
- Приложение с доступом к открытым линиям и CRM
- Код коннектора из параметра
IDметода imconnector.register. В примерах используетсяmyconnector - Идентификатор открытой линии. В примерах используется
107 - Внешний идентификатор чата или канала. В примерах используется
channel-123 - Внешний идентификатор клиента. В примерах используется
ext-user-42
1. Отправим сообщение клиента
Передадим сообщение в открытую линию методом imconnector.send.messages. В блоке user укажем контактные данные клиента.
-
CONNECTOR— код коннектора, который передали в параметреIDметода imconnector.register. Укажемmyconnector -
LINE— идентификатор открытой линии. Укажем107 -
MESSAGES— массив сообщений. Передадим данные клиента, сообщения и внешнего чата
Как использовать примеры в документации
BX24.callMethod(
'imconnector.send.messages',
{
CONNECTOR: 'myconnector',
LINE: 107,
MESSAGES: [
{
user: {
id: 'ext-user-42',
name: 'Иван',
phone: '+79990000000'
},
message: {
id: 'ext-msg-1001',
date: Math.floor(Date.now() / 1000),
text: 'Добрый день'
},
chat: {
id: 'channel-123',
name: 'Канал поддержки',
url: 'https://example.ru/chats/123'
}
}
]
},
function(result)
{
if(result.error())
{
console.error(result.error());
}
else
{
console.dir(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'imconnector.send.messages',
[
'CONNECTOR' => 'myconnector',
'LINE' => 107,
'MESSAGES' => [
[
'user' => [
'id' => 'ext-user-42',
'name' => 'Иван',
'phone' => '+79990000000',
],
'message' => [
'id' => 'ext-msg-1001',
'date' => time(),
'text' => 'Добрый день',
],
'chat' => [
'id' => 'channel-123',
'name' => 'Канал поддержки',
'url' => 'https://example.ru/chats/123',
],
],
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Если сообщение передано успешно, метод вернет данные сессии открытой линии в блоке session.
{
"result": {
"SUCCESS": true,
"DATA": {
"RESULT": [
{
"SUCCESS": true,
"session": {
"ID": "323",
"CHAT_ID": "1767"
}
}
]
}
}
}
Сохраните значения:
-
session.ID— идентификатор сессии открытой линии -
session.CHAT_ID— идентификатор чата в Битрикс24. Он понадобится на следующем шаге
2. Получим данные диалога
Получим данные чата методом imopenlines.dialog.get. В параметр CHAT_ID передадим значение session.CHAT_ID из ответа метода imconnector.send.messages.
BX24.callMethod(
'imopenlines.dialog.get',
{
CHAT_ID: 1767
},
function(result)
{
if(result.error())
{
console.error(result.error());
}
else
{
console.dir(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'imopenlines.dialog.get',
[
'CHAT_ID' => 1767,
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
В ответе важны два поля:
-
entity_id— код пользователя открытой линии. По нему можно сформировать значение поля Мессенджер в CRM -
entity_data_2— строка с привязками CRM, которые уже есть у диалога
{
"result": {
"id": 1767,
"entity_type": "LINES",
"entity_id": "myconnector|107|channel-123|ext-user-42",
"entity_data_2": "LEAD|0|COMPANY|0|CONTACT|42|DEAL|0",
"dialog_id": "chat1767"
}
}
Чтобы получить значение поля Мессенджер в CRM, добавьте к entity_id префикс imol|. В примере это:
imol|myconnector|107|channel-123|ext-user-42
3. Найдем CRM-объект по полю мессенджера
Выполните точный поиск по полю мессенджера методом crm.item.list. Передавайте тип CRM-объекта в параметре entityTypeId:
1— лид3— контакт4— компания
В универсальных методах CRM значение мессенджера IMOL доступно в поле imol. Поле fm с мультиполями нельзя явно запросить через select. Чтобы получить fm в ответе, передайте select: ['*'].
В примере найдем контакт, поэтому передадим entityTypeId = 3.
-
entityTypeId— тип CRM-объекта. Для контакта укажите3 -
filter[=imol]— значение поля Мессенджер: префиксimol|иentity_idиз ответа методаimopenlines.dialog.get -
select— список полей, которые нужно вернуть. Для поиска идентификатора достаточно поляid
BX24.callMethod(
'crm.item.list',
{
entityTypeId: 3,
select: [
'id',
'title',
'imol'
],
filter: {
'=imol': 'imol|myconnector|107|channel-123|ext-user-42'
}
},
function(result)
{
if(result.error())
{
console.error(result.error());
}
else
{
console.dir(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'crm.item.list',
[
'entityTypeId' => 3,
'select' => [
'id',
'title',
'imol',
],
'filter' => [
'=imol' => 'imol|myconnector|107|channel-123|ext-user-42',
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Если контакт найден, метод вернет его данные в массиве items.
{
"result": {
"items": [
{
"id": 42,
"title": "Иван",
"imol": "imol|myconnector|107|channel-123|ext-user-42"
}
]
},
"total": 1
}
Значение items[0].id — идентификатор найденного CRM-объекта. В примере найден контакт с идентификатором 42.
Если контакт не найден, повторите запрос с entityTypeId = 1 для лида и entityTypeId = 4 для компании.
Если CRM-объект не найден
Проверьте значения, которые связывают шаги сценария:
- в ответе
imconnector.send.messagesесть блокsessionсCHAT_ID - в запрос
imopenlines.dialog.getпереданCHAT_IDиз ответаimconnector.send.messages - в ответе
imopenlines.dialog.getесть непустое полеentity_id - в фильтр
crm.item.listпередано значение с префиксомimol|, напримерimol|myconnector|107|channel-123|ext-user-42 - в
entityTypeIdуказан тип CRM-объекта, который мог создать CRM-трекер:1,3или4 - пользователь, от имени которого выполняется
crm.item.list, имеет право на чтение найденного CRM-объекта
Если метод crm.item.list возвращает ошибку INVALID_ARG_VALUE, проверьте поле в фильтре. Для поиска по мессенджеру используйте =imol.
Что важно учитывать
- Не используйте поле
emailдля технических маркеров. Передавайте в него только настоящий адрес электронной почты клиента - Сохраняйте
session.CHAT_IDиsession.IDиз ответа imconnector.send.messages - Используйте
entity_idиз imopenlines.dialog.get с префиксомimol|как точное значение для поиска по мессенджеру - Проверяйте несколько типов CRM-объектов, если настройки CRM-трекера могут создавать лиды, контакты или компании