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 code | Error 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 code | Error 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 code | Error 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 code | Error 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 code | Error 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 code | Error 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 code | Error 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 code | Error 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 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. |
|