For AI agents: markdown of this page — /docs-content-en/bots/openlines/finish.md documentation index — /llms.txt

Finish a session

POST /v1/bots/:botId/openlines/session/finish

Finishes the current Open Channel session on behalf of the bot that runs the conversation. Call it when the bot has resolved the customer's question itself and the conversation does not need to go to an operator.

Parameters

Parameter Type Required Default Description
ParameterbotId (path) Typeinteger Requiredyes Default— DescriptionID of a bot registered with this key. List: GET /v1/bots

Request fields (body)

Field Type Required Description
FieldchatId Typeinteger | string Requiredyes DescriptionOpen Channel chat ID: a positive integer, a string of digits or the chat<N> form. Source: the data.chat.id field of a bot event or sessions[].chatId in POST /v1/openlines/sessions/search. Instead of chatId, you can pass dialogId or CHAT_ID
FielddialogId Typestring Requiredno DescriptionThe same chat, only in the chat<N> form, for example chat2043. A number without the prefix is not accepted here
FieldCHAT_ID Typeinteger | string Requiredno DescriptionAlternative name for chatId with the same formats

The first of chatId, dialogId and CHAT_ID that is set is read, checked in exactly this order. A field set to null counts as not set. An invalid value in the first filled field returns 400 INVALID_CHAT_ID, and the remaining fields are not checked in that case.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bots/621/openlines/session/finish" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bots/621/openlines/session/finish" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/621/openlines/session/finish', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})

const { success, data, error } = await res.json()
console.log(success ? data.finished : error.code)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/621/openlines/session/finish', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})

const { success, data, error } = await res.json()
console.log(success ? data.finished : error.code)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when Bitrix24 confirmed the call
Fielddata.chatId Typeinteger DescriptionID of the chat the action was applied to. Returned as a number even if the request passed the chat<N> form
Fielddata.finished Typeboolean DescriptionAlways true in a successful response

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 2043,
    "finished": true
  }
}

Error response example

404 — no bot with this botId on the Bitrix24 account:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999999 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId in the path is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object, for example an array or a string
HTTP400 CodeINVALID_CHAT_ID DescriptionNone of the chatId, dialogId, CHAT_ID fields was passed, the value is invalid, or dialogId was passed without the chat prefix. A body that cannot be parsed as JSON is treated as empty and also gets this code. message says where to get the chat ID
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens. For an application key, the user session token was not passed
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imbot or imopenlines scope — both are required
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot was registered by another key. To regain control, see Restoring access to a bot
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the chat
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot with this botId on the portal — register it via POST /v1/bots
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 reported that the record was not found
HTTP409 CodeBOT_ID_REPLACED DescriptionThe bot was registered again after the portal address changed. The new ID is in error.details.botId
HTTP409 CodeBOT_RECOVERY_IN_PROGRESS DescriptionThe bot is being restored automatically after the portal address changed. Retry after the pause from the Retry-After header
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled. To bring the bot back, see Bot disabled
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the call. The Bitrix24 code is in error.b24Code, for example BOT_ID_ERROR
HTTP429 CodeRATE_LIMITED DescriptionThe shared platform ceiling of 30 requests per minute per portal was exceeded. The ceiling is shared by the four Open Channel bot actions and the POST /v1/openlines/operator/answer and POST /v1/openlines/operator/finish calls, and is split between platform replicas, so the code can arrive before the 30th request. The effective value is in the x-ratelimit-limit header, and the time until a retry is in error.message. A request rejected with 400 because of an error in the body also counts against the limit
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 throttled requests to the portal. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_OVERFLOW DescriptionThe request queue to the portal is full. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_TIMEOUT DescriptionThe request did not get its turn in the portal queue and was not sent to Bitrix24. Retry after the pause from the Retry-After header
HTTP502 CodeOPENLINE_BOT_SESSION_FAILED DescriptionBitrix24 did not confirm the finish: the call result is not true
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable
HTTP503 CodeBITRIX_TIMEOUT DescriptionThe Bitrix24 portal did not respond in time
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner's account on the portal is pending deletion

Full list of common API errors: Errors.

Known specifics

finished: true does not prove that a session existed. A 200 response with finished: true also arrives when there is nothing to finish, for example for a nonexistent chatId. To make sure the session is closed, check the status and dateClose fields of the session in POST /v1/openlines/sessions/search.

See also