For AI agents: markdown of this page — /docs-content-en/chats/management/auto-delete.md documentation index — /llms.txt

Configure message auto-delete

PUT /v1/chats/:dialogId/auto-delete

Turns on auto-delete of chat messages with the chosen delay, or turns it off. The delay is set in hours from a fixed set.

Parameters

Parameter Type Required Description
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog ID: chatXXX for a group chat, a numeric user ID for private messages, me — the current user's personal dialog. To find a CRM entity chat, use Find a CRM entity chat

The endpoint takes no query parameters: any parameter in the query string is refused with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
Fieldhours Typenumber Requiredyes DescriptionThe delay in hours, as a JSON number: 1 — an hour, 24 — a day, 168 — a week, 720 — 30 days. 0 turns auto-delete off. Other values and the string "24" are refused

Other body fields are refused with 400 INVALID_PARAMS, and the message names the extra field.

Examples

curl — personal key

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/auto-delete \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hours": 168}'

curl — OAuth application

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/auto-delete \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hours": 168}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2741/auto-delete', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ hours: 168 }),
})

const { data } = await res.json()
console.log('Delay:', data.messagesAutoDeleteConfigs[0].delay)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2741/auto-delete', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ hours: 168 }),
})

const { data } = await res.json()
console.log('Delay:', data.messagesAutoDeleteConfigs[0].delay)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.messagesAutoDeleteConfigs Typearray DescriptionThe chat's auto-delete setting, a single item
Fielddata.messagesAutoDeleteConfigs[].chatId Typenumber DescriptionNumeric chat ID
Fielddata.messagesAutoDeleteConfigs[].delay Typenumber DescriptionThe delay in hours that Bitrix24 saved. 0 — auto-delete is off

Response example

JSON 
{
  "success": true,
  "data": {
    "messagesAutoDeleteConfigs": [
      {
        "delay": 168,
        "chatId": 264427
      }
    ]
  }
}

Error response example

400 — the delay is not in the allowed set:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `hours` must be one of 0, 1, 24, 168, 720 (a JSON number; 0 switches auto-delete off)."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionhours is missing from the body, is not a JSON number, or is not one of 0, 1, 24, 168, 720. Also returned when the body has another field, the body is not a JSON object, or the query string has a parameter. Checked before the Bitrix24 call
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused: the user is not a chat member or has no permission to change auto-delete
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code. If the chat does not exist, the code is CHAT_NOT_FOUND
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — setting auto-delete counts as a write
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptiondialogId=me — the current user's ID could not be resolved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

Check the delay in the response. The delay field in the response is the value Bitrix24 saved, not an echo of the request. If it differs from hours in the request, auto-delete is not set the way you asked.

A system message about turning auto-delete on. Turning auto-delete on posts a system message to the chat naming the user on whose behalf the call is made.

See also