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

Clear chat history

POST /v1/chats/:dialogId/history/clear

Clear history for the caller with scope: "self" or for all participants with scope: "all". The chat is retained. Bitrix24 authorizes the selected operation as the user whose tokens are used in the request.

Irreversible: clearing history for everyone removes the shared history. Ask the user to confirm the selected scope before making the request.

Parameters

Parameter Type Required Description
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog ID from recent dialogs: chatN, a positive user ID or me. The numeric part is an integer without leading zeros, at most 9007199254740991

Query parameters are not accepted.

Request fields (body)

Field Type Required Description
Fieldscope Typestring Requiredyes Descriptionself clears history for the caller, all for everyone. There is no default

The body must be a JSON object with only the scope field. Additional fields are refused before any Bitrix24 call.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/chat42/history/clear \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"self"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/chat42/history/clear \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope":"self"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/history/clear', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ scope: 'self' }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/history/clear', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ scope: 'self' }),
})
const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the operation is confirmed
Fielddata.result Typeboolean Descriptiontrue confirms the operation

Response example

JSON 
{
  "success": true,
  "data": {
    "result": true
  }
}

Error response example

400 — scope is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Body field `scope` is required."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionThe scope field is missing
HTTP400 CodeINVALID_PARAMS DescriptionMalformed dialogId, invalid scope, wrong body type, extra body field or query parameter
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key access mode forbids changing Bitrix24 data. See access rights
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused access to the selected operation
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned a refusal. The original code, including HISTORY_CLEANUP_CONFLICT, is in error.b24Code
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionNo explicit confirmation was received, or Bitrix24 is unavailable
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionThe user could not be resolved for me

For the full list of common API errors, see Errors.

Known specifics

A 502 response may arrive after the operation has changed data. Vibecode does not automatically repeat the write after a Bitrix24 503 response. Before retrying, check the chat state and obtain a new user confirmation.

See also