API ВКонтакте

# 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 | Формат запросов

# Клавиатура

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

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

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

Если она включена, и у пользователя еще нет переписки с сообществом, мы показываем кнопку «Начать», которая отправляет команду `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) используемого языка.

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

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

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

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

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

![](47b0490c93d3c32d6c544be551a8806fe61b18d0ea3a07e85e0fcb85 "-5636580476323788944")

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сообщество

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# «Код Петербурга — 2022»

> Сроки проведения: с 1 июня по 30 сентября 2022 года.
> Подведение итогов: 14 октября 2022 года.
> [Итоги конкурса](https://vk.com/press/spb-code-2022)
> [Список победителей](https://vk.com/vkappsdev?w=wall-166562603_4652)

Вместе с [Комитетом по информатизации и связи](https://kis.gov.spb.ru/) и [Экосистемой городских сервисов «Цифровой Петербург»](https://about.petersburg.ru/) мы запускаем конкурс «Код Петербурга». Присоединяйтесь, если у вас есть готовый проект или идея [мини-приложения](mini-apps/getting-started), [чат-бота](api/bots/getting-started) или [навыка для умного помощника Маруси](marusia/getting-started).

Конкурс состоит из двух отдельных этапов и продлится четыре месяца. За это время новые проекты найдут свою аудиторию, а победители конкурса получат [вознаграждение](https://vk.com/@vkappsdev-polozhenie-o-publichnom-konkursee-kod-peterburga).

## Основная информация

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

Санкт-Петербургский информационно-аналитический центр даст вам доступ к API, с помощью которого вы сможете реализовать свои идеи. Узнайте больше о его возможностях на сайте [api.petersburg.ru](https://api.petersburg.ru/?role=0). Использовать другие открытые API тоже можно — но только в дополнение к уже предоставленным.

> Мы советуем вам ознакомиться со статьёй [Список API «Код Петербурга»](https://vk.com/@vkappsdev-spisok-api-kod-peterburga). В ней команда «Цифрового Петербурга» собрала список API по разным направлениям, которые помогут сделать ваши проекты оригинальнее и интереснее.

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

Сроки подачи заявки на конкурс:

* первый этап — с 1 июня по 31 июля 2022 года,
* второй этап — с 1 августа по 30 сентября 2022 года.

Экспертное жюри будет оценивать работы по нескольким критериям. Больше баллов получат проекты, которые:

* точно соответствуют заявленной тематике;
* основаны на оригинальной идее, которая ещё не реализована на платформе [VK Mini Apps](https://vk.com/services), в [каталоге навыков](https://marusia.mail.ru/) Маруси или в виде чат-бота для [сообщества](https://vk.com/groups);
* продуманы в плане UI и UX;
* могут масштабироваться с использованием технологий других платформ (например, [Одноклассников](https://apiok.ru/apps/rules));
* технически качественно реализованы, не содержат ошибок, запускаются в вебе и на мобильных устройствах;
* активно набирают аудиторию в течение первой недели после публикации.

## Как участвовать в конкурсе

### Шаг 1. Создайте оригинальный сервис

Создайте проект, который соответствует заявленной теме и не повторяет идеи, уже реализованные на платформе VK Mini Apps, в каталоге навыков Маруси или на платформе чат-ботов.

Следующие ресурсы помогут вам при подготовке проекта:

* Документация по созданию мини-приложений. Если вы новичок, начните с [первых шагов](mini-apps/getting-started).
* [Гайд на Хабре](https://habr.com/ru/company/vk/blog/521192/), в котором описан весь процесс разработки мини-приложения — от идеи до релиза.
* Публикации в [сообществе VK Mini Apps](https://vk.com/vkappsdev).
* [Библиотека VKUI](libraries/vkui), [макеты Figma](https://www.figma.com/@vk) и [стайлгайд](https://vkcom.github.io/VKUI/).
* Документация [Маруси](marusia/getting-started) и [чат-ботов](api/bots/getting-started).
* [Чат](https://vk.me/join/WI/WK4g2kUBnCAOXEkzOML64hEz_C/RA3Lc=) с участниками и организаторами конкурса.

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

#### Мини-приложения

Мини-приложение должно попасть в [каталог](https://vk.com/services), а перед этим пройти [модерацию](mini-apps/management/moderation) и тестирование. Здесь важно рассчитать время, чтобы уложиться в сроки программы. В среднем этот этап занимает около двух недель.

>**Важно!** На первом этапе отправить заявку на модерацию можно не позднее 31 июля. На втором этапе мы советуем отправлять мини-приложение на модерацию в середине сентября. Так больше шансов успеть пройти проверку и попасть в каталог, а значит — претендовать на приз.

После публикации в каталоге ваше мини-приложение будет доступно всем пользователям ВКонтакте. Они смогут найти его на вкладке **Сервисы** мобильного приложения, в пункте меню **Мини-приложения** в мобильной и десктопной версиях сайта, а также по ссылке [vk.com/services](https://vk.com/services).

#### Навыки для Маруси

Скилл Маруси также нужно опубликовать в [каталоге](https://marusia.mail.ru/). Модерация и тестирование занимают, как правило, 5–7 дней. Полезные советы и подробное описание процесса проверки вы найдёте [в документации Маруси](marusia/moderation).

>**Важно!** На первом этапе отправить заявку на модерацию можно не позднее 31 июля. На втором этапе мы советуем отправлять скилл на модерацию в середине сентября.

#### Чат-боты

Для создания чат-бота вам потребуется [сообщество](https://vk.com/groups) ВКонтакте. Как только вы добавите в него своего чат-бота, можно подать заявку на участие в конкурсе. Проходить модерацию не потребуется. Примеры реализации на разных языках программирования, руководство по работе с API ВКонтакте и многое другое мы собрали [в документации](api/bots/getting-started).

### Шаг 3. Участвуйте в брифингах с экспертами

На протяжении всего конкурса мы будем проводить питчинги с представителями Команды ВКонтакте. Вы научитесь презентовать свой проект и получите рекомендации по его улучшению. Следите за объявлениями в [сообществе VK Mini Apps](https://vk.com/vkappsdev).

### Шаг 4. Подайте заявку

Чтобы подать заявку, нужно заполнить [форму](https://vk.cc/ccy5y8) и указать в ней ссылку на готовое приложение.

Подать заявку могут только физические лица — авторы проектов. При этом неважно, создан проект независимым разработчиком или командой. Ждём участников от 14 лет и старше.

### Шаг 5. Дождитесь итогов

Эксперты оценят проекты и выберут лидеров в каждой теме. Авторы этих проектов получат денежные призы. Общий призовой фонд — 15 миллионов рублей.

Итоги конкурса по каждому из этапов будут подведены 14 октября 2022 года. Результаты будут опубликованы в [сообществе VK Mini Apps](https://vk.com/vkappsdev).

## Конкурс «Код Петербурга» это не только вознаграждения

### Новые идеи и механики для ваших проектов

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

### Опыт питчингов и обратная связь от экспертов

У каждого участника будет возможность показать свой проект на питчингах. Все, кто готов представить идеи или прототипы своих мини-приложений, смогут выступить и получить рекомендации.

Конкурс «Код Петербурга» это не просто конкурс. Это шанс сделать удобный сервис для горожан и всех гостей Петербурга, а также проверить свои идеи на практике.

С вопросами о программе пишите в [сообщество VK Mini Apps](https://vk.com/vkappsdev).

Ждём ваших заявок!

## Полезные ссылки

[Публичное положение об участии в конкурсе](https://vk.com/@vkappsdev-polozhenie-o-publichnom-konkursee-kod-peterburga).
[Чат с участниками и организаторами](https://vk.me/join/WI/WK4g2kUBnCAOXEkzOML64hEz_C/RA3Lc=).

Сообщество | Архив | Код Петербурга — 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)
Автоматизируйте рутинные и похожие задачи с помощью чат-бота ВКонтакте.

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

# Платформа

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

Маски широко используются в историях, клипах, видеозвонках и трансляциях.

![alt=Примеры масок](58f8bb9537759117f9063616564131ad64e3afe279c72199d8f6d0f0 "1294238990372714489")

На нашей платформе можно создавать:
* Маски — визуальные элементы, привязанные к точкам на лице пользователя. Например: шапки, рога, очки, причёски.
* Эффекты — визуальные элементы, не привязанные к лицу. Например: фильтры цветокоррекции, постэффекты, шейдеры.
* Интерактивы — визуальные элементы, реагирующие на какие-то события (триггеры). Например: игры, викторины, рандомайзеры.

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

Создайте свою первую маску с помощью [пошаговой инструкции](masks/getting-started).

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

Научитесь [просматривать и тестировать](masks/view) маску.
Посмотрите [список программ](masks/tools), которые могут пригодиться в работе. 

## Создание маски

По сути маска ВКонтакте — это папка с конфигурационным файлом и набором текстур, 3D-моделей и скриптов.

Начните изучение с того, как устроен [конфигурационный файл](masks/configuration), как работают [эффекты](masks/effects/overview) и [плагины](masks/plugins/overview).

## Скрипты

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

Прокачайте свою маску с помощью [скриптов](masks/development/script-creation) и [событий](masks/development/events/overview).

## Публикация

Чтобы каждая маска нашла свою аудиторию, мы создали [каталог](https://vk.com/masks). 

Поделитесь своей маской — отправьте её на [модерацию](masks/publication/moderation).

Маски | Платформа

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

Возвращает информацию о текущем профиле.

Метод возвращает объект, описывающий профиль пользователя, со следующими полями:

`first_name`
`string`
Имя пользователя. 
 
`last_name`
`string`
Фамилия пользователя.

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

`screen_name`
`string`
Короткое имя пользователя (если есть).

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

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

`relation_partner`
`object`
Объект [пользователя](reference/objects/user), с которым связано семейное положение (если есть).

`relation_pending`
`integer`
Передается `1`, если пользователь, указанный в `relation_partner`, не подтвердил отношения.

`relation_requests`
`array`
Список объектов [пользователей](reference/objects/user), которые указали, что состоят в отношениях с данным пользователем (если есть).

`bdate`
`string`
Дата рождения пользователя, возвращается в формате D.M.YYYY.

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

`home_town`
`string`
Название родного города.

`country`
`object`
Страна. Объект, содержащий поля:
*  `id` (`integer`) — идентификатор страны,
*  `title` (`string`) — название страны.

`city`
`object`
Город. Объект, содержащий поля:
*  `id` (`integer`) — идентификатор города,
*  `title` (`string`) — название города.

`name_request`
`object`
Информация о заявке на смену имени, если она была подана. Объект, содержащий поля:
*  `id` (`integer`) – идентификатор заявки, необходимый для её отмены (только если `status` равен `processing`).
*  `status` (`string`) – статус заявки. Возможные значения:
    *  `processing` – заявка рассматривается,
    *  `declined` – заявка отклонена,
    *  `response` – общий ответ по статусу обработки заявки,
    *  `response_with_link` – общий ответ по статусу обработки заявки, содержащий ссылку в поле `link`.
*  `first_name` (`string`) – имя пользователя, указанное в заявке,
*  `last_name` (`string`) – фамилия пользователя, указанная в заявке.

`status`
`string`
Статус пользователя.

`phone`
`string`
Номер телефона.

account.getProfileInfo

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

* `image_type` (`string`) — тип изображения. Возможные значения:
   * `160x160`,
   * `160x240`,
   * `24x24`,
   * `510x128`,
   * `50x50`.

Возвращает объект с единственным полем `upload_url`, содержащим URL для загрузки изображения.
Для загрузки изображения сгенерируйте `POST`-запрос с файлом в поле `image` на полученный адрес, а затем вызовите метод [`appWidgets.saveGroupImage`](method/appWidgets.saveGroupImage).

appWidgets.getGroupImageUploadServer

Метод возвращает количество очков пользователя в этой игре.

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

user_id

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

apps.getScore

Возвращает адрес сервера для [загрузки аудиозаписей](api/upload#Загрузка%20аудиозаписей).

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

audio.getUploadServer

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

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

group_id

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

topic_id

`1` — будет возвращено дополнительное поле `likes`. По умолчанию поле `likes` не возвращается.

need_likes

Идентификатор комментария, начиная с которого нужно вернуть список (подробности см. ниже).

start_comment_id

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

offset

Количество сообщений, которое необходимо получить (но не более **100**). По умолчанию — **20**.

count

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

extended

Порядок сортировки комментариев:
* `asc` — хронологический;
* `desc` — антихронологический.

sort

Если был передан параметр `start_comment_id`, будет найдена позиция комментария в списке (или ближайший к нему более ранний). Начиная с этой позиции будет возвращено `count` комментариев. Смещение `offset` в этом случае будет отсчитываться от этой позиции (оно может быть отрицательным).

В случае успеха возвращает объект, содержащий поле `items`, поле `poll`, если к теме прикреплен опрос, а также поле `profiles` (если был указан параметр `extended`). 

Поле `items` представляет собой массив, содержащий [объекты, описывающие комментарии](reference/objects/comment-topic).


Если к теме был прикреплен опрос, возвращается поле `poll` следующего вида:
* `owner_id` — идентификатор владельца опроса;
* `poll_id` — идентификатор опроса;
* `created` — время создания опроса в формате `unixtime`;
* `is_closed` — `1`, если опрос закрыт (в нем больше нельзя принимать участие) или `0` в противном случае;
* `question` — текст вопроса для опроса;
* `votes` — общее количество ответивших пользователей;
* `answer_id` — идентификатор ответа текущего пользователя (если текущий пользователь еще не отвечал в данном опросе, то содержит `0`);
* `answers` — массив, содержащий объекты с вариантами ответа на вопрос в опросе:
   * `id` — идентификатор ответа на вопрос;
   * `text` — текст ответа на вопрос;
   * `votes` — количество пользователей, проголосовавших за данный вариант ответа;
   * `rate` — рейтинг данного варианта ответа, выраженный в процентах.

В случае передачи параметра `extended` равным `1`, поле `profiles` содержит массив объектов [`user`](reference/objects/user) с информацией о данных пользователей, являющихся авторами сообщений. 

Если был передан параметр `start_comment_id`, будет также возвращено поле `real_offset` – итоговое смещение данного подмножества комментариев (оно может быть отрицательным, если был указан отрицательный `offset`).

board.getComments

Возвращает информацию о городах и регионах по их идентификаторам.

Идентификаторы городов и регионов.

city_ids

Возвращает массив объектов, описывающих города. 

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

`id`
`integer`
Идентификатор города или региона,

`title`
`string`
Название города или региона.

database.getCitiesById

Удаляет документ пользователя или группы.

1150

1151

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

> Обратите внимание, идентификатор сообщества в параметре `owner_id` необходимо указывать со знаком `«-»` — например, `owner_id=-1` соответствует идентификатору сообщества [ВКонтакте API](https://vk.com/apiclub) (club1).

owner_id

Идентификатор документа.

doc_id

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

docs.delete

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

Строка поискового запроса. Например, «зелёные тапочки».

`1` — искать среди собственных документов пользователя.

search_own

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

> Обратите внимание, даже при использовании параметра `offset` для получения информации доступны только первые 1000 результатов.

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

return_tags

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

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

docs.search

Возвращает информацию о подписке VK Donut.

Идентификатор сообщества.

> Обратите внимание, идентификатор сообщества в параметре `owner_id` необходимо указывать со знаком `«-»` — например, `owner_id`=`-1` соответствует идентификатору сообщества [ВКонтакте API](https://vk.com/apiclub) (club1).

После успешного выполнения возвращает объект, содержащий следующие поля:
* `owner_id` (`integer`) — идентификатор сообщества, доном которого является пользователь;
* `next_payment_date` (`integer`) — дата следующего платежа в формате `unixtime`;
* `amount` (`integer`) — стоимость подписки (в рублях);
* `status` (`string`) — статус подписки.

donut.getSubscription

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

Код алгоритма в VKScript-формате, похожем на JavaSсript или ActionScript (предполагается совместимость с ECMAScript). Алгоритм должен завершаться командой `return %выражение%`. Операторы должны быть разделены точкой с запятой.

> Внутри `code` может содержаться не более 25 обращений к методам API.

code

func_v

### Пример значения параметра `code`

```VKScript
// Присваивает переменной a результат поиска по фотографиям с данными параметрами. 
var a = API.photos.search({"q":"Nature","count":3});

// Присваивает переменной b список владельцев найденных фотографий.
var b = a.items@.owner_id;

// Присваивает переменной с данные о страницах владельцев из списка b. 
var c = API.users.get({"user_ids":b});

// Возвращает список фамилий из данных о владельцах.
return c@.last_name;

// Пример цикла.
var a = 1; 
var b = 10; 
while (b != 0) { 
    b = b - 1; 
    a = a + 1; 
}; 
return a;
```

То же самое можно более коротко записать так:

```VKScript
return API.users.get({"user_ids": API.photos.search({"q":"Beatles", "count":3}).items@.owner_id})@.last_name;
```

Поддерживаются:
* арифметические операции,
* логические операции,
* создание массивов и списков ([X,Y]),
* `parseInt` и `parseDouble`,
* конкатенация (`+`),
* конструкция `if`,
* фильтр массива по параметру (`@.`),
* вызовы методов API, параметр `length`,
* циклы, используя оператор `while`,
* методы Javascript: `slice`, `push`, `pop`, `shift`, `unshift`, `splice`, `substr`, `split`,
* оператор `delete`,
* присваивания элементам маcсива, например: `row.user.action = "test"`,
* поиск в массиве или строке — `indexOf`, например: `"123".indexOf(2) = 1, [[1, 2, 3]].indexOf(3) = 2`. Возвращает `-1`, если элемент не найден.

В данный момент не поддерживается создание функций. 

Обращение к элементам массива с результатом какого-либо метода всего должно основываться на структуре JSON, а не XML. Например, правильным обращением является:

```VKScript
API.photos.search({"q":"Nature","count":3}).items@.owner_id;
```

А не:

```VKScript
API.photos.search({"q":"Nature","count":3}).items@.photo@.owner_id;
```

 Метод `execute` также может использоваться и для получения результатов нескольких не связанных между собой запросов.

**Пример значений параметра `code`**

```VKScript
return [API.friends.get(), API.status.get()];
return {"friends": API.friends.get(), "status": API.status.get()};
```

 В методе `execute` поддерживаются логические операции `<` (меньше), `>` (больше), `<=` (меньше или равно), `>=` (больше или равно), `==` (равно) и `!=` (не равно). В данный момент поддерживаются сравнения двух строк, двух чисел и строки и числа (в этом случае строка приводится к числу).

 Результат логического выражения может быть использован в управляющей конструкции `if...[[else...]]`:

**Пример значения параметра `code`**

```VKScript
var posts = API.wall.get({"count": 1});
 
if (posts.count<0) {
  return {"post": null, "copy_owner": null};
} else {
  var post = posts.items[0];
  var copy_owner=null;
  if (post.copy_history[0]){
    if (post.copy_history[0].owner_id > 0) {
      copy_owner = API.users.get({"user_id": post.copy_history[0].owner_id})[0];
    } else
    if (post.copy_history[0].owner_id  < 0) {
      copy_owner = API.groups.getById({"group_ids": -post.copy_history[0].owner_id})[0];
    }
    return {"post": post, "copy_owner": copy_owner};
  } else {
    return {"post": post, "copy_owner": null};
  }
}
```


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

Обратите внимание: версия API, указанная при вызове `execute`, не применяется автоматически к методам, вызываемым внутри `code`.

> **Обратите внимание!** 
> Существует ограничение на объём ответа. В случае, если данные в ответе занимают больше 5 МБ, вернётся ошибка 13 с комментарием `"response size is too big"`.


execute

Редактирует данные сервера для [Callback API](api/callback/getting-started) в сообществе.

Идентификатор сообщества.

Идентификатор сервера, данные которого нужно отредактировать.

server_id

Новое название сервера.

title

Новый секретный ключ сервера.

secret_key

groups.editCallbackServer

Возвращает информацию о заданном сообществе или о нескольких сообществах.

Идентификаторы или короткие имена сообществ. Максимальное число идентификаторов — 500.

group_ids

Иидентификатор или короткое имя сообщества.

Список дополнительных полей, которые необходимо вернуть. Например: 
* `activity`;
* `ban_info`;
* `can_post`;
* `can_see_all_posts`;
* `city`;
* `contacts`;
* `counters`;
* `country`;
* `cover`;
* `description`;
* `finish_date`;
* `fixed_post`;
* `links`;
* `market`;
* `members_count`;
* `place`;
* `site`;
* `start_date`;
* `status`;
* `verified`;
* `wiki_page`.

Полный список полей доступен [на этой странице](reference/objects/group). 

> Обратите внимание, для получения некоторых полей требуется право доступа `groups`. Подробнее смотрите [описание полей объекта `group`](reference/objects/group).

fields

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

groups.getById

Позволяет разрешить отправку сообщений от сообщества текущему пользователю.

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

messages.allowMessagesFromGroup

Помечает сообщения как важные либо снимает отметку.

Помечает сообщения как прочитанные.

messages.markAsRead

Список идентификаторов сообщений, которые необходимо пометить.

message_ids

`1`, если сообщения необходимо пометить, как важные;
`0`, если необходимо снять пометку.

important

Возвращает массив идентификаторов успешно помеченных сообщений.

messages.markAsImportant

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

Изменяет название беседы.

messages.editChat

Позволяет получить список пользователей мультидиалога по его `id`.

messages.getChatUsers

Метод [messages.removeChatUser](messages.removeChatUser) возвращает ошибку "935: User not found in chat", если пользователя нет в чате.



5.88

Метод [messages.removeChatUser](messages.removeChatUser) принимает новый параметр **member_id** (integer). В Callback API и Bots Longpoll добавлено новое [событие](api/events/overview) — платёж через VK Pay.

Метод [messages.deleteConversation](messages.deleteConversation) в ответе возвращает поле **last_deleted_id**, содержащее идентификатор последнего удалённого сообщения.



5.81 chat_id

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

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

member_id

messages.removeChatUser

Can't send messages for users from blacklist

Can't send messages for users without permission

Can't send messages to this user due to their privacy settings

This is a chat bot feature, change this status in settings

You can't access donut chat without subscription

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

Число в пределах `int32` — уникальный (в привязке к API_ID и ID отправителя) идентификатор, предназначенный для предотвращения повторной отправки одинакового сообщения. Сохраняется вместе с сообщением и доступен в истории сообщений. 

Переданный в запросе `random_id` используется для проверки уникальности, проверяя в заданном диалоге сообщения за последний час (но не более 100 последних сообщений).

random_id

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

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

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

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

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

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

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

peer_id

Идентификаторы получателей сообщения (при необходимости отправить сообщение сразу нескольким пользователям). Доступно только для ключа доступа сообщества. Максимальное количество идентификаторов: 100.

peer_ids

Короткий адрес пользователя (например, `illarionov`).

domain

Идентификатор беседы, к которой будет относиться сообщение.

user_ids

Текст личного сообщения. Обязательный параметр, если не задан параметр `attachment`.

message

После успешного выполнения возвращает идентификатор отправленного сообщения.
Если передан параметр `peer_ids`, возвращает массив объектов, каждый из которых содержит поля:
* `peer_id` — идентификатор назначения;
* `message_id` — идентификатор сообщения;
* `conversation_message_id` — идентификатор сообщения в диалоге;
* `error` — сообщение об ошибке, если сообщение не было доставлено получателю.

docs.delete

Параметры

Результат

Коды ошибок