imbot.v2.Chat.add — метод REST API Битрикс24

Описание

Метод imbot.v2.Chat.add создает новый групповой чат от имени бота. Если владелец не указан — им становится бот.

Параметры

botId integer обязательный

ID бота

botToken string необязательный

Уникальный токен авторизации бота. Обязателен при авторизации через вебхук, не нужен для OAuth.

Передавайте тот же botToken, который был указан при регистрации чат-бота

fields object необязательный

Свойства создаваемого чата. Структура объекта описана ниже

Параметр fields

title string необязательный

Название чата

description string необязательный

Описание чата

color string необязательный

Цвет чата — доступные цвета.

Если не указан или некорректен — назначается автоматически

avatar file необязательный

Аватар чата в формате Base64

userIds integer[] необязательный

Массив ID участников

ownerId integer необязательный

ID владельца чата. Если не указан — владельцем становится бот

message string необязательный

Первое сообщение в чате

Доступные цвета

red необязательный

#df532d

green необязательный

#64a513

mint необязательный

#4ba984

lightBlue необязательный

#4ba5c3

darkBlue необязательный

#3e99ce

purple необязательный

#8474c8

aqua необязательный

#1eb4aa

pink необязательный

#f76187

lime необязательный

#58cc47

brown необязательный

#ab7761

azure необязательный

#29619b

khaki необязательный

#728f7a

sand необязательный

#ba9c7b

marengo необязательный

#556574

gray необязательный

#909090

graphite необязательный

#5e5f5e

Примеры запроса

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"botToken":"my_bot_token","fields":{"title":"Support Chat","color":"mint","userIds":[1,2]}}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Chat.add

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"fields":{"title":"Support Chat","color":"mint","userIds":[1,2]},"auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/imbot.v2.Chat.add

try {
  const response = await $b24.callMethod('imbot.v2.Chat.add', {
    botId: 456,
    fields: {
      title: 'Support Chat',
      color: 'mint',
      userIds: [1, 2],
    },
  });

  const { result } = response.getData();
  console.log('result:', result);
} catch (error) {
  console.error('Error:', error);
}

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.imbot.v2.chat.add(
        bot_id=456,
        fields={
            "title": "Support Chat",
            "color": "mint",
            "userIds": [
                1,
                2,
            ],
        },
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

try {
    $response = $b24Service
        ->core
        ->call(
            'imbot.v2.Chat.add',
            [
                'botId' => 456,
                'fields' => [
                    'title' => 'Support Chat',
                    'color' => 'mint',
                    'userIds' => [1, 2],
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'result: '. print_r($result, true);
} catch (Throwable $exception) {
    error_log($exception->getMessage());
    echo 'Error: '. $exception->getMessage();
}

BX24.callMethod(
    'imbot.v2.Chat.add',
    {
        botId: 456,
        fields: {
            title: 'Support Chat',
            color: 'mint',
            userIds: [1, 2],
        },
    },
    function(result) {
        if (result.error()) {
            console.error(result.error().ex);
        } else {
            console.log('Chat ID:', result.data().chat.id);
        }
    }
);

require_once('crest.php');

$result = CRest::call(
    'imbot.v2.Chat.add',
    [
        'botId' => 456,
        'fields' => [
            'title' => 'Support Chat',
            'color' => 'mint',
            'userIds' => [1, 2],
        ],
    ]
);

if (!empty($result['error'])) {
    echo 'Error: '. $result['error_description'];
} else {
    echo 'Chat ID: '. $result['result']['chat']['id'];
}

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "imbot.v2.Chat.add", b24.Params{
	"botId":    456,
	"botToken": "my_bot_token",
	"fields": b24.Params{
		"title":   "Support Chat",
		"color":   "mint",
		"userIds": []int{1, 2},
	},
})
if err != nil {
	return fmt.Errorf("imbot.v2.Chat.add: %w", err)
}

// Форма ответа показана ниже на этой странице.
fmt.Printf("%s\n", res.Result)

Ответ

HTTP-статус: 200

{
    "result": {
        "chat": {
            "id": 5,
            "dialogId": "chat5",
            "name": "Support Chat",
            "description": "",
            "type": "chat",
            "messageType": "C",
            "owner": 456,
            "color": "#4ba984",
            "avatar": "",
            "extranet": false,
            "containsCollaber": false,
            "entityType": "",
            "entityId": "",
            "entityData1": "",
            "entityData2": "",
            "entityData3": "",
            "entityLink": {},
            "diskFolderId": 42,
            "role": "owner",
            "permissions": {},
            "muteList": [],
            "parentChatId": null,
            "parentMessageId": null,
            "isNew": true,
            "textFieldEnabled": "Y",
            "backgroundId": null,
            "dateCreate": "2025-01-15T10:00:00+03:00",
            "lastMessageId": 789,
            "lastMessageViews": "{}",
            "lastId": null,
            "managerList": [],
            "markedId": null,
            "messageCount": 1,
            "public": "",
            "unreadId": null,
            "userCounter": 3
        },
        "users": [
            {
                "id": 1,
                "active": true,
                "name": "John Smith",
                "firstName": "John",
                "lastName": "Smith",
                "workPosition": "Developer",
                "color": "#ab7761",
                "avatar": "",
                "gender": "M",
                "birthday": "15-03",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T14:25:00+03:00",
                "absent": false,
                "departments": [7],
                "phones": false,
                "type": "employee"
            },
            {
                "id": 2,
                "active": true,
                "name": "Anna Davis",
                "firstName": "Anna",
                "lastName": "Davis",
                "workPosition": "Manager",
                "color": "#5b7e91",
                "avatar": "",
                "gender": "F",
                "birthday": "22-08",
                "extranet": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "default",
                "status": "online",
                "idle": false,
                "lastActivityDate": "2025-01-15T14:20:00+03:00",
                "absent": false,
                "departments": [12],
                "phones": false,
                "type": "employee"
            }
        ]
    },
    "time": {
        "start": 1728626400.123,
        "finish": 1728626400.234,
        "duration": 0.111,
        "processing": 0.045,
        "date_start": "2024-10-11T10:00:00+03:00",
        "date_finish": "2024-10-11T10:00:00+03:00"
    }
}

Обработка ошибок

HTTP-статус: 400

{
    "error": "BOT_NOT_FOUND",
    "error_description": "Bot not found"
}

Код	Описание	Значение
`BOT_TOKEN_NOT_SPECIFIED`	Bot token is not specified	Не указан `botToken`. Обязателен при авторизации через вебхук
`BOT_ID_REQUIRED`	Bot ID is required	Не указан `botId`
`BOT_NOT_FOUND`	Bot not found	Бот не найден
`BOT_OWNERSHIP_ERROR`	Bot is registered by another application	Бот зарегистрирован другим приложением