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

Send an automatic line message

POST /v1/bots/:botId/openlines/session/auto-message

The bot sends either the welcome message from the Open Channel settings or a system message with the given text to the Open Channel conversation. To reply to the customer on behalf of the bot, use a different method: Send message.

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
Fieldtype Typestring Requiredyes DescriptionAutomatic message type: WELCOME is the welcome message from the Open Channel settings, DEFAULT is a system message with the text from message
Fieldmessage Typestring Requiredno DescriptionMessage text. Required with type: "DEFAULT", and in that case an empty string and the string "0" are not accepted

Of chatId, dialogId and CHAT_ID, the first field that is set is used, checked in exactly this order. A field set to null counts as not set. An invalid value in the first set 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/auto-message \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 2043,
    "type": "DEFAULT",
    "message": "Thank you for reaching out! We will reply within 10 minutes."
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/621/openlines/session/auto-message \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 2043,
    "type": "DEFAULT",
    "message": "Thank you for reaching out! We will reply within 10 minutes."
  }'

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/bots/621/openlines/session/auto-message',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatId: 2043,
      type: 'DEFAULT',
      message: 'Thank you for reaching out! We will reply within 10 minutes.',
    }),
  }
)

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

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/bots/621/openlines/session/auto-message',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatId: 2043,
      type: 'DEFAULT',
      message: 'Thank you for reaching out! We will reply within 10 minutes.',
    }),
  }
)

const { success, data, error } = await res.json()
console.log(success ? data.accepted : 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.accepted Typeboolean DescriptionAlways true: Bitrix24 accepted the call. The field does not confirm delivery of the message to the customer

Response example

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

Error response example

400 — type: "DEFAULT" was passed without message text:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "DEFAULT requires a non-empty message other than \"0\""
  }
}

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_PARAMS Descriptiontype is neither WELCOME nor DEFAULT
HTTP400 CodeINVALID_PARAMS DescriptionWith type: "WELCOME", the message field is not 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
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionWith type: "DEFAULT", message is missing, is not a string, or is an empty string or "0"
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 DescriptionThere is no 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 delay given in 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
HTTP429 CodeRATE_LIMITED DescriptionThe shared platform ceiling of 30 requests per minute per portal was exceeded. The ceiling is shared by the four bot actions in an Open Channel 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. 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 delay given in the Retry-After header
HTTP429 CodeQUEUE_OVERFLOW DescriptionThe request queue to the portal is full. Retry after the delay given in 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 delay given in the Retry-After header
HTTP502 CodeOPENLINE_BOT_SESSION_FAILED DescriptionBitrix24 did not confirm the call: 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

accepted: true does not mean the message was sent. A 200 response with accepted: true also arrives when the message was not added to the chat, for example if there is no chat with this chatId.

See also