Битрикс24

Пользовательский инструмент нужен для работы с контактами в Битрикс24: агент сможет создавать контакты, обновлять их данные и проверять на дубли.

Для задач и сделок используйте MCP-сервер Битрикс24 — подробнее в разделе MCP-сервер. Один агент может работать с Битрикс24 через пользовательский инструмент, MCP-сервер или оба подключения сразу. Если подключаете оба, задайте им разные имена — так их будет проще различать в настройках агента.

Подключение выполняется в три шага.

Шаг 1. Создайте входящий вебхук в Битрикс24

В Битрикс24 откройте Настройки → Разработчикам → Другое → Входящий вебхук.
Выдайте вебхуку права на CRM (crm).
Сохраните и скопируйте URL вебхука — он понадобится на следующем шаге.

URL вебхука даёт доступ к данным CRM. Не передавайте его третьим лицам.

Шаг 2. Добавьте пользовательский инструмент в EvoAI

Откройте раздел Инструменты → вкладку Пользовательские и нажмите Добавить инструмент.
Заполните Имя — под ним инструмент будет отображаться в настройках агента.
В поле схемы вставьте OpenAPI-схему (пример схемы — ниже) и подставьте в поле servers URL вебхука из шага 1.
Нажмите Сохранить.

После сохранения инструмент появится в списке и станет доступен для добавления агентам.

Шаг 3. Проверьте подключение

Откройте настройки нужного агента и добавьте инструмент Битрикс24.
Попросите агента создать тестовый контакт — например, «Создай контакт Иван Иванов». Агент запросит список полей портала, проверит дубликаты по телефону и почту, уточнит недостающие обязательные поля и создаст контакт, вернув в чат его ID и основные данные. Если по телефону или email уже найден контакт, агент сообщит об этом и предложит обновить существующую запись вместо создания новой.
Убедитесь, что контакт появился в CRM.

Пример спецификации

{
  "openapi": "3.0.0",
  "info": {
    "title": "Bitrix24 CRM Contacts API",
    "version": "1.0.0",
    "description": "API для работы с контактами (сущность Contact, entityTypeId=3) в Bitrix24 CRM"
  },
  "servers": [
    {
      "url": "https://{portal}.bitrix24.ru/rest/{user_id}/{webhook_code}"
    }
  ],
  "paths": {
    "/crm.item.add.json": {
      "post": {
        "summary": "Создать контакт",
        "description": "Создаёт новый контакт в CRM. Внимание: метод НЕ проверяет дубли сам — если нужно избежать повторного контакта с тем же телефоном или email, сначала вызови findContactDuplicates и прими решение по его результату.",
        "operationId": "createContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entityTypeId", "fields"],
                "properties": {
                  "entityTypeId": { "type": "integer", "enum": [3], "description": "3 = Contact. Единственное допустимое значение — этот метод создаёт только контакты." },
                  "fields": {
                    "type": "object",
                    "description": "Поля создаваемого контакта. Полный набор (включая кастомные UF_*-поля вашего портала) — через getContactFields.",
                    "properties": {
                      "NAME": { "type": "string", "description": "Имя контакта" },
                      "LAST_NAME": { "type": "string", "description": "Фамилия" },
                      "SECOND_NAME": { "type": "string", "description": "Отчество" },
                      "COMPANY_TITLE": { "type": "string", "description": "Название компании контакта (текст, не привязка)" },
                      "POST": { "type": "string", "description": "Должность" },
                      "COMMENTS": { "type": "string", "description": "Комментарий" },
                      "OPENED": { "type": "string", "enum": ["Y", "N"], "description": "Доступен для всех (Y) или только для ответственного (N)" },
                      "TYPE_ID": { "type": "string", "description": "Тип контакта, справочник CRM_CONTACT_TYPE (CLIENT/SUPPLIER/PARTNER и т.д.)" },
                      "SOURCE_ID": { "type": "string", "description": "Источник, справочник CRM_SOURCE" },
                      "ASSIGNED_BY_ID": { "type": "integer", "description": "Ответственный, ID пользователя" },
                      "PHONE": {
                        "type": "array",
                        "description": "Телефоны контакта. Каждый элемент — объект {VALUE, VALUE_TYPE}.",
                        "items": {
                          "type": "object",
                          "required": ["VALUE", "VALUE_TYPE"],
                          "properties": {
                            "VALUE": { "type": "string", "description": "Номер телефона" },
                            "VALUE_TYPE": { "type": "string", "enum": ["WORK", "MOBILE", "FAX", "HOME", "OTHER"], "description": "Тип номера" }
                          }
                        }
                      },
                      "EMAIL": {
                        "type": "array",
                        "description": "Email-адреса контакта. Каждый элемент — объект {VALUE, VALUE_TYPE}.",
                        "items": {
                          "type": "object",
                          "required": ["VALUE", "VALUE_TYPE"],
                          "properties": {
                            "VALUE": { "type": "string", "description": "Email" },
                            "VALUE_TYPE": { "type": "string", "enum": ["WORK", "HOME", "OTHER"], "description": "Тип адреса" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Созданный контакт (result.item, включая присвоенный id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BitrixResponse" } } } }
        }
      }
    },
    "/crm.item.update.json": {
      "post": {
        "summary": "Обновить контакт",
        "description": "Обновляет существующий контакт по его id. Передавай только те поля, которые нужно изменить.",
        "operationId": "updateContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entityTypeId", "id", "fields"],
                "properties": {
                  "entityTypeId": { "type": "integer", "enum": [3], "description": "3 = Contact. Единственное допустимое значение." },
                  "id": { "type": "integer", "description": "ID обновляемого контакта" },
                  "fields": {
                    "type": "object",
                    "description": "Поля контакта для изменения. ВАЖНО про PHONE и EMAIL: при обновлении они заменяют весь набор значений целиком, а не дополняют его. Если передать новый массив PHONE без ранее существовавших значений — старые телефоны будут потеряны. Чтобы изменить один номер, не потеряв остальные: сначала получи контакт через getContact, возьми полный текущий список PHONE/EMAIL (вместе с их полем ID у каждого значения) и передай его обратно с внесённой правкой.",
                    "properties": {
                      "NAME": { "type": "string", "description": "Имя контакта" },
                      "LAST_NAME": { "type": "string", "description": "Фамилия" },
                      "SECOND_NAME": { "type": "string", "description": "Отчество" },
                      "COMPANY_TITLE": { "type": "string", "description": "Название компании контакта" },
                      "POST": { "type": "string", "description": "Должность" },
                      "COMMENTS": { "type": "string", "description": "Комментарий" },
                      "OPENED": { "type": "string", "enum": ["Y", "N"] },
                      "TYPE_ID": { "type": "string", "description": "Тип контакта, справочник CRM_CONTACT_TYPE" },
                      "SOURCE_ID": { "type": "string", "description": "Источник, справочник CRM_SOURCE" },
                      "ASSIGNED_BY_ID": { "type": "integer", "description": "Ответственный, ID пользователя" },
                      "PHONE": {
                        "type": "array",
                        "description": "Полный набор телефонов (замена целиком, см. предупреждение выше).",
                        "items": {
                          "type": "object",
                          "required": ["VALUE", "VALUE_TYPE"],
                          "properties": {
                            "VALUE": { "type": "string" },
                            "VALUE_TYPE": { "type": "string", "enum": ["WORK", "MOBILE", "FAX", "HOME", "OTHER"] }
                          }
                        }
                      },
                      "EMAIL": {
                        "type": "array",
                        "description": "Полный набор email (замена целиком, см. предупреждение выше).",
                        "items": {
                          "type": "object",
                          "required": ["VALUE", "VALUE_TYPE"],
                          "properties": {
                            "VALUE": { "type": "string" },
                            "VALUE_TYPE": { "type": "string", "enum": ["WORK", "HOME", "OTHER"] }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Обновлённый контакт (result.item)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BitrixResponse" } } } }
        }
      }
    },
    "/crm.item.get.json": {
      "post": {
        "summary": "Получить контакт по ID",
        "description": "Возвращает один контакт по его id со всеми полями.",
        "operationId": "getContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entityTypeId", "id"],
                "properties": {
                  "entityTypeId": { "type": "integer", "enum": [3], "description": "3 = Contact. Единственное допустимое значение." },
                  "id": { "type": "integer", "description": "ID контакта" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Контакт (result.item)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BitrixResponse" } } } }
        }
      }
    },
    "/crm.item.list.json": {
      "post": {
        "summary": "Список контактов с фильтром",
        "description": "Возвращает список контактов, отфильтрованных и отсортированных по заданным условиям. Постранично, по 50 записей за вызов.",
        "operationId": "listContacts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entityTypeId"],
                "properties": {
                  "entityTypeId": { "type": "integer", "enum": [3], "description": "3 = Contact. Единственное допустимое значение." },
                  "select": { "type": "array", "items": { "type": "string" }, "description": "Поля для выборки, например ['id','name','lastName','phone','email']" },
                  "filter": { "type": "object", "description": "Условия фильтрации, например {'=lastName':'Иванов'}" },
                  "order": { "type": "object", "description": "Сортировка, например {'id':'DESC'}" },
                  "start": { "type": "integer", "description": "Смещение для пагинации (шаг 50)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Список контактов (result.items)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BitrixResponse" } } } }
        }
      }
    },
    "/crm.contact.fields.json": {
      "post": {
        "summary": "Описание полей контакта",
        "description": "Возвращает метаданные полей контакта: обязательность (isRequired), типы, допустимые значения справочников и кастомные UF_*-поля, заведённые на вашем портале. Вызывай перед созданием или обновлением, если не уверен, какие поля обязательны или какие кастомные поля есть. Параметров не требует.",
        "operationId": "getContactFields",
        "responses": {
          "200": {
            "description": "Описание полей контакта",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/crm.duplicate.findbycomm.json": {
      "post": {
        "summary": "Найти контакт-дубликат по телефону или email",
        "description": "Проверяет, есть ли уже контакт с указанным телефоном или email. Вызывай ПЕРЕД созданием нового контакта, чтобы не плодить дубли (сам createContact дубли не блокирует). Возвращает ID найденных контактов.",
        "operationId": "findContactDuplicates",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entity_type", "type", "values"],
                "properties": {
                  "entity_type": { "type": "string", "enum": ["CONTACT"], "description": "Всегда CONTACT — этот метод ищет дубли только среди контактов." },
                  "type": { "type": "string", "enum": ["PHONE", "EMAIL"], "description": "По чему искать: телефон или email" },
                  "values": { "type": "array", "items": { "type": "string" }, "description": "Массив телефонов или email для поиска. Телефон передавай в том виде, в котором он хранится у контакта (обычно только цифры, без +) — Битрикс не всегда нормализует формат сам, при несовпадении формата ответ будет пустым, а не ошибкой." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ID найденных контактов-дублей (пусто, если совпадений нет)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BitrixResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BitrixResponse": {
        "type": "object",
        "properties": {
          "result": {},
          "time": { "type": "object" },
          "error": { "type": "string" },
          "error_description": { "type": "string" }
        }
      }
    }
  }
}

Пользовательские инструменты

MCP-сервер