Views: 800 (Data available since 06.02.2017)

Attention! The restCommand function is used in all methods. This method is used to send data in Bitrix24 and is available in the EchoBot example as well as in this article. You can use your own function or BX24.callMethod, or bitrix24-php-sdk JavaScript methods.


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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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 codeError 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.



Chapter contents:


Courses developed by «Bitrix», Inc.