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

Send a message to the client

POST /v1/openlines/crm/messages

Sends a message to the Open Channel chat linked to a CRM card. The message reaches the client in their messenger on behalf of the specified employee or bot.

Important: a real client receives the message. Before calling, check that chatId belongs to the right dialog.

Request fields (body)

Field Type Required Description
FieldcrmEntityType Typestring Requiredyes DescriptionCRM card type: lead, deal, company or contact. Case-insensitive
FieldcrmEntityId Typenumber Requiredyes DescriptionCRM card ID. Lists: GET /v1/leads, GET /v1/deals, GET /v1/companies, GET /v1/contacts
FielduserId Typenumber Requiredyes DescriptionID of the employee or bot on whose behalf the message is sent. Employees: GET /v1/users, bots: the data.bots[].id field in the GET /v1/bots response
FieldchatId Typenumber Requiredyes DescriptionID of this card's Open Channel chat — a positive integer without the chat prefix. List: GET /v1/openlines/crm/chats with activeOnly=false
Fieldmessage Typestring Requiredyes DescriptionMessage text. A whitespace-only string is not accepted

Numeric fields also accept a string of digits.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/crm/messages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crmEntityType": "deal",
    "crmEntityId": 42,
    "userId": 7,
    "chatId": 123,
    "message": "Hello! Your order is ready for pickup."
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/crm/messages \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "crmEntityType": "deal",
    "crmEntityId": 42,
    "userId": 7,
    "chatId": 123,
    "message": "Hello! Your order is ready for pickup."
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/crm/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    crmEntityType: 'deal',
    crmEntityId: 42,
    userId: 7,
    chatId: 123,
    message: 'Hello! Your order is ready for pickup.',
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
console.log('Message ID:', data.messageId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/crm/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    crmEntityType: 'deal',
    crmEntityId: 42,
    userId: 7,
    chatId: 123,
    message: 'Hello! Your order is ready for pickup.',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the message is sent
Fielddata.chatId Typenumber DescriptionChat ID from the request
Fielddata.messageId Typenumber DescriptionID of the sent message in the chat

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 123,
    "messageId": 456
  }
}

Error response example

404 — the chat does not belong to the specified CRM card:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "CRM chat not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptioncrmEntityType is missing or outside the list, crmEntityId or userId is missing or not a positive integer, or the request body is not a JSON object
HTTP400 CodeINVALID_JSON_BODY DescriptionThe request body cannot be parsed as JSON
HTTP400 CodeINVALID_CHAT_ID DescriptionchatId is not a positive integer, including the chat123 form
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionchatId is missing, or message is missing, not a string, empty or whitespace-only
HTTP404 CodeENTITY_NOT_FOUND DescriptionMessage CRM chat not found: the CRM card has no chat with that chatId, closed ones included. The check runs before sending; the message is not sent
HTTP404 CodeENTITY_NOT_FOUND DescriptionMessage Record not found: Bitrix24 did not find the chat when sending
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe employee making the call has no access to the CRM card or no permission to send the message
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused to send; its code is returned in error.b24Code
HTTP502 CodeOPENLINE_OPERATOR_FAILED DescriptionBitrix24 did not return a message ID. The message may still have been sent
HTTP502 CodeOPENLINE_OPERATOR_FAILED DescriptionThe card's chat list came back in an unexpected shape. The check runs before sending; the message is not sent
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imopenlines scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_MISSING DescriptionA personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in Authorization
HTTP429 CodeRATE_LIMITED DescriptionThe limit of 120 requests per minute per portal was exceeded. The limit is divided across platform replicas, so the code can arrive before the 120th request. The effective value for the key is in the x-ratelimit-limit header, the remaining quota is in x-ratelimit-remaining
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 rejected the call under its request rate limit for the portal. The response carries a Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or the connection to it dropped before the full response
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond in time. The message may still have been sent

Full list of common API errors — Errors.

Known specifics

  • The chat is checked before sending. Before sending, Vibecode matches chatId against all of the card's chats, closed dialogs included.
  • Retry after a failure. After 502 OPENLINE_OPERATOR_FAILED or 503 BITRIX_TIMEOUT the message may have reached the client. A repeated call sends it again, so check the dialog's messages before retrying.

See also