Для AI-агентов: markdown этой страницы — /docs-content/entities/activities.md индекс документации — /llms.txt

Дела

Управление делами CRM: звонки, встречи, задачи, email. Привязываются к сделкам, лидам, контактам и другим сущностям.

Bitrix24 API: crm.activity.* Скоуп: crm

Одно дело можно показать в таймлайне сразу нескольких CRM-сущностей — см. Привязки дел.

Дело с собственным оформлением в таймлайне — иконка, заголовок, блоки, кнопки — создаётся через Конфигурируемые дела.

AI-расшифровку звонка клиента — дела типа «Звонок» — возвращает Расшифровки звонков CRM.

To-do создаются через to-do дела CRM, а читаются и перечисляются здесь с фильтром providerId=CRM_TODO.

Дела также можно читать и создавать прямо у сделки, лида, контакта или компании. Основным входом для фильтров и сортировки остаётся /v1/activities.

Создать дело

POST /v1/activities

Создаёт новое CRM-дело: звонок, встречу, задачу или email. Дело привязывается к CRM-сущности через ownerTypeId + ownerId.

Поля запроса (body)

Минимальный набор для создания дела — subject, typeId, communications плюс привязка к CRM-сущности. Привязку задаёт либо пара ownerTypeId + ownerId, либо поля entityTypeId + entityId внутри элемента communications. Если не задано ни одно из двух, Bitrix24 не может привязать коммуникацию и возвращает ошибку про communications.

Параметр Тип Обяз. Описание
subject string да Тема дела
typeId number да Тип: 1 — встреча, 2 — звонок, 3 — задача, 4 — письмо, 5 — действие, 6 — пользовательское действие
communications object[] да Коммуникации дела. Массив объектов: [{ "value": "+7…", "entityTypeId": 3, "entityId": 17 }]. Вложенные ключи принимаются в camelCase (type, value, entityTypeId, entityId) — как и во всём остальном API — либо в ВЕРХНЕМ регистре Bitrix24 (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). value — телефон/e-mail; entityTypeId + entityId — CRM-сущность, которой принадлежит коммуникация (задаёт привязку, если не переданы ownerTypeId/ownerId). Когда владелец указан, достаточно [{ "value": "+7…" }]
ownerTypeId number да¹ Тип родительской сущности: 1 — лид, 2 — сделка, 3 — контакт, 4 — компания
ownerId number да¹ ID родительской сущности. Поиск: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies
responsibleId number Ответственный. По умолчанию — текущий пользователь. Список: GET /v1/users
description string Описание. У письма — текст письма
descriptionType number Формат description: 1 — обычный текст, 2 — BB-код, 3 — HTML
priority number Приоритет: 1 — низкий, 2 — средний, 3 — высокий
direction number Направление: 1 — входящее, 2 — исходящее
completed boolean Завершено. У письма с direction: 2 значение true отправляет письмо при создании дела, false создаёт дело без отправки
settings object Настройки дела, структура зависит от typeId. Для отправки письма — MESSAGE_FROM: адрес отправителя, строка sales@example.com или Отдел продаж <sales@example.com>. Допустимые адреса — GET /v1/mail/mailboxes/:id/senders. DISABLE_SENDING_MESSAGE_COPY: "Y" отключает копию письма на адрес отправителя. Ключи внутри settings передаются в ВЕРХНЕМ регистре
startTime datetime Дата начала
endTime datetime Дата окончания
deadline datetime Крайний срок. На создании Bitrix24 игнорирует переданное значение и вычисляет deadline из startTime/endTime — отдельно задать его при POST нельзя

¹ Пара ownerTypeId + ownerId нужна вместе и только если привязка не задана через entityTypeId/entityId внутри communications. Если привязка идёт через коммуникацию — оба поля можно опустить.

ℹ️ Вложенные ключи communications принимаются в двух формах: camelCase (type, value, entityTypeId, entityId) — единообразно с остальным API — и в ВЕРХНЕМ регистре Bitrix24 (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). Если в одном объекте заданы обе формы одного ключа, приоритет у ВЕРХНЕГО регистра.

Полный список полей: GET /v1/activities/fields.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+7 999 123-45-67", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+7 999 123-45-67", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Звонок клиенту',
    description: 'Обсудить условия поставки',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+7 999 123-45-67', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+03:00',
    endTime: '2026-04-16T10:15:00+03:00',
  }),
})

const { success, data } = await res.json()
console.log('Activity ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Звонок клиенту',
    description: 'Обсудить условия поставки',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+7 999 123-45-67', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+03:00',
    endTime: '2026-04-16T10:15:00+03:00',
  }),
})

const { success, data } = await res.json()

curl — отправка письма из сделки

Письмо контакту 17 уходит при создании дела. Дело привязывается к сделке 575 и к контакту из communications.

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 4,
    "direction": 2,
    "completed": true,
    "ownerTypeId": 2,
    "ownerId": 575,
    "subject": "Коммерческое предложение",
    "description": "<p>Добрый день! Направляем предложение по поставке.</p>",
    "descriptionType": 3,
    "communications": [
      { "type": "EMAIL", "value": "client@example.com", "entityTypeId": 3, "entityId": 17 }
    ],
    "settings": {
      "MESSAGE_FROM": "Отдел продаж <sales@example.com>",
      "DISABLE_SENDING_MESSAGE_COPY": "Y"
    }
  }'

Привязки созданного дела — GET /v1/activities/:id/bindings.

Поля ответа

Поле Тип Описание
id number ID созданного дела
typeId number Тип дела
ownerTypeId number Тип родительской сущности
ownerId number ID родительской сущности
subject string Тема
responsibleId number Ответственный
settings object Настройки дела. У отправленного письма — MESSAGE_FROM, IS_MESSAGE_SENT: true и MESSAGE_HEADERS с заголовком Message-Id. Если IS_MESSAGE_SENT нет, письмо не отправлялось
createdAt datetime Дата создания
updatedAt datetime Дата изменения

Ответ содержит все поля дела.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 3894,
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "completed": false,
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00",
    "deadline": "2026-04-16T10:00:00+03:00",
    "createdAt": "2026-04-15T14:30:00+03:00",
    "updatedAt": "2026-04-15T14:30:00+03:00"
  }
}

Пример ответа при ошибке

400 — не передано обязательное поле (subject, typeId или communications):

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"communications\" is required to create activity."
  }
}

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Не передано одно из обязательных полей: subject, typeId, communications (проверяется до вызова Bitrix24)
400 INVALID_REQUEST Некорректные значения полей
404 ENTITY_NOT_FOUND Письмо — typeId: 4, completed: true — без settings.MESSAGE_FROM, сообщение Email send error. "From" is not found. Дело при этом создаётся, см. «Известные особенности»
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Подпись в тексте письма. К description письма добавляется строка <br/><br/>Отправлено из «Битрикс24». Её видит получатель, она же возвращается в description ответа.

Повторный запрос отправляет письмо ещё раз. Каждый вызов с тем же телом создаёт новое дело и отправляет новое письмо, одинаковый originId этого не предотвращает. После ответа 201 запрос не повторяйте.

При ошибке отправки дело остаётся в карточке. Ответ 404 ENTITY_NOT_FOUND на письмо без MESSAGE_FROM приходит, когда дело уже создано: письмо не отправлено, а дело есть. Перед повторным запросом найдите его в списке дел по ownerTypeId и ownerId и удалите.

Отправитель без подключённого почтового ящика. Если адрес из MESSAGE_FROM не принадлежит ни одному ящику из списка почтовых ящиков, письмо уходит с адреса no-reply-crm@<portal>. Получатель видит имя из MESSAGE_FROM и этот адрес. <portal> — домен портала.

Адрес отправителя не сверяется со списком. Значение MESSAGE_FROM вне списка адресов отправителя тоже даёт 201 и IS_MESSAGE_SENT: true. Берите адрес из этого списка.

Служебный идентификатор — только в заголовке. Тема и текст письма уходят без служебных меток. Идентификатор дела передаётся в заголовке Message-Id, его значение — в settings.MESSAGE_HEADERS ответа.

Смотрите также