Per gli agenti AI: markdown di questa pagina — /docs-content-en/chats/service.md indice della documentazione — /llms.txt

Gli articoli della documentazione sono attualmente disponibili solo in inglese.

Service methods

Messenger methods that do not belong to a single section: the forms for creating a task or a flow from a chat, context for chat bots, a Zoom meeting, the update state and counters, plan restrictions, promo hints, the user's department and the desktop app logout.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Task form

Data for the form that creates a task from a chat or from a message: a link to the form and its fields — the assignee, observers, the chat, the group, and for a message also a quote and files. The task itself is not created: the user fills in and saves the form in Bitrix24.

The form for a message with files copies the files to the caller's Drive — every call creates new copies.

Form for a chat

GET /v1/chats/:dialogId/task-form

The v2 messenger method im.v2.Chat.Task.prepare with a chat.

Parameters

Parameter	Type	Required	Description
`dialogId` (path)	string	yes	Dialog ID: `chat123` for a group chat, a user ID for a private chat, `me` for the chat with yourself

There are no query parameters. messageId in the query is rejected with 400 — the form for a message is a separate operation below.

Examples

curl — personal key

Terminal

curl "https://vibecode.bitrix24.com/v1/chats/chat42/task-form" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl "https://vibecode.bitrix24.com/v1/chats/chat42/task-form" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/task-form', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Form:', data.link, 'assignee:', data.params.responsibleId)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/task-form', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Form:', data.link)

Response fields

Field	Type	Description
`data.link`	string	Relative link to the task creation form in Bitrix24
`data.params.responsibleId`	number	Assignee — the calling user
`data.params.imChatId`	number	Chat ID
`data.params.auditors`	string	Observers — comma-separated IDs of the chat members except the caller, no more than 50. A group or project chat has no observers
`data.params.groupId`	number \| null	Group or project ID — for a group or project chat
`data.params.isTasksV2`	boolean	`true` — the new version of tasks is enabled in Bitrix24; the response then includes the fields below
`data.params.entityId`	number	Chat ID
`data.params.subEntityId`	number \| null	Message ID — in the form for a message
`data.params.taSec`, `data.params.taEl`	string	Source labels for Bitrix24 analytics
`data.params.description`	string \| null	Task description — in the form for a message, this is the message quote

Bitrix24 defines the contents of params: Open Channels chats carry a CRM binding, and with the previous version of tasks the isTasksV2 field and the fields below it are absent. Field names are converted to camelCase.

Response example

JSON

{
  "success": true,
  "data": {
    "link": "/company/personal/user/1/tasks/task/edit/0/?ta_sec=chat&ta_el=chat_context_menu",
    "params": {
      "responsibleId": 1,
      "imChatId": 42,
      "auditors": "4",
      "isTasksV2": true,
      "entityId": 42,
      "subEntityId": null,
      "taSec": "chat",
      "taEl": "chat_context_menu",
      "description": null,
      "groupId": null
    }
  }
}

Error response example

400 — messageId was passed:

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `messageId` is not accepted by GET /v1/chats/:dialogId/task-form: the task form of a message is POST /v1/chats/messages/:messageId/task-form."
  }
}

Errors

HTTP	Code	Description
400	`INVALID_PARAMS`	A query parameter was passed — the operation accepts none
401	`TOKEN_MISSING`	The API key has no Bitrix24 tokens configured
403	`SCOPE_DENIED`	The API key does not have the `im` scope
403	`WRITE_BLOCKED_READONLY_KEY`	The key is read-only: the call may make the key owner a chat member
404	`ENTITY_NOT_FOUND`	Bitrix24 returned "not found"; the portal code is in `error.b24Code`
422	`BITRIX_ERROR`	Bitrix24 returned an error; the portal code is in `error.b24Code`. `TASK_ACCESS_ERROR` — no access to the chat, `TASKS_NOT_INSTALLED` — the tasks module is not installed
502	`ME_ALIAS_RESOLUTION_FAILED`	Failed to resolve the current user for `me`
502	`BITRIX_UNAVAILABLE`	Bitrix24 is unavailable or returned a server error

Form for a message

POST /v1/chats/messages/:messageId/task-form

The im.v2.Chat.Task.prepare method with a message. Bitrix24 resolves the chat from the message. The chat form fields are extended with the message quote, its ID and, if the message has files, copies of those files.

Parameters

Parameter	Type	Required	Description
`messageId` (path)	number	yes	Message ID

The operation accepts no body and no query parameters: any body field or query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1002/task-form" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1002/task-form" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1002/task-form', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Quote:', data.params.description)
console.log('Files:', data.params.ufTaskWebdavFilesData?.map((f) => f.name))

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1002/task-form', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Form:', data.link)

Response fields

The chat form fields (see above), plus:

Field	Type	Description
`data.params.imMessageId`	number	Message ID
`data.params.subEntityId`	number	Message ID
`data.params.description`	string	Message quote with BB codes: the chat name, the author, the text
`data.params.ufTaskWebdavFiles`	string[]	IDs of the file copies on Drive in the `n<id>` format — present only if the message has files
`data.params.ufTaskWebdavFilesSign`	string	Bitrix24 signature over the list of copies — the form sends it back when the task is saved
`data.params.ufTaskWebdavFilesData[]`	object[]	File copies: `id`, `objectId`, `name`, `type`, `url` (download link), `height`, `width`, `previewUrl`

Response example

JSON

{
  "success": true,
  "data": {
    "link": "/company/personal/user/1/tasks/task/edit/0/?ta_sec=chat&ta_el=chat_context_menu",
    "params": {
      "responsibleId": 1,
      "imChatId": 42,
      "auditors": "4",
      "imMessageId": 1002,
      "subEntityId": 1002,
      "isTasksV2": true,
      "entityId": 42,
      "taSec": "chat",
      "taEl": "chat_context_menu",
      "groupId": null,
      "description": "[QUOTE][B]Chat:[/B] [URL=/online/?IM_DIALOG=chat42&IM_MESSAGE=1002]Project[/URL]\n[B]Maria Smith[/B]\nThe report is attached[File: report.txt]\n[/QUOTE]",
      "ufTaskWebdavFiles": ["n6773"],
      "ufTaskWebdavFilesSign": "<signature>",
      "ufTaskWebdavFilesData": [
        {
          "id": "n6773",
          "objectId": 6773,
          "name": "report (1).txt",
          "type": "txt",
          "url": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=6773&exact=N&fileName=report%20%281%29.txt",
          "height": 0,
          "width": 0,
          "previewUrl": ""
        }
      ]
    }
  }
}

Error response example

400 — messageId is not a positive integer:

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "messageId must be a positive integer."
  }
}

Errors

HTTP	Code	Description
400	`INVALID_PARAMS`	`messageId` is not a positive integer, or a body field or query parameter was passed
401	`TOKEN_MISSING`	The API key has no Bitrix24 tokens configured
403	`SCOPE_DENIED`	The API key does not have the `im` scope
403	`WRITE_BLOCKED_READONLY_KEY`	The key is read-only
404	`ENTITY_NOT_FOUND`	Bitrix24 returned "not found"; the portal code is in `error.b24Code`
422	`BITRIX_ERROR`	Bitrix24 returned an error; the portal code is in `error.b24Code`. `TASK_ACCESS_ERROR` — no access to the message or its chat
502	`BITRIX_UNAVAILABLE`	Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

The form for a message with files copies the files to the "Uploaded files" folder on the caller's Drive, making new copies on every call. Bitrix24 automatically deletes copies that never make it into a task, on a schedule.
Both operations may make the caller a chat member if the chat allows auto-join (a collab or a comment chat, for example), as opening the chat in Bitrix24 does. That is why a read-only key cannot get the form for a chat, even though it is a GET.
The link is relative: to open the form, prepend your Bitrix24 address to it.

Service methods

Task form

Form for a chat

Parameters

Examples

curl — personal key

curl — OAuth application

JavaScript — personal key

JavaScript — OAuth application

Response fields

Response example

Error response example

Errors

Form for a message

Parameters

Examples

curl — personal key

curl — OAuth application

JavaScript — personal key

JavaScript — OAuth application

Response fields

Response example

Error response example

Errors

Known specifics

See also