## Task form

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

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

## 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. `chat123` is the `id` field of a [recent dialogs](/docs/chats/discovery/recent) row, a user ID comes from the [user list](/docs/entities/users/list) |

There are no query parameters. `messageId` in the query is rejected with `400` — the form for a message is described on the [Task form for a message](/docs/chats/service/task-form-message) page.

## 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 |
|------|-----|---------|
| `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. Their set depends on the chat — see the paragraph after the table |
| `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` | null | Message ID. Always `null` in the form for a chat |
| `data.params.taSec`, `data.params.taEl` | string | Source labels for Bitrix24 analytics |
| `data.params.description` | null | Task description. Always `null` in the form for a chat |

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",
      "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 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 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 |

The full list of common API errors — [Errors](/docs/errors).

## See also

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