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 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 |
|
Attention! The method is specified with using of the
restCommand function. 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.