Message Formatting
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
BB codes let you format message text: highlight fragments, add links and line breaks, insert icons, images, and dates.
When to Use Formatting
Markup is needed when a message should read as formatted text rather than a single line: to highlight the main point, split it into lines, link to an employee or a chat, or show code without distortion.
For other tasks, the section has its own mechanisms:
- add buttons under the message — keyboards
- attach structured blocks, images, or tables — attachments
- add items to the message context menu — menu
Before You Start
- the
imscope - permission to send messages to the chat the message is addressed to
- a message no longer than 20,000 characters
Bitrix24 always retains the first 20,000 characters, and may truncate longer text at this boundary, appending (...) at the end. The method does not return an error in this case, so check the length on your side.
The markup is passed in the MESSAGE field of the im.message.add and im.message.update methods. The codes are case-insensitive: [b] and [B] work the same way.
Bitrix24 retains the message together with the codes and parses them when the message is displayed in the messenger. When you retrieve the message with im.dialog.messages.get, it returns the same text with the codes, not rendered markup.
Supported Codes
Below are the main codes for messages sent by the im.message.* methods. Chatbots support a wider set — see Text Formatting (BB Codes) for the full reference. Processing details of individual codes are in Important Considerations.
Text Formatting
|
Code |
What It Does |
Example |
|
|
Bold text |
|
|
|
Italic |
|
|
|
Underline |
|
|
|
Strikethrough |
|
|
|
Font size from 8 to 30 pixels. Bitrix24 raises smaller values to 8 and lowers larger ones to 30. The |
|
|
|
Text color, |
|
|
|
Text with no code parsing inside |
|
Line Breaks
|
What to Pass |
What It Does |
Example |
|
|
Line break |
|
|
The |
Line break |
|
Links and Mentions
|
Code |
What It Does |
Example |
|
|
Link whose text matches the address |
|
|
|
Link with custom text |
|
|
|
Mention of an employee |
|
|
|
Mention of all chat participants |
|
|
|
Link to a chat |
|
|
|
Link to a message in a dialog |
|
Actions
|
Code |
What It Does |
Example |
|
|
Link that sends text to the chat |
|
|
|
Same, but the link text is sent to the chat |
|
|
|
Link that inserts text into the input field |
|
|
|
Same, but the link text is inserted into the input field |
|
|
|
Link that starts a call |
|
|
|
Same, but the number is taken from the link text |
|
Inserts
|
Code |
What It Does |
Example |
|
|
Icon from an image URL. Also accepts |
|
|
|
Image. The size is |
|
|
|
Date and time from a Unix timestamp in the reader's time zone. The allowed formats are listed below |
|
Date and Time Formats
The FORMAT value must match one of the listed ones. If the format is not recognized, Bitrix24 displays the code itself as plain text.
|
Format |
What It Shows |
|
|
Date |
|
|
Date and time with seconds |
|
|
Numeric date |
|
|
Date with an abbreviated month name |
|
|
Date with a full month name |
|
|
Day and full month name, without the year |
|
|
Day and abbreviated month name, without the year |
|
|
Abbreviated day of the week, day, and full month name |
|
|
Abbreviated day of the week, day, and abbreviated month name |
|
|
Full day of the week, day, and month name |
|
|
Day of the week, date, and year |
|
|
Hours and minutes |
|
|
Hours, minutes, and seconds |
What the result looks like depends on the language and settings of Bitrix24. The same SHORT_TIME_FORMAT code gives 00:26 in one case and 3:26 am in another. The time is converted to the reader's time zone, so different chat participants see different values.
Important Considerations
Three cases where the behavior differs from what you might expect.
[BR]is not retained as a code. On saving, Bitrix24 replaces[BR]and[br]with the\ncharacter, so retrieving the message returns a line break rather than a tag. Mixed-case spelling remains in the text but is also displayed as a line break in the chat[IMG]works only with a direct link to an image. If the address points to a page or a file of another type, the code remains plain text in the message[DISK=id]is not markup but an attachment marker. Bitrix24 tries to attach the Drive file with this ID to the message and removes the code itself from the text
Example of Sending a Formatted Message
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat2725","MESSAGE":"[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]"}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.message.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat2725","MESSAGE":"[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/im.message.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
try {
const response = await $b24.actions.v2.call.make<number>({
method: 'im.message.add',
params: {
DIALOG_ID: 'chat2725',
MESSAGE: '[B]Important[/B][BR]Open [URL=https://bitrix24.com]site[/URL][BR][SEND=/help]Help[/SEND]',
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Created message ID:', result)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function addMessage() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'im.message.add',
params: {
DIALOG_ID: 'chat2725',
MESSAGE: '[B]Important[/B][BR]Open [URL=https://bitrix24.com]site[/URL][BR][SEND=/help]Help[/SEND]',
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Created message ID:', result)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addMessage)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.im.message.add(
dialog_id="chat2725",
message="[B]Important[/B][BR]Open the [URL=https://bitrix24.com]website[/URL][BR][SEND=/help]Help[/SEND]",
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
try {
$response = $b24Service
->core
->call(
'im.message.add',
[
'DIALOG_ID' => 'chat2725',
'MESSAGE' => '[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]',
]
);
$result = $response
->getResponseData()
->getResult();
echo 'Created message ID: ' . $result;
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error: ' . $e->getMessage();
}
BX24.callMethod(
'im.message.add',
{
DIALOG_ID: 'chat2725',
MESSAGE: '[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]',
},
function(result) {
if (result.error()) {
console.error(result.error().ex);
} else {
console.log(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'im.message.add',
[
'DIALOG_ID' => 'chat2725',
'MESSAGE' => '[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]',
]
);
print_r($result);
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "im.message.add", b24.Params{
"DIALOG_ID": "chat2725",
"MESSAGE": "[B]Important[/B][BR]Visit [URL=https://bitrix24.com]the website[/URL][BR][SEND=/help]Help[/SEND]",
})
if err != nil {
return fmt.Errorf("im.message.add: %w", err)
}
// The response comes as json.RawMessage — the method returns
// the ID of the created message.
fmt.Printf("%s\n", res.Result)
The current documentation on formatting can be found in the Chat Bots 2.0 section: