## 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 |
|----------|-----|:-----:|----------|
| `messageId` (path) | number | yes | Message ID, a positive integer — the `id` field of a message from the [message history](/docs/chats/messages/list) or [chat loading](/docs/chats/messages/load). 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

```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

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Form data |
| `data.link` | string | Relative link to the task creation form in Bitrix24: to open the form, prepend your Bitrix24 address to it |
| `data.params` | object | Form fields. The set depends on the chat — see the paragraph after the table |
| `data.params.responsibleId` | number | Assignee — the calling user |
| `data.params.imChatId` | number | ID of the message's chat |
| `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.imMessageId` | number | Message ID |
| `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 |
| `data.params.ufTaskWebdavFilesData[].id` | string | Copy ID in the `n<id>` format, as in `ufTaskWebdavFiles` |
| `data.params.ufTaskWebdavFilesData[].objectId` | number | Copy ID on Drive |
| `data.params.ufTaskWebdavFilesData[].name` | string | Copy name |
| `data.params.ufTaskWebdavFilesData[].type` | string | File type |
| `data.params.ufTaskWebdavFilesData[].url` | string | Download link of the copy |
| `data.params.ufTaskWebdavFilesData[].previewUrl` | string | Preview link. An empty string if there is no preview |
| `data.params.ufTaskWebdavFilesData[].height`, `data.params.ufTaskWebdavFilesData[].width` | number | Image height and width in pixels. `0` for files without dimensions |
| `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 | Message ID |
| `data.params.taSec`, `data.params.taEl` | string | Source labels for Bitrix24 analytics |
| `data.params.description` | string | Message 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 |
|------|-----|---------|
| 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 Bitrix24 code is in `error.b24Code` |
| 422 | `BITRIX_ERROR` | Bitrix24 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 |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |

The full list of common API errors — [Errors](/docs/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

- [Task form](/docs/chats/service/task-form)
- [Flow form](/docs/chats/service/flow-form)
- [Messages around a message](/docs/chats/messages/context)
- [Service methods](/docs/chats/service)