Как настроить api вконтакте
Чат-бот — это скрипт на Вашем сервере, который получает уведомления о новых событиях из ВКонтакте и обрабатывает их. Например, определяет текстовую команду в сообщении от пользователя и присылает в ответ какое-нибудь изображение.
Для создания бота Вам потребуются:
- Сообщество, от имени которого Ваш бот будет общаться с пользователями ВКонтакте.
- Сервер, который будет принимать уведомления о событиях.
- Логика самого бота — скрипт, который определяет, как бот реагирует на то или иное событие.
В первую очередь Вам нужно продумать функциональность чат-бота. Составьте список возможных текстовых команд или событий, на которые бот должен реагировать, и соответствующие им ответные действия бота. Стоит помнить, что люди могут ошибаться, набирая команды, и присылать боту текст, который отличается от всех учтённых Вами вариантов — важно предусмотреть действие по умолчанию (можно в таком случае присылать пользователю список всех поддерживаемых команд).
Если ранее Вы не работали с API ВКонтакте, перед началом работы мы рекомендуем Вам прочитать это руководство.
Для подключения чат-бота Вы можете использовать любое своё сообщество ВКонтакте — группу, встречу или публичную страницу. Ваш бот должен соответствовать правилам, подробнее о них Вы можете узнать здесь.
Первым делом нужно указать, что в вашем сообществе будет работать бот. Для этого перейдите в «Управление сообществом» →»Сообщения» →»Настройки для бота» и включите пункт «Возможности ботов».
Сообщество — это точка входа для пользователей, которые будут общаться с Вашим ботом. Стоит позаботиться о том, чтобы оно выглядело привлекательно и содержало описание Вашего бота, иначе его действия могут стать сюрпризом для пользователей. Не забудьте включить сообщения в Вашем сообществе («Управление сообществом» → «Сообщения»), когда бот будет готов к использованию, чтобы ему можно было написать.
Итак, если Вы выбрали сообщество, можно приступать к настройке уведомлений.
Ключ доступа потребуется Вам для получения обновлений (в Long Poll), а также для работы с API.
Откройте раздел «Управление сообществом» («Управление страницей», если у Вас публичная страница), выберите вкладку «Работа с API» и нажмите «Создать ключ доступа».
Отметьте необходимые права доступа и подтвердите свой выбор.
Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени Вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.
Также Вы можете получить ключ доступа с помощью OAuth. Используйте схему авторизации Authorization Code Flow.
Чтобы пользователи смогли добавлять бота в беседы, необходимо включить эту возможность в настройках. Перейдите в «Управление сообществом» →«Сообщения» →«Настройки для бота» и поставьте галочку в пункте «Разрешать добавлять сообщество в беседы». После этого в сообществе появится кнопка «Пригласить в беседу», открывающая модальное окно со списком бесед.
Сейчас у бота в беседе есть три уровня доступа:
Важное замечание: для получения событий из беседы версия API у callback-сервера должна быть не ниже 5.80.
Чтобы реагировать на какие-либо события, Ваш скрипт должен о них узнать. Для этого существуют два подхода — Callback API и Long Poll.
Callback API присылает уведомления на Ваш сервер, как только в сообществе происходит нужное событие. Событие может быть каким угодно: комментарий к фотографии, новая запись на стене, вступление в сообщество, отправка сообщения, и многое другое. Посмотреть полный список доступных событий, а также прочитать подробнее о настройке Вы можете в документации Callback API.
Для подключения Callback API в сообществе нужно указать адрес скрипта на Вашем сервере и выбрать события, которые Вы хотите получать. Например, если Ваш бот должен распознавать текстовые команды, отметьте событие «Входящее сообщение».
Уведомления от Callback API выглядят как JSON с основной информацией о событии:
В этом примере пользователь с id 123456 отправил сообществу сообщение с текстом «start».
Для каждого события Callback API отправляет отдельный запрос на Ваш сервер. Ваш скрипт должен подтверждать получение каждого запроса, отправляя в ответ строку «ok».
function api($method, $params) <
$params[‘access_token’] = VK_API_ACCESS_TOKEN;
$params[‘v’] = VK_API_VERSION;
$query = http_build_query($params);
$url = VK_API_ENDPOINT . $method . ‘?’ . $query;
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($curl);
$error = curl_error($curl);
if ($error) <
error_log($error);
throw new Exception(«Failed <$method>request»);
>
curl_close($curl);
$response = json_decode($json, true);
if (!$response || !isset($response[‘response’])) <
error_log($json);
throw new Exception(«Invalid response for <$method>request»);
>
return $response[‘response’];
>
Второй способ получения обновлений — это подключение к Bots Long Poll API. Прочитать подробнее о работе с Bots Long Poll API Вы можете на этой странице.
Когда произойдет новое событие или истечет время ожидания, сервер вернет Вам ответ в формате JSON:
Некоторые функции ботов могут быть недоступны, так как пользователи:
- переходят на новые версии официальных приложений ВКонтакте постепенно;
- открывают ВКонтакте на разных платформах (iOS, Android, в мобильной и веб-версии);
- используют приложения от сторонних разработчиков. Например, клавиатура ботов может быть недоступна в старой версии официального приложения ВКонтакте.
Отправляйте сообщения в нужном формате, исходя из возможностей, которые доступны пользователю. Если он не может воспользоваться клавиатурой, предложите варианты ответов и пронумеруйте их — чтобы можно было ответить цифрой. И наоборот: если пользователь может взаимодействовать с ботом с помощью клавиатуры — не нужно отправлять ему варианты ответа в тексте сообщения.
Начиная с версии API 5.103 информация о доступных функциях будет приходить вместе с событием message_new в Callback API и Bots Long Poll API. Она будет находиться в объекте client_info:
По мере появления новых возможностей в объекте client_info и массиве button_actions могут появляться новые сущности.
Поля объекта:
- button_actions — массив кнопок, которые поддерживает клиент. Возможные значения смотрите в разделе «Клавиатуры для ботов» → «Структура данных»;
- keyboard (bool) — поддерживается ли клавиатура ботов клиентом;
- inline_keyboard (bool) — поддерживается ли inline-клавиатура ботов клиентом;
- carousel (bool) — поддерживаются ли карусели клиентом;
- lang_id — id используемого языка.
Продолжение
Источник
Как настроить api вконтакте
В этом руководстве рассказывается о том, как использовать API для работы с сообщениями сообществ. Для чего нужен этот сервис и чем он может быть Вам полезен, можно прочитать на этой странице.
Для работы с API от имени сообщества необходимо получить специальный ключ доступа. Вы можете сделать это двумя способами — в интерфейсе управления сообществом или программно, с помощью специального запроса к нашему серверу.
Ключ доступа — это строка, включающая латинские буквы и цифры. Ее необходимо передавать в параметре «access_token», обращаясь к методам API от имени сообщества.
Откройте раздел «Управление сообществом» («Управление страницей», если у Вас публичная страница), выберите вкладку «Работа с API» и нажмите «Создать ключ доступа».
Отметьте необходимые права доступа и подтвердите свой выбор.
Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени Вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.
Мы предлагаем два способа авторизации, основанных на протоколе OAuth 2.0. Используйте этот подход, если необходимо работать со многими сообществами пользователя, например, при разработке мобильного приложения.
Для работы с API с серверной стороны используйте Authorization Code Flow.
Для работы с API со стороны клиента используйте Implicit Flow.
В API сообщений сообществ используются те же методы, что и для работы с личными сообщениями пользователя. Если раньше Вы уже имели дело с сообщениями в API ВКонтакте, схема работы будет Вам знакома. Стоит, однако, учитывать некоторые особенности:
- необходимо проставлять статус прочитанности сообщения при общении с клиентом;
- если ответ получен пользователем, его необходимо помечать как прочитанный;
- в диалогах сообществ доступны специальные метки: Важные, Неотвеченные, Непрочитанные.
Чтобы Вы могли отправлять пользователю сообщения от имени сообщества, пользователь должен разрешить их получение. Если пользователь написал сообщение сообществу первым, это приравнивается к согласию на получение ответных сообщений (без ограничений по времени, если пользователь не запретил сообщения вручную). Чтобы запросить у пользователя разрешение на отправку сообщений, используйте:
- Метод showAllowMessagesFromCommunityBox Client API в приложениях сообществ;
- Метод messages.allowMessagesFromGroup в Standalone-приложениях;
- Виджет «Разрешить писать сообществу» на внешнем сайте.
В Callback API и Bots Longpoll API события message_allow и message_deny помогут отслеживать факт разрешения и запрета сообщений от сообщества. Обратите внимание, получить список всех пользователей, разрешивших сообщения сообществу, через API нельзя, необходимо хранить и синхронизировать этот список на своей стороне.
- Long Poll сервер — синхронизация обновлений;
- Callback API — мгновенные оповещения о новых сообщениях и других действиях пользователей в сообществе.
- messages.getDialogs — метод для получения списка диалогов;
- messages.markAsRead — метод для присвоения сообщению метки «Прочитано»;
- messages.markAsImportantDialog, messages.markAsAnsweredDialog — методы для присвоения меток диалогам;
- messages.send — метод для отправки нового сообщения;
- messages.delete, messages.deleteDialog, messages.restore — методы для удаления и восстановления сообщений и диалогов;
- messages.search — метод для поиска по сообщениям;
- messages.allowMessagesFromGroup, messages.denyMessagesFromGroup — методы для подписки на сообщения сообщества и запрета на получение сообщений;
- docs.getWallUploadServer, docs.save, photos.getMessagesUploadServer, photos.saveMessagesPhoto — методы для загрузки фотографий и документов.
- groups.getCallbackConfirmationCode, groups.getCallbackServerSettings, groups.getCallbackSettings, groups.setCallbackServer, groups.setCallbackServerSettings, groups.setCallbackSettings — методы для работы с настройками Callback API.
Параметр start_message_id используется для защиты от смещения из-за новых сообщений при подгрузке старых диалогов. При первом вызове не передавайте start_message_id, «запомните» значение id у сообщения в первом диалоге и используйте его в качестве start_message_id в последующих вызовах при подгрузке диалогов.
Передавайте в start_message_id значение id сообщения в первом диалоге, в count максимальное количество новых диалогов, а в offset, соответственно, отрицательное значение.
Чтобы получить историю конкретного диалога, используйте параметр peer_id. Параметр start_message_id используется для защиты от смещения из-за новых сообщений при подгрузке истории. При первом вызове не передавайте start_message_id, «запомните» значение id первого сообщения из ответа и используйте его в качестве start_message_id в последующих вызовах.
Callback API позволяет мгновенно получать информацию о новых сообщениях в адрес сообщества.
Для работы с Callback API Вам потребуется серверный скрипт для обработки уведомлений. Настройте оповещения, следуя документации, среди типов событий выберите «Получение нового сообщения» (message_new).
ВКонтакте будет отправлять на Ваш сервер оповещение о каждом новом сообщении в таком формате:
В уведомлении содержится исчерпывающая информация о сообщении — Вы можете сразу ответить на него, используя метод messages.send.
vk.me — это сервис коротких URL, который перенаправляет пользователей в указанный диалог.
Ссылка имеет формат http://vk.me/
Вы можете не только создать красивую ссылку на диалог с сообществом, но и передать в такой ссылке произвольные параметры ref и ref_source, которые вернутся в объекте сообщения в событии message_new Callback API или Bots Long Poll API, в случае если пользователь начнет или продолжит беседу по ссылке вида vk.me.
Это полезно для отслеживания эффективности ссылок, размещенных в разных каналах, или привязки пользователя к сеансу или аккаунту во внешнем приложении. В зависимости от переданного параметра можно варьировать ответы бота в сообществе.
Источник
Как настроить api вконтакте
В этом руководстве вы найдете базовую информацию о принципах работы API ВКонтакте и о подготовке к его использованию. Если вы уже работали с нашим API или с аналогичными сервисами других платформ, и знаете, какое приложение хотите создать, мы рекомендуем вам перейти в соответствующий раздел документации.
API (application programming interface) — это посредник между разработчиком приложений и какой-либо средой, с которой это приложение должно взаимодействовать. API упрощает создание кода, поскольку предоставляет набор готовых классов, функций или структур для работы с имеющимися данными.
API ВКонтакте — это интерфейс, который позволяет получать информацию из базы данных vk.com с помощью http-запросов к специальному серверу. Вам не нужно знать в подробностях, как устроена база, из каких таблиц и полей каких типов она состоит — достаточно того, что API-запрос об этом «знает». Синтаксис запросов и тип возвращаемых ими данных строго определены на стороне самого сервиса.
Например, для получения данных о пользователе с идентификатором 210700286 необходимо составить запрос такого вида:
Рассмотрим отдельно все его составляющие.
- https:// — протокол соединения.
- api.vk.com/method — адрес API-сервиса.
- users.get — название метода API ВКонтакте. Методы представляют собой условные команды, которые соответствуют той или иной операции с базой данных — получение информации, запись или удаление. Например, users.get — метод для получения информации о пользователе, video.add — метод для добавления видеозаписи в свой список, likes.delete — метод для удаления отметки «Мне нравится».
Все методы разделены на секции. Например, для работы с сообществами вам нужны методы секции groups, для работы с фотографиями — photos, и так далее. Полный список методов по секциям доступен на этой странице.
В ответ сервер вернет JSON-объект с запрошенными данными (или сообщение об ошибке, если что-то пошло не так). JSON — это формат записи данных в виде пар «имя свойства»: «значение». Если вы раньше не встречались с этим форматом, мы рекомендуем познакомиться с ним, прежде чем продолжить чтение: JSON, Wikipedia
Ответ на наш запрос выглядит так:
Структура ответа каждого метода также строго задана, и при работе с API вы заранее знаете, что в поле id придет число, а в поле first_name — строка. Такие правила оговариваются на страницах с описанием метода и соответствующих объектов, которые он возвращает в ответе. Например, users.get — здесь описаны входные параметры метода и структура его ответа, а здесь — user подробно расписано каждое поле объекта из ответа.
Если вы уже имеете опыт работы с JSON, вам также может быть полезна информация о JSON схеме API ВКонтакте: JSON схема API ВКонтакте.
Объект из ответа может быть не уникален для конкретного метода. Например, объект пользователя с набором полей, содержащих данные о его образовании, возрасте, интересах, может возвращаться в ответе от методов users.get, users.search, groups.getMembers и еще нескольких.
В примере мы использовали метод users.get, который позволяет получить информацию о пользователях, но для разработки приложений этого будет мало. Чтобы использовать все возможности API ВКонтакте, нужно зарегистрировать своё приложение.
Выберите Мои приложения в верхнем меню и нажмите кнопку Создать. Создать приложение можно для одной из четырех платформ:
- Встраиваемое приложение — вы получите приложение, которое можно встроить во фрейм с внешного сайта. Готовые приложения можно увидеть в наших каталогах: Мини-приложения, Игры.
- Standalone-приложение — вы получите API_ID для внешнего сайта, мобильного или десктопного клиента. Основная мысль в том, что запросы к API должны отправляться с устройства пользователя. В интерфейсе такого приложения можно настроить SDK и подключить сертификаты для push-уведомлений.
- Сайт — вы получите API_ID для внешнего сайта и работы с API через сервер. Если вы хотите написать скрипт (например, на PHP), который будет обращаться к API ВКонтакте, выберите именно этот вариант.
- Скилл Маруси — платформа для создания приложений, которые взаимодействуют с голосовым помощником.
Совет. Если вы пока не знаете, какую платформу выбрать, используйте Standalone-приложение. Мы обычно рекомендуем его для тренировки.
ВКонтакте — социальная сеть, где есть дружеские связи, настройки приватности и даже черные списки. Многое зависит от того, кто просматривает страницу: кто-то увидит на ней всю ту же информацию, что и владелец, а кто-то — лишь общедоступные данные.
В API этот принцип сохраняется. Если вы скрыли список своих групп от не-друзей, то и через API ваши не-друзья не должны его увидеть. Поэтому почти все методы требуют авторизации пользователя перед началом работы. Проще говоря, сервер должен знать, кто к нему обращается за информацией, чтобы предоставить ее в том же виде, что и в основной версии сайта.
В общем случае для идентификации в API используется специальный ключ доступа, который называется access_token. Токен — это строка из цифр и латинских букв, которую вы передаете на сервер вместе с запросом. Из этой строки сервер получает всю нужную ему информацию. Есть разные способы получения токена, более того, он может быть выдан не только пользователю, но и сообществу, и сразу всему приложению — подробнее об этом вы можете прочитать здесь.
Мы воспользуемся самым простым способом (Implicit flow) и получим токен для работы с API из созданного вами на прошлом этапе приложения.
Откройте новую вкладку в браузере и введите в адресную строку такой запрос:
Число 5490057 в запросе нужно заменить на API_ID вашего приложения.
Нажмите Enter. Откроется окно с запросом прав. В нем отображаются название приложения, иконки прав доступа, и ваши имя с фамилией.
Нажмите «Разрешить». Вы попадете на новую страницу с предупреждением о том, что токен нельзя копировать и передавать третьим лицам. В адресной строке будет URL https://oauth.vk.com/blank.html, а после # вы увидите дополнительные параметры — access_token, expires_in и user_id. Токен может выглядеть, например, так:
Токен — это ваш ключ доступа. При выполнении определенных условий человек, получивший ваш токен, может нанести существенный ущерб вашим данным и данным других людей. Поэтому очень важно не передавать свой токен третьим лицам.
Поле expires_in содержит время жизни токена в секундах. 86400 секунд — это ровно сутки. Через сутки полученный токен перестанет действовать, для продолжения работы нужно будет получить новый. Есть возможность получить токен без срока действия — для этого в scope добавьте значение offline. Вы можете принудительно отозвать токен (например, в том случае, если он стал известен постороннему), сбросив сеансы в настройках безопасности вашего аккаунта или сменив пароль. Также, если речь идет о токене не из вашего собственного приложения, можно просто удалить приложение из настроек: https://vk.com/settings?act=apps
Поле user_id содержит id пользователя, для которого получен токен.
Теперь вы можете сделать вызов метода от своего имени. Например, получить список друзей, которые сейчас находятся на сайте.
Для этого введите в адресную строку:
и вставьте после знака «=» Ваш access_token, затем нажмите Enter. В ответе сервер вернет список идентификаторов ваших друзей, которые сейчас онлайн. Почитать подробнее о работе этого метода можно здесь. Заметьте, вы не указали в запросе, для какого пользователя (user_id) нужно получить список — сервер использовал значение по умолчанию, т.е. ваш идентификатор, который он получил из токена.
Подробное руководство о получении ключей доступа находится на этой странице.
Как вы уже знаете, все методы делятся на секции — friends, photos, video и так далее. Каждая секция соответствует определенному разделу на сайте. Часто приложения создаются для работы с конкретным разделом. Например, для просмотра фотографий или для редактирования видео. При этом логично, что приложению, которое работает только с аудиозаписями пользователя, не нужен доступ одновременно и к его личным сообщениям.
Поэтому в API права доступа приложения разграничены, как и методы. Приложение может запросить доступ только к группам, а может — к группам, фотографиям и аудиозаписям. На этой странице перечислены все существующие права доступа, которые можно запросить.
Чтобы запросить права, используйте параметр scope диалога авторизации. Когда вы получали токен для своего приложения, в scope было указано значение friends — и в окне авторизации приложение запросило доступ к друзьям.
У каждого права доступа есть уникальное название («friends», «video» и т.д.) и код (+2, +4, +4096).
В scope можно перечислить названия нужных прав доступа (например, scope=friends,video,photos), а можно указать сумму их кодов (например, scope=22). Каждый код представляет собой степень двойки, и полученную таким образом сумму (битовую маску) вы всегда можете проверить на предмет содержания какого-то конкретного кода (см. account.getAppPermissions).
Некоторые права доступа из соображений безопасности можно запрашивать только в Standalone-приложениях и только в процессе авторизации Implicit Flow, обратите на это внимание.
Вы познакомились с основными понятиями, связанными с API ВКонтакте. Дальше все зависит лишь от вашего вдохновения.
Конечно, на практике никто не работает с API из соседней вкладки браузера. Для этого используют самые разные языки программирования, SDK, генераторы кода. Сам механизм работы с API весьма прост, средства для отправки http-запросов и обработки ответа от сервера предусмотрены практически в любой среде разработки: а значит, возможность выбора всегда есть.
Источник
