Views: 2166 (Data available since 06.02.2017)

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.


Attention! These methods of message processing are usually employed when the user is typing something, that is why the ONIMBOTMESSAGEADD event must be processed.


Sending message from chatbot

REST method: imbot.message.add

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

    'BOT_ID' => 39, // ID of chatbot that sends request. Is optional, there is only one chatbot
    'DIALOG_ID' => 1, // Dialog ID: it can be either USER_ID, or chatXX - where XX is chat ID, transmitted in events ONIMBOTMESSAGEADD and ONIMJOINCHAT
    'MESSAGE' => 'answer text' // Message text
    'ATTACH' => '' // Attachment, optional field 
    'KEYBOARD' => '' // Keyboard, optional field 
    'MENU' => '' // Context menu, optional field
    'SYSTEM' => 'N' // Display messages as system messages, optional field, by default 'N'
    'URL_PREVIEW' => 'Y' // Convert links to rich-links, optional field, by default 'Y'

), $_REQUEST["auth"]);

You can post message on behalf of bot in private dialogues (they will be shown as system message). To do it, specify USER_FROM_ID and USER_TO_ID instead of DIALOG_ID.

Return: MESSAGE_ID message ID or an error.

Related Links:

Using Keyboards
Attachments
Formatting
Working with Events - ONIMBOTMESSAGEADD

Possible errors:

Error codeError description
BOT_ID_ERROR Chatbot not found.
APP_ID_ERROR Chatbot is not part of this application: you can only work with chatbots, installed within application framework.
DIALOG_ID_EMPTY Dialogue ID is not transmitted.
MESSAGE_EMPTY Message text is not transmitted.
ATTACH_ERROR Complete transmitted object was not validated.
ATTACH_OVERSIZE Maximum permissible attachment size was exceeded (30 Kb).
KEYBOARD_ERROR Complete transmitted keyboard object was not validated.
KEYBOARD_OVERSIZE Maximum permissible keyboard size was exceeded (30 Kb).
MENU_ERROR Complete transmitted menu object was not validated.
MENU_OVERSIZE Maximum permissible menu size was exceeded (30 Kb).
WRONG_REQUEST Something went wrong.


Updates (changes) the chatbot message

REST method: imbot.message.update

Method call:
$result = restCommand('imbot.message.update', Array(

    'BOT_ID' => 39, // ID of chatbot that sends request. Is optional, there is only one chatbot
    'MESSAGE_ID' => 1, // Message ID
    'MESSAGE' => 'answer text' // Message text, optional field, if null value is specified – message will be deleted
    'ATTACH' => '' // Attachment, optional field 
    'KEYBOARD' => '' // Keyboard, optional field 
    'MENU' => '' // Context menu, optional field
    'URL_PREVIEW' => 'Y' // Convert links to rich-links, optional field, by default 'Y'

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

Related Links:

Using Keyboards
Attachments
Formatting
Working with Events - ONIMBOTMESSAGEADD message for chatbot

Possible errors:

Error codeError description
BOT_ID_ERROR Chatbot not found.
APP_ID_ERROR Chatbot is not part of this application: you can only work with chatbots, installed within application framework.
MESSAGE_EMPTY Message text is not transmitted.
CANT_EDIT_MESSAGE You do not have access to this message or time to modify it has expired (more than 3 days passed since publishing).
ATTACH_ERROR Complete transmitted attachment was not validated.
ATTACH_OVERSIZE Maximum permissible attachment size was exceeded (30 Kb).
KEYBOARD_ERROR Complete transmitted keyboard object was not validated.
KEYBOARD_OVERSIZE Maximum permissible keyboard size was exceeded (30 Kb).
MENU_ERROR Complete transmitted menu object was not validated.
MENU_OVERSIZE Maximum permissible menu size was exceeded (30 Kb).


Deletes chatbot message

REST method: imbot.message.delete

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

    'BOT_ID' => 39, // ID of chatbot that sends request. Is optional, there is only one chatbot
    'MESSAGE_ID' => 1, // Message ID
    'COMPLETE' => 'N', //  If message is required to be deleted completely, without a trace, then specify 'Y' (optional parameter)

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

Possible errors:

Error codeError description
BOT_ID_ERROR Chatbot not found.
APP_ID_ERROR Chatbot is not part of this application: you can only work with chatbots, installed within application framework.
MESSAGE_ID_ERROR Message ID was not transmitted.
CANT_EDIT_MESSAGE You do not have access to this message or time to modify it has expired (more than 3 days passed since publishing).


Message «Like»

REST method: imbot.message.like

Method call:
$result = restCommand('imbot.message.like', Array(

    'BOT_ID' => 39, // ID of chatbot that sends request. Is optional, there is only one chatbot
    'MESSAGE_ID' => 1, // Message ID (any message, sent in personal dialogues or in group chats, where chatbot is located)
    'ACTION' => 'auto' // Action, connected with method: plus – click «Like»; minus – «Like» is removed; auto – automatic calculation, tick should/shouldn't be specified. If not specified, it will work in auto mode 

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

Possible errors:

Error codeError description
BOT_ID_ERROR Chatbot not found.
APP_ID_ERROR Chatbot is not part of this application: you can only work with chatbots, installed within application framework.
MESSAGE_ID_ERROR Message ID was not transmitted.
WITHOUT_CHANGES After «Like» status call, it did not change.


Send "Chatbot is typing a message...»

REST method:imbot.chat.sendTyping

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

    'BOT_ID' => 39, // ID of chatbot that sends request. Is optional, there is only one chatbot
    'DIALOG_ID' => 1, // Dialogue ID, it is either USER_ID, or chatXX – where XX is chat ID, transmitted in events ONIMBOTMESSAGEADD and ONIMJOINCHAT

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

Related Links:

Working with Events - ONIMBOTMESSAGEADD message for chatbot
Working with Events - ONIMJOINCHAT message for chatbot to join chat (or private chat)

Possible errors:

Error codeError description
BOT_ID_ERROR Chatbot not found.
DIALOG_ID_EMPTY Dialogue ID not transmitted.




Courses developed by «Bitrix», Inc.