# 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 | Ключ доступа | Общие сведения

# Формат запросов

## Синтаксис запроса

Чтобы обратиться к методу API ВКонтакте, нужно выполнить `POST` или `GET` запрос вида:

```
https://api.vk.com/method/METHOD?PARAMS&access_token=TOKEN&v=V
```

Он состоит из нескольких частей:
* `METHOD` (**обязательно**) — название [метода API](method), к которому вы хотите обратиться. 
    > **Обратите внимание:** имя метода чувствительно к регистру.
* `PARAMS` (**не обязательно**) — входные параметры соответствующего метода API, последовательность пар `name=value`, разделенных амперсандом. Список параметров указан на странице с описанием метода.
* `TOKEN` (**обязательно**) — [ключ доступа](api/access-token/getting-started).
* `V` (**обязательно**) — используемая версия API. Использование этого параметра применяет некоторые изменения в формате ответа различных методов. Сейчас [актуальная версия API](reference/versions) — :version. Этот параметр следует передавать со всеми запросами.

Параметры могут передаваться как методом `GET`, так и `POST`. Если вы будете передавать большие данные (больше 2 килобайт), следует использовать `POST` и формат `FormData`.

Например, вызовем метод [`users.get`](method/users.get) для пользователя с идентификатором `210700286`:

```
https://api.vk.com/method/users.get?user_ids=210700286&fields=bdate&access_token=533bacf01e11f55b536a565b57531ac114461ae8736d6506a3&v=:version
```

В ответ на такой запрос вы получите ответ в формате JSON:

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

## Общие параметры

Каждый метод API имеет собственный набор входных параметров. Помимо этого, существуют общие параметры, которые могут быть использованы во всех методах:
* `lang` — определяет язык, на котором будут возвращаться различные данные, например, названия стран и городов. Может содержать строковое обозначение языка или его идентификатор (получить идентификатор языка пользователя вы можете методом [`account.getInfo`](method/account.getInfo)). Кириллические имена будут автоматически транслитерированы в латиницу для всех языков, кроме русского, украинского и белорусского.
* `ru` (`0`) — русский,
* `uk` (`1`) — украинский,
* `be` (`2`) — белорусский,
* `en` (`3`) — английский,
* `es` (`4`) — испанский,
* `fi` (`5`) — финский,
* `de` (`6`) — немецкий,
* `it` (`7`) — итальянский.
* `test_mode=1` — тестовый режим, позволяет выполнять запросы из нативного приложения без его включения на всех пользователей.

## Ограничения и рекомендации

### Частотные ограничения

К методам API ВКонтакте (за исключением методов из секций [`secure`](method/secure) и [`ads`](method/ads)) с ключом доступа пользователя можно обращаться не чаще **3** раз в секунду. Для ключа доступа сообщества ограничение составляет **20** запросов в секунду. Если логика вашего приложения подразумевает вызов нескольких методов подряд, имеет смысл обратить внимание на метод [`execute`](method/execute). Он позволяет совершить до **25** обращений к разным методам в рамках одного запроса.

Для сервисного ключа доступа лимиты такие:

| Кол-во пользователей приложения | Частотный лимит (кол-во запросов в секунду) |
| ----------- | ----------- |
| до 10 000 | 5 |
| до 100 000 | 20 |
| до 500 000 | 40 |
| до 1 млн | 50 |
| больше 1 млн | 60 |

Для методов секции [`ads`](method/ads) действуют собственные [ограничения](method/ads#Ограничения%20на%20вызов%20методов%20рекламного%20API).

Максимальное число обращений к методам секции [`secure`](method/secure) зависит от числа пользователей, установивших приложение. Если приложение установило меньше 10 000 человек, то можно совершать 5 запросов в секунду, до 100 000 — 8 запросов, до 1 000 000 — 20 запросов, больше 1 млн. — 35 запросов в секунду.

Если вы превысите частотное ограничение, сервер вернет ошибку с кодом `6: "Too many requests per second."`.

### Количественные ограничения

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

После превышения количественного лимита доступ к конкретному методу может требовать ввода капчи (см. [`captcha_error`](api/captcha-error)), а также может быть временно ограничен (в таком случае сервер не возвращает ответ на вызов конкретного метода, но без проблем обрабатывает любые другие запросы).

## Примеры

### Кроссдоменный запрос с использованием JSONP

Запросы к API ВКонтакте могут быть выполнены из браузера со страниц сторонних сайтов или [IFrame приложений](sdk/overview).

Чтобы осуществлять кроссдоменные запросы к API, вы можете использовать протокол [JSONP](https://ru.wikipedia.org/wiki/JSONP). Для этого необходимо подключать к документу скрипт с адресом запроса в `src`. Запрос должен содержать дополнительный параметр `callback` c именем функции, которая будет вызвана при получении результата.

Например:

```HTML
<html>
   <title>JSONP</title>
   <head></head>
   <body>
      <script type="text/javascript">
         var script = document.createElement('SCRIPT');
         script.src = "https://api.vk.com/method/users.get?user_ids=210700286&fields=bdate&v=:version&callback=callbackFunc";
         document.getElementsByTagName("head")[0].appendChild(script);
         function callbackFunc(result) {
         alert(result.response[0].first_name)
         }
      </script>
   </body>
</html>
```

В нашем примере после загрузки документа вызывается метод [`users.get`](method/users.get), а после получения ответа от сервера управление передается функции `callbackFunc()`, которая выводит содержимое поля `first_name` из ответа во всплывающем окне.

### Запрос из PHP

```PHP
<?php
$user_id = 210700286;
$request_params = array(
    'user_id' => $user_id,
    'fields' => 'bdate',
    'v' => '5.52',
    'access_token' => '533bacf01e11f55b536a565b57531ac114461ae8736d6506a3'
);
$get_params = http_build_query($request_params);
$result = json_decode(file_get_contents('https://api.vk.com/method/users.get?' . $get_params));
echo ($result->response[0]
    ->bdate);
?>
```

В нашем примере скрипт выводит дату рождения пользователя (`bdate`), полученную обращением к методу [`users.get`](method/users.get).

### Запрос с использованием Open API

[Open API](api/open-api/getting-started) — JS-библиотека для упрощения работы с API ВКонтакте на внешних сайтах.

```HTML
<script type="text/javascript">
   VK.Api.call('users.get', { user_ids: 210700286, fields: 'bdate' }, function(r) {
   if(r.response) {
   alert(r.response[0].bdate);
   }
   });
</script>
```

Использование API | Формат запросов

# Bots Long Poll API

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

Чтобы использовать Bots Long Poll API, откройте раздел **Управление сообществом**, на вкладке **Работа с API** → **Long Poll API** выберите **Включён**.

## Подключение

Перед подключением к Long Poll серверу необходимо получить данные сессии (`server`, `key`, `ts`) методом [`groups.getLongPollServer`](method/groups.getLongPollServer).

Затем составьте запрос такого вида:

```
{$server}?act=a_check&key={$key}&ts={$ts}&wait=25
```

В нём используются следующие параметры:
*  `key` — секретный ключ сессии;
*  `server` — адрес сервера;
*  `ts` — номер последнего события, начиная с которого нужно получать данные;
*  `wait` — время ожидания (так как некоторые прокси-серверы обрывают соединение после 30 секунд, мы рекомендуем указывать `wait`=`25`). Максимальное значение — `90`.

Для первого запроса в рамках сессии значения для параметров `server`, `key` и `ts` необходимо получить методом [`groups.getLongPollServer`](method/groups.getLongPollServer). В последующих запросах используйте те же `server` и `key` и новое значение `ts`, которое придет вам в ответе от Long Poll сервера.

В разделе **Управление сообществом** → **Работа с API** → **Bots Long Poll API** → **Типы событий** отметьте те события, которые вы хотите отслеживать. Полный список событий вы найдёте [на этой странице](api/community-events/json-schema).

### Настройка через API

Вы можете управлять настройками Bots Long Poll API в вашем сообществе не только в веб-интерфейсе, но и с помощью методов API:
* [`groups.getLongPollServer`](method/groups.getLongPollServer) — получает адрес для подключения к Long Poll серверу ВКонтакте;
* [`groups.getLongPollSettings`](method/groups.getLongPollSettings) — получает настройки событий Bots Long Poll API;
* [`groups.setLongPollSettings`](method/groups.setLongPollSettings) — устанавливает настройки событий Bots Long Poll API.

## Формат данных

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

```JSON
{
  "ts": "4",
  "updates": [
    {
      "type": "wall_post_new",
      "event_id": "c68dfb983247fea8ac98ea0ea59717df71d8064f",
      "v": ":version",
      "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
    }
  ]
}
```

JSON-объект в ответе содержит два поля:
* `ts` (`string`) — номер последнего события. Используйте его в следующем запросе.
* `updates` (`array`) — массив, элементы которого содержат представление новых событий. 

После получения любого ответа для продолжения связи нужно отправить запрос с новым `ts`, полученным в последнем ответе.   

### Типы событий

Событие в массиве `updates` представляет собой JSON, имеющий следующую структуру:

```JSON
{
  "type": <тип события>,
  "event_id": <идентификатор события>,
  "v": <версия API, для которой сформировано событие>,
  "object": <объект, инициировавший событие>,
  "group_id": <ID сообщества, в котором произошло событие>
}
```

Например:

```JSON
{
  "type": "group_join",
  "event_id": "c68dfb983247fea8ac98ea0ea59717df71d8064f",
  "v": ":version",
  "object": {
    "user_id": 1,
    "join_type": "approved"
  },
  "group_id": 1
}
```

Структура событий в Bots Long Poll API идентична событиям в Callback API. Полный список событий вы найдёте [на этой странице](api/community-events/json-schema).

### Ошибки

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

```JSON
{
  "failed": 1,
  "ts": 30
}
```
```JSON
{
  "failed": 2
}
```
```JSON
{
  "failed": 3
}
```

* `"failed":1` — история событий устарела или была частично утеряна, приложение может получать события далее, используя новое значение `ts` из ответа.
* `"failed":2` — истекло время действия ключа, нужно заново получить `key` методом [`groups.getLongPollServer`](method/groups.getLongPollServer).
* `"failed":3` — информация утрачена, нужно запросить новые `key` и `ts` методом [`groups.getLongPollServer`](method/groups.getLongPollServer).

Обратите внимание: объекты в сообщении об ошибке могут содержать поля, не описанные  в документации. Их необходимо игнорировать и не обрабатывать. 

## Поддержка в SDK

Вы можете работать с Bots Long Poll API средствами наших SDK:
* [Java SDK](sdk/java),
* [PHP SDK](sdk/php),
* [Node.js SDK](https://github.com/Naltox/node-vk-sdk) (неофициальный).

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

# Клавиатура

## Подключение

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

## Кнопка «Начать»

Если она включена, и у пользователя еще нет переписки с сообществом, мы показываем кнопку «Начать», которая отправляет команду `start`. [Payload](#Отправка%20клавиатуры) этого сообщения будет выглядеть так: 

```
{"command":"start"}
```

## Внешний вид

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

### Стандартное отображение

По умолчанию, если не передан параметр `inline`, клавиатура показывается под полем ввода в диалоге с пользователем. Максимальный размер стандартной клавиатуры — 5 × 10. Максимальное количество клавиш: 40. 

![](23da71d33405de08fec50d8805eb69fbf7024196a16dad3d328de21b "616200134238115590")

### Inline-отображение

Клавиатура может отображаться внутри сообщения — это inline-отображение. Чтобы включить его, передайте параметр inline в объект клавиатуры. Её максимальный размер составит 5 × 6. Максимальное количество клавиш: 10. 

![](ea51b7f45bf0a0d0c1d393d5990e6e51728c00ddb5ab984134578f1a "6537326869192998723")

## Структура данных

### `one_time`
`bool`
Скрывать ли клавиатуру после первого использования. Параметр срабатывает только для кнопок, отправляющих сообщение (поле `type` - `text, location`) Для `type` равных `open_app`, `vk_pay` параметр игнорируется. 
Возможные значения:
* `true` — клавиатура будет скрыта при нажатии на кнопку с типом `text` или `location`;
* `false` — клавиатура не скрывается; 

### `buttons`

`array`
Массив массивов с кнопками. 

### `inline`

`bool`
Должна ли клавиатура отображаться внутри сообщения. Возможные значения:
*  `true` — клавиатура отображается внутри сообщения. Параметр `one_time` при этом не поддерживается;
*  `false` — стандартное отображение клавиатуры.

### `action`

`object`
Объект, описывающий тип действия и его параметры. Поля объекта зависят от значения параметра `type` и описаны в таблице ниже.

### `color`

`string`
Цвет кнопки. Параметр используется только для кнопок с `type`: `text` и `callback`. Возможные значения:
*  `primary` — синяя кнопка, обозначает основное действие. `#5181B8` 
*  `secondary` — обычная белая кнопка. `#FFFFFF` 
*  `negative` — опасное действие, или отрицательное действие (отклонить, удалить и тд). `#E64646` 
*  `positive` — согласиться, подтвердить. `#4BB34B`

Поля объекта `action` в зависимости от типа кнопки.

### `Text`

Текстовая кнопка. Отправляет сообщение c текстом, указанным в `label`. Поля текстовой кнопки:
* `type` (`string`) — для текстовой кнопки имеет значение `text`;
* `label` (`string`) — текст кнопки. Будет отправлен пользователем в диалог с сообществом/беседу при нажатии;
*  `payload` (`string`) — дополнительная информация. Вернется в [событии](api/community-events/json-schema) `message_new` в одноименном поле. Максимум 255 символов.

### `Open Link`

Открывает указанную ссылку. Поля:
* `type` (`string`) — для кнопки открытия ссылки имеет значение `open_link`;
* `link` (`url`) — ссылка, которую необходимо открыть по нажатию на кнопку;
* `label` (`string`) — текст кнопки;
*  `payload` (`string`) — дополнительная информация. В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.

### `Location`

 По нажатию отправляет местоположение в диалог с ботом/беседу. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки местоположения имеет значение `location`;
* `payload` (`string`) — дополнительная информация. Вернется в [событии](api/community-events/json-schema) `message_new` в одноименном поле. Максимум 255 символов.


### `VK Pay`

Открывает окно оплаты VK Pay с предопределёнными параметрами. Кнопка называется «Оплатить через VK pay», VK pay отображается как логотип. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки вызова платежного окна имеет значение `vkpay`;
* `payload` (`string`) — дополнительная информация.  В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
*  `hash` (`string`) — строка, содержащая [параметры платежа VK Pay](pay/getting-started) и идентификатор приложения в параметре `aid` , разделенные `&`. Пример: `action=transfer-to-group&group_id=1&aid=10`.

### `VK Apps`

Открывает указанное приложение VK Apps. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:
* `type` (`string`) — для кнопки открытия сервиса имеет значение `open_app`;
* `app_id` (`int`) — идентификатор вызываемого приложения с типом VK Apps.  
* `owner_id` (`int`) — идентификатор сообщества, в котором установлено приложение, если требуется открыть в контексте сообщества;
* `payload` (`string`) — дополнительная информация.  В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
* `label` (`string`) — название приложения, указанное на  кнопке. 
* `hash` (`string`) — хеш для навигации в приложении, будет передан в строке параметров запуска после символа `#`.

### `Callback`

Позволяет без отправки сообщения от пользователя получить уведомление о нажатии на кнопку и выполнить необходимое действие.  Поля:
* `type` (`string`) — для callback-кнопки имеет значение `callback`;
* `label` (`string`) — текст кнопки. 
*  `payload` (`string`) —  дополнительная информация. В кнопках, не отправляющих текст, передаётся для совместимости со старыми клиентами. Максимум 255 символов. Подробнее читайте в разделе [Callback-кнопки](api/bots/development/keyboard#Callback-кнопки).

### Пример клавиатуры в JSON

```JSON
{  
   "one_time":false,
   "buttons":[  
      [  
         {  
            "action":{  
               "type":"location",
               "payload":"{\"button\": \"1\"}"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"open_app",
               "app_id":6232540,
               "owner_id":-157525928,
               "hash":"123",
               "label":"LiveWidget"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"vkpay",
               "hash":"action=transfer-to-group&group_id=181108510&aid=10"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"1\"}",
               "label":"Red"
            },
            "color":"negative"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Green"
            },
            "color":"positive"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Blue"
            },
            "color":"primary"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"White"
            },
            "color":"secondary"
         }
      ]
   ]
}
```

## Отправка клавиатуры

JSON-объект клавиатуры передается строкой в параметре `keyboard` в методе [`messages.send`](method/messages.send) с последней версией API. 

Как только пользователь нажимает на одну из кнопок клавиатуры, отправляется сообщение с текстом из поля `label`. Если задан параметр `payload`, он дополнительно придет в callback API. 

> **Важное замечание**: чтобы получать параметр `payload`, нужно поднять версию callback API до 5.69 или выше. Параметр `payload` нужно передавать в формате JSON.

## Пример события в Callback API

```JSON
{
    "type": "message_new",
    "object": {
        "id": 41,
        "date": 1526898082,
        "out": 0,
        "user_id": 163176673,
        "read_state": 0,
        "title": "",
        "body": "Blue",
        "payload": "{\"button\":\"4\"}"
    },
    "group_id": 1
}
```

Также, если клавиатура была определена с флагом `one_time`, она сразу же скрывается. Если нет, остается как была и пользователь может отправить еще сколько угодно команд.
Чтобы убрать у пользователя клавиатуру, необходимо отправить сообщение с пустым параметром `buttons`:

```JSON
{"buttons":[],"one_time":true}
```

## Callback-кнопки

Callback-кнопки — тип кнопок, который работает в стандартном и в inline-отображении клавиатур ботов.

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

### Примеры использования

* Реализация основного меню бота: после нажатия на callback-кнопку на клавиатуре бот обновляет её, выполняя переход на уровень глубже по вложенности меню. При этом пользователю не нужно отправлять боту дополнительное сообщение.
* Редактирование сообщения: пользователь нажимает на callback-кнопку в inline-клавиатуре из сообщения, выбирая категорию блюда в меню, — бот редактирует сообщение, предлагая блюда из этой категории. Пользователь при этом не отправляет боту сообщение.
* Отправка результата действия: пользователь нажимает на callback-кнопку, например «Пополнить баланс», которая совершает определённое действие. После его успешного выполнения бот показывает пользователю информацию «Баланс пополнен» при помощи snackbar. Отправка сообщения при этом не требуется.

### Принцип работы

```JSON
{
  action: {
    type: "callback",
    payload: "{}", // максимум 255 символов
    label: "Нажми меня"
  }
}
```
* пользователь нажимает на клавишу;
* бот получает новое событие `message_event` в Callback или LongPoll API:
```JSON
{
  "conversation_message_id": 1234,
  "user_id": 612512941,   // id пользователя, который нажал на кнопку
  "peer_id": 2000000094, // id диалога со стороны бота
  "event_id": "feleyinek", // Случайная строка. Активна в течение минуты, спустя минуту становится недействительной
  "payload": "{}"
}
```
* бот формирует запрос к API, используя метод [`messages.sendMessageEventAnswer`](method/messages.sendMessageEventAnswer);
* клиент пользователя получает ответ от бота и выполняет нужное действие.

### Действие после нажатия на кнопку

Бот отправляет `event_data` — объект действия, которое должно произойти после нажатия на кнопку.
```JSON
{
    "type": "show_snackbar",
    "text": "Покажи исчезающее сообщение на экране"
  }
```
Метод [`messages.sendMessageEventAnswer`](method/messages.sendMessageEventAnswer) можно выполнить только один раз за нажатие на клавишу.  

### Типы действий

1. `show_snackbar` — показать исчезающее сообщение.
    Содержит поле `text` — текст, который нужно вывести (максимум 90 символов). Snackbar показывается в течение 10 секунд и автоматически скрывается, при этом у пользователя есть возможность смахнуть его с экрана.
    ![](de951d983e604c2aabe128a8e5e1ccb37de792b2b582d9ca221db1dc "-3563741600283602501")
2. `open_link` — открыть ссылку. Осуществляется переход по указанному адресу.
    ```JSON
    {
      type: "open_link",
      link: url
    }
    ```
3. `open_app` — открыть VK Mini App. Происходит переход в мини-приложение.
    ```JSON
    {
      type: "open_app",
      app_id: int,
      owner_id: int | null,
      hash: string
    }
    ```
### Внешний вид

Callback-кнопки выглядят так же, как и обычные кнопки, и поддерживают все стили. После нажатия на кнопку на время выполнения действия возникает индикатор загрузки.
![](2ded1e4a35c7dae08f9d64009478dee14f2498cd1876683b67a36bcf "-532726193596602097")

### Обработка ошибок

Если в формате объекта клавиатуры есть ошибки, [`messages.send`](method/messages.send) вернёт ошибку `911. Keyboard format is invalid`.

Интеграция | Чат-боты | Разработка | Клавиатура

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

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

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

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

> Если ранее вы не работали с 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) используемого языка.

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

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

В этом руководстве вы найдете базовую информацию о принципах работы 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 | Быстрый старт

# Товары ВКонтакте

**Товары ВКонтакте** – это витрина с товарами и услугами в вашем сообществе ВКонтакте. 

![title=Блок с товарами на главной странице сообщества](11022d528d5d387fbb61f51e4b046d5e0d78379a23f968b0861afd1d "-5203208861033356884")

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

## Как это работает?

Вы добавляете в сообщество товары с фотографиями, ценами и подробным описанием. Используйте подборки (коллекции товаров по категориям), чтобы клиенты могли быстро разобраться в ассортименте. 

![title=В разделе с товарами доступен поиск по наименованию и цене](2cc1ea6be1122788c3e90128a73878337ddd05d50a8fcb2ec055c406 "2682289002888373244")

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

![title=Карточка товара – сюда можно добавить любую информацию, полезную для покупателя](b386c4e88a09935cb2b07d43dfdcc36b04ad0e3353da8b99f177dbf1 "-637134464653778470")

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

В настройках сервиса (раздел **Управление сообществом** → **Товары**) вы можете задать валюту магазина, регионы доставки, контактное лицо. Заполните вики-страницу **Описание магазина** – здесь пользователи смогут прочитать об условиях оплаты и доставки перед покупкой. 

Выбор способа оплаты и доставки заказов остается за вами. 

## Доставка

Теперь доставлять товары через Boxberry и СДЭК можно прямо из Магазина ВКонтакте. Это удобное решение для бизнеса и клиентов, которое поможет продавать быстрее и больше. 

![](d84302030ec7bf82e0824216cd40405b0f35762c05c8fbd7f123eeb8 "-536902625946196038")

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

Вначале убедитесь, что у вас включён Магазин 2.0 в настройках сообщества. 

Нажмите **Управление** → **Настройки** → **Разделы**. Включите раздел **Товары**. Для работы с доставкой должен быть выбран **Расширенный** режим. 

![](d2b5b34c5da9100bff19aec8d49be18a7d99ded64798fe42c557a02e "8014173844027144298")

Нажмите **Показать настройки** → **Доставка**. Также перейти в настройки магазина можно через главную страницу сообщества. 

![](7a6b0cd237030915c8546f4023ef9e4f75796655401306a5c23a113c "7767136780412586436")

Нажмите **Включить** для Boxberry и СДЭК. 

![](39a7f82a6cf220740f1e7d3b86b4a387e7bc86579d064c6207bc7827 "-4074010642457854577")

Для СДЭК и Boxberry стоимость доставки рассчитывается по габаритам и весу товара. Указать эти параметры вы можете заранее в карточке товара – тогда прогноз для покупателя будет точным. Вес и габариты также можно прописать на этапе получения заказа. 

## Укажите свойства товаров

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

![](75cafdffa3a261a3af5ebdb6788b3c3a0e9c6f0168e611b45a0802c2 "-4967459588447635267")

## Проверьте поступивший заказ

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

Из этого же окна вы можете связаться с покупателем и уточнить детали заказа. 

![](7dd640fdd996ee64368dd36520497c5f916cda6c226e47d2a1e03d9d "-6931970821843698708")

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

## Договоритесь об оплате

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

>  **Важно.** Доставку оплачивает покупатель. Она уже будет включена в стоимость заказа, если вы указали габариты и вес товара. Если вы не вносили эти данные, то клиент увидит сообщение **Стоимость уточняйте у продавца**. 

Отправка через СДЭК рассчитывается по тарифу **Экспресс-лайт**, подробности описаны по [ссылке](https://cdek.ru/express-light). Стоимость доставки Boxberry рассчитывается по специальному тарифу для магазинов ВКонтакте. 

## Отправьте заказ

Получив заказ, в котором указан способ доставки через СДЭК или Boxberry, нужно убедиться, что рассчитана стоимость. 

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

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

Что делать дальше:

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

Найти ближайшее отделение можно здесь: [Boxberry](https://boxberry.ru/find_an_office/) и [СДЭК](https://cdek.ru/offices). Обе компании работают с физическими и юридическими лицами. 

## Добавьте трек-номер

Впишите трек-номер в соответствующее поле. Так пользователю будет проще отслеживать посылку на сайте доставки – будет достаточно одного клика из раздела **Заказы**. 

![](a5b0a5d31fbae44ec0aedc30e75625128639282b0279dc8529c5ffd8 "1565333712537667774")

> **Важно.** Не забудьте при отправке сменить статус заказа на **Доставляется**: тогда пользователь сразу получит уведомление о том, что товар в пути. 

![](55f4339a699abb4df078b1f3293c5fc25900ecae0c844aac4b617bd0 "5578399229701508714")

## API для товаров

API позволяет автоматизировать работу с товарами и заказами. Используйте готовое решение для импорта товаров из внешней базы или создайте собственный инструмент – это просто. 

> Подробнее о методах API ВКонтакте для работы с товарами в сообществах мы рассказали в разделе [API для товаров](api/market/getting-started).

## Готовые инструменты

Используйте готовые решения, созданные нашими партнерами, для быстрого импорта товаров из вашего магазина в сообщество ВКонтакте:

###  Конструкторы интернет магазинов

*  InSales – [https://www.insales.ru/collection/integratsiya-s-vkontakte/product/nastroyka-vygruzki-tovarov-iz-insales-vo-vkontkakte](https://www.insales.ru/collection/integratsiya-s-vkontakte/product/nastroyka-vygruzki-tovarov-iz-insales-vo-vkontkakte)
*  AdvantShop – [https://www.advantshop.net/help/pages/module-vkmarket](https://www.advantshop.net/help/pages/module-vkmarket)
*  Эквид – [https://www.ecwid.ru/blog/ecwid-with-vkmarket.html](https://www.ecwid.ru/blog/ecwid-with-vkmarket.html)
*  Tilda – [https://help-ru.tilda.cc/online-store-payments/vk](https://help-ru.tilda.cc/online-store-payments/vk)
*  Setup.ru – [https://www.setup.ru/instructions/vk](https://www.setup.ru/instructions/vk)
*  OpenCart – [https://github.com/crmagent-developers/opencart-vk-module](https://github.com/crmagent-developers/opencart-vk-module)
*  WordPress – [https://github.com/crmagent-developers/woocommerce-vk-module](https://github.com/crmagent-developers/woocommerce-vk-module)
*  Nethouse – [https://vk.nethouse.ru/](https://vk.nethouse.ru/)

###  CRM системы

*  RetailCRM – [https://vk.cc/bVtnwH](https://vk.cc/bVtnwH)
*  1C-CRM – [https://1crm.ru/help/integratsiya-s-magazinom-vkontakte/](https://1crm.ru/help/integratsiya-s-magazinom-vkontakte/)
*  amoCRM – [https://cmdf5.ru/widjety-amocrm/vk-amocrm](https://cmdf5.ru/widjety-amocrm/vk-amocrm)
*  Битрикс 24 – [https://www.bitrix24.ru/apps/?app=integrations24.vkmarket](https://www.bitrix24.ru/apps/?app=integrations24.vkmarket&_ga=2.210223517.984684472.1635850697-325262892.1635850697&)
*  1С-Битрикс – [https://marketplace.1c-bitrix.ru/solutions/vkapi.market](https://marketplace.1c-bitrix.ru/solutions/vkapi.market)

###  Программы складского учёта

*  МойСклад – [https://support.moysklad.ru/hc/ru/articles/226865387](https://support.moysklad.ru/hc/ru/articles/226865387)
*  Бизнес.Ру – [https://vk.com/@ecom-integraciya-magazina-vkontakte-i-biznesru](https://vk.com/@ecom-integraciya-magazina-vkontakte-i-biznesru)

###  Прочее

*  October CMS – плагин [Shopaholic for VK Goods](https://octobercms.com/plugin/lovata-vkgoodsshopaholic)
*  Workzen – [https://workzen.mts.ru/help/vk](https://workzen.mts.ru/help/vk)
*  Загрузка товаров в vk.com через фиды данных Яндекс.Маркета, Яндекс.Недвижимости и Auto.ru – [ZoomKit](https://vkm.zoomkit.ru)
*  Выгрузка товаров с сайтов поставщиков – [Cloudparser](https://cloudparser.ru)
*  Soc-commerce – [https://soc-commerce.com/](https://soc-commerce.com/)
*  Albato – [https://albato.ru/app-vkmarket](https://albato.ru/app-vkmarket)
* [iBurattino](http://iburattino.com), [VK-Sync](http://vk-sync.ru), [Soc-commerce](http://soc-commerce.com), [vkExport](https://vkexport.net/) — YML
*  [1С-Битрикс](https://marketplace.1c-bitrix.ru/solutions/vkapi.vkmarket/), [https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/](https://marketplace.1c-bitrix.ru/solutions/bxmaker.vk/)
*  [Электронный Заказ](https://ez-catalog.ru/) — электронный заказ, импорт товаров из XML, YML, CSV
*  [Trimpo](https://trimpo.org/) — импорт из YML, Excel, ручное добавление товаров
*  CMS ShopScript — [vkgoods](https://www.webasyst.ru/store/plugin/shop/vkgoods/)
*  [Sliza](https://sliza.ru/pages/instruction)
*  [Выгрузка товаров ВКонтакте и Одноклассники](https://my-market-app.ru/)

API ВКонтакте | Товары | Товары ВКонтакте

# API историй

Статистика историй ВКонтакте — 12 миллионов авторов, 71 миллион историй, 4,4 миллиарда просмотров от 46 миллионов пользователей каждый месяц. Загружать истории с помощью API могут любые пользователи и сообщества.

![](d0618ed378f440b275f817e6cce855080d6a77c542f56f07848f6566 "4448781307036623856")

#### Как работать с API историй

Пошаговая инструкция при работе с API Историй ВКонтакте заключает в себе несколько шагов:

1. Авторизуйте пользователя ВКонтакте [одним из этих способов](api/access-token/getting-started) или с помощью наших SDK для [Android](sdk/android) и [iOS](sdk/ios).
2. Подготовьте историю — фотографию или видео.
3. Если вы разрабатываете мини-приложение, опубликуйте историю с помощью редактора историй (событие [`VKWebAppShowStoryBox`](bridge/VKWebAppShowStoryBox)).
4. Если вы работаете над другим приложением, размещайте историю с помощью методов секции [`Stories`](method/stories). Сначала получите адрес для загрузки с помощью [`stories.getPhotoUploadServer`](method/stories.getPhotoUploadServer), затем загрузите фотографию или видео и сохраните историю, воспользовавшись [`stories.save`](method/stories.save).

История появится в новостях у друзей и подписчиков пользователя в зависимости от настроек приватности. [С помощью API](method/stories) можно также управлять историями и следить за количеством просмотров.

API ВКонтакте | Истории | API историй 

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

# Сервис распознавания речи

[Сервис распознавания речи ВКонтакте](https://vk.com/voice-tech) позволяет преобразовать аудиозапись в текстовую расшифровку. Сервис использует ASR (Automatic Speech Recognition)&nbsp;— технологию распознавания речи на базе нейросетей, которая считывает голос и переводит его в текст. Эта технология используется ВКонтакте для расшифровки голосовых сообщений, генерации субтитров в видео и многого другого.

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

* Спонтанная — распознавание речи со сленгом и ненормативной лексикой.
* Нейтральная — распознавание разборчивой речи, как в интервью или телешоу.

Сервис можно встроить как в мини-приложение, так и в игру на любой платформе.

## Ограничения

* Поддерживаемые форматы аудиозаписи: OGG, WAV, MP3 в качестве от 16000&nbsp;Гц (16&nbsp;кГц).
* Максимальный размер файла аудиозаписи: 100&nbsp;МБ.
* Суммарная максимальная длительность файлов аудиозаписей в сутки: 100 минут.
* [Ссылка на адрес сервера для загрузки аудиозаписи](method/asr.getUploadUrl) доступна 1 сутки.
* Методы, указанные в разделе [Интеграция](#Интеграция), можно вызвать только с сервисным ключом доступа.
* Поддерживается распознавание только русского языка.

> **Обратите внимание!** Безлимитное использование технологии возможно за дополнительную плату. Об условиях можно узнать, отправив заявку на электронную почту `bizdev@corp.vk.com`.

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

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

1. [Получите адрес сервера для загрузки аудиозаписи](method/asr.getUploadUrl).
1. [Отправьте аудиозапись по адресу сервера загрузки](#Запрос%20на%20отправку%20аудиозаписи).
1. [Запустите распознавание аудиозаписи](method/asr.process).
1. [Получите результат распознавания аудиозаписи](method/asr.checkStatus).

### Запрос на отправку аудиозаписи

Сформируйте и отправьте POST-запрос по адресу сервера, полученному из метода [`asr.getUploadUrl`](method/asr.getUploadUrl), с файлом аудиозаписи, преобразованным в формат [`multipart/form-data`](https://ru.wikipedia.org/wiki/Multipart/form-data).

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

```HTTP
POST https://pu.vk.com/gu/speech/v2/upload?token=eyJ0e13iOiJKV1QiLCJhbGmdOiJIUzI1NiJ9.eyqlmAQiOjE2NjM1OTAzNDYsInZrX3VzZXJfaWQiOjgxNDI3MDksInZrX2FwcF9pZCI6ODE0MjcwOSwidmtfdXBsb2FkX3R5cGUiOiJzcGVlY2gifQ.9PStNUU8cf-rlFdPhM5hKQ2xSjhbxzxy7SRKYHvXC_M HTTP/1.1

Content-Type: multipart/form-data

{
  "file": "\x9b\x9f\xf4\xac\xce\xb5\xac,\xf1o,\x9e6\xf3\xadQl\xb4.3~.\xaf\xa8\xb3\x95/\xd4\xbf\xdd\xaf\x06\x96\x100\..."
}
```

Пример успешного ответа:

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "sha": "894e6ab2092d7d2bb093dc8f7e5c60d0ce09c2ane698121c53fefcdc",
  "secret": "1248134271945096002",
  "meta": {
    "duration": "43.6652",
    "size": "1065633",
    "type": "ogg"
  },
  "hash": "50a9f8dasf073969e92ca20ad47031e6",
  "server": "230305",
  "user_id": 123,
  "request_id": "19d5e34ca1e740e283dfc844027a1df7",
  "app_id": 123
}
```

Пример ответа с ошибкой:

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "19d5e34ca1e740e283dfc844027a1df7",
  "error_code": 123,
  "error_msg": "Internal Server Error"
}
```

Интеграция | Распознавание речи | Сервис распознавания речи

# VKWebAppClose

`VKWebAppClose` закрывает мини-приложение или игру. Если закрываемое мини-приложение или игра были запущены с помощью события [`VKWebAppOpenApp`](bridge/VKWebAppOpenApp), при успешном закрытии в родительское приложение будет передано событие `VKWebAppCloseResult`.

## Пример

```JavaScript
bridge.send('VKWebAppClose', {
  status: 'success',
  payload: {
    name: 'value'
  }})
  .then((data) => { 
    if (data.status) {
      // Событие отправлено
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `status` &#x0d;&#x0a;*обязательное* | `string` | Статус закрытия мини-приложения или игры, передаваемый в родительское приложение. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — мини-приложение или игра закрылись успешно.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `failed` — мини-приложение или игра закрылись с ошибкой. |
| `payload` &#x0d;&#x0a;*необязательное* | `object` | Данные, передаваемые в родительское приложение. |

## Результат

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

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

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `status` | `string` | Статус закрытия мини-приложения или игры, передаваемый в родительское приложение. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — мини-приложение или игра закрылись успешно.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `failed` — мини-приложение или игра закрылись с ошибкой. |
| `payload` | `object` | Данные, передаваемые в родительское приложение. |

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

### События

#### `VKWebAppCloseResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppCloseResult",
    data: {
      status: "success",
      payload: {
        name: "value"
      }
    }
  }
}
```

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

#### `VKWebAppCloseFailed`

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

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

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

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

## Песочница

[VKWebAppClose](https://vk.cc/bZfsEx)


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

# VKWebAppGetGrantedPermissions

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

Чтобы пользователь мог выдать нужные разрешения на iOS, откройте системные настройки устройства. Для этого добавьте в нужное место своего мини-приложения ссылку: 

```HTML
<a href="app-settings:" target="_blank">
```

## Пример

```JavaScript
bridge.send('VKWebAppGetGrantedPermissions')
  .then((data) => { 
    if (data.permissions) {
      // Список разрешений получен
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });  
```

## Платформы

Android, iOS

## Параметры

—

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `permissions` | `array[string]` | Список разрешений, выданных мобильному приложению ВКонтакте. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `camera` — разрешено использовать камеру, чтобы делать фотографии и записывать видео.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `location` — разрешено запрашивать местоположение устройства.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `photo` — доступ к фотографиям и видео на мобильном устройстве с iOS.&#x0d;&#x0a;&#x0d;&#x0a; Пустой результат означает, что никакие разрешения не выданы. Есть ли доступ к фотографиям, можно проверить только на iPhone. |

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

### События

#### `VKWebAppGetGrantedPermissionsResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppGetGrantedPermissionsResult",
    data: {
      "permissions": [
        "camera",
        "location",
        "photo"
      ]
    }
  }
}
```

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

#### `VKWebAppGetGrantedPermissionsFailed`

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

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

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

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

## Песочница

[VKWebAppGetGrantedPermissions](https://vk.com/app6909581#VktXZWJBcHBHZXRHcmFudGVkUGVybWlzc2lvbnNAJTdCJTdE)


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

# VKWebAppOpenContacts

`VKWebAppOpenContacts` запрашивает доступ к телефонной книге на устройстве, открывает окно выбора контакта из телефонной книги и получает данные контакта. 

## Пример

```JavaScript
bridge.send('VKWebAppOpenContacts')
  .then((data) => { 
    if (data.phone) {
      // Данные контакта получены
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

—

## Результат

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

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

* С помощью [событий](#События) `VKWebAppContactsDone`, `VKWebAppOpenContactsFailed` и `VKWebAppContactsClosed`.

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `phone` | `string` | Номер телефона в формате, в котором он хранится в телефонной книге. |
| `first_name` | `string` | Имя пользователя, указанное в телефонной книге. |
| `last_name` | `string` | Фамилия пользователя, указанная в телефонной книге. |

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

### События

#### `VKWebAppContactsDone`

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

```JavaScript
{
  detail: {
    type: "VKWebAppContactsDone",
    data: {
      phone: "79217770099",
      first_name: "Персик",
      last_name: "Рыжий" 
    }
  }
}
```

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

#### `VKWebAppOpenContactsFailed`

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

#### `VKWebAppContactsClosed`

Информирует о закрытии пользователем телефонной книги.

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

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


VK Bridge | Пользователи | VKWebAppOpenContacts

# VKWebAppRetargetingPixel

`VKWebAppRetargetingPixel` позволяет добавить пользователя в аудиторию ретаргетинга. Параметры соответствуют параметрам `event` и `audience` при подключении пикселя в [мобильном приложении](https://vk.com/faq14154).

## Пример

```JavaScript
bridge.send("VKWebAppRetargetingPixel", {
 pixel_code: "VK-RTRG-447253-dUuM",
 event: "click-to-button"
});
```

## Платформы

Android (с версии клиента 6.1), iOS, Mobile Web, Web

## Параметры

* `pixel_code` (`string`, `required`)
Код пикселя. Например: `VK-RTRG-447253-dUuM`. 
* `event` (`string`)
Идентификатор события, правило пикселя. 
* `target_group_id` (`integer`) 
Идентификатор группы ретаргетинга, в которую нужно добавить текущего пользователя. 
* `price_list_id` (`integer`)
Идентификатор прайс-листа. Используется для динамического ретаргетинга продуктов. 
* `products_event` (`string`)
Тип продуктового события.  Используется для динамического ретаргетинга продуктов. 
* `products_params` (`string`)
Параметры товара. Используется для динамического ретаргетинга продуктов. 

## Результат

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

```JSON
{
  "type":"VKWebAppRetargetingPixelResult",
  "data":{
    "result":true
  }
}
```

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

```JSON
{ 
  "type": "VKWebAppRetargetingPixelFailed", 
  "data": {
     "error_type": "...",
     "error_data": {
        ...
     }
  }
}
```

> Обратите внимание: при создании пикселя в рекламном кабинете можно указывать только идентификатор мини-приложения (поле **Разрешённый Mini App id**). Указывать домен или поддомен не обязательно.

## Примеры соответствия для Open API

Если вы использовали Opеn API (`openapi.js`), ваш JS-код по-прежнему будет работать. Но в будущем мы прекратим поддержку Opеn API и поэтому рекомендуем использовать события VK Bridge так, как показано ниже. 

### `VK.Retargeting.Event`

**Open API** 

```JavaScript
VK.Retargeting.Event("purchase");
```

**VK Bridge**

```JavaScript
bridge.send("VKWebAppRetargetingPixel", {
  pixel_code: "VK-Boo-427253-dUuM",
  event: "purchase"
});
```

### VK.Retargeting.Hit

**Open API**

```JavaScript
VK.Retargeting.Hit();
```

**VK Bridge**

```JavaScript
bridge.send("VKWebAppRetargetingPixel", {
 pixel_code: "VK-Boo-427253-dUuM"
});
```

### VK.Retargeting.Add

**Open API**

```JavaScript
VK.Retargeting.Add(8839163);
```

**VK Bridge**

```JavaScript
bridge.send("VKWebAppRetargetingPixel", {
 "pixel_code": "VK-Boo-427253-dUuM",
 "target_group_id": 8839163
});
```

###  VK.Retargeting.ProductEvent

**Open API**

```JavaScript
VK.Retargeting.ProductEvent(12345 /* PRICE_LIST_ID */, "view_product", {
 "total_price": 34899
});
```

**VK Bridge**

```JavaScript
bridge.send("VKWebAppRetargetingPixel", {
 "pixel_code": "VK-Boo-427253-dUuM",
 "price_list_id": 12345,
 "products_event": "view_product",
 "products_params": {
  "total_price": 34899
 }
});
```

VK Bridge | Отслеживание пользователей | VKWebAppRetargetingPixel

# VKWebAppSendToClient

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

## Пример

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

## Платформы

Mobile Web, Web

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `fragment` &#x0d;&#x0a;*необязательное* | `string` | Хеш — строка после символа `#` в URL вида `vk.com/app6909581#`. |

## Результат

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если мини-приложение или игра запущены на мобильном устройстве. |

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

### События

#### `VKWebAppSendToClientResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppSendToClientResult",
    data: {
      result: true
    }
  }
}
```

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

#### `VKWebAppSendToClientFailed`

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

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

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

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

## Песочница

[VKWebAppSendToClient](https://vk.cc/bZfu1G)


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

# VKWebAppStorageGetKeys

`VKWebAppStorageGetKeys`  возвращает названия всех переменных.

## Пример

```JavaScript
bridge.send("VKWebAppStorageGetKeys", {"count": 20, "offset": 0});
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

* `count` (`integer`)
Количество названий переменных, информацию о которых необходимо получить.
* `offset` (`integer`)
Смещение, необходимое для выборки определённого подмножества названий переменных.

## Результат

В случае успеха генерируется событие `VKWebAppStorageGetKeysResult` с массивом ключей в поле `keys`:

```JSON
{
  "type": "VKWebAppStorageGetKeysResult",
  "data": {
    "keys": [["example", "example2", "example3"]]
  }
}
```

В случае ошибки генерируется событие `VKWebAppStorageGetKeysFailed`.

```JSON
{ 
  "type": "VKWebAppStorageGetKeysFailed", 
  "data": {
     "error_type": "...",
     "error_data": {
        ...
     }
  }
}
```

## Песочница

[VKWebAppStorageGetKeys](https://vk.cc/bZfuSa)

VK Bridge | Секция Storage | VKWebAppStorageGetKeys

# VKWebAppStorageSet

`VKWebAppStorageSet`  задаёт значение переменной, название которой передано в параметре `key`.  Срок жизни ключа — 1 год.

## Пример

```JavaScript
bridge.send("VKWebAppStorageSet", {
   key: "example",
   value: "example_value"
});
```

## Платформы

Android, iOS, Mobile Web, Web

## Параметры

* `key` (`string`, обязательный)
Название ключа, `[a-zA-Z_\-0-9]`. Максимальная длина — 100 символов. 
* `value` (`string`)
 Значение переменной, сохраняются только первые 4096 байт.

## Результат

В случае успеха генерируется событие `VKWebAppStorageSetResult`.

```JSON
{
  "type":"VKWebAppStorageSetResult",
  "data":{
    "result": true
  }
}
```

В случае ошибки генерируется событие `VKWebAppStorageSetFailed`.

```JSON
{ 
  "type": "VKWebAppStorageSetFailed", 
  "data": {
     "error_type": "...",
     "error_data": {
        ...
     }
  }
}
```

## Песочница

[VKWebAppStorageSet](https://vk.cc/bZfuKd)

VK Bridge | Секция Storage | VKWebAppStorageSet

# VKWebAppTapticImpactOccurred

`VKWebAppTapticImpactOccurred` вызывает вибрацию мобильного устройства. В iOS вызывает [`impactOccurred`](https://developer.apple.com/documentation/uikit/uiimpactfeedbackgenerator/2374287-impactoccurred) в Taptic Engine.

## Пример

```JavaScript
bridge.send('VKWebAppTapticImpactOccurred', {
  style: 'heavy'
  })
  .then((data) => { 
    if (data.result) {
      // Вибрация вызвана
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `style` &#x0d;&#x0a;*обязательное* | `string` | Сила вибрации. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `light` — лёгкая.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `medium` — средняя.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `heavy` — сильная. |

## Результат

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

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

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если вибрация вызвана. |

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

### События

#### `VKWebAppTapticImpactOccurredResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppTapticImpactOccurredResult",
    data: {
      result: true
    }
  }
}
```

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

#### `VKWebAppTapticImpactOccurredFailed`

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

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

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

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


VK Bridge | Виброотклик (Taptic Engine) | VKWebAppTapticImpactOccurred

# VKWebAppTapticNotificationOccurred

`VKWebAppTapticNotificationOccurred` передаёт генератору виброотклика информацию о том, что задача или действие:

* Успешно выполнено.
* Не выполнено.
* Выдало предупреждение.

В ответ генератор может воспроизводить соответствующие параметру тактильные отклики. В iOS `VKWebAppTapticNotificationOccurred` вызывает [`notificationOccurred`](https://developer.apple.com/documentation/uikit/uinotificationfeedbackgenerator/2369826-notificationoccurred) в Taptic Engine.

## Пример

```JavaScript
bridge.send('VKWebAppTapticNotificationOccurred', {
  type: 'error'
  })
  .then((data) => { 
    if (data.result) {
      // Информация передана генератору
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });
```

## Платформы

Android, iOS

## Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `type` &#x0d;&#x0a;*обязательное* | `string` | Тип информации. Возможные значения:&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `error` — ошибка.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `success` — успех.&#x0d;&#x0a; &nbsp;&nbsp; &bullet; `warning` — предупреждение. |

## Результат

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

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

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

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

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

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

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

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `result` | `boolean` | `true`, если информация передана генератору. |

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

### События

#### `VKWebAppTapticNotificationOccurredResult`

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

```JavaScript
{
  detail: {
    type: "VKWebAppTapticNotificationOccurredResult",
    data: {
      result: true
    }
  }
}
```

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

#### `VKWebAppTapticNotificationOccurredFailed`

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

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

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

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


VK Bridge | Виброотклик (Taptic Engine) | VKWebAppTapticNotificationOccurred

# Первые шаги

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

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

> Если ранее вы не работали с API ВКонтакте, рекомендуем прочитать раздел [Использование API](api/getting-started).
>
> Если ранее вы не работали с React, советуем ознакомиться с [документацией к библиотеке](https://ru.reactjs.org/tutorial/tutorial.html).
NPM: [`vk-bridge`](https://www.npmjs.com/package/@vkontakte/vk-bridge)

GitHub: [`vk-bridge`](https://github.com/VKCOM/vk-bridge)

## Как использовать библиотеку VK Bridge

Чтобы использовать библиотеку:

1. Создайте проект мини-приложения.
1. [Подключите VK Bridge](#Подключение%20VK%20Bridge).
1. [Вызовите событие VK Bridge](#Вызов%20события%20VK%20Bridge).
1. Обработайте вернувшийся результат:
    * [Метод `bridge.send`](#Метод%20bridge.send).
    * [Метод `bridge.subscribe`](#Метод%20bridge.subscribe).

Инструкция ниже актуальна для любой операционной системы. Для первых шагов потребуется знание языка JavaScript и умение работать с командной строкой.

## Подключение VK Bridge

> Если вы используете [библиотеку для создания шаблона](mini-apps/getting-started#Создание%20мини-приложения), отдельно подключать библиотеку VK Bridge не нужно.

Мы рекомендуем отправлять сообщение как можно раньше при запуске мини-приложения. В идеале — после выполнения минимума начальных действий и до массовой загрузки ресурсов. Допустимый интервал — 30 секунд после старта.

> **Обратите внимание!** В коде приложения обязательно нужно вызывать событие инициализации [`VKWebAppInit`](bridge/VKWebAppInit), иначе приложение не запустится.

### Через пакет NPM

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

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

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

    ```sh
    npm install @vkontakte/vk-bridge || yarn add @vkontakte/vk-bridge
    ```

1. Инициализируйте VK Bridge в файле `index.js`:

    ```JavaScript
    import bridge from '@vkontakte/vk-bridge';

    // Отправляет событие инициализации нативному клиенту
    bridge.send("VKWebAppInit");      
    ```

### Включение скрипта в HTML-код страницы

Этот способ подходит, если вы не используете менеджеры пакетов, такие как `npm` или `yarn`, для создания своего HTML-приложения.

1. В код каждой HTML-страницы, где вы будете вызывать библиотеку, добавьте ссылку на файл `browser.min.js`.

    > В репозитории VK Bridge этот файл находится в папке `dist`. Мы рекомендуем ссылаться на копию файла, расположенную на сервисе [unpkg.com](https://unpkg.com). В этом случае вы автоматически будете получать последнюю версию библиотеки и вам не нужно будет самостоятельно следить за выходом её обновлений.

    ```HTML
    <script src="https://unpkg.com/@vkontakte/vk-bridge/dist/browser.min.js"></script>
    ```

1. В коде каждой HTML-страницы, где вы будете вызывать библиотеку, инициализируйте VK Bridge:

    ```HTML
    <script>
      // Отправляет событие инициализации нативному клиенту
      vkBridge.send('VKWebAppInit');
    </script>
    ```


Обратите внимание, что когда вы включаете .js-файл библиотеки в HTML-код своих страниц, то в JavaScript-коде надо использовать имя объекта `vkBridge`, а не `bridge`.

## Вызов события VK Bridge

Используйте события объекта `bridge`:

```JavaScript
// Подписывается на события, отправленные нативным клиентом
bridge.subscribe((e) => console.log(e)); 
    
// Отправляет событие нативному клиенту
bridge.send("VKWebAppInit", {});      
    
// Проверяет, поддерживается ли событие на текущей платформе
if (bridge.supports("VKWebAppResizeWindow")) {
  bridge.send("VKWebAppResizeWindow", {"width": 800, "height": 1000});
}
```

> [Список всех событий VK Bridge](bridge/overview).

## Обработка результата

### Метод `bridge.send`

При использовании метода `bridge.send` вернётся промис. Работа с промисами не требует подключения дополнительных библиотек.

```JavaScript
// Отправка события
bridge.send('VKWebAppGetEmail')
  .then((data) => {
    if (data.result) {
      // Обработка события в случае успеха
      console.log(data.email);
    } else {
      // Ошибка
    }
  })
  .catch((error) => {
    // Обработка события в случае ошибки
    console.log(error);
  });
```

> Подробнее о промисах:
>
> * [developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
>
> * [learn.javascript.ru/promise](http://learn.javascript.ru/promise)

### Метод `bridge.subscribe`

При использовании метода `bridge.subscribe` в общем случае вернётся событие:

* c постфиксом `Result`, если метод выполнился успешно;
* с постфиксом `Failed`, если метод выполнился с ошибкой.

> **Обратите внимание!** Также бывают события с другими постфиксами. Они подробно описаны в разделе конкретного события.

```JavaScript
// Подписывается на события, отправленные нативным клиентом
bridge.subscribe(event => {
  if (!event.detail) {
    return;
  }

  switch(event.detail.type) {
    case 'VKWebAppOpenCodeReaderResult':
      if (event.detail.data.result) {
        // Обработка события в случае успеха
        console.log(event.detail.data.result);
      } else {
        // Ошибка
      }
      break;
    case 'VKWebAppOpenCodeReaderFailed':
      // Обработка события в случае ошибки
      console.log(event.detail.data.error_type, event.detail.data.error_data);      
      break;
  }
});
```

## Обработка ошибок VK Bridge

При работе с VK Bridge в ответе могут возвращаться ошибки в объекте `data`.

```JSON
{
  "type": "EventNameFailed", 
  "data": { 
    "error_type": "...",
    "error_data": {}
  } 
}
```

### `"data"`

| Параметр | Тип | Описание |
|---|---|---|
|`error_type` | `string` | Тип ошибки. Возможные значения:&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `client_error` — ошибки, возникающие на клиенте;&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `api_error` — ошибки API;&#x0d;&#x0a;&nbsp;&nbsp; &bullet; `auth_error` — ошибки авторизации. |
|`error_data` | `object` | Дополнительные данные ошибки, которые зависят от `error_type`. См. описание ниже. |
|`request_id` | `integer` | Информация, которая используется для внутренних целей: успешного выполнения или отклонения промиса. |

### `"error_type": "client_error"`

К этому типу относятся ошибки, связанные с некорректным синтаксисом событий VK Bridge. Параметры объекта `error_data`:

| Параметр | Тип | Описание |
|---|---|---|
|`error_code` | `integer` | Код ошибки. См. список возможных значений в таблице ниже. |
|`error_reason` | `string` | Описание ошибки. |
|`error_description` | `string` | **Необязательное поле**. Детальное описание ошибки. |

| Код ошибки (`error_code`) |  Описание (`error_reason`) |
|---|---|
|1 | Unknown error |
|2 | Missing required params |
|3 | Connection lost |
|4 | User denied |
|5 | Invalid params |
|6 | Unsupported platform |
|7 | No device permission |
|8 | Need user permission |
|9 | This action cannot be performed in the background |
|10 | Requests limit reached |
|11 | Access denied |
|12 | Uninitialized App |
|13 | Custom error for every handler |

### `"error_type": "api_error"`

К этому типу относятся ошибки, перечисленные на странице [Возвращаемые ошибки](reference/errors) или в описании метода. Параметры объекта `error_data`:

| Параметр | Тип | Описание |
|---|---|---|
|`error_code` | `integer` | Код ошибки. |
|`error_msg` | `string` | Описание ошибки. |
|`request_params` | `array` | Массив, содержащий параметры запроса к API. |

### `"error_type": "auth_error"`

К этому типу относятся ошибки, которые возвращаются в ходе авторизации. Параметры объекта `error_data`:

| Параметр | Тип | Описание |
|---|---|---|
|`error` | `integer` | Код ошибки. |
|`error_reason` | `string` | Описание ошибки. |
|`error_description` | `array` | **Необязательное поле**. Детальное описание ошибки. |

VK Bridge | Быстрый старт

# Введение

**Библиотека 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)

Сообщество

# Mini Design Award — 2022

> Сроки проведения: с 1 по 15 июля 2022 года.

Чтобы принять участи в конкурсе Mini Design Award, с 1 по 15 июля отправьте нам уже готовый сервис через [специальную форму](https://vk.cc/mda2022) и узнайте, как хороший дизайн [мини-приложения](mini-apps/overview) влияет на его метрики.
Мы будем оценивать все работы по следующим критериям:

* Качество UX-дизайна.
* Качество UI-дизайна.
* Работоспособность мини-приложения.

Что получат участники конкурса: 

* 1-е место — набор продукции с символикой ВКонтакте и уникальной толстовкой и 10 000 рублей на рекламное продвижение ВКонтакте.
* 2-е место – набор продукции с символикой ВКонтакте с уникальной толстовкой и 5 000 рублей на рекламное продвижение.
* 3-е место – набор продукции с символикой ВКонтакте и 2 500 рублей на рекламное продвижение.

Кроме того, авторы работ, занявшие первые 10 мест, получат анимированную Lottie-иконку, а 3 последних места — полную разработку дизайна от нашей команды.

[Итоги конкурса](https://vk.com/wall-166562603_4442) смотрите в сообществе VK Mini Apps.

Сообщество | Архив | Mini Design Award — 2022

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

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

### [Мини-приложения](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)
Автоматизируйте рутинные и похожие задачи с помощью чат-бота ВКонтакте.

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

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

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

**Скилл** — это приложение, которое работает сразу на всех платформах, где доступна Маруся. Создать его можно в этом разделе: [https://vk.com/editapp?act=create](https://vk.com/editapp?act=create). Главное, чтобы скилл соблюдал [протокол взаимодействия](marusia/api) с Марусей.

## Платформы

Сейчас Маруся работает на следующих платформах:
*  мобильное приложение ВКонтакте,
*  мобильное приложение Маруси на [iOS](https://apps.apple.com/ru/app/%D0%BC%D0%B0%D1%80%D1%83%D1%81%D1%8F-%D0%B3%D0%BE%D0%BB%D0%BE%D1%81%D0%BE%D0%B2%D0%BE%D0%B9-%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%BD%D0%B8%D0%BA/id1467719381) и [Android](https://play.google.com/store/apps/details?id=ru.mail.search.electroscope&hl=ru),
*  умная колонка [«Капсула»](https://capsula.mail.ru),
*  умная колонка «Капсула мини»,
*  умная колонка Prestigio Smartvoice,
*  приложение Почта Mail.ru для [iOS](https://apps.apple.com/ru/app/%D0%BF%D0%BE%D1%87%D1%82%D0%B0-mail-ru/id511310430) и [Android](https://play.google.com/store/apps/details?id=ru.mail.mailapp&hl=ru&gl=US). 

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

Список всех скиллов Маруси можно изучить в [каталоге](https://marusia.mail.ru). 

## Создание скиллов

Создать скилл можно двумя способами:
1. Использовать конструктор [Aimylogic](https://aimylogic.com/ru), который позволяет собрать необходимый сценарий в визуальном редакторе, а затем получить готовый webhook. Его, в свою очередь, уже можно зарегистрировать в качестве скилла Маруси. 
2. Написать код самостоятельно. Для этого изучите документацию. В ней подробно описан [протокол](marusia/api), по которому Маруся взаимодействует с внешними навыками, а также порядок работы с [TTS](marusia/tts), со [звуками](marusia/sound) и [изображениями](marusia/cards). Код приложения может быть написан на любом удобном вам языке и размещён на любом сервере. Главное, чтобы webhook был доступен из интернета и воспроизводил протокол Маруси из документации. 

После того как вы создадите скилл, необходимо его зарегистрировать и отправить на модерацию. Для этого выполните следующие действия:
1. [Создайте приложение](https://vk.com/editapp?act=create) в разделе для разработчиков. 
2. Выберите **Скилл Маруси** в типах приложения. 
3. Добавьте название, которое будет совпадать с командой для активации скилла. 
4. Введите в поле **Webhook URL** адрес сервера, на котором будет размещён навык, например [`https://example.com/test-webhook`](https://example.com/test-webhook). 
5. Нажмите на кнопку **Создать скилл**. 

![](cec687cc653698c24cee3af05ceaf922b93ba80f4dade06cf9b6af77 "4940476498664586883")

Вы попадёте в интерфейс администрирования скилла. 
> Все изменения полей скилла становятся доступны на всех платформах, где работает Маруся, примерно через 1–2 минуты.

## Некоторые ограничения и советы

> В день можно добавлять не более 3 скиллов, за 5 дней — не более 10. 

Фразы для вызова должны быть специфичными и уникальными, чтобы мы могли использовать их для внешних скиллов. Например, фразу «Расскажи анекдот» мы добавить не сможем, так как она уже используется во внутренних скиллах Маруси. А вот фразу «Давай сделаем код-ревью» — пока свободна и подойдёт для внешнего скилла. 

> Обратите внимание: имя «Маруся» будет первым словом фразы и триггером для вызова скилла.
>
> Длина фразы активации не может превышать 64 символа.

Маруся | Быстрый старт

# Вставка звуков в TTS

## Собственные звуки

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

Загруженный аудиофайл станет доступен приблизительно через 15 минут после окончания загрузки. Его можно будет использовать только в вашем скилле.

Чтобы вставить файл в речь, используйте тег `speaker`. В его атрибуте `audio_vk_id` укажите идентификатор загруженного звука.

#### Пример

```SSML
tts = "Угадайте, чей это голос? <speaker audio_vk_id=-2000000002_123456789>"
```

## Библиотека звуков

Произносимый Марусей текст можно разнообразить аудиоэффектами, которые входят в её библиотеку звуков. Для этого в поле tts (текст, предназначенный для перевода в речь) ответа внешнего скилла нужно вставить самозакрывающийся тег `speaker`, в котором необходимо указать атрибут `audio`. 

#### Пример 
```SSML
tts = "Поздравляю! <speaker audio=marusia-sounds/game-win-1> Вы правильно ответили на все мои вопросы!"
```
Полный список звуков для вставки:
```SSML
<speaker audio=marusia-sounds/things-sword-1> 
<speaker audio=marusia-sounds/things-water-3> 
<speaker audio=marusia-sounds/things-door-1> 
<speaker audio=marusia-sounds/things-sword-2> 
<speaker audio=marusia-sounds/things-cuckoo-clock-2> 
<speaker audio=marusia-sounds/things-construction-1> 
<speaker audio=marusia-sounds/things-bell-2> 
<speaker audio=marusia-sounds/things-phone-4> 
<speaker audio=marusia-sounds/things-explosion-1> 
<speaker audio=marusia-sounds/things-sword-3> 
<speaker audio=marusia-sounds/things-old-phone-2> 
<speaker audio=marusia-sounds/things-cuckoo-clock-1> 
<speaker audio=marusia-sounds/things-phone-5> 
<speaker audio=marusia-sounds/things-bell-1> 
<speaker audio=marusia-sounds/things-old-phone-1> 
<speaker audio=marusia-sounds/things-phone-2> 
<speaker audio=marusia-sounds/things-water-2> 
<speaker audio=marusia-sounds/things-phone-1> 
<speaker audio=marusia-sounds/things-switch-2> 
<speaker audio=marusia-sounds/things-toilet-1> 
<speaker audio=marusia-sounds/things-water-1> 
<speaker audio=marusia-sounds/things-chainsaw-1> 
<speaker audio=marusia-sounds/things-switch-1> 
<speaker audio=marusia-sounds/things-car-1> 
<speaker audio=marusia-sounds/things-gun-1> 
<speaker audio=marusia-sounds/things-siren-2> 
<speaker audio=marusia-sounds/things-car-2> 
<speaker audio=marusia-sounds/things-construction-2> 
<speaker audio=marusia-sounds/things-door-2> 
<speaker audio=marusia-sounds/things-siren-1> 
<speaker audio=marusia-sounds/things-glass-1> 
<speaker audio=marusia-sounds/things-glass-2> 
<speaker audio=marusia-sounds/transport-ship-horn-1> 
<speaker audio=marusia-sounds/transport-ship-horn-2> 
<speaker audio=marusia-sounds/things-phone-3> 
<speaker audio=marusia-sounds/animals-seagull-1> 
<speaker audio=marusia-sounds/animals-crow-2> 
<speaker audio=marusia-sounds/animals-cow-1> 
<speaker audio=marusia-sounds/animals-monkey-1> 
<speaker audio=marusia-sounds/animals-cuckoo-1> 
<speaker audio=marusia-sounds/animals-cat-2> 
<speaker audio=marusia-sounds/animals-cat-4> 
<speaker audio=marusia-sounds/animals-cow-3> 
<speaker audio=marusia-sounds/animals-elephant-2> 
<speaker audio=marusia-sounds/animals-cat-1> 
<speaker audio=marusia-sounds/animals-dog-2> 
<speaker audio=marusia-sounds/animals-sheep-2> 
<speaker audio=marusia-sounds/animals-rooster-1> 
<speaker audio=marusia-sounds/animals-frog-1> 
<speaker audio=marusia-sounds/animals-cat-3> 
<speaker audio=marusia-sounds/animals-horse-2> 
<speaker audio=marusia-sounds/animals-crow-1> 
<speaker audio=marusia-sounds/animals-cow-2> 
<speaker audio=marusia-sounds/animals-horse-1> 
<speaker audio=marusia-sounds/animals-dog-5> 
<speaker audio=marusia-sounds/animals-elephant-1> 
<speaker audio=marusia-sounds/animals-sheep-1> 
<speaker audio=marusia-sounds/animals-lion-1> 
<speaker audio=marusia-sounds/animals-cat-5> 
<speaker audio=marusia-sounds/animals-dog-3> 
<speaker audio=marusia-sounds/animals-owl-1> 
<speaker audio=marusia-sounds/animals-wolf-1> 
<speaker audio=marusia-sounds/animals-horse-galloping-1> 
<speaker audio=marusia-sounds/animals-chicken-1> 
<speaker audio=marusia-sounds/animals-horse-walking-1> 
<speaker audio=marusia-sounds/animals-owl-2> 
<speaker audio=marusia-sounds/animals-lion-2> 
<speaker audio=marusia-sounds/animals-dog-4> 
<speaker audio=marusia-sounds/animals-dog-1> 
<speaker audio=marusia-sounds/game-win-1> 
<speaker audio=marusia-sounds/game-loss-2> 
<speaker audio=marusia-sounds/game-loss-1> 
<speaker audio=marusia-sounds/game-loss-3> 
<speaker audio=marusia-sounds/game-8-bit-machine-gun-1> 
<speaker audio=marusia-sounds/game-ping-1> 
<speaker audio=marusia-sounds/game-8-bit-coin-2> 
<speaker audio=marusia-sounds/game-win-2> 
<speaker audio=marusia-sounds/game-8-bit-flyby-1> 
<speaker audio=marusia-sounds/game-powerup-1> 
<speaker audio=marusia-sounds/game-boot-1> 
<speaker audio=marusia-sounds/game-8-bit-coin-1> 
<speaker audio=marusia-sounds/game-win-3> 
<speaker audio=marusia-sounds/game-8-bit-phone-1> 
<speaker audio=marusia-sounds/game-powerup-2> 
<speaker audio=marusia-sounds/human-walking-dead-3> 
<speaker audio=marusia-sounds/human-walking-snow-1> 
<speaker audio=marusia-sounds/human-crowd-6> 
<speaker audio=marusia-sounds/human-walking-leaves-1> 
<speaker audio=marusia-sounds/human-crowd-2> 
<speaker audio=marusia-sounds/human-crowd-5> 
<speaker audio=marusia-sounds/human-walking-dead-2> 
<speaker audio=marusia-sounds/human-laugh-3> 
<speaker audio=marusia-sounds/human-laugh-4> 
<speaker audio=marusia-sounds/human-crowd-4> 
<speaker audio=marusia-sounds/human-sneeze-2> 
<speaker audio=marusia-sounds/human-cough-2> 
<speaker audio=marusia-sounds/human-crowd-3> 
<speaker audio=marusia-sounds/human-walking-dead-1> 
<speaker audio=marusia-sounds/human-laugh-5> 
<speaker audio=marusia-sounds/human-laugh-1> 
<speaker audio=marusia-sounds/human-cheer-1> 
<speaker audio=marusia-sounds/human-kids-1> 
<speaker audio=marusia-sounds/human-sneeze-1> 
<speaker audio=marusia-sounds/human-laugh-2> 
<speaker audio=marusia-sounds/human-cough-1> 
<speaker audio=marusia-sounds/human-cheer-2> 
<speaker audio=marusia-sounds/human-walking-room-1> 
<speaker audio=marusia-sounds/human-crowd-1> 
<speaker audio=marusia-sounds/human-crowd-7> 
<speaker audio=marusia-sounds/music-violin-b-1> 
<speaker audio=marusia-sounds/music-piano-c-2> 
<speaker audio=marusia-sounds/music-piano-b-1> 
<speaker audio=marusia-sounds/music-violin-c-2> 
<speaker audio=marusia-sounds/music-horn-2> 
<speaker audio=marusia-sounds/music-guitar-c-1> 
<speaker audio=marusia-sounds/music-bagpipes-2> 
<speaker audio=marusia-sounds/music-tambourine-100bpm-1> 
<speaker audio=marusia-sounds/music-violin-a-1> 
<speaker audio=marusia-sounds/music-piano-g-1> 
<speaker audio=marusia-sounds/music-violin-g-1> 
<speaker audio=marusia-sounds/music-drums-2> 
<speaker audio=marusia-sounds/music-piano-d-1> 
<speaker audio=marusia-sounds/music-tambourine-80bpm-1> 
<speaker audio=marusia-sounds/music-piano-a-1> 
<speaker audio=marusia-sounds/music-horn-1> 
<speaker audio=marusia-sounds/music-guitar-a-1> 
<speaker audio=marusia-sounds/music-drums-3> 
<speaker audio=marusia-sounds/music-guitar-g-1> 
<speaker audio=marusia-sounds/music-gong-1> 
<speaker audio=marusia-sounds/music-bagpipes-1> 
<speaker audio=marusia-sounds/music-drum-loop-1> 
<speaker audio=marusia-sounds/music-tambourine-120bpm-1> 
<speaker audio=marusia-sounds/music-piano-f-1> 
<speaker audio=marusia-sounds/music-drums-1> 
<speaker audio=marusia-sounds/music-gong-2> 
<speaker audio=marusia-sounds/music-violin-d-1> 
<speaker audio=marusia-sounds/music-violin-c-1> 
<speaker audio=marusia-sounds/music-piano-c-1> 
<speaker audio=marusia-sounds/music-drum-loop-2> 
<speaker audio=marusia-sounds/music-harp-1> 
<speaker audio=marusia-sounds/music-piano-e-1> 
<speaker audio=marusia-sounds/music-violin-f-1> 
<speaker audio=marusia-sounds/music-violin-e-1> 
<speaker audio=marusia-sounds/music-guitar-e-1> 
<speaker audio=marusia-sounds/nature-forest-1> 
<speaker audio=marusia-sounds/nature-wind-1> 
<speaker audio=marusia-sounds/nature-forest-2> 
<speaker audio=marusia-sounds/nature-stream-1> 
<speaker audio=marusia-sounds/nature-stream-2> 
<speaker audio=marusia-sounds/nature-jungle-2> 
<speaker audio=marusia-sounds/nature-rain-2> 
<speaker audio=marusia-sounds/nature-sea-2> 
<speaker audio=marusia-sounds/nature-thunder-1> 
<speaker audio=marusia-sounds/nature-thunder-2> 
<speaker audio=marusia-sounds/nature-wind-2> 
<speaker audio=marusia-sounds/nature-fire-1> 
<speaker audio=marusia-sounds/nature-jungle-1> 
<speaker audio=marusia-sounds/nature-sea-1> 
<speaker audio=marusia-sounds/nature-fire-2> 
<speaker audio=marusia-sounds/nature-rain-1>
```

Маруся | Вставка звуков в TTS

# Просмотр маски

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

## Просмотр маски на компьютере

### Шаг 1. Установите приложение для просмотра

#### Windows

1. Скачайте приложение  [test.mask для Windows](https://mask.vk.me/app/test.mask3_windows.zip). Извлеките содержимое архива.
1. Найдите `test.mask3_windows` — это и есть основной файл приложения. Щёлкните дважды по файлу, чтобы запустить приложение.

Рекомендуем сразу создать ярлык приложения на рабочем столе.

##### Запуск test.mask с консолью

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

Чтобы приложение test.mask открывалось с консолью, необходимо изменить его настройки:

1. Создайте ярлык приложения test.mask.
1. Откройте правой кнопкой мыши свойства ярлыка.
1. В конце строки `Объект` через пробел допишите: `-console`.
1. Сохраните настройки.

#### macOS

1. Скачайте приложение [test.mask для macOS](https://mask.vk.me/app/test.mask3_macos.zip). Извлеките содержимое архива.
1. Найдите `test.mask3_macos` — это и есть основной файл приложения. Щёлкните дважды по файлу, чтобы запустить приложение.

> В macOS консоль с сообщениями об ошибках запускается по умолчанию.

###  Шаг 2. Откройте маску в приложении

#### Windows

1. В приложении test.mask нажмите на кнопку **Open mask**.
1. Зайдите через проводник в каталог с вашей маской, выберите файл `mask.json` и нажмите **Открыть**. Если вы всё сделали правильно, то увидите маску на своём лице.

#### macOS

1. В меню приложения test.mask выберите **File** → **Open Mask...** .
1. Выберите каталог с проектом маски и нажмите **Open**. Если вы всё сделали правильно, то увидите маску на своем лице.

## Просмотр маски в мобильном приложении

1. Откройте на компьютере папку с проектом вашей маски и упакуйте все файлы и папки внутри неё в ZIP-архив. Обратите внимание, необходимо архивировать не папку проекта, а файлы и папки внутри проекта.
1. Откройте сообщество [Маски ВКонтакте](https://vk.com/msx) и нажмите **Написать сообщение**.
1. Прикрепите ZIP-архив к сообщению и отправьте его. В ответ бот пришлёт вам ссылку на маску. Например такую:
    ```
    https://vk.com/mask66629999_17689
    ```
1. Откройте ссылку на мобильном устройстве. Если вы всё сделали правильно, то увидите маску на своём лице. Маска будет видна только вам, её автору (см. раздел [Уровни доступа](masks/publication/overview)).

![alt=Маска на лице;title=Маска на лице](7649e608ceb6a6a20ef8e7290bf092e49b40d31b77584d60e8e72d22 "-1709775590157895052")

## FAQ

### Как получить ссылку на маску?

Нужно [отправить архив с готовой маской](#Просмотр%20маски%20в%20мобильном%20приложении) боту.

### Моя маска не открывается у друзей.

Сначала маску может тестировать только её автор. Если вы хотите показать свою маску друзьям, сперва её нужно [отправить на модерацию](masks/publication/moderation).

### Моя маска не отображается в каталоге.

Чтобы ваша маска появилась в каталоге, её нужно [отправить на модерацию](masks/publication/moderation).

### После загрузки архива не появляется ни ссылка на маску, ни ошибка.

![alt=Маска загружается и скоро будет доступна;title=Маска загружается и скоро будет доступна](db856c8dd9ad19bbc3c6211a82d0f75ac2d61a036a8d08c7e1547cc8 "-4356079128229541997")

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

1. **Удалите файлы скриптов**. Если в вашей маске не используются скрипты, удалите все файлы с расширением `.as` — обычно это файл `main.as`, а также содержимое папок `Scripts` и `ScriptEngine`.

1. **Проверьте формат изображений.** Чаще всего такая ошибка случается в macOS, если при сохранении изображения в графическом редакторе не указать формат файла явно. Проверьте, что все изображения сохранены в формате PNG. Не полагайтесь только на название файла — расширение `.png` не гарантирует, что используется именно PNG. Один из признаков неверного формата — большой вес файла.

    ![alt=Выбирайте формат PNG при сохранении;title=Выбирайте формат PNG при сохранении](5781ec295f045499653c81bafa2edbc6a1ad3a8ef7c3675dbc3883b3 "-5218902659859092982")

### Маска загрузилась, но не отображается в камере, хотя в приложении для тестирования всё было в порядке.

Обычно такая проблема связана с чувствительностью мобильных устройств к регистру символов. Например, текстура расположена по адресу `Textures/Stars.png`, а в файле конфигурации путь к ней описан в нижнем регистре (маленькими буквами), как в примере ниже. Такая маска не будет работать на мобильном устройстве. Чтобы решить проблему, поправьте описание пути к текстуре с учётом регистра.

```JSON
    {
        ...
        "effects" : [
            {
                "name" : "patch",
                "textures" : "textures/stars.png",
                ...
            }
        ]
    }
```

### [Ошибка] ZIP-архив содержит повторяющиеся имена файлов

![alt=Архив содержит повторяющиеся имена файлов;title=Архив содержит повторяющиеся имена файлов](cfc09de8f8276a8a3a91e2387e79eb21f2e879f1b4d838adc9273db5 "-6155024118646842628")

Эта ошибка может возникнуть в двух случаях: либо из-за встроенного архиватора macOS, либо вы упаковали в ZIP-архив лишние папки. Чтобы исправить проблему:

1. **Удалите лишние папки**. Решение проблемы описано ниже, в вопросе [В корне архива не найден файл `mask.json`](#В%20корне%20архива%20не%20найден%20файл%20`mask.json`).
1. **Попробуйте другой архиватор**. Эта ошибка возникает при использовании встроенного архиватора macOS. Он создаёт скрытые файлы с повторяющимися именами. Мы рекомендуем вам скачать с официального сайта бесплатный [архиватор Keka](https://www.keka.io/ru/) и в настройках отметить пункт **Исключить вилки ресурсов Mac (напр., .DS_Store)**. После этого перетащите нужные файлы в окно архиватора Keka, чтобы создать архив маски.
    :::carousel
    ![](d2da43d7d6b57791f66f78e401600e611fd482ff65b48001dcbfeec8             "2138365077486545752")
    ![](6922e8097149021e4aa4693b7146772bb3fdc395b53fb67bb4ce8a5e             "-4186616842356763240")
    ![](5d1ccd55bc0f959732124911bfa894a4abe689f7c7958557d712ae06             "6518801762968286297")
    :::

### [Ошибка] в корне архива не найден файл `mask.json`

Эта ошибка может возникнуть в двух случаях: либо в вашем архиве действительно отсутствует файл `mask.json`, либо вы упаковали в ZIP-архив лишние папки.

Если все файлы маски находятся, например, в папке `Stars`, то в архив надо поместить именно содержимое `Stars`, а не саму папку. В примерах ниже показано, как архивировать правильно, а как — неправильно.

:::carousel
![alt=Как архивировать маску правильно;title=Правильно!](67ee9ff93351afac5ac65a84db60a269e592c0e4094ae6522f542a92 "1602686782640535748")
![alt=Так архивировать маску неправильно;title=Неправильно!](5276416ca0c757f9d589d0c98fddfd08d59628147dc5c81e3bb560d2 "7222784579163567699")
:::

### Я не вижу здесь описание своей проблемы.

Если проблема возникла на этапе просмотра и её описания нет в этом разделе, пожалуйста, напишите сообщение в сообщество [Маски ВКонтакте](https://vk.me/msx).

Маски | Подготовка | Просмотр маски

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

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

Cчетчики, информацию о которых нужно вернуть. Может включать следующие значения:
* `friends` — новые заявки в друзья;
* `friends_suggestions` — предлагаемые друзья;
* `messages` — новые сообщения;
* `photos` — новые отметки на фотографиях;
* `videos` — новые отметки на видеозаписях;
* `gifts` — подарки;
* `events` — события;
* `groups` — сообщества;
* `notifications` — ответы;
* `sdk` — запросы в мобильных играх;
* `app_requests` — уведомления от приложений.
* `friends_recommendations` — рекомендации друзей.

filter

user_id

Возвращает объект, который может содержать поля `friends`, `messages`, `photos`, `videos`, `notes`, `gifts`, `events`, `groups`, `notifications`, `sdk`, `app_requests`, `friends_recommendations` со значением счетчиков (`integer`).




account.getCounters

Отключает push-уведомления на заданный промежуток времени.

Идентификатор устройства для сервиса push уведомлений.

token

Уникальный идентификатор устройства.

device_id

Время в секундах на которое требуется отключить уведомления, `-1` отключить навсегда.

time

Идентификатор чата, для которого следует отключить уведомления.

chat_id

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

Идентификатор назначения.

Для пользователя:

* `id`  пользователя.

Для групповой беседы:

* `2000000000` + `id` беседы.

Для сообщества:

* `-id` сообщества.

peer_id

`1` — включить звук в этом диалоге, `0` — отключить звук (параметр работает, только если в `peer_id` передан идентификатор групповой беседы или пользователя).

sound

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

account.setSilenceMode

Создает рекламные кампании.

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

Some part of the request has not been completed

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

account_id

Сериализованный JSON-массив объектов, описывающих создаваемые кампании. Описание объектов `campaign_specification` смотрите ниже.

data

## `campaign_specification`

`client_id` 
Обязательный параметр, `int` (числовое значение).
Только для рекламных агентств. id клиента, в рекламном кабинете которого будет создаваться кампания.

`type`
Тип кампании:
* `normal` — обычная кампания, в которой можно создавать любые объявления, кроме описанных в следующих пунктах;
* `promoted_posts` — кампания, в которой можно рекламировать только записи в сообществе;
* `adaptive_ads` — кампания, в которой можно рекламировать только объявления адаптивного формата.

`name` 
Название рекламной кампании. Строка длиной от 3 до 60 символов.

`day_limit`
Дневной лимит в рублях. Положительное число.

`all_limit` 
Общий лимит в рублях. Положительное число.

`start_time`
Время запуска кампании в формате `unixtime`. Положительное число.

`stop_time` 
Время остановки кампании в формате `unixtime`. Положительное число.

`status` 
[`0`, `1`]
Статус рекламной кампании (`1` — запущена, `0` — остановлена).



Возвращает массив ответов на запросы в массиве `data`. Соответствующий объект в выходном массиве содержит `id` созданной кампании (ноль в случае неудачи), и поля `error_code` и `error_desc` в случае возникновения ошибки. Ненулевой `id` и наличие `error_code 602` говорит о том, что кампания создана, но, возможно, некоторые поля не были ей присвоены по причине их некорректности.

ads.createCampaigns

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

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

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

client_id

Название аудитории ретаргетинга — строка до 64 символов.

name

Количество дней, через которое пользователи, добавляемые в аудиторию, будут автоматически исключены из неё.

lifetime

Идентификатор пикселя, если требуется собирать аудиторию с веб-сайта.

target_pixel_id

Массив правил для пополнения аудитории из пикселя. Имеет вид:

```JSON
[
    {"type": args},
    {"type": args},
    ...
    {"type": args}
](
    {"type": args},
    {"type": args},
    ...
    {"type": args}
)
```

target_pixel_rules

 Возможные значения типа правила `type` и аргументов правила `args`:
 | `type` | `args` |
|---|---|
 | `url_full_match` Полное совпадение URL страницы (`http referer`), на которой находится пользователь | URL страницы (`string`), включая протокол и домен. Например, `"https:// example.com/catalog/shoes?item=836451"` |
 | `url_substrings_match` Частичное совпадение URL страницы (`http referer`), на которой находится пользователь | Массив строк для поиска вхождения. Совпадение засчитывается в случае вхождения всех заданных подстрок в URL.   Например, `["catalog", "men", "shoes"]`. |
 | `url_regex_match` Соответствие URL страницы, на которой находится пользователь (`http referer`), регулярному выражению | Регулярное выражение (`string`). Например, `catalog/(men\|women)/shoes?item=\d+`. |
 | `event_full_match` Полное совпадение названия события | Название события.   Например, `"click-red-button"`. |
 | `event_substrings_match` Частичное совпадение названия события | Массив строк для поиска вхождения. Совпадение засчитывается в случае вхождения всех подстрок в название события.   Например, `["click", "red", "button"]`. |
 | `event_regex_match` Соответствие названия события регулярному выражению | Регулярное выражение (`string`).   Например, `"^click-(red\|green)-\d+$"`. |

Возвращает объект со следующими полями:
* `id` — идентификатор аудитории.

ads.createTargetGroup

Возвращает параметры таргетинга рекламных объявлений

**Для рекламных агентств**. 

id клиента, у которого запрашиваются рекламные объявления.

Флаг, задающий необходимость вывода архивных объявлений.
* `0` — выводить только активные объявления;
* `1` — выводить все объявления.

include_deleted

only_deleted

Фильтр по рекламным кампаниям.
Сериализованный JSON-массив, содержащий `id` кампаний. Если параметр равен `null`, то будут выводиться рекламные объявления всех кампаний.

campaign_ids

Фильтр по рекламным объявлениям.
Сериализованный JSON-массив, содержащий `id` объявлений. Если параметр равен `null`, то будут выводиться все рекламные объявления.

ad_ids

Ограничение на количество возвращаемых объявлений. Используется, только если параметр `ad_ids` равен `null`, а параметр `campaign_ids` содержит `id` только одной кампании.

limit

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

offset

**Замечание**
Если одновременно включены фильтры `campaign_ids` и `ad_ids`, то выведены будут следующие объявления:
1. Если `id` объявления указано в `ad_ids`, то оно выводится.
2. Если объявление принадлежит рекламной кампании, чей `id` указан в `campaign_ids`, то оно выводится.
3. Если существует объявление с `id`, указанным в `ad_ids` и оно принадлежит кампании, чей `id` указан в `campaign_ids`, то эта рекламная кампания игнорируется, т.е. для нее правило 2 не работает.

Выводится не более **2000** объявлений из не более чем **2000** кампаний.

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

ads.getAdsTargeting

Позволяет получить возможные тематики рекламных объявлений.

Язык, на котором нужно вернуть результаты. Список поддерживаемых языков Вы можете найти на странице [Запросы к API](api/api-requests).

lang

После успешного выполнения возвращает два массива объектов — **v1** и **v2**, каждый из которых содержит объекты, описывающие тематики в следующем формате:
* `id` — идентификатор тематики;
* `name` — название тематики;
* `subcategories` [`subcategory`] (если есть хотя бы один подраздел) — список подразделов. Массив объектов, каждый из которых содержит следующие поля:
   * `id` — идентификатор подраздела;
   * `name` — название подраздела.

Массив **v1** включает устаревшие тематики. Актуальный список содержится в массиве **v2**.

ads.getCategories

Возвращает размер целевой аудитории таргетинга, а также рекомендованные значения CPC и CPM.

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

Сериализованный JSON-объект, описывающий параметры таргетинга. Описание объекта `criteria` см. ниже. Игнорируется, если задан параметр `ad_id`.

criteria

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

ad_id

Формат объявления:
* `1` — изображение и текст;
* `2` — большое изображение;
* `3` — эксклюзивный формат;
* `4` — продвижение сообществ или приложений, квадратное изображение;
* `7` — специальный формат приложений;
* `8` — специальный формат сообществ;
* `9` — запись в сообществе;
* `10` — витрина приложений;
* `11` — адаптивный формат.

ad_format

Рекламные площадки, на которых будет показываться объявление:

* (если `ad_format` равен `1`):
   * `0` — ВКонтакте и сайты-партнёры;
   * `1` — только ВКонтакте.
* (если `ad_format` равен `9`):
   * `all` — все площадки;
   * `desktop` — полная версия сайта;
   * `mobile` — мобильный сайт и приложения.
* (если `ad_format` равен `11`):
   * `all` — все площадки;
   * `desktop` — полная версия сайта;
   * `mobile` — мобильный сайт и приложения.

ad_platform

Для `ad_format` = `9` и `11`.
`1` — не показывать объявление на стенах сообществ. По умолчанию: `0`.

ad_platform_no_wall

Для `ad_format` = `9` и `11`.
`1` — не показывать объявление в рекламной сети. По умолчанию: `0`.

ad_platform_no_ad_network

Ссылка на рекламируемый объект.

link_url

Домен рекламируемого объекта.

link_domain

Если установлен, то дополнительно в ответе будут рекомендованные значения CPC и CPM для достижения 5, 10, 15... 95% охвата.

need_precise

impressions_limit_period

## `criteria`

`sex`
`integer`, [`0`,`1`,`2`]
Пол. Возможные значения:
* `0` — любой;
* `1` — женский;
* `2` — мужской.

`age_from`
`integer`
Нижняя граница возраста (`0` — не задано).

`age_to`
`integer`
Верхняя граница возраста (`0` — не задано).

`birthday`
`integer`
День рождения. Задаётся в виде суммы флагов:
* `+1` — сегодня;
* `+2` — завтра;
* `+4` — в течение недели.

`country`
`integer`
Идентификатор страны (`0` — не задано).

`cities`
`string`
Идентификаторы городов и регионов. Идентификаторы регионов необходимо указывать со знаком «минус».

`cities_not`
`string`
Идентификаторы городов и регионов, которые следует исключить из таргетинга. Идентификаторы регионов необходимо указывать со знаком «минус».

`geo_near`
`string`
Места для гео-таргетинга. Список точек, разделённых «;». Каждая точка задаётся строкой вида `"<широта>,<долгота>,<радиус>[,название места]"`.
Широта и долгота задаются в десятичной записи градусов, радиус в метрах из списка допустимых: 
* `500`, 
* `1000`, 
* `1500`, 
* `2000`, 
* `2500`, 
* `3000`, 
* `3500`, 
* `4000`, 
* `4500`, 
* `5000`, 
* `6000`, 
* `7000`, 
* `8000`, 
* `9000`, 
* `10000`, 
* `11000`, 
* `12000`, 
* `13000`, 
* `14000`, 
* `15000`, 
* `20000`, 
* `25000`, 
* `30000`, 
* `35000`, 
* `40000`, 
* `45000`, 
* `50000`, 
* `55000`, 
* `60000`, 
* `65000`, 
* `70000`, 
* `75000`, 
* `80000`, 
* `85000`, 
* `90000`, 
* `95000`, 
* `100000`.
Использование этого критерия несовместимо с критериями `country`, `cities` и `cities_not`.

`geo_point_type`
`string`
Тип мест гео-таргетинга. Возможные значения:
* `regular` — регулярно бывает;
* `home` — дом;
* `work` — работа или учёба;
* `online` — находится сейчас. Ограничивает максимальное значение радиуса в 5000м.
Используется только вместе с критерием `geo_near`.

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

`groups`
`string`
Идентификаторы сообществ, разделенные запятой.

`groups_not`
`string`
Идентификаторы сообществ, разделенные запятой, которые следует исключить из таргетинга.

`apps`
`string`
Идентификаторы приложений, разделенные запятой.

`apps_not`
`string` 
Идентификаторы приложений, разделенные запятой, которые следует исключить из таргетинга.

`districts`
`string`
Идентификаторы районов, разделенные запятой.

`stations`
`string`
Идентификаторы станций метро, разделенные запятой.

`streets`
`string`
Идентификаторы улиц, разделенные запятой.

`schools`
`string`
Идентификаторы учебных заведений.

`positions`
`string`
Идентификаторы должностей.

`religions`
`string`
Идентификаторы религиозных взглядов.

`interest_categories`
`string`
Категории интересов.

`interests`
`string`
Интересы.

`user_devices`
`string`
Устройства.

`user_os`
`string` 
Операционные системы.

`user_browsers`
`string` 
Интернет-браузеры.

`retargeting_groups`
`string`
Идентификаторы групп ретаргетинга.

`retargeting_groups_not`
`string` 
Идентификаторы групп ретаргетинга, которые следует исключить из таргетинга.

`paying`
`integer`, [`1`, `2`]
Платежи. Возможные значения:
* `1` — не использовали голоса ВКонтакте;
* `2` — использовали голоса ВКонтакте.

`travellers`
`integer`, [`0`, `1`]
Только путешественники (`1` — включить фильтр).

`school_from`
`integer`
Нижняя граница года окончания школы (`0` — не задано).

`school_to`
`integer`
Верхняя граница года окончания школы (`0` — не задано).

`uni_from`
`integer`
Нижняя граница года окончания вуза (`0` — не задано).

`uni_to`
`integer`
Верхняя граница года окончания вуза (`0` — не задано).



Возвращает объект, описывающий целевую аудиторию и содержащий следующие поля:

 `audience_count` 
 `integer`
 Размер целевой аудитории.

 `recommended_cpc` 
 `number`
 Рекомендованная цена для объявлений за клики, указана в рублях с копейками в дробной части. 0 — для форматов, для которых недоступна оплата за клики. 
 
 `recommended_cpm` 
 `number`
 Рекомендованная цена для объявлений за показы, указана в рублях с копейками в дробной части.
 
 `recommended_cpc_50` 
 `number`
 Рекомендованная цена для объявлений за клики, с прогнозом на достижение 50% охвата за первую неделю.
 
 `recommended_cpm_50`
 `number`
 Рекомендованная цена для объявлений за показы, с прогнозом на достижение 50% охвата за первую неделю.
 
 `recommended_cpc_70`
 `number` 
 Рекомендованная цена для объявлений за клики, с прогнозом на достижение 70% охвата за первую неделю.
 
 `recommended_cpm_70`
 `number`
 Рекомендованная цена для объявлений за показы, с расчётом на достижение 70% охвата за первую неделю.
 
 `recommended_cpc_90`
 `number` 
 Рекомендованная цена для объявлений за клики, с прогнозом на достижение 90% охвата за первую неделю.
 
 `recommended_cpm_90`
 `number`
 Рекомендованная цена для объявлений за показы, с прогнозом на достижение 90% охвата за первую неделю.
 
 `recommended_cpm_precise`
 Если установлен  `need_precise`, то рекомендованная цена для объявлений за показы, с прогнозом на достижение 5, 10, 15... 95% охвата за первую неделю.
 
 `recommended_cpс_precise`
 Если установлен  `need_precise`, то рекомендованная цена для объявлений за клики, с прогнозом на достижение 5, 10, 15... 95% охвата за первую неделю.

> Обратите внимание, минимальный размер целевой аудитории — **100** человек. Если заданным критериям соответствует меньшее количество пользователей, размер аудитории будет считаться равным нулю.

ads.getTargetingStats

Методы для работы с приложениями.

apps

Возвращает данные о запрошенном приложении.

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

apps.getCatalog

В объекте [приложения](reference/objects/app) в поле **type** приходят новые значения.
* _app_ — социальное приложение
* _game_ — игра
* _site_ — подключенный сайт
* _standalone_ — отдельное приложение (для мобильного устройства)
* _vk_app_ — VK App приложение
* _community_app_ - приложение сообщества
* _html5_game_ - HTML5 игра

В объекте приложения больше не приходит поле **is_html5_app**.

Метод [messages.getConversationMembers](messages.getConversationMembers) возвращает новую ошибку 917.

Изменения в API опросов:
*  Новый формат [объекта опроса](reference/objects/poll).
*  Метод [polls.create](polls.create) поддерживает новые параметры для опросов с мультивыбором и фоном.

В методе [groups.getLongPollServer](groups.getLongPollServer) изменился тип поля **ts** — теперь это string, а не integer.



5.85

В [объекте приложения](objects/app) изменились названия полей и размеры изображений иконок и баннеров.

5.57

Добавлены параметры **app_ids**, **return_friends**. Добавлены поля **installed**, ** screenshots**.

5.36

Идентификатор приложения, данные которого необходимо получить. 
Если этот параметр и параметр `app_ids` не указан, возвращается идентификатор приложения, через которое выдан ключ доступа (`access_token`).

app_id

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

5.62