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
dialogId (path) string yes Dialog ID: chatXXX for a group chat, a numeric user ID for private messages, me — the current user's personal dialog. A CRM entity chat is found via 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
hours number yes The 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
success boolean Always true on success
data.messagesAutoDeleteConfigs array The chat's auto-delete setting, a single item
data.messagesAutoDeleteConfigs[].chatId number Numeric chat ID
data.messagesAutoDeleteConfigs[].delay number The 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
400 INVALID_PARAMS The body has no hours, it is not a JSON number, or it is not one of 0, 1, 24, 168, 720, the body has another field, the body is not a JSON object, or the query string has a parameter. Checked before the Bitrix24 call
403 BITRIX_ACCESS_DENIED Bitrix24 refused: the user is not a chat member or has no permission to change auto-delete
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. If the chat does not exist, the code is CHAT_NOT_FOUND
403 SCOPE_DENIED The API key lacks the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — setting auto-delete counts as a write
401 TOKEN_MISSING The API key has no configured Bitrix24 tokens
502 ME_ALIAS_RESOLUTION_FAILED dialogId=me — the current user's ID could not be resolved
502 BITRIX_UNAVAILABLE Bitrix24 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