# 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 ```bash curl "https://vibecode.bitrix24.com/v1/chats/chat42/task-form" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash 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 ```bash curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1002/task-form" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash 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` 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": "", "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](/docs/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. ## See also - [Flow form](/docs/chats/service/flow-form) - [Messages around a message](/docs/chats/messages/context) - [Service methods](/docs/chats/service)