# Authorization Code Flow для получения ключа доступа пользователя

Используйте Authorization Code Flow для вызова методов API ВКонтакте с серверной части вашего приложения (например, из PHP). Ключ доступа, полученный таким способом, не привязан к IP-адресу, но набор прав, которые может получить приложение, ограничен из соображений безопасности.

## Открытие диалога авторизации

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения.  
* `redirect_uri` (**обязательный**) — адрес, на который будет передан `code` (домен указанного адреса должен соответствовать основному домену в настройках приложения и перечисленным значениям в списке доверенных `redirect uri`, адреса сравниваются вплоть до `path`-части).  
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты: 
    *  `page` — форма авторизации в отдельном окне;  
    *  `popup` — всплывающее окно;  
    *  `mobile` — авторизация для мобильных устройств (без использования Javascript)  Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`. 
* `scope` –  битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации пользователя и запросить отсутствующие.  
* `response_type` — тип ответа, который вы хотите получить (укажите `code`).  
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.  

Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&display=page&redirect_uri=http://example.com/callback&scope=friends&response_type=code&v=:version
```

Если пользователь не вошел на сайт, то в диалоговом окне ему будет предложено ввести свой логин и пароль. 

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

Обратите внимание, что некоторые [права доступа](reference/access-rights)  пользователя из списка (например, `messages`) могут быть запрошены только Standalone-приложением — что означает необходимость использования [Implicit Flow](api/access-token/implicit-flow-user) для запроса таких прав. 

## Получение code

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом код для получения ключа доступа `code` будет передан как `GET`-параметр: 

```
REDIRECT_URI?code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a 
```

Параметр `code` может быть использован в течение 1 часа для получения ключа доступа к API `access_token` с вашего сервера. 

В случае возникновения ошибки браузер пользователя будет перенаправлен с кодом и описанием ошибки: 

```
REDIRECT_URI?error=invalid_request&error_description=Invalid+display+parameter 
```

## Получение access_token

Для получения `access_token` необходимо выполнить запрос с вашего сервера на [https://oauth.vk.com/access_token](https://oauth.vk.com/access_token), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения. 
* `client_secret` (**обязательный**) — защищенный ключ вашего приложения (указан в настройках приложения).  
* `redirect_uri` (**обязательный**) — URL, который использовался при получении `code` на первом этапе авторизации. Должен быть аналогичен переданному при авторизации.  
* `code` (**обязательный**) — временный код, полученный после прохождения авторизации. 

Пример запроса:

```
https://oauth.vk.com/access_token?client_id=1&client_secret=H2Pk8htyFD8024mZaPHm&redirect_uri=http://mysite.ru&code=7a6fa4dff77a228eeda56603b8f53806c883f011c40b72630bb50df056f6479e52a
```

В результате выполнения данного запроса ваш сервер получит вновь созданный `access_token`. Вместе с `access_token` серверу возвращается время жизни ключа `expires_in` в секундах. `expires_in` содержит `0`, если токен бессрочный (при использовании `scope` = `offline`). Процедуру авторизации приложения необходимо повторять в случае истечения срока действия `access_token`, смены пользователем своего логина или пароля или удаления приложения из настроек. 

```JSON
{
  "access_token": "533bacf01e11f55b536a565b57531ac114461ae8736d6506a3",
  "expires_in": 43200,
  "user_id": 66748
}
```

Если у пользователя указан email, а приложением были запрошены соответствующие [права](reference/access-rights), сервер также вернет `email` пользователя. 

В случае ошибки будут переданы параметры `error` и `error_description`.

```JSON
{
  "error": "invalid_grant",
  "error_description": "Code is expired."
}
```

Использование API | Ключ доступа | Authorization Code Flow для получения ключа доступа пользователя

# Общие сведения

Для работы со всеми методами API вам необходимо передавать в запросе `access_token` — специальный ключ доступа. Он представляет собой строку из латинских букв и цифр и может соответствовать отдельному пользователю, сообществу или самому вашему приложению.  

В API ВКонтакте для получения ключа доступа используется открытый [протокол OAuth 2.0](https://oauth.net/2/). При этом пользователь не передает логин и пароль приложению, поэтому его аккаунт не может быть скомпрометирован. 

Мы поддерживаем три способа получения ключа доступа по OAuth 2.0:

1. Implicit flow — самый короткий и простой вариант. Ключ возвращается на устройство пользователя, где был открыт диалог авторизации (в виде дополнительного параметра URL). Такой ключ может быть использован только для запросов непосредственно с устройства пользователя (например, для выполнения вызовов из Javascript на веб-сайте или из мобильного приложения). 

2. Authorization code flow — двухэтапный вариант с дополнительной аутентификацией вашего сервера. Ключ доступа возвращается непосредственно на сервер и может быть использован, например, для автоматизированных запросов из PHP. 

3. Client credentials flow — авторизация по секретному ключу приложения. Этот подход необходимо использовать только для доступа к специальным [secure](method/secure)-методам. 

## Ключ доступа пользователя

Такой ключ требуется для работы со всеми [методами](method) нашего API, за исключением методов секции [`secure`](method/secure). 

**Ключ доступа** — своего рода «подпись» пользователя в вашем приложении. Он сообщает серверу, от имени какого пользователя осуществляются запросы, и какие [права доступа](reference/access-rights) он выдал вашему приложению. 

Получить ключ доступа пользователя можно одним из этих способов:

*  [Implicit flow](api/access-token/implicit-flow-user). Для работы с API от имени пользователя в Javascript-приложениях и Standalone-клиентах (десктопных или мобильных). 
*  [Authorization code flow](api/access-token/authcode-flow-user). Для работы с API от имени пользователя с серверной стороны вашего сайта. 

В iFrame и Flash-приложениях ключ доступа передается при запуске с [остальными параметрами](api/app-run-parameters), вам не нужно самостоятельно реализовывать работу с OAuth. 

## Ключ доступа сообщества

Такой ключ позволяет работать с API от имени группы, встречи или публичной страницы. Например, с его помощью вы можете отвечать подписчикам сообщества на сообщения, поступившие в его адрес. 

С ключом доступа сообщества можно вызывать те методы, которые имеют специальную пометку в общем [списке](reference). 

Получить ключ доступа сообщества можно одним из этих способов:

*  [Implicit flow](api/access-token/implicit-flow-community). Для работы с API от имени сообщества в Javascript-приложениях и Standalone-клиентах (десктопных или мобильных). 
*  [Authorization code flow](api/access-token/authcode-flow-community). Для работы с API от имени сообщества с серверной стороны вашего сайта. 
*  В интерфейсе настроек сообщества. Для этого достаточно открыть раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выбрать вкладку **Работа с API** и нажать **Создать ключ доступа**. 

## Сервисный ключ доступа

Сервисный ключ нужен для запросов, которые не требуют авторизации пользователя или сообщества. Это такие методы, как [`secure.sendNotification`](method/secure.sendNotification) для отправки уведомлений от приложения, или [`secure.addAppEvent`](method/secure.addAppEvent) для добавления информации о достижениях, а также открытые методы, например, [`users.get`](method/users.get). 

Получить сервисный ключ доступа можно в [настройках вашего приложения](mini-apps/management/settings). Ключ не привязан к IP-адресу при использовании с открытыми методами, срок его действия не ограничен. Если ключ был скомпрометирован, вы можете сгенерировать новый ключ, при этом старый будет аннулирован.

Сервисный ключ доступа идентифицирует ваше приложение. Все запросы к API, совершённые с использованием вашего ключа доступа, будут считаться совершёнными от имени вашего приложения. Сервисный ключ доступа можно использовать только для запросов с серверной стороны приложения, его нельзя передавать и хранить на клиенте. 

## Дополнительно

*  Если вы разрабатываете приложение для iOS, Android или Windows Phone, мы рекомендуем использовать наши [мобильные SDK](sdk/overview) с возможностью авторизации через официальное приложение, установленное на устройстве клиента. 
*  Для встраиваемых iFrame приложений вам не нужно самостоятельно внедрять OAuth для работы с клиента, ключ доступа передается в приложение при запуске (подробнее см. на [этой странице](api/app-run-parameters)). 
*  Для внешних сайтов доступен [виджет авторизации](widgets/auth) — готовое решение для Implicit Flow на веб-сервисе.


Использование API | Ключ доступа | Общие сведения

# Implicit Flow для получения ключа доступа сообщества

Используйте Implicit Flow для вызова методов API ВКонтакте непосредственно с устройства пользователя (например, из Javascript).

## Получение списка администрируемых сообществ

Получить ключ доступа сообщества через OAuth может только его администратор. Чтобы получить ключи доступа сразу для всех или нескольких сообществ пользователя, мы рекомендуем добавить этот дополнительный шаг в процесс авторизации.

Получите ключ доступа пользователя ([для работы с клиента](api/access-token/implicit-flow-user) или [для работы с сервера](api/access-token/authcode-flow-user)) с правами `scope`=`groups` и сделайте запрос к методу [groups.get](groups.get) с параметром `filter`=`admin`, чтобы получить список идентификаторов администрируемых сообществ.

Затем используйте все полученные значения или их часть в качестве параметра `group_ids`.

## Открытие диалога авторизации

Перед открытием диалога авторизации мы рекомендуем убедиться, что пользователь является администратором сообщества, для которого необходимо получить ключ доступа

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения. 
* `redirect_uri` (**обязательный**) — адрес, на который будет переадресован пользователь после прохождения авторизации.
* `group_ids` (**обязательный**) —  идентификаторы сообществ, для которых необходимо получить ключ доступа. Параметр должен представлять собой строку, содержащую значения без знака «минус», разделенные запятой.
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты: 
    * `page` — форма авторизации в отдельном окне; 
    * `popup` — всплывающее окно; 
    * `mobile` — авторизация для мобильных устройств (без использования Javascript) 

Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`.
* `scope` — битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации и запросить отсутствующие. Сейчас доступны: `manage`,`messages`,`photos`,`docs`.
* `response_type` — тип ответа, который необходимо получить. Укажите `token`.
* `v` (обязательный) — [версия API](reference/versions), которую вы используете. Актуальная версия: `:version`.
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.  


Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&group_ids=1,123456&display=page&redirect_uri=http://example.com/callback&scope=messages&response_type=token&v=:version
```

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

Сейчас для ключей сообщества приложение любого типа может запрашивать права `manage`,`messages`,`photos`,`docs`. Методы, доступные с ключом доступа сообщества, помечены в общем [списке](method) специальным значком.

## Получение access_token

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом ключ доступа к API `access_token` и другие параметры будут переданы в URL-фрагменте ссылки:

```
http://REDIRECT_URI#access_token_XXXXXX= 533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400
```

Здесь `XXXXXX` — идентификатор сообщества, для которого был запрошен ключ доступа.

В случае возникновения ошибки авторизации в качестве `GET`-параметров в `redirect_uri` будет передана информация об этой ошибке. 

```
http://REDIRECT_URI#error=access_denied&error_description=The+user+or+authorization+server+denied+the+request.
```

Использование API | Ключ доступа | Implicit Flow для получения ключа доступа сообщества

# Implicit Flow для получения ключа доступа пользователя

> Для приложений на iOS, Android, Windows Phone мы рекомендуем использовать [упрощенную схему авторизации через SDK](sdk/overview). 

Используйте Implicit Flow для вызова методов API ВКонтакте непосредственно с устройства пользователя (например, из Javascript). Ключ доступа, полученный таким способом, не может быть использован для запросов с сервера.

## Открытие диалога авторизации

Необходимо перенаправить браузер пользователя по адресу
[`https://oauth.vk.com/authorize`](https://oauth.vk.com/authorize), передав следующие параметры:

* `client_id` (**обязательный**) — идентификатор вашего приложения.
* `redirect_uri` (**обязательный**) — адрес, на который будет переадресован пользователь после прохождения авторизации (см. [`redirect_uri`](#Redirect_uri)).
* `display` — указывает тип отображения страницы авторизации. Поддерживаются следующие варианты:

    * `page` — форма авторизации в отдельном окне;
    * `popup` — всплывающее окно;
    * `mobile` — авторизация для мобильных устройств (без использования Javascript)

    Если пользователь авторизуется с мобильного устройства, будет использован тип `mobile`.
* `scope` — битовая маска [настроек доступа приложения](reference/access-rights), которые необходимо проверить при авторизации пользователя и запросить отсутствующие.
* `response_type` — тип ответа, который необходимо получить. Укажите `token`.
* `state` — произвольная строка, которая будет возвращена вместе с результатом авторизации.
* `revoke=1` — параметр, указывающий, что необходимо не пропускать этап подтверждения прав, даже если пользователь уже авторизован.

Пример запроса:

```
https://oauth.vk.com/authorize?client_id=1&display=page&redirect_uri=http://example.com/callback&scope=friends&response_type=token&v=:version&state=123456
```

### Redirect_uri

**Redirect_uri** — это URL, на который будет переадресован браузер пользователя после разрешения им прав доступа. 

Если вы разрабатываете веб-приложение и хотите работать с API из Javascript, в `redirect_uri` необходимо указать адрес страницы на Вашем сайте. В целях безопасности, этот адрес также должен быть указан в настройках вашего приложения (поля «Адрес сайта», «Базовый домен» и «Доверенный Redirect URI»). 

> **Обратите внимание**, вы не сможете работать с методами, которые помечены как доступные только для Standalone-приложений. Во всех остальных случаях (мобильное, десктопное приложение) необходимо использовать `redirect_uri` по умолчанию: [`https://oauth.vk.com/blank.html`](https://oauth.vk.com/blank.html)

Если пользователь не авторизован ВКонтакте в используемом браузере, то в диалоговом окне ему будет предложено ввести свой логин и пароль.

## Разрешение прав доступа

После успешного входа на сайт пользователю будет предложено авторизовать приложение, разрешив доступ к необходимым настройкам, запрошенным при помощи параметра `scope`. Полный список настроек доступен в разделе [прав доступа приложений](reference/access-rights).  

С ключом пользователя, полученным в Implicit Flow, можно работать с наибольшим количеством прав доступа и соответствующих методов по сравнению с остальными способами авторизации. 

>  **Обратите внимание,** что некоторые права могут быть запрошены только Standalone-приложением (например, право доступа `messages`). Это автоматически означает необходимость использования `redirect_uri` по умолчанию (см. [`redirect_uri`](#Redirect_uri)).


## Получение access_token

После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу `redirect_uri`, указанному при открытии диалога авторизации. При этом ключ доступа к API `access_token` и другие параметры будут переданы в URL-фрагменте ссылки:

```
http://REDIRECT_URI#access_token=533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400&user_id=8492&state=123456
```

Вместе с ключом `access_token` также будет указано время его жизни `expires_in`, заданное в секундах. `expires_in` содержит `0`, если токен бессрочный (при использовании `scope` = `offline`). Если срок использования ключа истек, то необходимо повторно провести все описанные выше шаги, но в этом случае пользователю уже не придется дважды разрешать доступ. Запрашивать `access_token` также необходимо при смене пользователем логина или пароля или удалением приложения в настройках доступа. 

Кроме того, среди возвращаемых параметров будет указан `user_id` — идентификатор авторизовавшегося пользователя. 

В случае возникновения ошибки авторизации в качестве GET-параметров в `redirect_uri` будет передана информация об этой ошибке. 

```
http://REDIRECT_URI#error=access_denied&error_description=The+user+or+authorization+server+denied+the+request.
```

Использование API | Ключ доступа | Implicit Flow для получения ключа доступа пользователя

Интеграция | Чат-боты | Разработка | Сообщения

# Быстрый старт

**Чат-бот** — это скрипт на вашем сервере, который получает уведомления о новых событиях из ВКонтакте и обрабатывает их. Например, определяет текстовую команду в сообщении от пользователя и присылает в ответ какое-нибудь изображение.

Для создания бота вам потребуются:
*  Сообщество, от имени которого ваш бот будет общаться с пользователями ВКонтакте.
*  Сервер, который будет принимать уведомления о событиях.
*  Логика самого бота — скрипт, который определяет, как бот реагирует на то или иное событие.

В первую очередь вам нужно продумать функциональность чат-бота. Составьте список возможных текстовых команд или событий, на которые бот должен реагировать, и соответствующие им ответные действия бота. Стоит помнить, что люди могут ошибаться, набирая команды, и присылать боту текст, который отличается от всех учтённых вами вариантов — важно предусмотреть действие по умолчанию (можно в таком случае присылать пользователю список всех поддерживаемых команд).

> Если ранее вы не работали с API ВКонтакте, перед началом работы мы рекомендуем вам прочитать [это руководство](api/getting-started).


## Примеры реализации

### PHP

[VK PHP Бот](https://vk.com/botexample), созданный нашим разработчиком на PHP. Для обработки событий используется Callback API, голосовые сообщения генерируются с помощью API [Яндекс SpeechKit](https://tech.yandex.ru/speechkit/). [Код проекта на GitHub](https://github.com/VKCOM/bot-example-php). 

### Java

Бот для работы с Youtrack, созданный нашими разработчиками на Java ([Java SDK](sdk/java)). Для обработки событий используется Callback API. [Код проекта на GitHub](https://github.com/VKCOM/vk-java-sdk/wiki/YouTrack-bot). 

### JS

Библиотека для работы с ботами на Node JS, автор [Михаил Семин](https://vk.com/bifot). Используется Long Poll, предусмотрена возможность быстро и удобно добавлять новые команды и реакции. [Код проекта на GitHub](https://github.com/bifot/node-vk-bot-api). 

## Сообщество

Для подключения чат-бота вы можете использовать любое своё сообщество ВКонтакте — группу, встречу или публичную страницу. Ваш бот должен соответствовать правилам, подробнее о них вы можете узнать [здесь](bots-rules).

Первым делом нужно указать, что в вашем сообществе будет работать бот. Для этого перейдите в **Управление сообществом** → **Сообщения** → **Настройки для бота** и включите пункт **Возможности ботов**.

Сообщество — это точка входа для пользователей, которые будут общаться с вашим ботом. Стоит позаботиться о том, чтобы оно выглядело привлекательно и содержало описание вашего бота, иначе его действия могут стать сюрпризом для пользователей. Не забудьте включить сообщения в вашем сообществе (**Управление сообществом** → **Сообщения**), когда бот будет готов к использованию, чтобы ему можно было написать. 

Итак, если вы выбрали сообщество, можно приступать к настройке уведомлений.

### Получение ключа доступа

Ключ доступа потребуется вам для получения обновлений (в Long Poll), а также для работы с API. 

Откройте раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выберите вкладку **Работа с API** и нажмите  **Создать ключ доступа**.

Отметьте необходимые права доступа и подтвердите свой выбор. 

![](94dbda6f9957847362a13776b0676208b2cedee8d63b617201bc5742 "-8033473622113514247")

Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.

Также вы можете получить ключ доступа с помощью OAuth. Используйте схему авторизации [Authorization Code Flow](api/access-token/authcode-flow-user).

### Добавление ботов в беседы

Чтобы пользователи смогли добавлять бота в беседы, необходимо включить эту возможность в настройках. Перейдите в **Управление сообществом** →**Сообщения** →**Настройки для бота** и поставьте галочку в пункте **Разрешать добавлять сообщество в беседы**. После этого в  сообществе появится кнопка **Пригласить в беседу**, открывающая модальное окно со списком бесед.

Сейчас у бота в беседе есть три уровня доступа:

#### Только упоминания

Этот уровень доступа выдается сразу после добавления в беседу. Бот может:
*  видеть все сообщения, которые его касаются. Это упоминания бота и ответы на его сообщения
*  отправлять сообщения в беседу

#### Доступ ко всей переписке

Выдать его может любой администратор беседы. Бот может:
*  видеть все сообщения в беседе 
*  отправлять сообщения в беседу

#### Администратор

Выдать его может только создатель беседы. Бот может:
*  видеть все сообщения в беседе 
*  отправлять сообщения в беседу
*  Получать [объект беседы](reference/objects/conversation)
*  Получать участников беседы

>  **Важно!** Для получения событий из беседы версия API у callback-сервера должна быть не ниже 5.80.

## Получение событий и обновлений

Чтобы реагировать на какие-либо события, ваш скрипт должен о них узнать. Для этого существуют два подхода — Callback API и Long Poll.

### Callback API

Callback API присылает уведомления на ваш сервер, как только в сообществе происходит нужное событие. Событие может быть каким угодно: комментарий к фотографии, новая запись на стене, вступление в сообщество, отправка сообщения, и многое другое. Посмотреть полный список доступных событий, а также прочитать подробнее о настройке вы можете [в документации Callback API](api/callback/getting-started).

Для подключения Callback API в сообществе нужно указать адрес скрипта на вашем сервере и выбрать события, которые Вы хотите получать. Например, если ваш бот должен распознавать текстовые команды, отметьте событие **Входящее сообщение**.

Уведомления от Callback API выглядят как JSON с основной информацией о событии:
```JSON
{  
   "type":"message_new",
   "object":{  
      "id":694,
      "date":1499441696,
      "out":0,
      "user_id":123456,
      "read_state":0,
      "title":" ... ",
      "body":"start"
   },
   "group_id":1,
   "secret":"sjr948dff3kjnfd3"
}
```
В этом примере пользователь с `id` = `123456` отправил сообществу сообщение с текстом `start`. 

Для каждого события Callback API отправляет отдельный запрос на ваш сервер. Ваш скрипт должен подтверждать получение каждого запроса, отправляя в ответ строку `ok`.

### Пример на PHP
```PHP
<?
define('CALLBACK_API_CONFIRMATION_TOKEN', '213fefef3');  // Строка, которую должен вернуть сервер
define('VK_API_ACCESS_TOKEN', '016cb552 ... 989fb8345');   // Ключ доступа сообщества

define('CALLBACK_API_EVENT_CONFIRMATION', 'confirmation'); // Тип события о подтверждении сервера
define('CALLBACK_API_EVENT_MESSAGE_NEW', 'message_new'); // Тип события о новом сообщении
define('VK_API_ENDPOINT', '[https://api.vk.com/method/]');   // Адрес обращения к API
define('VK_API_VERSION', '5.89'); // Используемая версия API

$event = json_decode(file_get_contents('php://input'), true);

switch ($event['type']) {
  // Подтверждение сервера
  case CALLBACK_API_EVENT_CONFIRMATION:
    echo(CALLBACK_API_CONFIRMATION_TOKEN);
    break;
  // Получение нового сообщения
  case CALLBACK_API_EVENT_MESSAGE_NEW:
    $message = $event['object'];
    $peer_id = $message['peer_id'] ?: $message['user_id'];
    send_message($peer_id, "Hello world! (peer_id: {$peer_id})");
    echo('ok');
    break;
  default:
    echo('Unsupported event');
    break;
}

function send_message($peer_id, $message) {
  api('messages.send', array(
    'peer_id' => $peer_id,
    'message' => $message,
  ));
}

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'];
}
```
[Скрипт полностью на GitHub](https://github.com/VKCOM/bot-example-php)

### Bots Long Poll API

Второй способ получения обновлений — это подключение к Bots Long Poll API. Прочитать подробнее о работе с Bots Long Poll API вы можете [на этой странице](api/bots-long-poll/getting-started).

Когда произойдет новое событие или истечет время ожидания, сервер вернет вам ответ в формате JSON:

```JSON
{
  "ts": "4",
  "updates": [
    {
      "type": "wall_post_new",
      "object": {
        "id": 28,
        "from_id": -123456,
        "owner_id": -123456,
        "date": 1519631591,
        "marked_as_ads": 0,
        "post_type": "post",
        "text": "Post text",
        "can_edit": 1,
        "created_by": 564321,
        "can_delete": 1,
        "comments": {
          "count": 0
        }
      },
      "group_id": 123456
    }
  ]
}
```

### Информация о доступных пользователю функциях

Некоторые функции ботов могут быть недоступны, так как пользователи:
*  переходят на новые версии официальных приложений ВКонтакте постепенно;
*  открывают ВКонтакте на разных платформах (iOS, Android, в мобильной и веб-версии);
*  используют приложения от сторонних разработчиков. Например, клавиатура ботов может быть недоступна в старой версии официального приложения ВКонтакте.

Отправляйте сообщения в нужном формате, исходя из возможностей, которые доступны пользователю. Если он не может воспользоваться клавиатурой, предложите варианты ответов и пронумеруйте их — чтобы можно было ответить цифрой. И наоборот: если пользователь может взаимодействовать с ботом с помощью клавиатуры — не нужно отправлять ему варианты ответа в тексте сообщения.

Начиная с версии API 5.103 информация о доступных функциях будет приходить вместе с событием [`message_new`](api/community-events/json-schema) в Callback API и Bots Long Poll API. Она будет находиться в объекте `client_info`:

```JSON
"client_info": { 
    "button_actions": [ 
      "text", 
      "vkpay", 
      "open_app", 
      "location", 
      "open_link", 
      "callback" 
    ], 
    "keyboard": true, 
    "inline_keyboard": true, 
    "carousel": false, 
    "lang_id": 0 
} 
```

По мере появления новых возможностей в объекте `client_info` и массиве `button_actions` могут появляться новые сущности.

Поля объекта:
*  `button_actions` — массив кнопок, которые поддерживает клиент. Возможные значения смотрите в разделе [Клавиатура](api/bots/development/keyboard#Структура%20данных);
*  `keyboard` (`bool`) — поддерживается ли клавиатура ботов клиентом;
*  `inline_keyboard` (`bool`) — поддерживается ли inline-клавиатура ботов клиентом;
*  `carousel` (`bool`) — поддерживаются ли [карусели](api/bots/development/messages) клиентом;
*  `lang_id` — [ID](api/api-requests) используемого языка.

Интеграция | Чат-боты | Быстрый старт

# Боты для сообществ

**Бот** — это программа, которая имитирует некоторые действия человека. С его помощью можно автоматизировать рутинные задачи. 

Они нужны там, где есть много похожих действий, которые сейчас выполняются руками (или не выполняются вовсе — просто потому что нет столько рук).

Бот может принять заказ в интернет-магазине, прислать подборку видеороликов, посоветовать подходящие концерты или ближайший ресторан. 

![](47b0490c93d3c32d6c544be551a8806fe61b18d0ea3a07e85e0fcb85 "-5636580476323788944")

ВКонтакте боты общаются с вашими клиентами через [сообщения сообществ](api/community-messages/getting-started).
Это простой и привычный для пользователя интерфейс.

Бот будет полезен, если вы хотите:
*  обрабатывать много однотипных обращений,
*  организовывать рассылки для подписчиков,
*  фильтровать заявки в системах поддержки,
*  мгновенно реагировать на сообщения.

Это самые распространенные сценарии. На самом деле, боты пригодятся в сообществе любой тематики. Можно придумать собственную реализацию, которая подошла бы для развития именно вашей группы или публичной страницы.

> Бот может стать дополнительным средством для привлечения внимания к сообществу. Создавайте интерактивные квесты, присылайте подписчикам мультимедиа-материалы, подключайте сторонние API для реализации игровых сценариев — пользователи не пройдут мимо интересных предложений.


## Преимущества платформы

### Социальный граф

ВКонтакте вы можете работать с социальным графом, анализируя связи и интересы пользователя. Например, для создания рекомендательной системы или сервиса персональной инфографики.

### Мультимедиа

Огромная библиотека медиаконтента, который можно использовать для создания подборок фотографий, видео или аудиозаписей.

### Кроссплатформенность

Сообщения сообществ работают в полной и мобильной версиях, а также во всех официальных клиентах. Это значит, что пользователь может взаимодействовать с ботом на любой платформе.

## Документация

Чтобы научиться создавать ботов ВКонтакте, прочитайте [Быстрый старт](api/bots/getting-started).

## Примеры ботов

* Бот [РБК](https://vk.com/rbc) предлагает подписаться на рассылку актуальных новостей, умеет принимать жалобы на опечатки и решает вопросы, связанные с размещением рекламы.
* Бот принимал обращения от граждан в рамках [Прямой линии с Владимиром Путиным](https://vk.com/moskvaputinu).
* Бот [Vinci](https://vk.com/vinci) обрабатывает присланную фотографию с помощью хитрых алгоритмов и предлагает подходящие теги и Emoji для подписи.

:::carousel
![title=Бот РБК предлагает подписаться на рассылку актуальных новостей, умеет принимать жалобы на опечатки и решает вопросы, связанные с размещением рекламы.](bd62819e0364f07d86ec1137cb419a1bda0aa63058cd4a7e657592d2 "-3327336004805555787")
![title=Бот принимал обращения от граждан в рамках Прямой линии с Владимиром Путиным.](60fac052a021f365547cc1655b896ebab720dd620b13c44658233f3f "-4939451182648991171")
![Бот Vinci обрабатывает присланную фотографию с помощью хитрых алгоритмов и предлагает подходящие теги и Emoji для подписи.](3b415358de0139ef4e6477cf045321cb9c20ca02f52f3ddc270a4caa "7598733202427498813")
:::

Интеграция | Чат-боты | Боты для сообществ

# Сообщения сообществ

Сообщения сообществ — сервис для прямого диалога между пользователем и сообществом ВКонтакте. 

![](45ee4961609a0b9362f7cedaf27e3c682d2e5bdb2f0e1304b6bf6486 "-5881812424441223520")

Это удобно для ваших клиентов. Не нужно искать форму обратной связи, проходить регистрацию, отвечать через email — никаких лишних действий.

Это удобно для вас. Вместе с сообщением вы получаете все необходимые данные о его авторе, можете автоматически обрабатывать типовые заявки и мгновенно отвечать на сообщения с помощью бота.

Миллионы пользователей предпочитают общаться с друзьями, близкими и деловыми партнерами именно ВКонтакте. Используя сервис сообщений, вы можете стать ближе к клиентам и поддерживать тесную связь с ними в привычном для них окружении.

Сообщения сообществ работают в полной и мобильной версиях ВКонтакте, а также во всех официальных приложениях:  с вашей компанией можно связаться на любой платформе.

![](7bc2a650a8d1ec1313f0acc698c6b3302a648aaea8b8102b6618e049 "9214525706664327534")

Подробнее обо всех преимуществах для бизнеса мы рассказали на [отдельной странице](https://vk.com/page-19542789_51260895).

## API для сообщений сообществ

В этом руководстве рассказывается о том, как использовать API для работы с сообщениями сообществ. 

## Ключ доступа

Для работы с API от имени сообщества необходимо получить специальный ключ доступа. Вы можете сделать это двумя способами — в интерфейсе управления сообществом или программно, с помощью специального запроса к нашему серверу.

Ключ доступа — это строка, включающая латинские буквы и цифры. Ее необходимо передавать в параметре `access_token`, обращаясь к методам API от имени сообщества.

## Получение ключа доступа в настройках сообщества

Откройте раздел **Управление сообществом** (**Управление страницей**, если у вас публичная страница), выберите вкладку **Работа с API** и нажмите  **Создать ключ доступа**.

Отметьте необходимые права доступа и подтвердите свой выбор. 
![](94dbda6f9957847362a13776b0676208b2cedee8d63b617201bc5742 "-8033473622113514247")

Вы можете создать несколько ключей с разными правами доступа. Ключи нельзя размещать публично — узнав его, третье лицо может обращаться к API ВКонтакте от имени вашего сообщества. Если ключ был скомпрометирован, необходимо удалить его из списка — после этого он станет недействителен.

## Получение ключа доступа на oauth.vk.com

Мы предлагаем два способа авторизации, основанных на протоколе OAuth 2.0. Используйте этот подход, если необходимо работать со многими сообществами пользователя, например, при разработке мобильного приложения. 

Для работы с API с серверной стороны используйте [Authorization Code Flow](api/access-token/authcode-flow-community).

Для работы с API со стороны клиента используйте [Implicit Flow](api/access-token/implicit-flow-community).

## Работа с сообщениями

В API сообщений сообществ используются те же методы, что и для работы с личными сообщениями пользователя. Если раньше вы уже имели дело с сообщениями в API ВКонтакте, схема работы будет вам знакома. Стоит, однако, учитывать некоторые особенности:
*  необходимо проставлять статус прочитанности сообщения при общении с клиентом; 
*  если ответ получен пользователем, его необходимо помечать как прочитанный; 
*  в диалогах сообществ доступны специальные метки: **Важные**, **Неотвеченные**, **Непрочитанные**. 

Чтобы вы могли отправлять пользователю сообщения от имени сообщества, пользователь должен разрешить их получение. Если пользователь написал сообщение сообществу первым, это приравнивается к согласию на получение ответных сообщений (без ограничений по времени, если пользователь не запретил сообщения вручную). Чтобы запросить у пользователя разрешение на отправку сообщений, используйте:
*  Метод [`showAllowMessagesFromCommunityBox`](sdk/javascript#showAllowMessagesFromCommunityBox) Client API в приложениях сообществ;
*  Метод [`messages.allowMessagesFromGroup`](method/messages.allowMessagesFromGroup) в Standalone-приложениях;
*  Виджет [Разрешить писать сообществу](widgets/allow-messages-from-community) на внешнем сайте.

В [Callback API](api/callback/getting-started) и [Bots Longpoll API](api/bots-long-poll/getting-started) события `message_allow` и `message_deny` помогут отслеживать факт разрешения и запрета сообщений от сообщества. **Обратите внимание**, получить список всех пользователей, разрешивших сообщения сообществу, через API нельзя, необходимо хранить и синхронизировать этот список на своей стороне.

## Доступные инструменты и методы

*  [Long Poll сервер](api/user-long-poll/getting-started) — синхронизация обновлений; 
*  [Callback API](api/callback/getting-started) — мгновенные оповещения о новых сообщениях и других действиях пользователей в сообществе.
*  [`messages.getDialogs`](method/messages.getDialogs) — метод для получения списка диалогов; 
*  [`messages.markAsRead`](method/messages.markAsRead) — метод для присвоения сообщению метки **Прочитано**;
*  [`messages.markAsImportantDialog`](method/messages.markAsImportantDialog), [`messages.markAsAnsweredDialog`](method/messages.markAsAnsweredDialog) — методы для присвоения меток диалогам;
*  [`messages.send`](method/messages.send) — метод для отправки нового сообщения;
*   [`messages.delete`](method/messages.delete), [`messages.deleteDialog`](method/messages.deleteDialog), [`messages.restore`](method/messages.restore) — методы для удаления и восстановления сообщений и диалогов;
*  [`messages.search`](method/messages.search) — метод для поиска по сообщениям;
*  [`messages.allowMessagesFromGroup`](method/messages.allowMessagesFromGroup), [`messages.denyMessagesFromGroup`](method/messages.denyMessagesFromGroup) — методы для подписки на сообщения сообщества и запрета на получение сообщений;
*   [`docs.getWallUploadServer`](method/docs.getWallUploadServer), [`docs.save`](method/docs.save), ,  — методы для загрузки фотографий и документов.
*  [`groups.getCallbackConfirmationCode`](method/groups.getCallbackConfirmationCode), [`groups.getCallbackServerSettings`](method/groups.getCallbackServerSettings), [`groups.getCallbackSettings`](method/groups.getCallbackSettings), [`groups.setCallbackSettings`](method/groups.setCallbackSettings) — методы для работы с настройками Callback API.

## Получение списка диалогов

Метод [`messages.getDialogs`](method/messages.getDialogs). 

Параметр `start_message_id` используется для защиты от смещения из-за новых сообщений при подгрузке старых диалогов. При первом вызове не передавайте `start_message_id`, запомните значение `id` у сообщения в первом диалоге и используйте его в качестве `start_message_id` в последующих вызовах при подгрузке диалогов.
 
```
https://api.vk.com/method/messages.getDialogs?v=5.41&access_token=ACCESS_TOKEN&count=10&offset=0
```

## Получение новых диалогов

Метод [`messages.getDialogs`](method/messages.getDialogs). 

Передавайте в `start_message_id` значение `id` сообщения в первом диалоге, в `count` максимальное количество новых диалогов, а в `offset`, соответственно, отрицательное значение. 

```
https://api.vk.com/method/messages.getDialogs?v=5.41&access_token=ACCESS_TOKEN&count=10&unread=1&offset=-10&start_message_id=64
```

## Получение истории сообщений в диалоге

Метод [`messages.getHistory`](method/messages.getHistory).

Чтобы получить историю конкретного диалога, используйте параметр `peer_id`. Параметр `start_message_id` используется для защиты от смещения из-за новых сообщений при подгрузке истории. При первом вызове не передавайте `start_message_id`, `запомните` значение `id` первого сообщения из ответа и используйте его в качестве `start_message_id` в последующих вызовах. 

```
https://api.vk.com/method/messages.getHistory?v=5.41&access_token=ACCESS_TOKEN&peer_id=494075&offset=0&count=10
```

```
https://api.vk.com/method/messages.getHistory?v=5.41&access_token=ACCESS_TOKEN&peer_id=494075&offset=10&count=10&start_message_id=60
```


## Получение новых сообщений с помощью Callback API

[Callback API](api/callback/getting-started) позволяет мгновенно получать информацию о новых сообщениях в адрес сообщества.

Для работы с Callback API вам потребуется серверный скрипт для обработки уведомлений. Настройте оповещения, следуя [документации](api/callback/getting-started), среди типов событий выберите **Получение нового сообщения** (`message_new`).

ВКонтакте будет отправлять на ваш сервер оповещение о каждом новом сообщении с [объектом личного сообщения](reference/objects/message) в таком формате:

```JSON
{
  "type": "message_new",
  "object": "..."
}
```

В уведомлении содержится исчерпывающая информация о сообщении — вы можете сразу ответить на него, используя метод [`messages.send`](method/messages.send).

## Передача произвольного параметра с помощью ссылки vk.me

vk.me — это сервис коротких URL, который перенаправляет пользователей в указанный диалог. 
Ссылка имеет формат http://vk.me/{group_name}, где `group_name` —  идентификатор сообщества. К примеру, vk.me/apiclub.

Вы можете  не только создать красивую ссылку на  диалог с сообществом, но и передать в такой ссылке произвольные параметры `ref` и `ref_source`, которые вернутся в объекте сообщения в [событии](api/community-events/json-schema) `message_new` [Callback API](api/callback/getting-started)  или [Bots Long Poll API](api/bots-long-poll/getting-started), в случае если пользователь начнет или продолжит беседу по ссылке вида vk.me.

Это полезно для отслеживания эффективности ссылок, размещенных в разных каналах, или привязки пользователя к сеансу или аккаунту во внешнем приложении. В зависимости от переданного параметра можно варьировать ответы бота в сообществе.

Ссылка vk.me с дополнительными параметрами выглядит следующим образом:

```
vk.me/{group_name}?ref={ref}&ref_source={ref_source}
```

Также сработает вот такая ссылка:

```
vk.com/write-{group_id}?ref={ref}&ref_source={ref_source}
```

## Отправка изображений

Чтобы отправить изображение в сообщении, используйте параметр `attachments` в методе [`messages.send`](method/messages.send). Вы можете использовать изображение, которое уже есть на сайте ВКонтакте, либо [загрузить новое](api/upload#Загрузка%20фотографии%20в%20личное%20сообщение).


Для загрузки фотографий и документов в сообщения сообщества используйте, соответственно, методы [`photos.getMessagesUploadServer`](method/photos.getMessagesUploadServer) и [`docs.getMessagesUploadServer`](method/docs.getMessagesUploadServer). Это позволит загружать вложения для неограниченного числа собеседников.

Интеграция | Сообщества и пользователи | Сообщения сообществ

# VK Donut API

**API ВКонтакте** позволяет получать информацию о платных подписках и подписчиках в сообществах, использующих [VK Donut](https://vk.com/@donut-faq), а также публиковать в них платный контент.

## Для кого этот раздел

Этот раздел для разработчиков приложений, которые хотят использовать API ВКонтакте. Вам будет проще, если вы уже знакомы с [API ВКонтакте](api/getting-started), методами [авторизации](api/access-token/getting-started) и знаете, что такое [VK Donut](https://vk.com/@donut-faq).

Если вы уже используете [VK Donut](https://vk.com/@donut-faq) и разобрались, как получить [ключ доступа](api/access-token/getting-started) к API ВКонтакте, переходите к разделу [Методы](#Методы). Если нет, сначала прочитайте раздел [Подготовка](#Подготовка).

## Подготовка

1. Подключите [VK Donut](https://vk.com/@donut-faq) в настройках сообщества.

2. [Создайте приложение](api/getting-started#Регистрация%20приложения). API можно использовать в приложении любого типа. Если вы пока не знаете, какой тип выбрать, создайте **Standalone-приложение**. Идентификатор приложения понадобится вам на следующем шаге, чтобы получить ключ доступа к API.

3. Получите [ключ доступа](api/access-token/getting-started). Ключ доступа нужно будет указывать во всех запросах из приложения (параметр `access_token`). Получить его можно разными способами. Всё зависит от того, какие [права доступа](reference/access-rights) вам нужны и как вы будете отправлять запросы (от имени пользователя или сообщества, со стороны клиента или сервера).

> **Совет.** Отправлять запросы можно прямо из [документации](method/donut.isDon). Идентификатор приложения и ключ доступа указывать не понадобится, достаточно войти в свой аккаунт ВКонтакте.

## Методы

В [запросе](api/api-requests) нужно указать:

* Метод. В таблице ниже собраны методы, которые понадобятся для работы с сообществами, использующими VK Donut. Название метода может начинаться с префиксов: [`donut`](method/donut.isDon), [`groups`](method/groups.getMembers), [`wall`](method/wall.post).

* Параметры. Обязательные параметры: `access_token` (ключ доступа) и `v` (версия API). В [справочнике методов](method) написано, к какой версии API относится каждый метод, какие ещё параметры есть у метода и какие нужны [права доступа](reference/access-rights). В запросе нужно указать тот ключ доступа, права доступа которого соответствуют методу.

### Пример

Чтобы узнать, является ли пользователь доном (так мы называем получателей платного контента в сообществе), отправьте запрос:

```
https://api.vk.com/method/donut.isDon?owner_id=-1&access_token=42&v=:version
```

В этом примере замените `-1` на идентификатор сообщества (со знаком минуса), а `42` — на ключ доступа пользователя.

> **Совет.** Войдите в свой аккаунт ВКонтакте и отправьте запрос прямо из [документации](method/donut.isDon).

### Методы, которые относятся к работе VK Donut

| Метод | Результат |
| --- | --- |
| [`donut.isDon`](method/donut.isDon) | Подписан ли пользователь на платный контент (является ли доном).|
| [`donut.getSubscription`](method/donut.getSubscription) | Стоимость подписки, статус, дата следующего платежа.|
| [`donut.getSubscriptions`](method/donut.getSubscriptions) | Подписки пользователя.|
| [`donut.getFriends`](method/donut.getFriends) | Список донов из числа друзей пользователя.|
| [`groups.getMembers`](method/groups.getMembers) | Список донов сообщества по ключу пользователя (ключ должен принадлежать как минимум редактору сообщества) и по ключу сообщества (см. параметр `filter`).|
| [`wall.post`](method/wall.post) | Публикует на стене запись только для донов. Позволяет задать время, через которое запись появится для всех подписчиков, то есть станет бесплатной (см. параметр `donut_paid_duration`).|
| [`wall.edit`](method/wall.edit) | Меняет значение параметра `donut_paid_duration`.|

## События

Вы можете получать информацию о [событиях](api/events/overview), которые происходят в вашем сообществе, с помощью:

* [Callback API](api/callback/getting-started). Мы будем отправлять на ваш сервер уведомление о каждом новом событии.
* [Bots Long Poll API](api/bots-long-poll/getting-started). Очередь из событий хранится на серверах ВКонтакте, вы получаете уведомления когда захотите, используя запросы.

### События, которые относятся к работе VK Donut

|Название события | Что произошло в сообществе |
| --- | --- |
|[`donut_subscription_create`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь оформил подписку.|
|[`donut_subscription_prolonged`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь продлил подписку.|
|[`donut_subscription_expired`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Подписка пользователя истекла.|
|[`donut_subscription_cancelled`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Пользователь отменил подписку.|
|[`subscription_price_changed`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Изменилась стоимость подписки.|
|[`donut_money_withdraw`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Руководитель сообщества вывел деньги.|
|[`donut_money_withdraw_error`](api/community-events/json-schema#Платные%20подписки%20VK%20Donut)|Ошибка при выводе денег.|

## FAQ

#### Зачем нужен VK Donut?

VK Donut позволяет руководителям сообществ принимать платежи от подписчиков.

#### Где ещё можно прочитать про VK Donut?

В [сообществе](https://vk.com/donut) есть [правила публикаций](https://vk.com/@donut-pravila) и подробный FAQ, в котором мы рассказали, например, про [платежи](https://vk.com/@donut-faq?anchor=chto-vybrat-kartu-ili-vk-pay).

#### Кто такие доны?

Доны — это получатели платного контента, которые подписываются на него с помощью VK Donut.

#### Как выглядит идентификатор сообщества?

Идентификатор сообщества — это целое число (порядковый номер). Например, на странице нашего официального сообщества указан `ID:` [192668858](https://vk.com/donut). Но при работе с API используется отрицательное число -192668858, чтобы отличить идентификатор сообщества от идентификатора пользователя.

#### Почему в примере идентификатор сообщества: `-1`?

Пользователи и сообщества нумеруются по порядку, поэтому у пользователя и сообщества может быть одинаковый идентификатор. Например, есть [пользователь](https://vk.com/id1) и [сообщество](https://vk.com/apiclub) с `ID:` 1. Если метод требует передать идентификатор пользователя, нужно указывать `owner_id=1` (положительное число), если идентификатор сообщества, то `owner_id=-1` (отрицательное число).

#### В запросах можно передавать `lang`?

Да. [Параметры, общие для всего API](api/api-requests#Общие%20параметры), можно использовать во всех методах API ВКонтакте.

#### Можно ли сделать платным бесплатный контент?

Нет, если запись уже опубликована. Можно, если вы создали [отложенную запись](api/posts#Публикации%20из%20приложений) и она ещё не опубликована.

#### Можно ли сделать бесплатным платный контент?

Да. Используйте метод [`wall.post`](method/wall.post), в запросе укажите идентификатор записи (`post_id`). Обратите внимание, что в этом случае создастся бесплатная копия платной записи. Но только одна — создать больше копий не получится.

#### Я создал запись для донов, но потом решил сделать её бесплатной пораньше. Можно ли изменить время, указанное в donut_paid_duration?

Да. Чтобы изменить значение `donut_paid_duration` (время, через которое платная запись должна стать бесплатной), нужно задать новое значение этого параметра с помощью метода [`wall.edit`](method/wall.edit). Обратите внимание, что когда время истечёт, появится копия платной записи.

Интеграция | Платежи | VK Donut API

# События в реальном времени

API ВКонтакте позволяет работать с событиями пользователя или сообщества в реальном времени. Это нужно для отображения нового сообщения, для моментальной реакции на комментарий в сообществе, для создания [чат-ботов](api/bots/overview) или для анализа текстовых данных.

## Для сообществ

Для работы с событиями сообществ мы предлагаем два разных подхода:

* [Callback API](api/callback/getting-started) — в этом случае мы будем отправлять уведомление на ваш сервер о каждом новом событии.
* [Bots Long Poll API](api/bots-long-poll/getting-started) — очередь из событий хранится на стороне ВКонтакте, вы получаете их, используя Long Polling запросы.

Callback API и Bots Long Poll API поддерживают события, связанные с сообщениями сообщества, активностью пользователей на стене и в остальных разделах вашей группы или публичной страницы. Полный список событий в сообществах вы можете найти [на этой странице](api/community-events/json-schema).

## Для пользователей

[User Long Poll API](api/user-long-poll/getting-started) нужен для работы с событиями пользователя в вашем приложении. Очередь из событий хранится на стороне ВКонтакте, вы получаете их, используя Long Polling запросы.

User Long Poll API поддерживает все события, связанные с личными сообщениями (получение, редактирование, удаление), изменение статуса онлайн или счётчиков в меню.

## Для аналитики

[Streaming API](api/streaming/getting-started) позволяет получать текстовые публикации из ВКонтакте по заданным ключевым словам, не совершая лишних поисковых запросов.

Streaming API доставляет данные с помощью технологии WebSocket. Благодаря этому инструменту вы можете проанализировать частоту, тональность и контекст упоминания вашего бренда ВКонтакте, провести социологическое исследование, и многое другое.

Интеграция | Сообщества и пользователи | События пользователей и сообществ

# Быстрый старт

В этом руководстве вы найдете базовую информацию о принципах работы API ВКонтакте и о подготовке к его использованию. Если вы уже работали с нашим API или с аналогичными сервисами других платформ, и знаете, какое приложение хотите создать, мы рекомендуем вам перейти в соответствующий раздел документации.

[API (application programming interface)](https://ru.wikipedia.org/wiki/API) — это посредник между разработчиком приложений и какой-либо средой, с которой это приложение должно взаимодействовать. API упрощает создание кода, поскольку предоставляет набор готовых классов, функций или структур для работы с имеющимися данными.

## Методы и объекты

**API ВКонтакте** — это интерфейс, который позволяет получать информацию из базы данных [vk.com](https://vk.com) с помощью http-запросов к специальному серверу.  Вам не нужно знать в подробностях, как устроена база, из каких таблиц и полей каких типов она состоит — достаточно того, что API-запрос об этом знает. Синтаксис запросов и тип возвращаемых ими данных строго определены на стороне самого сервиса. 

Например, для получения данных о пользователе с идентификатором `210700286` необходимо составить запрос такого вида:

```
https://api.vk.com/method/users.get?user_id=210700286&v=:version
```

Рассмотрим отдельно все его составляющие:

* `https://` — протокол соединения,
* `api.vk.com/method` — адрес API-сервиса,
* `users.get` — название метода API ВКонтакте,
* `?user_id= &v= ` — параметры запроса.

Методы представляют собой условные команды, которые соответствуют той или иной операции с базой данных — получение информации, запись или удаление. Например, `users.get` — метод для получения информации о пользователе, `video.add` — метод для добавления видеозаписи в свой список, `likes.delete` — метод для удаления отметки «Мне нравится».

Все методы разделены на секции. Например, для работы с сообществами вам нужны методы секции `groups`, для работы с фотографиями — `photos`, и так далее. Полный список методов по секциям доступен в разделе [Методы API](method).

После названия метода нужно передать его входные данные (если они есть) — как обычные GET-параметры в http-запросе. В нашем примере мы сообщаем серверу, что хотим получить данные о пользователе с `id=210700286` и формат этих данных должен соответствовать версии API  :version (о версиях мы еще поговорим позже). Входные параметры всегда перечислены на странице с описанием метода.

В ответ сервер вернет JSON-объект с запрошенными данными (или сообщение об ошибке, если что-то пошло не так). 
**JSON** — это формат записи данных в виде пар «имя свойства»: «значение». Если вы раньше не встречались с этим форматом, мы рекомендуем познакомиться с ним, прежде чем продолжить чтение: [JSON, Wikipedia](https://ru.wikipedia.org/wiki/JSON).

Ответ на наш запрос выглядит так:

```JSON
{
  "response": [
    {
      "id": 210700286,
      "first_name": "Lindsey",
      "last_name": "Stirling"
    }
  ]
}
```

Структура ответа каждого метода также строго задана, и при работе с API вы заранее знаете, что в поле `id` придет число, а в поле `first_name` — строка. Такие правила оговариваются на страницах с описанием метода и соответствующих объектов, которые он возвращает в ответе. Например, [`users.get`](method/users.get) — здесь описаны входные параметры метода и структура его ответа, а здесь — [`user`](reference/objects/user) подробно расписано каждое поле объекта из ответа.

Объект из ответа может быть не уникален для конкретного метода. Например, [объект пользователя](reference/objects/user) с набором полей, содержащих данные о его образовании, возрасте, интересах, может возвращаться в ответе от методов [`users.get`](method/users.get), [`users.search`](method/users.search), [`groups.getMembers`](method/groups.getMembers) и еще нескольких.

## Регистрация приложения

В [примере](#Методы%20и%20объекты) мы использовали метод [`users.get`](method/users.get), который позволяет получить информацию о пользователях, но для разработки приложений этого будет мало. Чтобы использовать все возможности API ВКонтакте, нужно зарегистрировать своё приложение.

Выберите [Мои приложения](https://vk.com/apps?act=manage) в верхнем меню и нажмите кнопку [Создать](https://vk.com/editapp?act=create). Создать приложение можно для одной из четырех платформ:

*  Встраиваемое приложение — вы получите приложение, которое можно встроить во фрейм с внешнего сайта. Готовые приложения можно увидеть в наших каталогах: [Мини-приложения](https://vk.com/services), [Игры](https://vk.com/apps).
*  Standalone-приложение — вы получите `API_ID` для внешнего сайта, мобильного или десктопного клиента. Основная мысль в том, что запросы к API должны отправляться с устройства пользователя. В интерфейсе такого приложения можно настроить [SDK](sdk/overview) и подключить сертификаты для push-уведомлений. 
*  Сайт — вы получите `API_ID` для внешнего сайта и работы с API через сервер. Если вы хотите написать скрипт (например, на PHP), который будет обращаться к API ВКонтакте, выберите именно этот вариант. 
*  Скилл Маруси — платформа для создания приложений, которые взаимодействуют с голосовым помощником. 

> **Совет.** Если вы пока не знаете, какую платформу выбрать, используйте Standalone-приложение. Мы обычно рекомендуем его для тренировки.

После подтверждения откроется страница с информацией о приложении. 
Откройте раздел **Настройки** в меню слева. В поле **ID приложения** будет число (например, `5490057`). Это идентификатор вашего приложения, в дальнейшем он понадобится вам, чтобы указать значение `API_ID`, `APP_ID` или `client_id`.

## Авторизация пользователя

ВКонтакте — социальная сеть, где есть дружеские связи, настройки приватности и даже черные списки. Многое зависит от того, кто просматривает страницу: кто-то увидит на ней всю ту же информацию, что и владелец, а кто-то — лишь общедоступные данные.

В API этот принцип сохраняется. Если вы скрыли список своих групп от не-друзей, то и через API ваши не-друзья не должны его увидеть. Поэтому почти все методы требуют авторизации пользователя перед началом работы. Проще говоря, сервер должен знать, кто к нему обращается за информацией, чтобы предоставить ее в том же виде, что и в основной версии сайта.

В общем случае для идентификации в API используется специальный ключ доступа, который называется `access_token`. 
**Токен** — это строка из цифр и латинских букв, которую вы передаете на сервер вместе с запросом. Из этой строки сервер получает всю нужную ему информацию. Есть разные способы получения токена, более того, он может быть выдан не только пользователю, но и сообществу, и сразу всему приложению — подробнее об этом вы можете прочитать [здесь](api/access-token/getting-started).

Мы воспользуемся самым простым способом ([Implicit flow](api/access-token/implicit-flow-user)) и получим токен для работы с API из созданного вами на прошлом этапе приложения.

Откройте новую вкладку в браузере и введите в адресную строку такой запрос:

```
https://oauth.vk.com/authorize?client_id=5490057&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=friends&response_type=token&v=:version
```

Число `5490057` в запросе нужно заменить на `API_ID` вашего приложения.

Нажмите **Enter**. Откроется окно с запросом прав. В нем отображаются название приложения, иконки прав доступа, и ваши имя с фамилией.

Нажмите **Разрешить**. вы попадете на новую страницу с предупреждением о том, что токен нельзя копировать и передавать третьим лицам. В адресной строке будет URL [`https://oauth.vk.com/blank.html`](https://oauth.vk.com/blank.html), а после `#` вы увидите дополнительные параметры — `access_token`, `expires_in` и `user_id`. Токен может выглядеть, например, так:

```
51eff86578a3bbbcb5c7043a122a69fd04dca057ac821dd7afd7c2d8e35b60172d45a26599c08034cc40a
```

Токен — это ваш ключ доступа. При выполнении определенных условий человек, получивший ваш токен, может нанести существенный ущерб вашим данным и данным других людей. Поэтому очень важно не передавать свой токен третьим лицам.

Поле `expires_in` содержит время жизни токена в секундах. 86400 секунд — это ровно сутки. Через сутки полученный токен перестанет действовать, для продолжения работы нужно будет получить новый. Есть возможность получить токен без срока действия — для этого в `scope` добавьте значение `offline`. Вы можете принудительно отозвать токен (например, в том случае, если он стал известен постороннему), сбросив сеансы в настройках безопасности вашего аккаунта или сменив пароль. Также, если речь идет о токене не из вашего собственного приложения, можно просто удалить приложение из настроек: [https://vk.com/settings?act=apps](https://vk.com/settings?act=apps)

Поле `user_id` содержит id пользователя, для которого получен токен.

Теперь вы можете сделать вызов метода от своего имени. Например, получить список друзей, которые сейчас находятся на сайте.

Для этого введите в адресную строку:

```
https://api.vk.com/method/friends.getOnline?v=:version&access_token=
```

и вставьте после знака `=` свой `access_token`, затем нажмите Enter. В ответе сервер вернет список идентификаторов ваших друзей, которые сейчас онлайн. Почитать подробнее о работе этого метода можно [здесь](method/friends.getOnline). Заметьте, вы не указали в запросе, для какого пользователя (`user_id`) нужно получить список — сервер использовал значение по умолчанию, т.е. ваш идентификатор, который он получил из токена.

Подробное руководство о получении ключей доступа находится [на этой странице](api/access-token/getting-started).

## Права доступа

Как вы уже знаете, все методы делятся на секции — `friends`, `photos`, `video` и так далее. Каждая секция соответствует определенному разделу на сайте. Часто приложения создаются для работы с конкретным разделом. Например, для просмотра фотографий или для редактирования видео. При этом логично, что приложению, которое работает только с аудиозаписями пользователя, не нужен доступ одновременно и к его личным сообщениям.

Поэтому в API права доступа приложения разграничены, как и методы. Приложение может запросить доступ только к группам, а может — к группам, фотографиям и аудиозаписям. [На этой странице](reference/access-rights) перечислены все существующие права доступа, которые можно запросить.

Чтобы запросить права, используйте параметр `scope` диалога авторизации. Когда вы получали токен для своего приложения, в `scope` было указано значение `friends` — и в окне авторизации приложение запросило доступ к друзьям.

У каждого права доступа есть уникальное название (`friends`, `video` и т.д.) и код (+2, +4, +4096). 
В `scope` можно перечислить названия нужных прав доступа (например, `scope`=`friends,video,photos`), а можно указать сумму их кодов (например, `scope`=`22`). Каждый код представляет собой степень двойки, и полученную таким образом сумму (битовую маску) вы всегда можете проверить на предмет содержания какого-то конкретного кода (например, с помощью [`account.getAppPermissions`](method/account.getAppPermissions)). 

Некоторые права доступа из соображений безопасности можно запрашивать только в Standalone-приложениях и только в процессе авторизации Implicit Flow, обратите на это внимание. 

## Что дальше

Вы познакомились с основными понятиями, связанными с API ВКонтакте. Дальше все зависит лишь от вашего вдохновения.

Конечно, на практике никто не работает с API из соседней вкладки браузера. Для этого используют самые разные языки программирования, SDK, генераторы кода. Сам механизм работы с API весьма прост, средства для отправки http-запросов и обработки ответа от сервера предусмотрены практически в любой среде разработки: а значит, возможность выбора всегда есть.

Использование API | Быстрый старт

# Быстрый старт

**Платёжный API** — это API для работы с платёжной системой в играх и мини-приложениях. Он нужен, чтобы продавать в приложении виртуальные товары или услуги. 

Пользователь оплачивает покупки внутренней валютой ВКонтакте (голосами), но для удобства стоимость товара отображается в рублях.

![title=Диалоговое окно платежа в приложении.](6bdd0b4f3e1eb1e9b339105672c7472128d9b3aa284d76f8c3c9799b "-708128452752560712")

В этом руководстве мы расскажем, как подключить платёжную систему в вашем приложении ВКонтакте.

## Платежи ВКонтакте

> Для платежей за товары и услуги используйте [VK Pay](pay/getting-started).

Подойдёт для платежей в чат-ботах, сообществах ВКонтакте, сервисах VK Mini Apps и на сторонних сайтах. Оплата происходит с баланса VK Pay или привязанных к нему банковских карт.

> Для платежей в играх и мини-приложениях используйте голоса.

Голоса — универсальная платёжная единица ВКонтакте, которая используется для оплаты виртуальных товаров. Пользователи могут пополнить свой виртуальный счёт голосами с помощью банковских карт, электронных кошельков, СМС и другими способами. 

Пользователь оплачивает покупки в игре или мини-приложении внутренней валютой ВКонтакте (голосами) следующим образом:
1. Пользователь выбирает виртуальный товар в приложении.
2. С его личного баланса списывается число голосов, равное стоимости покупки.
3. Счёт приложения пополняется на стоимость покупки.

## Подготовка серверной части 

В первую очередь нужно реализовать на вашем сервере скрипт для [обработки уведомлений от платёжной системы ВКонтакте](api/payments/notifications/overview). Такое уведомление представляет собой `POST`-запрос с заданной структурой данных. Ваш сервер должен уметь своевременно отправлять ответ с запрошенной информацией. Например, это могут быть данные о товаре, который хочет купить пользователь в вашем приложении.

## Настройки платежей в приложении 

Откройте страницу редактирования вашего приложения и перейдите на вкладку **Платежи**. Здесь нужно указать адрес обратного вызова (URL на вашем сервере, где размещён скрипт обработки уведомлений). Чтобы проводить оплату в [тестовом режиме](#Тестовый%20режим), в поле **Тестировщики платежей** выберите пользователей, которые будут тестировать платёжную систему.

Пока приложение не прошло модерацию, в нём доступны только тестовые платежи.

## Вызов диалогового окна 

Пользователь выбирает виртуальный товар или подписку в приложении, после этого открывается диалоговое окно ВКонтакте с описанием и стоимостью. Можно подтвердить покупку или отменить её. Если на балансе недостаточно голосов, будет предложено пополнить его одним из доступных способов.

![title=Диалоговое окно платежа в приложении;](d1be181ea82a0a515a5476d52cb862a79143548e587b81e2a0db94cb "-2162674972032947764")

Чтобы показать диалоговое окно, используйте метод [`showOrderBox`](sdk/javascript#showOrderBox) или [`showSubscriptionBox`](sdk/javascript#showSubscriptionBox) из Client API. 

Типовой JS-код для открытия окна:

```JavaScript
function order() {
    const params = {
        type: 'item',
        item: 'item_25new'
    };

   VK.callMethod('showOrderBox', params);
}
```

После успешной оплаты товара приложению будет отправлено событие `onOrderSuccess` с идентификатором заказа. 

**Внимание!** Это событие нельзя использовать для принятия решения о предоставлении пользователю виртуального товара. Проверяйте специальное уведомление [`order_status_change`](api/payments/notifications/order-status-change), которое отправляется на ваш сервер.

### Диалоговое окно платежа

Этот диалог показывается пользователю после выбора виртуального товара на странице приложения.

![title=Диалоговое окно платежа в приложении.](d1be181ea82a0a515a5476d52cb862a79143548e587b81e2a0db94cb "-2162674972032947764")

#### Параметры `showOrderBox`

Чтобы показать диалоговое окно платежа, используйте метод [`showOrderBox`](sdk/javascript#showOrderBox) из Client API. Он принимает следующие параметры:

### `type` 

`string`

 Тип заказа. Возможные значения: 
  `votes` — окно для ввода голосов на счёт приложения; 
  `offers` — окно со списком специальных предложений (офферов), которые могут быть использованы пользователем для получения голосов; 
  `item` — покупка товара. 

### `votes` 

`integer`

Количество голосов для ввода на счёт приложения (для `type = votes`). 

### `offer_id` 

`integer`

Идентификатор рекламной акции (для `type = offers`). 

### `currency` 

`integer`, [`0`,`1`]

`1` — стоимость специальных предложений будет отображена в [валюте приложения](#Платежи%20в%20валюте%20приложения) (для `type = offers`). 

### `item` 

`string`

Наименование товара, которое будет отправлено в уведомлении `get_item` (для `type = item`). Строка длиной до 64 символов. Например, `item_25new`.   

#### События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

 | Название | Параметры | Описание |
|---|---|---|
 | `onOrderCancel` | — | Пользователь отменил покупку. |
 | `onOrderSuccess` | `orderId` (`integer`) | Покупка закончилась успешно. 
 `orderId` — идентификатор заказа. Подробную информацию об обработке платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview). |
 | `onOrderFail` | `errorCode`  (`integer`)| Покупка закончилась неуспешно. 
 `errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview#Формат%20ответа%20в%20случае%20ошибки). |

#### Пример кода на JavaScript 

```JavaScript
<script type="text/javascript">

// Функция order() отображает окно для покупки товара с наименованием "item_25new". 
// Названия платёжных событий пишутся в контейнер с id="callbacks".

  function order() {
    var params = {
      type: 'item',
      item: 'item_25new'
    };
    VK.callMethod('showOrderBox', params);
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onOrderSuccess', function(order_id) {
    callbacksResults.innerHTML += '<br />onOrderSuccess '+order_id;
  });
  VK.addCallback('onOrderFail', function() {
    callbacksResults.innerHTML += '<br />onOrderFail';
  });
  VK.addCallback('onOrderCancel', function() {
    callbacksResults.innerHTML += '<br />onOrderCancel';
  });
</script>
```

### Диалоговое окно подписки

#### Параметры `showSubscriptionBox`

Чтобы показать диалоговое окно подписки, нужно вызвать метод [`showSubscriptionBox`](sdk/javascript#showSubscriptionBox) из Client API. Вторым аргументом передайте `action` — действие, которое необходимо совершить. Возможные значения:
* `create` — приобрести подписку;
* `resume` — возобновить подписку;
* `cancel` — отменить подписку.

Метод `showSubscriptionBox` принимает следующие параметры:

### `item` 

`string`

Наименование подписки, которое будет отправлено в уведомлении [`get_subscription`](api/payments/notifications/get-subscription). Строка длиной до 64 символов. Например: `subscription_25new` (для `action = create`). 

### `subscription_id` 

`integer`

Идентификатор подписки (для `action = resume, cancel`). 

#### События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

 | Название | Параметры | Описание |
|---|---|---|
 | `onSubscriptionCancel` | — | Пользователь отменил покупку. |
 | `onSubscriptionSuccess` | `subscription_id` (`integer`) | Покупка закончилась успешно. 
`subscription_id` — идентификатор подписки. Подробную информацию об обработке платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview). |
 | `onSubscriptionFail` | `errorCode` (`integer`)| Покупка закончилась неуспешно. 
 `errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на [этой странице](api/payments/notifications/overview#Формат%20ответа%20в%20случае%20ошибки). |

> Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для `period = month`) и раз в 2 минуты для других значений `period`. После этого подписка автоматически отменяется.

#### Пример кода на JavaScript

```JavaScript
<script type="text/javascript">
  function order() {
    VK.callMethod('showSubscriptionBox', 'create', {item: 'subscription1'});
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onSubscriptionSuccess', function(subscription_id) {
    callbacksResults.innerHTML += '<br />onSubscriptionSuccess '+subscription_id;
  });
  VK.addCallback('onSubscriptionFail', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionFail';
  });
  VK.addCallback('onSubscriptionCancel', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionCancel';
  });
</script>
```

Функция `order` позволяет отобразить пользователю окно для покупки товара с наименованием `'subscription_25new'`. Названия произошедших платёжных событий пишутся в контейнер с `id="callbacks"`.

## Тестовый режим

Тестовый режим позволяет тестировать функциональность покупки товаров и перевода голосов в приложениях без реальной передачи голосов. 

Тестовый режим необходимо использовать пока ваше приложение не прошло проверку администрацией ВКонтакте. Платежи осуществляются в «боевом» режиме сразу после прохождения процедуры проверки приложения.

Для осуществления платежей в тестовом режиме необходимо добавить всех пользователей, совершающих тестовые платежи, в специальный список в настройках приложения (поле **Тестировщики платежей**).

![](33327db1023a46d0548612a270d8330ee0e7e4678ca689697daefe49 "4424661819184374092")

В тестовом режиме к параметру `notification_type` добавляется суффикс `'_test'`. Таким образом, уведомления будут называться `'get_item_test'`, `'order_status_change_test'`, `'get_subscription_test'`, `'subscription_status_change '` соответственно (см. [Платёжные уведомления](api/payments/notifications/overview)).

При этом идентификаторы заказов в тестовом режиме – параметры `order_id` у уведомлений – могут пересекаться с идентификаторами заказов в рабочем режиме.

Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для `period = month`) и раз в 2 минуты для других значений `period`. После этого подписка автоматически отменяется. Уведомления приходят только при изменении статуса подписки, в случае продления уведомления не приходят. Подробнее см. [Изменение статуса подписки](api/payments/notifications/subscription-status-change).

## Модерация приложения 

Если ваше приложение ещё не отправлялось на проверку и не размещено в общем каталоге, самое время сделать это. Иначе пользователи не смогут оплатить что-либо в нём.
После проверки вы можете убрать себя из списка тестировщиков платежей в настройках приложения, чтобы начать осуществлять платежи в боевом режиме.

Чтобы приложение успешно прошло модерацию, убедитесь, что оно соответствует Правилам.

## Методы `orders` 

Метод API [`orders.get`](method/orders.get) позволяет получить список заказов с их текущими статусами. 
Чтобы отменить заказ, используйте метод [`orders.changeState`](method/orders.changeState), передав идентификатор заказа и новый статус заказа `refund`. Голоса вернутся на баланс пользователя. На балансе приложения должно быть достаточно голосов для возврата. Весь список методов секции `orders` можно посмотреть [здесь](method/orders).

Интеграция | Платежи | Платёжный API | Быстрый старт

Интеграция | Сообщества и пользователи | Streaming API

Интеграция | Публикации | Загрузка файлов

# Одобренные способы оплаты

> **Важно!**
>
> Обратите внимание, что приложения-магазины **не могут** использовать как средство оплаты **SMS-платежи и подписки**.
>

В приложениях, соответствующих [требованиям к магазинам ВКонтакте](market-rules), разрешено использовать следующие внешние платёжные системы:
* QIWI Кошелёк
* WebMoney
* Яндекс.Деньги
* Google Checkout
* Paypal
* Money Mail
* RBK Money
* Robokassa
* 2pay
* Деньги-Онлайн
* Intellect Money
* Moneta.ru
* А также все платёжные шлюзы, осуществляющие приём банковских карт (Assist, Cyberplay, Platezh.ru и другие). Помимо указанных платёжных систем к оплате может также приниматься **оплата курьеру во время доставки** и **оплата товара наложенным платежом при получении**.

Правила | Одобренные способы оплаты

# VKWebAppAddToCommunity

`VKWebAppAddToCommunity` вызывает окно выбора сообщества и устанавливает в него мини-приложение.

:::note
**Важно!** Перед вызовом события установите флажок [Разрешить установку в сообществах](mini-apps/management/information#Разрешить%20установку%20в%20сообществах) и [включите мини-приложение](mini-apps/management/settings#Состояние).
:::

## Пример

```JavaScript
bridge.send('VKWebAppAddToCommunity')
  .then((data) => { 
    if (data.group_id) {
      // Мини-приложение установлено в сообщество
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

—

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppAddToCommunityResult` и `VKWebAppAddToCommunityFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

Возможные ошибки:

* `This action cannot be performed in the background`, если мини-приложение запущено в фоновом режиме.
* `User denied`, если пользователь закрывает окно выбора сообщества.

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующим полем:

| Поле | Тип | Описание |
| --- | --- | --- |
| `group_id` | `string` | Идентификатор сообщества, в котором установлено мини-приложение. |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех событий VK Bridge.

### События

#### `VKWebAppAddToCommunityResult`

Сигнализирует, что мини-приложение установлено в сообщество. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppAddToCommunityResult",
    data: {
      group_id: "166562603"
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppAddToCommunityFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).

## Песочница

[VKWebAppAddToCommunity](https://vk.cc/bZfqOq) 


VK Bridge | Сообщества | VKWebAppAddToCommunity

# VKWebAppCheckAllowedScopes

`VKWebAppCheckAllowedScopes` проверяет, есть ли у мини-приложения или игры доступ к тем или иным данным пользователя (смотрите раздел [Права доступа](reference/access-rights)).

## Пример

```JavaScript
bridge.send('VKWebAppCheckAllowedScopes', {
  scopes: 'friends,notify'
  })
  .then((data) => { 
    if (data.result) {
      // Права доступа получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `scopes` &#x0d;&#x0a;*обязательное* | `string` | Список прав, перечисленных через запятую. Пример: `'friends,notify'`. &#x0d;&#x0a;&#x0d;&#x0a;Возможные права:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notify` — отправлять уведомления (смотрите раздел [`VKWebAppAllowNotifications`](bridge/VKWebAppAllowNotifications)).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `friends` — получить список друзей пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photos` — получить фотографии пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `audio` — получить аудиозаписи пользователя. &#x0d;&#x0a; &nbsp;&nbsp; &bullet; `video` — получить видео пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stories` — получить истории пользователя. &#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pages` — получить вики-страницы пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `menu` — добавлять ссылку на мини-приложение или игру в меню слева.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `wallmenu` — публиковать записи на стене пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `status` — получить статус пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notes` — получить заметки пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `messages` — расширенные методы работы с сообщениями.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `wall` — использовать обычные и расширенные методы работы со стеной.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `ads` — использовать расширенные методы работы с [рекламным API](method/ads).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `offline` — доступ к [API](api/getting-started) в любое время.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `docs` — получить файлы пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `groups` — получить сообщества пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notifications` — получить оповещения об ответах пользователю.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stats` — получить статистику сообществ и приложений, в которых пользователь является администратором.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `email` — получить адрес электронной почты пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `adsweb` — работать с кабинетом рекламной сети.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `group_messages` — отправлять сообщения от имени официального сообщества мини-приложения или игры (смотрите раздел [`VKWebAppAllowMessagesFromGroup`](bridge/VKWebAppAllowMessagesFromGroup)).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `market` — получить товары пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `phone` — получить номер телефона пользователя. |

## Результат

Проверить результат можно:

* Используя объект [`Promise`](#Объект%20Promise), который возвращается вызовом `bridge.send(...)`.

* С помощью [событий](#События) `VKWebAppCheckAllowedScopesResult` и `VKWebAppCheckAllowedScopesFailed`.

[Подробнее о проверке результатов при вызовах VK Bridge](bridge/getting-started#Обработка%20результата).

### Объект `Promise`

Если обращение к платформе прошло успешно, управление будет передано в `then`-обработчик объекта `Promise`. В качестве ответа платформа возвращает объект со следующими полями:

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `array[object]` | Информация о том, проверен ли доступ к информации пользователя. Поля объекта:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `scope` (`string`) — право доступа.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `allowed` (`boolean`) — информация о том, есть ли право доступа.&#x0d;&#x0a;&#x0d;&#x0a; Возможные значения поля `scope`:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notify` — отправлять уведомления (смотрите раздел [`VKWebAppAllowNotifications`](bridge/VKWebAppAllowNotifications)).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `friends` — получить список друзей пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photos` — получить фотографии пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `audio` — получить аудиозаписи пользователя. &#x0d;&#x0a; &nbsp;&nbsp; &bullet; `video` — получить видео пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stories` — получить истории пользователя. &#x0d;&#x0a; &nbsp;&nbsp; &bullet; `pages` — получить вики-страницы пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `menu` — добавлять ссылку на мини-приложение или игру в меню слева.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `wallmenu` — публиковать записи на стене пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `status` — получить статус пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notes` — получить заметки пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `messages` — расширенные методы работы с сообщениями.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `wall` — использовать обычные и расширенные методы работы со стеной.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `ads` — использовать расширенные методы работы с [рекламным API](method/ads).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `offline` — доступ к [API](api/getting-started) в любое время.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `docs` — получить файлы пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `groups` — получить сообщества пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `notifications` — получить оповещения об ответах пользователю.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `stats` — получить статистику сообществ и приложений, в которых пользователь является администратором.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `email` — получить адрес электронной почты пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `adsweb` — работать с кабинетом рекламной сети.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `group_messages` — отправлять сообщения от имени официального сообщества мини-приложения или игры (смотрите раздел [`VKWebAppAllowMessagesFromGroup`](bridge/VKWebAppAllowMessagesFromGroup)).&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `market` — получить товары пользователя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `phone` — получить номер телефона пользователя.&#x0d;&#x0a;&#x0d;&#x0a; Возможные значения поля `allowed`:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `true` — у мини-приложения или игры есть право доступа.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `false` — у мини-приложения или игры нет права доступа (не было запрошено или пользователь запретил). |

Если при обращении к платформе произошла ошибка, управление передаётся в метод `catch`. В качестве ответа платформа возвращает [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий  для всех событий VK Bridge.

### События

#### `VKWebAppCheckAllowedScopesResult`

Сигнализирует, что права доступа получены. В обработчик события на стороне пользователя передаются следующие данные:

```JavaScript
{
  detail: {
    type: "VKWebAppCheckAllowedScopesResult",
    data: {
      "result": [
        {
          "scope": "friends",
          "allowed": true
        },
        {
          "scope": "notify",
          "allowed": false
        }
      ]
    }
  }
}
```

Передаваемый объект подобен объекту, возвращаемому при [успешном выполнении промиса](#Объект%20Promise).

#### `VKWebAppCheckAllowedScopesFailed`

Информирует об ошибке, которая произошла при взаимодействии с платформой.

В обработчик события на стороне пользователя передаётся [объект с информацией об ошибке](bridge/getting-started#Обработка%20ошибок%20VK%20Bridge), общий для всех методов VK Bridge.

#### Пример обработки событий

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | Общие события | VKWebAppCheckAllowedScopes

# VKWebAppShowLeaderBoardBox

`VKWebAppShowLeaderBoardBox` открывает окно с таблицей результатов.

## Пример

```JavaScript
bridge.send("VKWebAppShowLeaderBoardBox", {user_result:100})
         .then(data => console.log(data.success))  
        .catch(error => console.log(error));
```

## Платформы

Android, iOS, Mobile Web

## Параметры

* `user_result` (`integer`)
Результат пользователя. 

## Результат

* `success` (`boolean`)
Удачно ли завершена операция. 

> Таблица результатов может отображать прогресс пользователей по очкам, баллам миссий или уровню в игре (тип таблицы выбирается в настройках приложения). Для повышения уровня, добавления баллов миссий или очков используйте метод [`secure.addAppEvent`](secure.addAppEvent).

## Песочница

[VKWebAppShowLeaderBoardBox](https://vk.cc/bZfCRH)

VK Bridge | Игры | VKWebAppShowLeaderBoardBox

# VKWebAppViewRestore

`VKWebAppViewRestore` отправляется платформой, когда клиент открывает WebView мини-приложения из фонового режима.

## Пример

```JavaScript
bridge.subscribe((e) => {
  if (e.detail.type === 'VKWebAppViewRestore') {
    // Логика мини-приложения
  }
});
```

## Платформы

Android, iOS

## Параметры

—

## Результат

`VKWebAppViewRestore` сигнализирует, что мини-приложение открыто из фонового режима. В обработчик события на стороне пользователя передаются следующие данные:  

```JavaScript
{
  detail: {
    type: "VKWebAppViewRestore",
    data: { }
  }
}
```

## Пример обработки события

Смотрите раздел [Обработка событий-результатов](bridge/getting-started#Обработка%20результата).


VK Bridge | События жизненного цикла | VKWebAppViewRestore

# Введение

**Библиотека VK Bridge** позволяет приложениям использовать API ВКонтакте и API операционной системы, установленной на устройстве пользователя. В этом разделе содержится список всех событий VK Bridge.

## Как подключить и использовать

* [Руководство разработчика мини-приложений](bridge/getting-started)
* [Руководство разработчика игр](games/bridge)

## Инициализация

| Событие | Сценарий использования |
| --- | --- |
| [VKWebAppInit](bridge/VKWebAppInit) | Инициализировать VK Bridge. |

## Общие события

| Событие | Сценарий использования |
| --- | --- |
| [VKWebAppAddToFavorites](bridge/VKWebAppAddToFavorites) | Добавить приложение в избранное. |
| [VKWebAppAddToHomeScreen](bridge/VKWebAppAddToHomeScreen) | Добавить приложение на главный экран устройства. |
| [VKWebAppAddToHomeScreenInfo](bridge/VKWebAppAddToHomeScreenInfo) | Получить информацию о шорткате. |
| [VKWebAppAllowNotifications](bridge/VKWebAppAllowNotifications) | Запросить разрешение на отправку уведомлений. |
| [VKWebAppClose](bridge/VKWebAppClose) | Закрыть приложение. |
| [VKWebAppCopyText](bridge/VKWebAppCopyText) | Копировать текст в буфер обмена. |
| [VKWebAppDenyNotifications](bridge/VKWebAppDenyNotifications) | Отключить уведомления. |
| [VKWebAppDownloadFile](bridge/VKWebAppDownloadFile) | Скачать файл. |
| [VKWebAppGetClientVersion](bridge/VKWebAppGetClientVersion) | Получить номер версии приложения ВКонтакте. |
| [VKWebAppGetConfig](bridge/VKWebAppGetConfig) | Получить конфигурацию приложения. |
| [VKWebAppGetLaunchParams](bridge/VKWebAppGetLaunchParams) | Получить параметры запуска. |
| [VKWebAppOpenApp](bridge/VKWebAppOpenApp) | Открыть приложение. |
| [VKWebAppOpenCodeReader](bridge/VKWebAppOpenCodeReader) | Считать QR-код. |
| [VKWebAppOpenWallPost](bridge/VKWebAppOpenWallPost) | Открыть запись со стены в слое. |
| [VKWebAppSendToClient](bridge/VKWebAppSendToClient) | Отправить установочное уведомление на устройство. |
| [VKWebAppShare](bridge/VKWebAppShare) | Поделиться ссылкой. |
| [VKWebAppShowImages](bridge/VKWebAppShowImages) | Открыть нативный экран для просмотра изображений. |
| [VKWebAppShowWallPostBox](bridge/VKWebAppShowWallPostBox) | Опубликовать запись на стене. |
| [VKWebAppCreateHash](bridge/VKWebAppCreateHash) | Получить хеш. |
| [VKWebAppGetGrantedPermissions](bridge/VKWebAppGetGrantedPermissions) | Получить список разрешений. |
| [—](bridge/call) | Позвонить пользователю. |

## События жизненного цикла

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppChangeFragment](bridge/VKWebAppChangeFragment) | Открыть приложение по ссылке. |
 | [VKWebAppLocationChanged](bridge/VKWebAppLocationChanged) | Изменить хеш в адресной строке. |
 | [VKWebAppUpdateConfig](bridge/VKWebAppUpdateConfig) | Изменить конфигурацию приложения. |
 | [VKWebAppViewHide](bridge/VKWebAppViewHide) | Закрыть приложение. |
 | [VKWebAppViewRestore](bridge/VKWebAppViewRestore) | Восстановить приложение из кеша. |

## Пользователи

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCallAPIMethod](bridge/VKWebAppCallAPIMethod) | Вызвать метод API ВКонтакте. |
 | [VKWebAppGetAuthToken](bridge/VKWebAppGetAuthToken) | Получить права доступа у пользователя. |
 | [VKWebAppGetEmail](bridge/VKWebAppGetEmail) | Получить адрес электронной почты. |
 | [VKWebAppGetFriends](bridge/VKWebAppGetFriends) | Показать список друзей пользователя. |
 | [VKWebAppGetGeodata](bridge/VKWebAppGetGeodata) | Получить данные о текущем местоположении пользователя. |
 | [VKWebAppGetPersonalCard](bridge/VKWebAppGetPersonalCard) | Вызвать карточку контактов. |
 | [VKWebAppGetPhoneNumber](bridge/VKWebAppGetPhoneNumber) | Получить номер телефона пользователя. |
 | [VKWebAppGetUserInfo](bridge/VKWebAppGetUserInfo) | Получить данные о профиле пользователя. |
 | [VKWebAppOpenContacts](bridge/VKWebAppOpenContacts) | Показать контакты из телефонной книги. |

## Сообщества 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAddToCommunity](bridge/VKWebAppAddToCommunity) | Добавить приложение в сообщество.  |
 | [VKWebAppAllowMessagesFromGroup](bridge/VKWebAppAllowMessagesFromGroup) | Получить разрешение на отправку сообщений от имени сообщества. |
 | [VKWebAppGetCommunityToken](bridge/VKWebAppGetCommunityToken) | Получить права доступа. |
 | [VKWebAppGetGroupInfo](bridge/VKWebAppGetGroupInfo) | Получить информацию о сообществе. |
 | [VKWebAppJoinGroup](bridge/VKWebAppJoinGroup) | Предложить пользователю вступить в сообщество. |
 | [VKWebAppLeaveGroup](bridge/VKWebAppLeaveGroup) | Предложить пользователю выйти из сообщества. |
 | [VKWebAppSendPayload](bridge/VKWebAppSendPayload) | Отправить событие в сообщество. |
 | [VKWebAppShowCommunityWidgetPreviewBox](bridge/VKWebAppShowCommunityWidgetPreviewBox) | Показать виджет сообщества перед публикацией. |

## Платежи 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppShowOrderBox](bridge/VKWebAppShowOrderBox) | Открыть окно покупки товара. |
 | [VKWebAppOpenPayForm](bridge/VKWebAppOpenPayForm) | Показать платёжное окно VK Pay. |

## Кнопка в профиле пользователя 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAddToProfile](bridge/VKWebAppAddToProfile) | Добавить в профиль кнопку вызова мини-приложения. |
 | [VKWebAppRemoveFromProfile](bridge/VKWebAppRemoveFromProfile) | Удалить из профиля кнопку вызова мини-приложения. |

## Рекомендации

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppRecommend](bridge/VKWebAppRecommend) | Порекомендовать мини-приложение друзьям. |

## Редактор историй

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppShowStoryBox](bridge/VKWebAppShowStoryBox) | Открыть редактор историй. |
 | [VKWebAppSubscribeStoryApp](bridge/VKWebAppSubscribeStoryApp) | Подписать пользователя на обновления истории. |

## Реклама

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCheckNativeAds](bridge/VKWebAppCheckNativeAds) | Проверить наличие рекламы, доступной для показа. |
 | [VKWebAppGetAds](bridge/VKWebAppGetAds) | Получить данные для рекламного баннера. |
 | [VKWebAppShowNativeAds](bridge/VKWebAppShowNativeAds) | Показать рекламу. |

## Отслеживание пользователей

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppConversionHit](bridge/VKWebAppConversionHit) | Отслеживать конверсионные действия пользователей. |
 | [VKWebAppRetargetingPixel](bridge/VKWebAppRetargetingPixel) | Добавить пользователя в аудиторию ретаргетинга. |

## Интерфейс и навигация

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppResizeWindow](bridge/VKWebAppResizeWindow) | Изменить размер окна приложения. |
 | [VKWebAppScroll](bridge/VKWebAppScroll) | Прокрутить окно приложения.  |
 | [VKWebAppSetLocation](bridge/VKWebAppSetLocation) | Задать значение хеша в адресной строке. |
 | [VKWebAppSetSwipeSettings](bridge/VKWebAppSetSwipeSettings) | Включить свайп, как в браузере. |
 | [VKWebAppSetViewSettings](bridge/VKWebAppSetViewSettings) | Настроить вид статус- и экшен-бара. |

## Секция Storage

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppStorageGet](bridge/VKWebAppStorageGet) | Получить значение ключа. |
 | [VKWebAppStorageGetKeys](bridge/VKWebAppStorageGetKeys) | Получить названия всех переменных. |
 | [VKWebAppStorageSet](bridge/VKWebAppStorageSet) | Задать значение переменной. |

## Виброотклик (Taptic Engine)
 
 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppTapticImpactOccurred](bridge/VKWebAppTapticImpactOccurred) | Вызвать вибрацию при столкновении. |
 | [VKWebAppTapticNotificationOccurred](bridge/VKWebAppTapticNotificationOccurred) | Вызвать вибрацию после выполнения действия. |
 | [VKWebAppTapticSelectionChanged](bridge/VKWebAppTapticSelectionChanged) | Вызвать вибрацию при изменении выбора. |

## Управление фонариком

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppFlashGetInfo](bridge/VKWebAppFlashGetInfo) | Получить информацию о фонарике. |
 | [VKWebAppFlashSetLevel](bridge/VKWebAppFlashSetLevel) | Задать уровень яркости фонарика. |

## Данные датчиков 

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppAccelerometerStart](bridge/VKWebAppAccelerometerStart) | Получать данные акселерометра. |
 | [VKWebAppAccelerometerStop](bridge/VKWebAppAccelerometerStop) | Не получать данные акселерометра. |
 | [VKWebAppDeviceMotionStart](bridge/VKWebAppDeviceMotionStart) | Получать данные о вращении устройства. |
 | [VKWebAppDeviceMotionStop](bridge/VKWebAppDeviceMotionStop) | Не получать данные о вращении устройства. |
 | [VKWebAppGyroscopeStart](bridge/VKWebAppGyroscopeStart) | Получать данные гироскопа. |
 | [VKWebAppGyroscopeStop](bridge/VKWebAppGyroscopeStop) | Не получать данные гироскопа. |

## Игры

 | Событие | Сценарий использования |
 | --- | --- |
 | [VKWebAppCheckAllowedScopes](bridge/VKWebAppCheckAllowedScopes) | Проверить, есть ли доступ к данным. |
 | [VKWebAppShowInviteBox](bridge/VKWebAppShowInviteBox) | Пригласить друзей в игру. |
 | [VKWebAppShowLeaderBoardBox](bridge/VKWebAppShowLeaderBoardBox) | Показать таблицу результатов. |
 | [VKWebAppShowSubscriptionBox](bridge/VKWebAppShowSubscriptionBox) | Показать окно подписки. |
 | [VKWebAppShowRequestBox](bridge/VKWebAppShowRequestBox) | Отправить запрос пользователю. |

VK Bridge | Введение

## Актуальные события

* [Грантовая программа Fresh Code 2022](community/events/fresh-code-2022)

## Прошедшие события

* [Код Петербурга — 2022](community/events/code-of-petersburg)
* [Mini Design Award — 2022](community/events/mini-design-award)

Сообщество

# Правила размещения приложений в каталоге для сообществ

**Приложения для сообществ** — приложения, созданные на платформе [VK Mini Apps](mini-apps/getting-started), размещаемые в сообществах ВКонтакте и доступные в полной и мобильной версиях сайта, а также в мобильных клиентах. Каталог приложений для сообществ доступен по ссылке: https://vk.com/community_apps.

С помощью приложений для сообществ администратор может расширить функциональность своего сообщества. Самым простым примером таких приложений является системы создания и размещения форм опросов, регистрации на мероприятия или предварительной записи в различные заведения.

Установка приложения производится из каталога в разделе «Приложения» в настройках сообщества. Также пользователь может установить приложение не из каталога, но администратором которого он является.

**1.** Попасть в Каталог в разделе «Приложения» настроек сообщества может только одобренный сервис.

**2.** Приложения для сообществ, в отличие от обычных сервисов, проходят процедуру одобрения в особом порядке, описанном ниже. Кроме указанных ниже специальных условий, к приложениям для сообществ применимы Правила размещения приложений ВКонтакте.

**3.** Для подачи заявки на одобрение необходимо отправить заявку на модерацию из вкладки «Статус» созданного приложения с типом VK Mini Apps. В обращении должна быть пометка о желании попасть в каталог приложений для сообществ, а также должно содержаться описание функциональности приложения, ссылка на приложение и ссылка на сообщество, в котором оно установлено. В настройках приложения должно быть заполнено его описание, загружены иконка приложения и скриншоты.

**4.** В Каталоге могут быть размещены только те приложения, функциональность которых допускает их работу в неограниченном количестве сообществ и которые имеют возможность настройки под конкретное сообщество.

**5.** Приложения, размещенные в Каталоге для сообществ, в качестве механизма уведомления и связи с пользователями должны использовать сообщения сообщества.

**6.** Приложения, размещенные в Каталоге для сообществ, не должны использовать авторизацию через сторонние сервисы. Наличие авторизации через сторонние сервисы согласуется с Администрацией сайта в индивидуальном порядке.

**7.** В размещении в Каталоге может быть отказано приложениям, которые дублируют функциональность сайта или уже находящихся в Каталоге приложений.

**8.** В Каталоге могут быть размещены только приложения, поддерживающие работу и корректно отображающиеся как в полной версии сайта vk.com, так и в мобильных приложениях.

**9.** В приложении, которое находится в Каталоге, запрещено размещение рекламы.

**10.** Приложения сообществ, в отличие от обычных приложений, могут реализовывать функциональность сбора и последующей обработки полученных персональных данных пользователей, например: ФИО, номера телефонов, адреса электронной почты. Обработка персональных данных разрешена только при условии ее соответствия действующему законодательству РФ, в т.ч. в сфере обработки персональных данных, и в тех случаях, когда это необходимо для корректной работы приложения при условии предварительного уведомления пользователя о цели сбора данных. У приложений для сообществ должна быть политика конфиденциальности. Если ее нет, используется типовая политика конфиденциальности ВКонтакте.

**11.** Приложения сообществ, в отличие от обычных приложений, могут реализовывать оплату услуг средствами, отличными от голосов ВКонтакте.

**12.** Приложения, находящиеся в каталоге, имеют возможность отправлять сообщения пользователям от имени сообществ, в которых они установлены. Запрещена рассылка рекламных сообщений, сообщений, содержание которых противоречит правилам сайта, и других сообщений, содержание которых прямо не связано с функциональностью приложения. В случае массовой рассылки одинаковых сообщений приложение может быть заблокировано.

**13.** В размещении в Каталоге может быть отказано приложениям, которые используют сторонний контент или перенаправляют пользователей на сторонние ресурсы.

Правила | Правила размещения приложений в каталоге для сообществ

#  Как попасть в каталог

Чтобы попасть в каталог, игра должна пройти модерацию. Для этого нужно подать заявку и исправить недочёты, на которые укажет модератор. Если всё хорошо, игра будет добавлена в каталог.

Выполните следующие шаги:

1. [Подготовьте игру к модерации](#Шаг%201.%20Подготовьте%20игру%20к%20модерации)
1. [Отправьте заявку на модерацию](#Шаг%202.%20Отправьте%20заявку%20на%20модерацию)
1. [Следите за статусом модерации](#Шаг%203.%20Следите%20за%20статусом%20модерации)

## Шаг 1. Подготовьте игру к модерации

Игры в каталоге должны соответствовать требованиями, указанным ниже. Если игра не удовлетворяет какому-либо требованию, модератор может отклонить заявку на размещение в каталоге. Перед подачей заявки убедитесь, что:

1. Игра не нарушает:

    * [Правила платформы](rules)
    * [Политику конфиденциальности](privacy-policy)
    * [Требования для публикации в каталоге](games-catalog-rules)
    * [Правила размещения рекламы в игровых приложениях](ad-rules)

1. Игра работает без ошибок на всех выбранных для публикации [платформах](games/getting-started#Direct%20Games%20и%20Web-игры).
1. Если игра претендует на размещение в каталоге в приложении для iOS:

    * Игра не продаёт виртуальные ценности. Мы обязаны выполнять [правила размещения приложений в App Store](https://developer.apple.com/app-store/review/guidelines/) (пункты [3.1.3(b)](https://vk.cc/cgqBZv) и [3.2.1 (vi)](https://vk.cc/cgqC5o)). Монетизировать игру можно с помощью рекламы после размещения в каталоге. 
    * В настройках заполнены поля [Apple Developer Team ID](https://developer.apple.com/programs/enroll/) и **Apple Developer Team Name**. Это обязательное требование к играм в приложениях для App Store.
    * Игра использует технологию ODR для загрузки ресурсов. Для прохождения модерации в настройках игры нужно загрузить архив с ресурсами и протестировать его работу. Подробности в разделе [Работа с ресурсами для iOS](games/direct-games/on-demand-resources).

1. В игре есть возможность отключить звук.
1. В игре есть канал связи с технической поддержкой. Это может быть ссылка на сообщество, страница внутри игры, адрес электронной почты или личная страница автора.
1. Игра запрашивает у пользователей разрешение на публикацию личных данных: записей, фотографий. Пользователь должен понимать, как игра работает с такой информацией.
1. У пользователя должна быть возможность отказаться от публикации личных данных.
1. У вас нет похожей игры в каталоге. Новая будет одобрена только при наличии существенных различий. Вы можете использовать элементы старой игры, но в таком случае игровые механики должны значительно отличаться.

    > **Обратите внимание!** Мы не отклоняем игры из-за внешнего сходства с игрой, разработанной другим разработчиком (за исключением полного копирования). Если вы считаете, что другие разработчики нарушают ваши права, обратитесь к ним напрямую.

1. Основной язык игры — русский.
1. Графика игры качественно проработана.
1. В игре есть режим обучения с подсказками для новых игроков.
1. Купить игровую валюту можно только за голоса. 

    > **Важно!** В версии игры для iOS купить игровую валюту и другие виртуальные ценности нельзя.

1. В игре используются механики социального взаимодействия, например добавлена кнопка **Рассказать друзьям**.

Посмотрите на примеры игр, которые успешно прошли модерацию и попали в каталог:

:::carousel

![alt=Игра из каталога;title=Игра из каталога](7d4ba20604405928d693650a0c580baf001b369e452cb206aacf861e "-575441788945359711")
![alt=Ещё одна игра из каталога;title=Ещё одна игра из каталога](cd40ca4cc9797035ed8db8116cf07950e107d3a206f75ec89f429b6a "-2572540176541241675")
:::

## Шаг 2. Отправьте заявку на модерацию

Чтобы отправить заявку на добавление игры в каталог:

1. Откройте [Мои приложения](https://vk.com/apps?act=manage)&nbsp;&rarr;&nbsp;**Редактировать**&nbsp;&rarr;&nbsp;**Модерация**.

2. В блоке **Публикация в каталоге игр** нажмите **Отправить заявку на публикацию в каталоге**.

    ![alt=Отправка заявку на модерацию;title=Отправка заявку на модерацию;](3c31d125e3f813e0059d69ee8b16b120514dd5c4b74f90fc1760de41 "1215592287818649302")

    Если вы отправляете заявку для игры вида Direct Games, выберите платформы, на которых вы хотите её разместить (Android, iOS, мобильная версия сайта ВКонтакте). 

    ![alt=Выбор платформ;title=Выбор платформ;](997dc3d9adac929c2076235224c41bc58599ccf2b9b47f4ea650a9b5 "-6960402888854691202")

> Игра, размещённая в приложении ВКонтакте для iOS, появится и в каталоге для iPadOS.

## Шаг 3. Следите за статусом модерации

Проверка обычно занимает от 2 до 7 рабочих дней. После изменения статуса заявки её отправитель получит SMS-сообщение и уведомление в десктопной версии сайта в разделе **Модерация**.

Если модератор отклонит заявку, то укажет причину в ответе и попросит доработать игру. После исправления недочётов вы можете отправить игру на проверку ещё раз.

Задавайте вопросы модератору в заявке на модерацию или [используйте специальную форму](https://vk.com/support?act=new_app&from=sg), чтобы напрямую отправить запрос модератору.

![alt=Статус заявки;title=Статус заявки;](4ebf52fbce8f69123f8471584fccf95436dbe4dc0177d262a9ccabf8 "-6347055476794925580")

Если у модератора нет вопросов к вашей игре и она готова к размещению в каталоге, он обновит статус заявки и разместит игру в каталоге. На этом всё, поздравляем!

Теперь игру можно найти поиском по каталогу, а на иконке игры в зависимости от платформы появится бейдж **Новое** или **New**.

:::carousel
![alt=Новая игра в каталоге;title=Новая игра в каталоге;](b69e722c89c07f29ca8aa342a6cea6b72177664f5cf2a9149b9b0c0a "-3608911507285017423")
![alt=Новая игра в каталоге;title=Новая игра в каталоге;](33070df69bcaa5d5a2e1c681f84d562fb6781079b5cd7e8ccb6538e4 "6196702774876698020")
:::

## Что дальше

### Продвижение игры

Продумайте сценарий продвижения вашей игры, используйте указанные ниже инструменты и подавайте [заявки](https://vk.com/support?act=new_app&from=sg) на размещение в подборках.

После того как игра попала в каталог, для продвижения игры вы можете:

* Создать [миссии](games/promotion/game-mechanics#Миссии), настроить автоматические [уведомления](games/promotion/game-mechanics#Автоматические%20уведомления) и [массовые рассылки](games/promotion/game-mechanics#Массовые%20рассылки).
* Подать заявку на публикацию в разделе **Новые** в десктопной версии сайта ВКонтакте.
* Запустить [рекламу](games/promotion/ad) и добавить возможность [приглашать друзей](games/promotion/game-mechanics#Приглашения).

### Удаление из каталога

Если по какой-либо причине вы хотите удалить игру из каталога, напишите об этом модератору в разделе [Помощь](games/support) в настройках игры.

Модератор может удалить игру из каталога без запроса разработчика по следующим причинам:

* Игра отключена или не работает.
* Разработчик не исправляет критические проблемы и уязвимости.
* В игру внесены изменения, которые нарушают [требования](#Шаг%201.%20Подготовьте%20игру%20к%20модерации). 
* Разработчик не отвечает на сообщения пользователей и вопросы модератора.
> Предварительно модератор напишет разработчику игры о нарушении и попросит исправить его.

Чтобы сразу задать вопрос непосредственно модератору и оперативно получить ответ, [используйте специальную форму](https://vk.com/support?act=new_app&from=sg).

Игры | Каталоги | Как попасть в каталог

# Игровые покупки

**Игровые покупки** — это эффективный способ монетизации игр. Пользователи разнообразят игровой процесс с помощью виртуальных ценностей, а вы получаете прибыль.  

## Платёжный API

Пользователь всегда оплачивает покупки голосами, которые поступают на собственный счёт игры.  Для работы с платежами в играх используется Платёжный API. С его помощью можно обменивать виртуальные ценности на голоса. 

Чтобы подключить Платёжный API к вашей игре, ознакомьтесь с нашим [пошаговым руководством](api/payments/getting-started). 
> Пока игра не прошла модерацию и не размещена в каталоге, можно проводить только тестовые платежи. После публикации в каталоге не забудьте убрать себя из списка тестировщиков в настройках игры, чтобы вы могли платить в «боевом» режиме.

Пользователь может купить товаров не более, чем на 3000 голосов в день. Если ваши игроки часто сталкиваются с подобным ограничением, напишите в [Поддержку](https://vk.com/support?act=new_app), мы увеличим лимит.

## Типы платежей

Платежи делятся на два типа: разовые и регулярные (подписки).

### Разовые платежи

Пользователь однократно оплачивает товар в приложении. Такой механизм лучше всего подходит для покупки ресурсов, например игровой валюты.

![](0c1f6d99584b60a42e54f357cf1ed288b42589cfc7b0af13ab98b4f5 "4268314309978971220")

### Регулярные платежи (подписки)

**Подписка** — это регулярное (каждые 7, 30 или 90 дней) списание голосов со счёта игрока. Вы можете предложить пробный бесплатный период подписки (на 3, 7 или 30 дней), после которого с пользователя начнут регулярно списывать голоса.

![](87bdfaf35cc6d2df9f5ec55f28f023ad198af75c5da2d961085330ce "6793423694965375765")

Подписка лучше всего подходит для продажи бонусов, облегчающих прохождение игры (например, VIP-аккаунтов) или увеличивающих игровые показатели. Подписки можно использовать и для доступа к регулярно обновляющемуся контенту, например к новым уровням или персонажам. 

![](c2b4d6c07f3f3577bcf15b7baabe8aeded696852b34273d91ff6019c "7947755252339995172")

Мы не рекомендуем продавать внутреннюю валюту приложения по подписке, потому что это сильно уменьшит количество разовых покупок во время игры. Но можно выдавать небольшое количество валюты в дополнение к другим бонусам.

## Выплаты
Чтобы получить выплаты за голоса, нужно заключить договор со ВКонтакте [Мои приложения](https://vk.com/apps?act=manage) или с нашим партнёром — [AppsCentrum](https://appscentrum.com/).

Игры | Монетизация | Игровые покупки

# Игровая платформа

**Игры ВКонтакте** &mdash; игровая платформа для пользователей ВКонтакте. Пользователи могут легко запустить игру из интерфейса &mdash; никаких скачиваний, установок и регистрации.

Создайте и разместите игру ВКонтакте и используйте бесплатные методы продвижения для привлечения пользователей.

## Преимущества для разработчиков и издателей

* 10+ миллионов активных игроков ежемесячно.
* 500+ операций API ВКонтакте для интеграции.
* Бесплатные методы продвижения.
* Рекомендации и лучшие практики от платформы.

[Узнайте больше](games/benefits)

## Первые шаги

Игры ВКонтакте &mdash; это HTML5-приложения для мобильных устройств и компьютеров. Начните с создания простой игры и добавьте её на платформу ВКонтакте. [Посмотрите пошаговые инструкции](games/getting-started).

## Продвижение и монетизация

* [Публикация в каталоге игр](games/catalog/moderation)
* [Продвижение](games/promotion/featured)
* [Игровые покупки](games/monetization/digital-goods)
* [Реклама в играх](games/monetization/ad/overview)

## Поддержка и помощь

* [Частые вопросы](games/faq)
* [Как написать в Поддержку](games/support)
* [Сообщества разработчиков](games/support#Сообщества%20разработчиков)
  
## Полезные ссылки

* [Библиотека VK Bridge](games/bridge)
* [API ВКонтакте](https://dev.vk.com/reference)
* [Лучшие практики продвижения](games/promotion/best-practices)
* [Лучшие практики монетизации](games/monetization/best-practices)


Игры | Игровая платформа

# Лучшие практики

Лучшие практики и советы по внедрению [игровых механик](games/promotion/game-mechanics) помогут оптимизировать игровой опыт пользователей в проектах на платформе и повысить ключевые игровые показатели.

## Сообщения от игры

Узнайте, на что нужно обратить внимание при работе с [сообщениями от игры](https://dev.vk.com/games/promotion/game-mechanics#%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F%20%D0%BE%D1%82%20%D0%B8%D0%B3%D1%80%D1%8B), а также, что делать, чтобы пользователь не ушел из игры из-за надоедливых сообщений.
![](95f2ffae74a88fae572d649859fd5a1160b72c5f661ad3aa24ca9130 "-9016895608649483083")

## Общие рекомендации

При работе с механикой вам обязательно нужно:
*  Установить одинаковые или практически идентичные иконки игры и её официального сообщества. Именно от сообщества будут отправляться сообщения пользователю. 
* Отображать правильный контекст при переходе в игру из диалога: если игроку в сообщении написали о награде, при переходе сразу должно появиться окно с упомянутой наградой.
*  Предоставлять игроку релевантные, своевременные и ценные обновления.
*  Придерживаться одного стиля общения и тона языка с вашими игроками, персонализировать сообщения.

### Предсказуемость

Общение с игроками должно быть максимально предсказуемым и полезным. Не навязывайтесь и не просите. Предлагайте и награждайте, обязательно сохраняя игровой контекст. Сообщения могут как сильно повысить лояльность игрока, так и отпугнуть неожиданным вниманием. 

### Количество уведомлений

Не каждое игровое событие нуждается в уведомлении. Не заваливайте игрока сообщениями. Придерживайтесь ограничений на количество отправляемых сообщений и учитывайте ситуацию, в которой стоит их отправлять:
*  В течение трёх дней после последнего запуска игры отправлять одного сообщение в день. 
*  Если за эти три дня пользователь не запустил игру, отправлять ему одно сообщение раз в пять дней.
*  Если пользователь и за это время не запустит игру, дважды отправить ему сообщение с выгодной персональной скидкой или акцией и прекратить отправку сообщений, если пользователь не реагирует на сообщения и не переходит в игру. 

Помните, что сообщения — личный канал коммуникации, и постоянные напоминания лишь приведут к запрету на отправку сообщений.

## Что считается хорошим тоном

Ниже представлены механики и события, которые положительно влияют на возврат игроков. 
*  Сразу после выдачи разрешения отправить игроку приветственное сообщение и объяснить, какую выгоду он получит от сообщений и почему игра решила взаимодействовать с ним подобным образом. 
*  Связать все обновления с социальными механиками, сжатыми по времени событиями, наградами и обновлениями: настал ход игрока, друг обогнал в турнирной таблице, запустилась акция или скидка, открылся турнир/чемпионат, запустились новые уровни, которых игрок ждал и т.д.
*  Показывать игроку предложение разрешить отправку ему сообщений в контексте подходящего игрового момента (модальное окно «Разрешите отправлять вам сообщения и мы напомним, когда откроется сундук» в момент запуска обратного отсчета до открытия сундука). 

Не забывайте постоянно анализировать реакцию игроков на сообщения и выяснять, какие подходы, тексты и события вызывают наибольший интерес.

## Плохие практики

Некоторые подходы и форматы общения строго запрещены на платформе. Вам нужно избегать:
*  Потери контекста перехода в игру. Например, в сообщении говорилось об акции, а при переходе в игре открылся главный экран или модальные окна до окна, связанного с темой сообщения; 
*  Отправки сообщений сразу после закрытия игры;
*  Отправки сообщений без контекста («Вернись в игру немедленно! Тут такое!»);
*  Отправки любых ссылок, уводящих за пределы ВКонтакте.

Игры | Продвижение | Лучшие практики

# Документация

## Создание приложений

### [Мини-приложения](mini-apps/overview)
Создавайте полезные сервисы на каждый день с помощью кросс-платформенных приложений на базе веб-технологий: HTML, JavaScript, CSS.

### [Игры](games/overview)
Увлекайте миллионы игроков своими идеями. Ни паролей, ни скачиваний — игры мгновенно запускаются прямо из интерфейса ВКонтакте. 

### [VK Bridge](bridge/overview)
Используйте API ВКонтакте и API операционной системы, установленной на устройстве пользователя, с помощью одной библиотеки.

### [Маруся](marusia/getting-started)
Создавайте голосовой интерфейс своего продукта с помощью Маруси.

## Бизнес-инструменты

### [VK Pay](pay/getting-started)
Принимайте оплату за товары и услуги — прямо в чатах, сообществах и мини-приложениях, с баланса VK Pay или привязанных к нему карт.

### [VK Donut](api/donut/getting-started)
Управляйте платной подпиской и разнообразными программами лояльности в сообществе.

### [Рекламный API](api/ads/getting-started)
Автоматически запускайте объявления и целые рекламные кампании, обновляйте аудитории ретаргетинга и получайте статистику.

## Интеграция контента

### [Виджеты для сайтов](widgets/overview)
Предоставьте посетителям сайта возможность авторизовываться через ВКонтакте, добавлять комментарии и плейлисты, общаться в сообщениях.

### [Публикации ВКонтакте](api/posts)
Предложите пользователям делиться ВКонтакте статьями или комментариями с вашего сайта или из приложения.

### [Маски](masks/overview)
Создавайте маски — развивайте персональный бренд, заявляйте о себе и привлекайте подписчиков на личную страницу или в сообщество.

### [Чат-боты](api/bots/getting-started)
Автоматизируйте рутинные и похожие задачи с помощью чат-бота ВКонтакте.

Документация

# VK Tunnel

**VK Tunnel** — это утилита, которая позволит отобразить в интернете веб-сервер, работающий на вашем локальном компьютере.

Очень часто в веб-разработке требуется показать своё приложение другим пользователям. Если во время разработки вы пользуетесь локальным сервером, то показать промежуточные результаты на нём — нетривиальная задача. Ещё сложнее становится, когда вам нужно проверить взаимодействие приложения с внешними инструментами, например с VK Bridge, внутри мобильных приложений ВКонтакте.

После запуска VK Tunnel вы можете отслеживать в терминале информацию о состоянии и показателях соединений, установленных через ваш туннель.

> NPM: [`vk-tunnel`](https://www.npmjs.com/package/@vkontakte/vk-tunnel).

## Использование

Вы можете настроить работу через VK Tunnel для любого сервера. Ниже мы приведём пример запуска при создании VK Mini Apps из шаблона. В иных случаях внимательно изучите используемые [параметры](#Переменные%20окружения%20и%20параметры) и их значения.

### Проект мини-приложения из шаблона

1. Установите библиотеку:

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. [Создайте мини-приложение из шаблона](mini-apps/getting-started#Создание%20мини-приложения).
1. Перейдите к папке проекта мини-приложения:

    ```sh
    cd <ПУТЬ_К_МИНИ_ПРИЛОЖЕНИЮ>
    ```

1. В командной строке проекта запустите его:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

### Проект мини-приложения на Node.js

1. Установите библиотеку:

    ```sh
    npm install @vkontakte/vk-tunnel -g
    ```

1. Перейдите к папке проекта мини-приложения:

    ```sh
    cd <ПУТЬ_К_МИНИ_ПРИЛОЖЕНИЮ>
    ```

1. Установите библиотеку `react-scripts`:

    ```sh
    npm i react-scripts
    ```

1. Создайте папку `public` и переместите в неё файл `index.html`.
1. Создайте папку `src` и переместите в неё оставшиеся статические файлы.

    > **Обратите внимание!** Каталог `src` должен иметь файл `index.js`.
    Структура каталога проекта мини-приложения:
    ```
    .
    └── mini-app
        ├── public
            └── index.html
        ├── src
            ├── cactus.png
            ├── dinosaur.png
            ├── index.js
            └── style.css
        ├── package-lock.json
        ├── package.json
        └── README.md
    ```


1. В командной строке проекта запустите его:

    ```sh
    env PORT=10888 HTTPS=true react-scripts start
    ```

1. Или добавьте в файл `package.json` скрипт `start`, после чего сохраните файл:

    ```sh
    "start": "cross-env PORT=10888 HTTPS=true react-scripts start",
    ```

    И запустите проект:

    ```sh
    npm start
    ```

1. Откройте новую командную строку. Вызовите VK Tunnel:
    * Через переменные окружения:

        ```sh
        env NODE_TLS_REJECT_UNAUTHORIZED=0 PROXY_HTTP_PROTO=https PROXY_WS_PROTO=wss PROXY_HOST=0.0.0.0 PROXY_PORT=10888 vk-tunnel 
        ```

    * Через параметры:

        ```sh
        vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888
        ```

1. Или добавьте в файл `package.json` скрипт `tunnel`, после чего сохраните файл:

    ```sh
    "tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=10888 app_id=8174360 endpoints=[web]"
    ```

    И вызовите VK Tunnel:

    ```sh
    npm run tunnel
    ```

1. В командной строке будет предложено перейти по адресу в формате [`https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa`](https://oauth.vk.com/code_auth?stage=check&code=2a2aaaa) для авторизации. Откройте ссылку в браузере, вернитесь в терминал и нажмите **Enter**.
    
    После успешной авторизации в командной строке появится ссылка вида [`https://user12345-jv7zlzzz.wormhole.vk-apps.com`](https://user12345-jv7zlzzz.wormhole.vk-apps.com).
    
    Укажите её в поле **URL** в [Настройках](mini-apps/management/settings) для дальнейшей работы. Если приложение ещё не создано, воспользуйтесь разделом [Регистрация мини-приложения ВКонтакте](mini-apps/getting-started#Регистрация%20мини-приложения%20ВКонтакте).

## Переменные окружения и параметры

Вы можете настроить работу библиотеки при помощи переменных окружения или параметров.

### `NODE_TLS_REJECT_UNAUTHORIZED`

Флаг, который позволяет пропустить проверку самоподписанных сертификатов. Возможные значения:

* `0` — пропустить проверку;
* `1` — проверить сертификат.

Аналогом переменной окружения является параметр `--insecure`. Возможные значения:

* `0` — проверить сертификат;
* `1` — пропустить проверку.

### `PROXY_HTTP_PROTO`

Схема для протокола HTTP. Возможные значения:

* `http` — нешифрованное соединение (значение по умолчанию);
* `https` — шифрованное соединение.

Аналогом переменной окружения является параметр `--http-protocol`. Возможные значения совпадают.

### `PROXY_WS_PROTO`

Схема для WebSocket-протокола. Возможные значения:

* `ws` — нешифрованное соединение (значение по умолчанию);
* `wss` — шифрованное соединение.

Аналогом переменной окружения является параметр `--ws-protocol`. Возможные значения совпадают.

### `PROXY_HOST`

Хост, на котором запущен проект. Значение по умолчанию: `localhost`.

Аналогом переменной окружения является параметр `--host`.

### `PROXY_PORT`

Порт, на котором запущен ваш проект. Значение по умолчанию: `10888`.

Аналогом переменной окружения является параметр `--port`.

### `PROXY_TIMEOUT`

Тайм-аут запросов к вашему приложению. Значение по умолчанию: `5000` (5 секунд). Увеличьте тайм-аут, если мини-приложение получает ответ с ошибкой `Bad gateway` и вы видите в логах сообщение `Error: timeout of 5000ms exceeded`.

Аналогом переменной окружения является параметр `--timeout`.

## Файл `vk-tunnel-config.json`

Для удобства настройки утилиты в проекте мини-приложения создайте файл `vk-tunnel-config.json`, в котором укажите идентификатор мини-приложения и платформы.

Пример файла:

```JSON
{
  "app_id": "8174360",
  "endpoints": ["mobile", "mvk", "web"]
}
```

### `app_id`

Идентификатор мини-приложения.

### `endpoints`

Массив платформ, для которых нужно автоматически заменить адрес в [Настройках](mini-apps/management/settings). Возможные значения:

* `mobile` — мобильное приложение;
* `mvk` — мобильная версия сайта;
* `web` — десктопная версия сайта.

## Ошибки

### Получаю ошибку `Error: Пользователь не является создателем приложения`. Что делать?

Если при запуске утилиты вы видите ошибку `ERROR: Пользователь не является создателем приложения`, обновите токен утилиты:

```sh
rm ~/.config/configstore/@vkontakte/vk-tunnel.json
```

> **Обратите внимание!** Если ошибка сохраняется, убедитесь, что вас добавили в [администраторы](mini-apps/management/admin) мини-приложения.

### Получаю ошибку `Error: connect ECONNREFUSED 127.0.0.1:10888`. Что делать?

Убедитесь, что вы запустили проект:

```sh
npm start
```

Библиотеки | Утилита VK Tunnel

Account

AppWidgets

Apps

Auth

Board

Calls

Database

Docs

Donut

DownloadedGames

Fave

Friends

Gifts

Groups

LeadForms

Likes

Market

Messages

Newsfeed

Notes

Notifications

Orders

Pages

Photos

Places

Podcasts

Polls

PrettyCards

Search

Secure

Stats

Status

Storage

Store

Stories

Streaming

Users

Utils

Video

Wall

Widgets

Описание методов API

Возвращает список пользователей, находящихся в черном списке.

Смещение, необходимое для выборки определенного подмножества черного списка.

offset

Количество объектов, информацию о которых необходимо вернуть.

count

После успешного выполнения возвращает объект, содержащий число результатов в поле `count` и массив [объектов, описывающих пользователей](reference/objects/user) в поле `items`.

account.getBanned

Редактирует информацию текущего профиля.

1260

Имя пользователя. Обязательно с большой буквы.

first_name

Фамилия пользователя. Обязательно с большой буквы.

last_name

Девичья фамилия пользователя (только для женского пола).

maiden_name

Короткое имя страницы.

screen_name

Идентификатор заявки на смену имени, которую необходимо отменить. 
Если передан этот параметр, все остальные параметры игнорируются.

cancel_request_id

пол пользователя. Возможные значения:
*  `1` — женский;
*  `2` — мужской.

Семейное положение пользователя. Возможные значения:
* `1` — не женат/не замужем;
* `2` — есть друг/есть подруга;
* `3` — помолвлен/помолвлена;
* `4` — женат/замужем;
* `5` — всё сложно;
* `6` — в активном поиске;
* `7` — влюблён/влюблена;
* `8` — в гражданском браке;
* `0` — не указано.

relation

Идентификатор пользователя, с которым связано семейное положение.

relation_partner_id

Дата рождения пользователя в формате `DD.MM.YYYY`, например `15.11.1984`.

bdate

Видимость даты рождения. Возможные значения:
* `1` — показывать дату рождения;
* `2` — показывать только месяц и день;
* `0` — не показывать дату рождения.

bdate_visibility

Родной город пользователя.

home_town

Идентификатор страны пользователя.

country_id

Идентификатор города пользователя.

city_id

Статус пользователя, который также может быть изменен методом [`status.set`](method/status.set).

status

Метод возвращает объект, содержащий следующие поля:
*  `changed` – возвращает `1` — если информация была сохранена, `0` — если ни одно из полей не было сохранено.
Если в параметрах передавалось имя или фамилия пользователя, в объекте также будет возвращено поле `name_request` – объект, содержащий информацию о заявке на смену имени, со следующими полями:
*  `id` – идентификатор заявки, необходимый для её отмены (только если `status` равен `processing`). Для отмены заявки необходимо вызвать метод `account.saveProfileInfo` с параметром `cancel_request_id`;
*  `status` – статус заявки, возвращаемые значения:
   * `success` – имя было успешно изменено;
   * `processing` – заявка рассматривается;
   * `declined` – заявка отклонена;
   * `was_accepted` – недавно уже была одобрена заявка, повторную заявку можно подать не раньше даты, указанной в поле `repeat_date`;
   * `was_declined` – предыдущая заявка была отклонена, повторную заявку можно подать не раньше даты, указанной в поле `repeat_date`;
   * `response` – общий ответ по статусу обработки заявки;
   * `response_with_link` – общий ответ по статусу обработки заявки, содержащий ссылку в поле `link`;
*  `first_name` – имя пользователя, указанное в заявке;
*  `last_name` – фамилия пользователя, указанная в заявке.

account.saveProfileInfo

Рекламный API позволяет автоматизировать работу с рекламными возможностями ВКонтакте и эффективно реализовать специфичные для вашего бизнеса рекламные кампании.

## Ключ доступа

Перед вызовом методов API необходимо получить ключ доступа пользователя с помощью [Implicit Flow](api/access-token/implicit-flow-user) или [Authorization Code Flow](api/access-token/authcode-flow-user). После этого можно [выполнять любые запросы к API](api/api-requests). 

## Ограничения на вызов методов рекламного API

При работе с рекламным API учитывайте следующие ограничения:

* Примитивное ограничение — ограничение на количество вызываемых методов в течение короткого промежутка времени (для каждого пользователя). Платформа не позволяет запускать методы более 2 раз в течение одной секунды. 
* Часовое ограничение — ограничение на количество вызываемых методов в течение часа (для каждого рекламного кабинета). У каждого рекламного кабинета есть лимит на вызов методов Ads API в час. При превышении этого лимита доступ к методам Ads API прекращается на час. После окончания часа счетчик использованного количества методов сбрасывается и доступ к методам возобновляется. Час начинает отсчитываться в момент получения запроса и только если счётчик равен нулю. 

### Примитивное ограничение

Сложные методы ([`ads.createAds`](method/ads.createAds), [`ads.updateAds`](method/ads.updateAds), [`ads.getTargetingStats`](method/ads.getTargetingStats), [`ads.importTargetContacts`](method/ads.importTargetContacts), [`ads.getPostsReach`](method/ads.getPostsReach)) разрешается запускать не чаще 5 раз в 10 секунд. 

Все методы (включая сложные) разрешается запускать не чаще 2 раз в секунду. 

Метод [`ads.getUploadURL`](method/ads.getUploadURL) разрешается запускать частотой, заданной для всего API. 

### Часовое ограничение

Ограничение на количество запускаемых методов (кроме [`ads.getUploadURL`](method/ads.getUploadURL)) — 5000 методов в час для обычных кабинетов и 10000 для кабинетов рекламных агентств.
 
Чтобы узнать количество операций, оставшихся до окончания часового периода, используйте [`ads.getFloodStats`](method/ads.getFloodStats). При этом вызов метода [`ads.getUploadURL`](method/ads.getUploadURL) не учитывается при подсчёте количества вызовов, сделанных в течение часа. 

## Ошибки

При превышении примитивного ограничения API возвращает ошибку с кодом `9`. 

При превышении часового ограничения API возвращает ошибку с кодом `601`. 

Ниже представлен список всех методов для работы с данными рекламных кабинетов ВКонтакте.

Метод возвращает список клиентов рекламного агентства. Доступен только для рекламных агентств.

Permission denied. You have requested too many actions this day. Try later.

**Необязательный параметр**. Идентификатор рекламного кабинета.

account_id

Метод возвращает массив объектов.

Объект в массиве имеет следующие параметры:

| Поле | Тип | Описание |
| --- | --- | --- |
| `id` | `integer` | Идентификатор клиента. |
| `name` | `string` | Название клиента. Длина строки: от 3 до 60 символов. |
| `day_limit` | `integer` | Дневной лимит в рублях. |
| `all_limit` | `integer` | Общий лимит в рублях. |
| `ord_data` | `object` | Данные оператора рекламных данных ([`ord_data_specification`](#ord_data_specification)).&#x0d;&#x0a;&#x0d;&#x0a; Доступно с версии 5.194. |

### `ord_data_specification`

Объект описывает оператора рекламных данных.

| Поле | Тип | Описание |
| --- | --- | --- |
| `client_type` | `string` | Тип клиента. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `person` — физическое лицо.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `individual` — индивидуальный предприниматель.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `legal` — юридическое лицо. |
| `client_name` | `string` | Полное имя клиента или название организации клиента. |
| `contract_number` | `string` | Номер контракта. |
| `contract_date` | `string` | Дата контракта в формате `DD.MM.YYYY`. |
| `contract_type` | `string` | Тип контракта. Примеры:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `Договор оказания услуг`.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `Дополнительное соглашение`.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `Посреднический договор`. |
| `contract_object` | `string` | Предмет контракта. Вы можете скопировать информацию из текста договора — пункт «Предмет договора» — или кратко опишите суть договора (что должны сделать заказчик и исполнитель). |
| `with_vat` | `boolean` | Информация о том, подлежит ли НДС оплате в рамках этого контракта. |
| `inn` | `string` | ИНН клиента. Длина строки: 10 или 12 символов. |
| `phone` | `string` | Телефон клиента. Длина строки: от 7 до 20 символов. |
| `subagent` Необязательное поле  | `object` | Данные о подрядчике ([`ord_subagent`](#ord_subagent)). |

### `ord_subagent`

Объект описывает подрядчика.

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` | `string` | Тип подрядчика. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `person` — физическое лицо.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `individual` — индивидуальный предприниматель.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `legal` — юридическое лицо. |
| `name` | `string` | Название подрядчика. |
| `inn` | `string` | ИНН подрядчика. Длина строки: 10 или 12 символов. |
| `phone` | `string` | Телефон подрядчика. Длина строки: от 7 до 20 символов. |

Пример ответа:

```JSON
[
   {
      "id": 1600000000,
      "name": "Клиент 1",
      "day_limit": "100",
      "all_limit": "1000",
      "ord_data": {
         "client_type": "individual",
         "client_name": "Персик Рыжий",
         "contract_number": "№134",
         "contract_date": "05.10.2022",
         "contract_type": "Договор оказания услуг",
         "contract_object": "Услуга",
         "with_vat": true,
         "inn": "111111111111",
         "phone": "+79000000000",
         "subagent": {
            "type": "individual",
            "name": "Пинг Пингвин",
            "inn": "123456789012",
            "phone": "+79000000001"
         }
      }
   },
   {
      "id": 1600000001,
      "name": "Клиент 2",
      "day_limit": "100",
      "all_limit": "1000",
      "ord_data": {
         "client_type": "person",
         "client_name": "Сеня Хомяк",
         "contract_number": "№135",
         "contract_date": "05.10.2022",
         "contract_type": "Договор оказания услуг",
         "contract_object": "Услуга",
         "with_vat": true,
         "inn": "111111111112",
         "phone": "89000000000"
         "subagent": {
            "type": "individual",
            "name": "Пинг Пингвин",
            "inn": "123456789012",
            "phone": "89000000001"
         }
      }
   }
]
```

ads.getClients

Возвращает набор подсказок для различных параметров таргетинга.

Раздел, по которому запрашиваются подсказки.
Поддерживаются следующие значения:
* `countries` — страны.
   * `q` — необязательный параметр;
      * `1` — возвращается полный список стран;
      * `не задан` — возвращается краткий список стран.
* `regions` — регионы.
   * `country` — обязательный параметр;
   * `q` — обязательный параметр.
* `cities` — города.
   * `country` — обязательный параметр;
   * `q` — необязательный параметр.
* `districts` — районы.
   * `cities` — обязательный параметр.
* `stations` — станции метро.
   * `cities` — обязательный параметр.
* `streets` — улицы.
   * `cities` — обязательный параметр,
   * `q` — обязательный параметр.
* `schools` — учебные заведения: школы, университеты, факультеты, кафедры.
   * `cities` — обязательный параметр;
   * `q` — обязательный параметр.
* `interest_categories_v2` — категории интересов.
* `interest_categories` — устаревшие категории интересов.
* `positions` — должности (профессии).
   * `q` — необязательный параметр.
* `religions` — религиозные взгляды.
* `user_devices` — устройства.
* `user_os` — операционные системы.
* `user_browsers` — интернет-браузеры.

section

ID объектов, разделённые запятыми. Служит для расшифровки ID, возвращаемых в методе [`ads.getAdsTargeting`](method/ads.getAdsTargeting). Если задан этот параметр, то параметры `q`, `country`, `cities` не должны передаваться, таким образом отменяется их обязательность для конкретного раздела. Объекты возвращаются в том же порядке, в каком они были заданы в этом параметре.

Строка-фильтр запроса. 

Id страны, в которой ищутся объекты.

country

Id городов, в которых ищутся объекты, разделенные запятыми.

cities

Язык возвращаемых строковых значений. Поддерживаемые языки:
* `ru` — русский;
* `ua` — украинский;
* `en` — английский. 

lang

Возвращает список объектов (подсказок), удовлетворяющих запросу. 

Для разделов `countries`, `positions`, `interest_categories`, `religions`, `user_devices`, `user_os`, `user_browsers` ответ возвращается в виде массива объектов со следующими полями:
* `id` — идентификатор объекта;
* `name` — название объекта.

Для раздела `regions` ответ возвращается в виде массива объектов со следующими полями:
* `id` — идентификатор региона;
* `name` — название региона;
* `type` (необязательное) — название типа региона (область, автономный округ, край).

Для разделов `cities`, `districts`, `streets` ответ возвращается в виде массива объектов со следующими полями:
* `id` — идентификатор объекта;
* `name` — название объекта;
* `parent` — название города или страны, в котором находится объект.

Для раздела `schools` ответ возвращается в виде массива объектов со следующими полями:
* `id` — идентификатор учебного заведения;
* `name` — название учебного заведения;
* `desc` — полное название учебного заведения;
* `type` — тип учебного заведения:
   * `school` — школа;
   * `university` — университет;
   * `faculty` — факультет;
   * `chair` — кафедра. 
* `parent` — название города, в котором находится учебное заведение.

Для раздела `interests` ответ возвращается в виде массива строк.


ads.getSuggestions

Принимает запрос на исключение контактов рекламодателя из аудитории ретаргетинга.

Идентификатор рекламного кабинета.

**Только для рекламных агентств**. 

Id клиента, в рекламном кабинете которого находится аудитория.

client_id

Bдентификатор аудитории таргетинга.

target_group_id

Список телефонов, email адресов или идентификаторов пользователей, указанных через запятую. Также принимаются их MD5-хеши.

contacts

Возвращает `1` в случае успешного принятия заявки на исключение аудитории.

ads.removeTargetContacts

Позволяет сохранить изображение в коллекцию сообщества для [виджетов приложений сообществ](api/community-apps-widgets/getting-started). после загрузки на сервер.

* `hash`  (`string`) — параметр `hash`, полученный после загрузки на сервер.
* `image` (`string`) — параметр `image`, полученный после загрузки на сервер.

Возвращает объект, который содержит следующие поля:
* `id` (`string`) — идентификатор изображения.
* `type` (`string`) — тип изображения. Возможные значения:
   * `160x160`,
   * `160x240`,
   * `24x24`,
   * `510x128`,
   * `50x50`.
* `images ` (`array`) — массив копий изображения. Каждый объект в массиве содержит следующие поля:
   * `url` (`string`) — URL копии;
   * `width` (`integer`) — ширина в px;
   * `height` (`integer`) — высота в px.

appWidgets.saveGroupImage

Проверить есть ли у пользователя подарок в игре.

Идентификатор промо-акции.

promo_id

Идентификатор пользователя. Используется только при запросе с сервисным токеном.

user_id

Идентификатор акции будет сообщен администрацией заранее при планирование проведения акции.

```json
{
  "response": 0|1
}
```

Где в поле `response` хранятся данные о наличии подарка в игре:
`1` - у пользователя есть активный подарок, нужно выдать подарок пользователю в игре и затем погасить его используя метод `apps.promoUseGift`.
`0` - у пользователя нет активного подарка в вашей игре.

apps.promoHasActiveGift

Восстанавливает удаленное сообщение темы в обсуждениях группы.

Удаляет сообщение темы в обсуждениях сообщества.

board.deleteComment

идентификатор сообщества, в котором размещено обсуждение.

group_id

идентификатор обсуждения.

topic_id

comment_id

После успешного выполнения возвращает `1`.

board.restoreComment

Возвращает список станций метро.

Идентификатор города, полученный методом [`database.getCities`](method/database.getCities).

Отступ, необходимый для выбора определенного подмножества станций.

Количество станций, которое необходимо вернуть.

extended

После успешного выполнения возвращает объект, содержащий число результатов в поле `count` и массив объектов, описывающих станции метро, в поле `items`. 

Каждый объект содержит следующие поля:

`id`
`integer`
Идентификатор. 

`name`
`string`
Название.

`color`
`string`
Цвет линии.

database.getMetroStations

Сохраняет документ после его успешной [загрузки](api/upload) на сервер.

Параметр, возвращаемый в результате [загрузки файла](api/upload) на сервер.

file

title

return_tags

После успешного выполнения возвращает массив объектов, описывающих загруженные документы. Каждый объект массива содержит поле `type` (`string`) с возможными значениями `audio_message`, `doc`, и одноименный объект, описывающий загруженный документ.

Для `type` = `audio_message` объект `audio_message`, описывающий [голосовое сообщение](reference/objects/audio-message).
Для `type` = `doc` объект `doc`, описывающий другие типы [документов](reference/objects/doc).

docs.save

Возвращает результаты поиска по документам.

После успешного выполнения возвращает список объектов [документов](reference/objects/doc).

Если установлен флаг `search_own`, в поле `local` дополнительно вернется список документов из локального поиска. Начиная с версии 5.74, вместо этого в `items` сначала возвращаются документы пользователя, а потом документы из глобального поиска.