Bitrix24 Bot Platform

• im.chat.add - create chat.
• im.chat.user.list - retrieve list of chat participants.
• im.chat.user.add - invite chat participants.
• im.chat.user.delete - delete chat participants.
• im.chat.leave - exit chat.
• im.chat.sendTyping - send «Is typing a message...» status.
• im.chat.updateTitle - chat title update.
• im.chat.updateColor - chat color update.
• im.chat.updateAvatar - chat icon update.
• im.chat.setOwner - change chat owner.
• im.chat.get - get chat ID.
• im.chat.mute - disable notifications in chat.

Create chat

REST method: im.chat.add

Method call:

$result = restCommand('im.chat.add', Array(

   'TYPE' => 'CHAT' // OPEN - opened to join chat, CHAT - usual chat with invitations, CHAT by default 
   'TITLE' => 'My new private chat', // Chat title
   'DESCRIPTION' => 'Very important chat', // Chat description
   'COLOR' => 'PINK', // Chat color for mobile application - RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
   'MESSAGE' => 'Welcome to the chat', // First greeting message in the chat
   'USERS' => Array(1,2), // Chat participants (req.)
   'AVATAR' => '/* base64 image */', // Chat icon in base64 format
   'ENTITY_TYPE' => 'CHAT', // Arbitrary entity ID (for example CHAT, CRM, OPENLINES, CALL and etc.), can be used for chat search and easy context definition in the following event handlers: ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE
   'ENTITY_ID' => 13, // Entity numerical ID; it can be used for chat search and for easy context definition in the following event handlers: ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE
   'OWNER_ID' => 39, // Chat owner ID. May not be specified, if your are creating chat under the necessary user.

), $_REQUEST["auth"]);

Required fields: USERS (chat participants).

Returns: CHAT_ID chat numerical ID or an error.

Possible errors:

Error code Error description USERS_EMPTY No chat participants. WRONG_REQUEST Something went wrong.

Retrieve list of participants

REST method: im.chat.user.list

Method call:

$result = restCommand('im.chat.user.list', Array(

   'CHAT_ID' => 13 // Chat ID

), $_REQUEST["auth"]);

Return: array of participants IDs or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID.

Invite participants

REST method: im.chat.user.add

Method call:

$result = restCommand('im.chat.user.add', Array(

   'CHAT_ID' => 13 // Chat ID
   'USERS' => Array(3,4) // New user IDs

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. WRONG_REQUEST You have insufficient rights to add participant to chat or this participant is already joined the chat.

Delete chat participants

REST method: im.chat.user.delete

Method call:

$result = restCommand('im.chat.user.delete', Array(

   'CHAT_ID' => 13 // Chat ID
   'USER_ID' => 4 // Deleted user ID

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. USER_ID_EMPTY No User ID. WRONG_REQUEST You have insufficient rights to add participant to chat or this participant is already joined the chat.

Exit chat

REST method: im.chat.leave

Method call:

$result = restCommand('im.chat.leave', Array(

   'CHAT_ID' => 13 // Chat ID

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. WRONG_REQUEST You are not a member of this chat.

Send «Writing to you...» status

REST method: im.chat.sendTyping

Method call:

$result = restCommand('im.chat.sendTyping', Array(

   'CHAT_ID' => 13 // Chat ID

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. ACCESS_ERROR You have insufficient rights to send status to this chat.

Chat title update

REST method: im.chat.updateTitle

Method call:

$result = restCommand('im.chat.updateTitle', Array(

   'CHAT_ID' => 13 // Chat ID
   'TITLE' => 'New name for chat' // New title

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. TITLE_EMPTY New chat title unavailable. WRONG_REQUEST Title is not specified or indicated chat does not exist.

Chat color update

REST method: im.chat.updateColor

Method call:

$result = restCommand('im.chat.updateColor', Array(

   'CHAT_ID' => 13 // Chat ID
   'COLOR' => 'MINT' // Chat color for mobile application - RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY No Chat ID. WRONG_COLOR Color is not in available colors list. WRONG_REQUEST Color is already specified or indicated chat does not exist.

Chat icon update

REST method: im.chat.updateAvatar

Method call:

$result = restCommand('im.chat.updateAvatar', Array(

   'CHAT_ID' => 13 // Chat ID
   'AVATAR' => '/* base64 image */' // Image in base64 format

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY Chat ID was not transmitted. AVATAR_ERROR Incorrect image format is transmitted. WRONG_REQUEST Chat does not exist.

Change of chat owner

REST method: im.chat.setOwner

Method call:

$result = restCommand('im.chat.setOwner', Array(

   'CHAT_ID' => 13 // Chat ID
   'USER_ID' => '2' // New chat owner ID

), $_REQUEST["auth"]);

Return: true or an error.

Possible errors:

Error code Error description CHAT_ID_EMPTY Chat ID was not transmitted. USER_ID_EMPTY New chat owner ID was not transmitted. WRONG_REQUEST Method is called by user without owner's rights or indicated user is not a chat participant.

Get chat ID

REST method: im.chat.get

Method call:

$result = restCommand('im.chat.get', Array(


   'ENTITY_TYPE' => 'OPEN', // Arbitrary entity ID (for example CHAT, CRM, OPENLINES, CALL and etc.), can be used for chat search and easy context definition in the following event handlers: ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE (req.)
   'ENTITY_ID' => 13, // Numerical entity ID; it can be used for chat search and easy context definition in the following events handlers: ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE  (req.)

), $_REQUEST["auth"]);

Required fields:
ENTITY_TYPE - arbitrary entity ID (for example CHAT, CRM, OPENLINES, CALL and etc); it can be used for chat search and for easy app context definition in the event handlers ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE.
ENTITY_ID - numeric entity ID; it can be used for chat search and for easy app context definition in the event handlers ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE.

Returns: returns chat ID CHAT_ID or null.
REST method: im.chat.mute

Disabling notifications in chat

REST method: im.chat.mute

Revision: 19

Get information on the current API revision (platform version) – im.revision.get.

Parameters

Parameter Example Req. Description Revision CHAT_ID 17 Yes Chat ID 19 MUTE Y No Disable or enable notifications - Y|N 19

• Variants of MUTE key: Y or N.

Method call

JavaScript

BX24.callMethod('im.chat.mute', {
	'CHAT_ID': 17,
	'MUTE': 'Y'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.chat.mute', Array(
	'CHAT_ID' => 17,
	'MUTE' => 'Y'
), $_REQUEST["auth"]);

Examples of result

{
	"result": true
}

Example of result with errors

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

Description of keys:

• error – error code
• error_description – brief description of error

Possible error codes

Code Description CHAT_ID_EMPTY Chat ID not passed