API ВКонтакте(функции для использования всех возможностей Вконтакте)
Доступно на тарифах "Бизнес" и "Инфобиз"
Last updated
Доступно на тарифах "Бизнес" и "Инфобиз"
Last updated
1 способ:
Ваше сообщество должно быть подключено к проекту
Отправьте любое сообщение в диалог с сообществом, куда должны приходить сообщения бота
В списке клиентов проекта выбираете диалог клиента, которому будете отправлять сообщение
Копируете значение ID в мессенджере
2 способ:
Получить идентификатор группы/пользователя Вконтакте можно из адресной строки браузера.
Адрес профиля пользователя имеет вид https://vk.com/idXXXXXX, адрес сообщества — https://vk.com/publicXXXXXX или https://vk.com/clubXXXXXX, где XXXXXX — ID страницы. Посмотреть ID можно в адресной строке браузера. Если профилю или сообществу присвоен буквенно-цифровой адрес, то ID можно определить иначе. Откройте любую фотографию пользователя/сообщества; первые цифры после слова photo (XXXXXX в ссылке вида https://vk.com/photoXXXXXX_YYYYYYY) — это и есть интересующий вас ID. Найти ID своей страницы вы можете в разделе Настройки → Адрес страницы.
Пример reply-кнопок:
knop = {"one_time":false, "buttons":[[{"action":{"type":"text", "payload":"{"button": "1"}", "label":"Red"}, "color":"negative"}, {"action":{"type":"text","payload":"{"button": "2"}","label":"Green"},"color":"positive"},{"action":{"type":"text","payload":"{"button": "2"}", "label":"Blue"},"color":"primary"},{"action":{"type":"text","payload":"{"button": "2"}", "label":"White"},"color":"secondary"}]]}
Пример inline-кнопок:
knop={"inline": true, "buttons": [[{"action": {"type": "open_link", "link": "https://dev.vk.com/", "label": "Оформить"}}, {"action": {"type": "text", "label": "Поддержка"}}]]}
Более подробные примеры и объяснения смотрите в первоисточнике
Чтобы убрать у пользователя клавиатуру, необходимо отправить сообщение с пустым параметром buttons:
{"buttons":[],"one_time":true}
vk_send_message(platform_id, message, keyboard, reply_to, forward_messages, sticker_id, dont_parse_links, disable_mentions, attachments_photo, attachments_files)
Параметры:
! platform_id — id клиента в мессенджере *
! message — текст сообщения
keyboard — кнопки в сообщении **
reply_to — id сообщения для ответа/цитаты
forward_messages — id пересылаемых сообщений (формат списка "{#айдипервогосообщения}, #{второго}, #{итакдалее}"
sticker_id — id стикера
dont_parse_links — создавать сниппет или нет, может принимать значение 1 — создавать, 0 — нет
disable_mentions — отключить уведомление об упоминании в сообщении, для отключения уведомлений передайте в этот параметр что угодно, иначе оставьте пустым
attachments_photo — добавить в медиавложения сообщения фотографии, которые пока не загружены во ВКонтакте, в виде списка ссылок на фотографии в формате:
'["#{url1}","#{url2}"]', где
url - это ссылка на фотографию на доступных ресурсах в Интернете.
attachments_files — различные вложения из ВКонтакте. Для использования attachments_files потребуется строка с вложениями, перечисленными через запятую и уже находящимися во ВКонтакте, имеющая следующий вид:
'doc-182762603_638918266, photo-182762603_638918266'
Каждое вложение описываем следующим образом:
<type>-<owner_id>_<media_id> - где:
<type> — тип медиа-вложения:
photo — фотография;
video — видеозапись;
audio — аудиозапись;
doc — документ;
wall — запись на стене;
market — товар;
poll — опрос.
<owner_id> — идентификатор владельца медиа-вложения.
<media_id> — идентификатор медиа-вложения.
Обратите внимание, если прикрепляется объект, принадлежащий другому пользователю, следует добавлять к вложению его access_key в формате -<owner_id><media_id>_<access_key>
Если присвоить функцию переменной, то в переменную будет помещен id сообщения, который будет необходим для возможно последующего редактирования сообщения.
Чтобы в переменную записать текст с переносами строк, укажите значение следующим образом:
message = "Текст первой строки" + "\n" + "Текст второй строки" + "\n" +"Третья строка"
vk_edit_message(platform_id, message_id, text, attachments_photo, attachments_files, keyboard, keep_forward_messages, keep_snippets, dont_parse_links, disable_mentions)
Параметры:
! platform_id — id клиента в мессенджере *
! message_id — id редактируемого сообщения
text — текст сообщения
attachments_photo — добавить в медиавложения сообщения фотографии, которые пока не загружены во ВКонтакте, в виде списка ссылок на фотографии в формате:
'["#{url1}","#{url2}"]', где
url - это ссылка на фотографию на доступных ресурсах в Интернете.
attachments_files — различные вложения из ВКонтакте. Для использования attachments_files потребуется строка с вложениями, перечисленными через запятую и уже находящимися во ВКонтакте, имеющая следующий вид:
'doc-182762603_638918266, photo-182762603638918266'.
Каждое вложение описываем следующим образом:
<type>-<owner_id>_<media_id> - где:
<type> — тип медиа-вложения:
photo — фотография;
video — видеозапись;
audio — аудиозапись;
doc — документ;
wall — запись на стене;
market — товар;
poll — опрос.
<owner_id> — идентификатор владельца медиа-вложения.
<media_id> — идентификатор медиа-вложения.
Обратите внимание, если прикрепляется объект, принадлежащий другому пользователю, следует добавлять к вложению его access_key в формате -<owner_id><media_id>_<access_key>
keyboard — кнопки в сообщении **
keep_forward_messages — признак необходимости сохранить прикреплённые пересланные сообщения (любое значение)
keep_snippets — признак необходимости сохранить прикреплённые внешние ссылки (сниппеты)(любое значение)
dont_parse_links — признак того, что не надо создавать сниппет (любое значение)
disable_mentions — признак того, что надо отключить уведомление об упоминании в сообщении (любое значение)
vk_delete_messages(platform_id, message_ids)
Параметры:
! platform_id — id чата в мессенджере ! message_ids – список из conversation_message_id Вы можете удалить как одно сообщение, так и несколько. Для удаления нескольких сообщений передайте перечень conversation_message_id сообщений, которые хотите удалить, через запятую в общих кавычках
vk_delete_last_message()
Параметры: НЕТ
Удаляет последнее сообщение в чате. На личные сообщения из диалога бота с клиентом не распространяется!
vk_get_short_link(link, private, user_token)
Параметры:
! link — ссылка, которую нужно будет открывать по короткой ссылке private — позволяет сделать статистику ссылки приватной (любое значение) user_token — персональный токен пользователя. Обязательный параметр в случае использования private
Присвойте функцию переменной . Тогда в случае успешного выполнения в переменной будет содержаться короткая ссылка, а в случае наличия ошибок в эту же переменную будет помещен весь ответ сервера.
vk_send_sticker(platform_id, sticker_id)
Параметры:
! platform_id — id клиента в мессенджере
! sticker_id — id стикера.
Как узнать id стикера?
Отправьте стикер в чат и в разделе переменных клиента появится переменная sticker_id
vk_send_some_photo(platform_id, image_list, text, keyboard, dont_parse_links, disable_mentions)
Параметры:
! platform_id — id клиента в мессенджере ! image_list - массив с картинками text - текст для сообщения с картинками keyboard - кнопки в сообщении ** dont_parse_links - отключение превью ссылок disable_mentions -отключение уведомлений
Пример
image_list=["Ссылка на картинку 1", "Ссылка на картинку 2", "Ссылка на картинку 3"]
vk_liked_object(type, owner_id, item_id, user_id, user_token)
Параметры:
type - тип объекта owner_id - идентификатор владельца Like-объекта. Если параметр не задан, то считается, что он равен идентификатору текущего пользователя* item_id - идентификатор объекта user_id - идентификатор пользователя в вк user_token - персональный токен
post — запись на стене пользователя или группы;
comment — комментарий к записи на стене;
photo — фотография;
video — видеозапись;
note — заметка;
photo_comment — комментарий к фотографии;
video_comment — комментарий к видеозаписи;
topic_comment — комментарий в обсуждении.
Результат выполнения функции - словарь вида: {"response":{"liked":1,"copied":0}}
liked — есть ли отметка «Мне нравится» от текущего пользователя (0 — отметки нет, 1 — отметка есть);
copied — сделан ли репост текущим пользователем (0 — не сделан, 1 — сделан).
vk_remove_chat_user(member_id)
Параметры:
! member_id — id пользователя, которого нужно исключить. Здесь же вы можете использовать значение from_id.
vk_get_name(member_id, full)
Параметры:
! member_id — id пользователя. Здесь же вы можете использовать значение from_id.
! full - признак какие данные выдать. Может принимать значение True, тогда будет выдано имя и фамилия пользователя, иначе (False) - только имя
vk_create_wall_post(token, owner_id, text, attachments, from_group, signed, mark_as_ads, close_comments, mute_notifications, copyright)
Параметры: НЕТ
token - персональный токен ВКонтакте с правами wall
owner_id - id пользователя или сообщества, на стене которого необходимо опубликовать запись *
text - текст публикации, если есть вложения, то можно вместо текста передать пустую строку ("")
attachments — список объектов, приложенных к комментарию и разделённых символом «,». Поле attachments представляется в формате:
<type><owner_id>_<media_id>,где
<type> — тип медиа-вложения:
photo — фотография;
video — видеозапись;
audio — аудиозапись;
doc — документ;
page — вики-страница;
note — заметка;
poll — опрос;
album — альбом;
market — товар;
market_album — подборка товаров;
audio_playlist — плейлист с аудио.
<owner_id> — идентификатор владельца медиавложения (идентификатор сообщества должен начинаться со знака -).
<media_id> — идентификатор медиавложения. Формат описания ссылки:
{protocol}{URL}, где:
<protocol> — протокол HTTP или HTTPS.
<URL> — оставшаяся часть URL.
Примечание. Можно указать несколько медиавложений, но только одну ссылку. Если указать больше одной ссылки, вернётся ошибка.
from_group - 0, если нужно опубликовать от своего имени, 1 - если от имени сообщества
signed - если опубликовано от имени сообщества, то можно оставить подпись под постом, для включения передайте 1
mark_as_ads - является ли пост рекламным, чтобы отметить пост как рекламный укажите 1 (Внимание! рекламным может быть только пост от имени группы)
close_comments - передайте 1, если хотите закрыть комментарии, иначе - 0
mute_notifications - информация о том, включены ли уведомления к публикации записи, для выключения передайте 1, иначе 0
copyright - источник материала. Поддерживаются внешние и внутренние ссылки. Просто передайте ссылку на источник в кавычках.
В vk_send_message и vk_edit_message есть параметр attachments_files.
Для репоста в сообщения в этот параметр нужно передать в виде:
'wall{owner_id}_{post_id}'
owner_id — владелец публикации (в случае с группами перед id нужно добавить знак минус)
post_id — идентификатор поста на стене этого владельца
vk_create_comment(post_id, message, reply_to_comment, sticker_id, token, attachments)
Параметры:
! post_id — id комментируемого поста
! message — текст комментария
reply_to_comment — id комментария, на который отвечаем
sticker_id — id стикера
token — токен
attachments — список объектов, приложенных к комментарию и разделённых символом «,». Поле attachments представляется в формате:
<owner_id><media_id>,<owner_id><media_id>
<type> — тип медиа-вложения:
photo — фотография;
video — видеозапись;
audio — аудиозапись;
doc — документ.
<owner_id> — идентификатор владельца медиа-вложения.
<media_id> — идентификатор медиа-вложения.
Если не передавать необязательные параметры, то функция будет выглядеть так: vk_create_comment(post_id, message)
comment_text()
Параметры: НЕТ
Внимание!!! Для данных действий нужен дополнительный ключ для работы с комментариями на стене. Как получить токен для работы с комментариями указано здесь
Включить комментирование поста
vk_open_comment(owner_id,post_id,token )
Параметры:
! owner_id — автор сообщения
Если используете токен для работы с комментариями, то для включения комментариев будут доступны только посты от имени группы
! post_id — идентификатор поста
token — токен
Закрыть комментирование поста
vk_close_comment(owner_id,post_id,token )
Параметры:
! owner_id — автор сообщения (если указывать идентификатор группы, то для выключения комментариев будут доступны только посты от имени группы, не забудьте указать перед идентификатором группы знак “-”
! post_id — идентификатор поста
token — токен
vk_delete_wall_post_comment(token, owner_id, comment_id)
Параметры:
! token — персональный токен пользователя
! owner_id — идентификатор пользователя, на чьей стене находится комментарий к записи
! comment_id — идентификатор комментария
Обратите внимание, идентификатор сообщества в параметре owner_id необходимо указывать со знаком «-» — например, owner_id = -123.., что соответствует идентификатору сообщества.
После успешного выполнения возвращает 1.
В случае успешного запроса выдаст:
vk_search_message(serched_text, platform_id,date,count)
Параметры:
! searched_text — текст для поиска в сообщениях группы ! platform_id — идентификатор назначения для поиска по отдельному диалогу, это либо id пользователя, либо id диалога, либо id сообщества (в этом случае нужно добавить знак “-” перед идентификатором), date — дата в формате DDMMYYYY, если параметр задан, в ответе будут только сообщения, отправленные не позднее указанной даты, count – необязательный параметр, количество возвращаемых сообщений (максимум - 20, по умолчанию - 10).
check_vk_subscription(group_id)
Параметры: ! group_id - идентификатор сообщества, подписку на которое необходимо проверить. Если к проекту подключена только одна группа/сообщество, то этот параметр можно опустить.
В ответ возвращается значение True, если подписан, и False, если не подписан.
Закрепление сообщения чата
vk_pin_message(platform_id, conversation_message_id)
Параметры
! platform_id - идентификатор чата ! conversation_message_id - идентификатор сообщения
Открепление сообщения чата
vk_unpin_message(platform_id)
Параметры
! platform_id - идентификатор чата
vk_send_chat_action(platform_id, bot_action)
Параметры
! platform_id – идентификатор назначения (групповой чат или переписка клиента с сообществом)
! bot_action – действие бота. Возможные значения bot_action: typing – печатает, audiomessage – записывает аудио.
В случае опечатки в названии действия будет использовано действие бота typing.
Данное уведомление будет отображаться пока не придет какой-либо ответ от бота, но не более 10 секунд.
У клиентов вк, после входящего сообщения появляется переменная cmid, в ней хранится порядковый номер сообщения в чате и переменная reply_cmid - id цитируемого сообщения, если сообщение это ответ.
Ниже описаны функции для создания реакции на сообщения в ВК. Данные функции указываем в Калькуляторе блока.
Добавлены коллбэки на реакции в чатах. Для включения нужно зайти в управление, пункт в настройках работа с API, выбрать во вкладке callback API наш сервер и зайти в типы событий, там найдете Действие с реакциями на сообщение и поставите галочку напротив этого поля. После этого в чаты будет приходить коллбэк с информацией на сообщение с каким conversation_id была реакция и какая.
react 2 on 629 - 2 реакция на cmID 629
cancel reaction on 629 - отменил ранее поставленную реакцию на cmID 629
vk_send_message_reaction(cmid, reaction_id) - Добавляет или изменяет ранее добавленную реакцию на сообщение
Все параметры обязательные.
cmid - порядковый номер сообщения в чате (переменная cmid). Или передайте переменную reply_cmid, чтобы поставить реакцию на цитируемое сообщение.
reaction_id - идентификатор реакции от 1 до 16 (на скриншоте слева направо)
Пример настройки функции в калькуляторе:
Результат выполнения функции в чате:
При успехе возвращает {'response': 1}
При ошибке описание ошибки: {'error': {'error_code': 100, 'error_msg': 'One of the parameters specified was missing or invalid', 'request_params': [{'key': 'method', 'value': 'messages.sendReaction'}, {'key': 'oauth', 'value': '1'}, {'key': 'v', 'value': '5.131'}, {'key': 'peer_id', 'value': '620578274'}, {'key': 'cmid', 'value': '106'}, {'key': 'reaction_id', 'value': '150'}]}}
vk_delete_message_reaction(cmid) - Удаляет как реакцию, созданную ботом, так и реакцию от лица сообщества.
cmid - порядковый номер сообщения в чате (переменная cmid или reply_cmid)
При успехе возвращает {'response': 1}
При ошибке: {'error': {'error_code': 100, 'error_msg': 'One of the parameters specified was missing or invalid: invalid cmid', 'request_params': [{'key': 'method', 'value': 'messages.deleteReaction'}, {'key': 'oauth', 'value': '1'}, {'key': 'v', 'value': '5.131'}, {'key': 'peer_id', 'value': '620578274'}, {'key': 'cmid', 'value': '1106'}]}}
vk_get_message_reactions(cmds) - Получить актуальные счётчики реакций на сообщения. Если реакций не много, возвращает так же id пользователей и сообществ, поставивших реакции
cmds - порядковый номер сообщения (переменная cmid) или список через запятую сообщений, для которых нужно вернуть счётчики реакций.
Например '3611' или '118,117,116,115'
Пример при успехе: {'response': {'items': [{'cmid': 118, 'counters': [{'reaction_id': 2, 'count': 1, 'user_ids': [620578000]}]}, {'cmid': 117, 'counters': [{'reaction_id': 12, 'count': 1, 'user_ids': [620578000]}]}]}}
При отсутствии реакций: {'response': {'items': []}}
При ошибке: {'error': {'error_code': 100, 'error_msg': 'One of the parameters specified was missing or invalid', 'request_params': [{'key': 'method', 'value': 'messages.getMessagesReactions'}, {'key': 'oauth', 'value': '1'}, {'key': 'v', 'value': '5.131'}, {'key': 'peer_id', 'value': '6205178274'}, {'key': 'cmids', 'value': '1187'}]}}
Как создать Callback-кнопку
Кнопки данного вида существуют только во ВКонтакте и Telegram. При добавлении кнопок выберите тип (функция) Callback-кнопка (ВКонтакте, Telegram)
Кнопки внешне выглядят как обычные кнопки, но при нажатии на них клиенту приходит колбек, указанные в поле "Текст ответного сообщения":
Как использовать реакции при нажатии на callback-кнопку
Разберём, как настроить реакцию на нажатие callback-кнопки. Для этого используйте любой условный блок или стрелку и в поле Условие укажите текст Callbackа:
Как это выглядит со стороны клиента:
Обратите внимание! После нажатия на callback-кнопки в карточке клиента появится переменная vk_event_id, которая потребуется для дальнейшей работы.
vk_callback_url(platform_id, vk_user_id, opened_url, event_id )
Параметры:
! platform_id — идентификатор диалога (в личных сообщениях совпадает с vk_user_id) ! vk_user_id — идентификатор пользователя в ВК, нажавшего кнопку opened_url — ссылка, которая будет открываться event_id — идентификатор события. Используйте переменную vk_event_id, которая появляется при нажатии callback-кнопки.
vk_show_alert_message(platform_id, vk_user_id, text, event_id)
Параметры:
! platform_id — идентификатор диалога (в личных сообщениях совпадает с vk_user_id), ! vk_user_id — идентификатор пользователя в ВК, нажавшего кнопку, ! text — текст исчезающего сообщения, который будет показан на несколько секунд, ! event_id — идентификатор события. Используйте переменную vk_event_id, которая появляется при нажатии callback-кнопки.
vk_get_chat_member_count(platform_id )
Параметры
! platform_id - идентификатор чата.
vk_export_chat_link(platform_id, new)
Параметры:
! platform_id – идентификатор чата new – при передаче в него любого значения прежняя ссылка перестает работать и будет возвращена новая ссылка, если же его не передавать, то вернет актуальную ссылку.
vk_mark_conversation(platform_id, mark_type)
Параметры
! platform_id — id пользователя, диалог с которым нужно отметить mark_type — тип отметки Возможные значения: 'important' - важный (значение по умолчанию) 'answered' - отвеченный 'read' - прочитанный
vk_unmark_conversation(platform_id, mark_type)
Параметры
! platform_id — id пользователя, для которого требуется снять отметку с диалога, mark_type — тип отметки Возможные значения: 'important' - важный (значение по умолчанию) 'answered' - отвеченный 'read' - прочитанный
vk_approve_request(platform_id, user_id, token)
Параметры
! platform_id – идентификатор группы, в которую оставили заявку на вступление, ! user_id – идентификатор пользователя, оставившего заявку, ! token – персональный токен администратора.
client_group_join request - подан запрос на вступление в группу client_group_join approved - клиент принят в группу
Добавление пользователя или сообщества в черный список
vk_ban_by_id(platform_id, user_id, token, end_date, reason, comment, visible)
! platform_id – идентификатор группы, в черный список которой нужно добавить пользователя или сообщество ! user_id – идентификатор пользователя или сообщества (если передаете идентификатор сообщества, то перед идентификатором нужно поставить символ “-”) ! token – персональный токен администратора, end_date – дата окончания бана (если не использовать, то бан будет перманентный. Максимальный возможный срок окончания бана, который можно указать, — один год с его начала) reason – код причины блокировки comment – комментарий администратора (может содержать пояснения по блокировке), visible – виден ли комментарий администратора забаненному (может принимать любое значение). По умолчанию комментарий забаненному клиенту не виден.
Дата окончания блокировки передается в виде D.M.Y, где D - число, M - месяц, Y - год. Также можно использовать current_date. Помимо этого может быть передана дата со временем в виде D.M.Y H:M, где D - число, M - месяц, Y - год, H - часы, M – минуты. Причины блокировки закодированы следующим образом: 0 — другое (по умолчанию) 1 — спам 2 — оскорбление участников 3 — нецензурные выражения 4 — сообщения не по теме В комментарии можно дать какие-либо разъяснения только для администраторов или доступные пользователю, если передан параметр видимости.
Удаление из черного списка
vk_unban_by_id(platform_id, user_id, token)
Параметры
! platform_id – идентификатор группы, из черного списка которой нужно убрать пользователя или сообщество, ! user_id – идентификатор пользователя или сообщества (если передаете идентификатор сообщества, то перед идентификатором нужно поставить символ “-”), ! token – персональный токен администратора.
vk_remove_group_user(platform_id, user_id, token)
Параметры
! platform_id – идентификатор группы, в черный список которой нужно добавить пользователя или сообщество ! user_id – идентификатор пользователя ! token – персональный токен администратора.
vk_edit_manager(platform_id, user_id, token, role, is_contact, position, phone, email)
Параметры
! platform_id – id целевой группы ! user_id – назначаемый пользователь ! token - персональный токен администратора role - роль назначаемого администратора (если оставить пустым или указать должность с ошибкой, то будет лишен прав администратора) is_contact – будет ли отображаться администратор в списке контактов группы (если оставить пустым, то отображаться не будет и если отображался, то будет убран из списка контактов) position – передается только при заполненном параметре is_contact, отображаемая должность (любой текст для должности в списке контактов) phone – передается только при заполненном параметре is_contact, телефон, отображаемый в списке контактов email – передается только при заполненном параметре is_contact, email, отображаемый в списке контактов.
В параметре role можно передать один из 4 вариантов роли администратора: moderator — модератор; editor — редактор; administrator — администратор; advertiser — рекламодатель.
Для работы данной функции необходима регистрация в VK Vision (VK cloud). После регистрации необходимо получить сервисный токен.
vk_vision_recognize_text(token, file_url)
Параметры
token- сервисный ключ от аккаунта VK Vision. file_url - ссылка, на фотографию, которую вы отправили в чат-бот.
Важно! Функция работает только с фотографиями, которые находятся на сервере Salebot.
