Views: 3565 (Data available since 06.02.2017)

Note: The restCommand function is used here for illustration only. You can send a REST command with your own function, or use the BX24.callMethod or bitrix24-php-sdk JavaScript-method.


Getting participants list

REST method: imbot.chat.user.list

Method call:
$result = restCommand('imbot.chat.user.list', Array(

   'CHAT_ID' => 13 // Chat ID
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: participants' IDs array or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.


Participants invitation

REST method: imbot.chat.user.add

Method call:
$result = restCommand('imbot.chat.user.add', Array(

   'CHAT_ID' => 13 // Chat ID
   'USERS' => Array(3,4) // New users ID
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
WRONG_REQUEST Insufficient rights to add a participant to the chat or the participant is already in the chat.


Removal of participants

REST method: imbot.chat.user.delete

Method call:
$result = restCommand('imbot.chat.user.delete', Array(

   'CHAT_ID' => 13 // Chat ID
   'USER_ID' => 4 // Deleted user ID
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
USER_ID_EMPTY User ID is unavailable.
WRONG_REQUEST Insufficient rights to add a particiant to the chat, or the participant is already in the chat.


Chatbot exit from specified chat

REST method: imbot.chat.leave

Method call:
$result = restCommand('imbot.chat.leave', Array(

   'CHAT_ID' => 13 // Chat ID to exit
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
ACCESS_ERROR Insufficient rights for sending status to this chat.
BOT_ID_ERROR Chatbot not found.


Chat title update

REST method: imbot.chat.updateTitle

Method call:
$result = restCommand('imbot.chat.updateTitle', Array(

   'CHAT_ID' => 13 // Chat ID
   'TITLE' => 'New name for chat' // New title
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
TITLE_EMPTY Fail to send new chat title.
WRONG_REQUEST Title is already set or the specified chat already exist.


Chat color update

REST method: imbot.chat.updateColor

Method call:
$result = restCommand('imbot.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
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
WRONG_COLOR Color is not included into available colors list.
WRONG_REQUEST Color is already defined or the existing chat does not exist.


Chat icon update

REST-method: imbot.chat.updateAvatar

Method call:
$result = restCommand('imbot.chat.updateAvatar', Array(

   'CHAT_ID' => 13 // Chat ID
   'AVATAR' => '/* base64 image */' // Image in base64 format
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_REQUEST["auth"]);
Returns: true or an error.

Possible errors:

Error codeError description
CHAT_ID_EMPTY Chat ID is unavailable.
AVATAR_ERROR incorrect image format is defined.
WRONG_REQUEST Chat does not exist.




Create chat on behalf of chatbot

REST method: imbot.chat.add

Method call:
$result = restCommand('imbot.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.
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot

), $_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.


Gets chat ID

REST method: imbot.chat.get

Method call:
$result = restCommand('imbot.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.)
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot
   
), $_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.
>

Change of chat owner

REST method: imbot.chat.setOwner

Method call:
$result = restCommand('imbot.chat.setOwner', Array(

   'CHAT_ID' => 13 // Chat ID
   'USER_ID' => '2' // New chat owner ID
   'BOT_ID' => 39, // Chatbot ID from which the request is sent. May not be specified, if there is only one chatbot   

), $_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.


Courses developed by «Bitrix», Inc.