Skip to content

bot-get.md

Latest commit

 

History

History
301 lines (245 loc) · 8.1 KB

bot-get.md

File metadata and controls

301 lines (245 loc) · 8.1 KB
Raw

Get Information About the Bot imbot.v2.Bot.get

{% note tip "" %}

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.

{% endnote %}

Scope: imbot

Who can execute the method: authorized user

The method imbot.v2.Bot.get returns information about the bot. It is used to verify the bot's installation.

For the owner application, it returns an extended format including moduleId, eventMode, and counters. For other applications, it returns a brief format.

Method Parameters

{% include Note on required parameters %}

#| || Name Type | Description || || botId integer | Bot ID. Required if code is not specified || || code string | Bot code. Required if botId is not specified || || botToken string | Unique bot authorization token. Required for webhook authorization, not needed for OAuth.

Pass the same botToken that was specified during the chatbot registration || |#

{% note info "" %}

You must provide one of the parameters: botId or code.

{% endnote %}

Code Examples

{% include Note on Examples %}

{% list tabs %}

  • cURL (Webhook)

    curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botToken":"my_bot_token","code":"support_bot"}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Bot.get

  • cURL (OAuth)

    curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"code":"support_bot","auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/imbot.v2.Bot.get

  • JS

    try {
  const response = await $b24.callMethod('imbot.v2.Bot.get', {
    code: 'support_bot',
  });

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

  • PHP

    try {
    $response = $b24Service
        ->core
        ->call(
            'imbot.v2.Bot.get',
            [
                'code' => 'support_bot',
            ]
        );

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

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

  • BX24.js

    BX24.callMethod(
    'imbot.v2.Bot.get',
    {
        code: 'support_bot',
    },
    function(result) {
        if (result.error()) {
            console.error(result.error().ex);
        } else {
            console.log(result.data());
        }
    }
);

  • PHP CRest

    require_once('crest.php');

$result = CRest::call(
    'imbot.v2.Bot.get',
    ['code' => 'support_bot']
);

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

  • Go

    // client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "imbot.v2.Bot.get", b24.Params{
	"botToken": "my_bot_token",
	"code":     "support_bot",
}, b24.WithIdempotent())
if err != nil {
	return fmt.Errorf("imbot.v2.Bot.get: %w", err)
}

// The response shape is shown below on this page.
fmt.Printf("%s\n", res.Result)

{% endlist %}

Response Handling

HTTP Status: 200

{
    "result": {
        "bot": {
            "id": 456,
            "code": "support_bot",
            "type": "bot",
            "isHidden": false,
            "isSupportOpenline": false,
            "isReactionsEnabled": true,
            "backgroundId": null,
            "language": "de",
            "moduleId": "rest",
            "eventMode": "fetch",
            "countMessage": 150,
            "countCommand": 3,
            "countChat": 12,
            "countUser": 45
        },
        "users": [
            {
                "id": 456,
                "active": true,
                "name": "Support Bot",
                "bot": true,
                "type": "bot"
            }
        ]
    },
    "time": {
        "start": 1728626400.123,
        "finish": 1728626400.234,
        "duration": 0.111,
        "processing": 0.045,
        "date_start": "2024-10-11T10:00:00+02:00",
        "date_finish": "2024-10-11T10:00:00+02:00"
    }
}

Returned Data

#| || Name Type | Description || || result object | Result of the request || || result.bot Bot | Bot object. Extended format for the owner, brief format for others (detailed description) || || result.users User[] | Array of related users (detailed description) || || time time | Information about the request execution time || |#

Fields of the Bot Object {#bot-object}

#| || Field Type | Description || || id integer | Bot identifier || || code string | Symbolic code of the bot || || type string | Type of the bot || || isHidden boolean | Bot is hidden from the contact list || || isSupportOpenline boolean | Bot supports open channels || || isReactionsEnabled boolean | Reactions are enabled for bot messages || || backgroundId string|null | Chat background ID or null || || language string | Language of the bot || || moduleId string | Module identifier || || eventMode string | Event delivery mode: webhook or fetch || || countMessage integer | Number of messages sent by the bot || || countCommand integer | Number of registered commands || || countChat integer | Number of bot chats || || countUser integer | Number of users interacting with the bot || |#

Fields of the User Object {#user-object}

#| || Field Type | Description || || id integer | User identifier || || active boolean | User is active || || name string | User's first and last name || || bot boolean | Indicates if the user is a bot || || type string | Type of user || |#

Full description of all object fields can be found on the Objects and Fields page.

Error Handling

HTTP Status: 400, 403

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

{% include notitle Error Handling %}

Possible Error Codes

#| || Code | Description | Value || || BOT_TOKEN_NOT_SPECIFIED | Bot token is not specified | botToken is required for webhook authorization || || PARAMS_REQUIRED | Required parameters are missing | Neither botId nor code is provided || || BOT_NOT_FOUND | Bot not found | Bot not found || |#

{% include System Errors %}

Continue Learning