For AI agents: markdown of this page — /docs-content-en/chats/service/task-form-message.md documentation index — /llms.txt

Task form for a message

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

Prepares the data for the form that creates a task from a chat message, but does not create the task itself: the user fills in and saves the form in Bitrix24.

Parameters

Parameter Type Required Description
ParametermessageId (path) Typenumber Requiredyes DescriptionMessage ID, a positive integer — the id field of a message from the message history or chat loading. The chat is resolved from the message

The request has 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

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionForm data
Fielddata.link Typestring DescriptionRelative link to the task creation form in Bitrix24: to open the form, prepend your Bitrix24 address to it
Fielddata.params Typeobject DescriptionForm fields. The set depends on the chat — see the paragraph after the table
Fielddata.params.responsibleId Typenumber DescriptionAssignee — the calling user
Fielddata.params.imChatId Typenumber DescriptionID of the message's chat
Fielddata.params.auditors Typestring DescriptionObservers — comma-separated IDs of the chat members except the caller, no more than 50. A group or project chat has no observers
Fielddata.params.groupId Typenumber | null DescriptionGroup or project ID — for a group or project chat
Fielddata.params.imMessageId Typenumber DescriptionMessage ID
Fielddata.params.ufTaskWebdavFiles Typestring[] DescriptionIDs of the file copies on Drive in the n<id> format — present only if the message has files
Fielddata.params.ufTaskWebdavFilesSign Typestring DescriptionBitrix24 signature over the list of copies — the form sends it back when the task is saved
Fielddata.params.ufTaskWebdavFilesData[] Typeobject[] DescriptionFile copies
Fielddata.params.ufTaskWebdavFilesData[].id Typestring DescriptionCopy ID in the n<id> format, as in ufTaskWebdavFiles
Fielddata.params.ufTaskWebdavFilesData[].objectId Typenumber DescriptionCopy ID on Drive
Fielddata.params.ufTaskWebdavFilesData[].name Typestring DescriptionCopy name
Fielddata.params.ufTaskWebdavFilesData[].type Typestring DescriptionFile type
Fielddata.params.ufTaskWebdavFilesData[].url Typestring DescriptionDownload link of the copy
Fielddata.params.ufTaskWebdavFilesData[].previewUrl Typestring DescriptionPreview link. An empty string if there is no preview
Fielddata.params.ufTaskWebdavFilesData[].height, data.params.ufTaskWebdavFilesData[].width Typenumber DescriptionImage height and width in pixels. 0 for files without dimensions
Fielddata.params.isTasksV2 Typeboolean Descriptiontrue — the new version of tasks is enabled in Bitrix24. The response then includes the fields below
Fielddata.params.entityId Typenumber DescriptionChat ID
Fielddata.params.subEntityId Typenumber DescriptionMessage ID
Fielddata.params.taSec, data.params.taEl Typestring DescriptionSource labels for Bitrix24 analytics
Fielddata.params.description Typestring DescriptionMessage quote with BB codes: the chat name, the author, the text

The contents of params depend on the chat and the Bitrix24 settings: Open Channels chats carry a CRM binding, and with the previous version of tasks the isTasksV2 field and the fields below it are absent.

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
HTTP400 CodeINVALID_PARAMS DescriptionmessageId is not a positive integer, or a body field or query parameter was passed
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The Bitrix24 code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The Bitrix24 code is in error.b24Code. TASK_ACCESS_ERROR — no access to the message or its chat, TASKS_NOT_INSTALLED — the tasks module is not installed
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • If the message has files, every call creates new copies of them in the "Uploaded files" folder on the caller's Drive. Copies that do not make it into a task are deleted on a schedule.
  • The operation may make the caller a chat member if the chat allows auto-join (a collab or a comment chat, for example), just as opening the chat in Bitrix24 does.

See also