Перейти в режим автора

Команды

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

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

Вы, как разработчик, можете обработать этот запрос и либо вернуть сообщение, которое нужно опубликовать в ответ на команду, либо вернуть HTTP STATUS 200, чтобы показать пользователю, что команда выполнена успешно.

Как задать URL для команд

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

Для того, чтобы защитить данные, URL для команд должен использовать HTTPS с валидным сертификатом.
Как только вы введете URL, мы отправим запрос с параметром challenge, и ваш сервер должен будет ответить отправленным нами значением.
Пример запроса:

{"requestType":4,"request":{"challenge":"***"},"lng":null,"token":"***"}

Пример ответа: 
{token:"***", response:{challenge:"***"}}

где token - это token, полученный разработчиком при создании бота.

Как только вы увидите, что URL провалидирован, можете включать команды и нажимать кнопку "Сохранить".
Далее вам нужно будет только добавлять команды с помощью кнопки "Добавить команду" в этом же пункте настроек бота.

Добавление команд

При добавлении команды необходимо указать:
  1. имя команды - оно будет отображаться непосредственно при вызове команды пользователем, поэтому должно максимально точно отражать ее суть;
  2. подсказка - отображается рядом с именем, предназначена для описания параметров команды, которые вводятся в текстовом поле рядом с командой, например, это может быть команда, которая переводит слово, передаваемое в команду в качестве параметра. см. пример использования команд;
  3. краткое описание - отображается ниже имени команды, для краткого разъяснения сути команды

Запросы при вызове команд:

Пример 1. Вызов команды из личной переписки:

{"userWmid":"***","commandName":"translate","ctx":1,"request":{"message":"***", "parentMessageId": 123},"lng":"ru-RU","token":"***","requestType":"2"}
  • "userWmid" - wmid пользователя, который вызвал команду;
  • "commandName" - имя команды;
  • "message" - текст, который ввел пользователь после непосредственно самой команды (в данном случае все, кроме "/translate:translator");
  • "parentMessageId" - идентификатор сообщения, на которое отвечает пользователь (может быть null);
  • "lng" - язык пользователя на сайте в момент вызова команды ("ru-RU" или "en-US");
  • "token" - токен, выданный при создании бота;
  • "ctx" - контекст вызова команды (1 - личная переписка, 2 - дискуссия, 4 - лента событий);
  • "requestType":"2" - тип запроса "команда".

Пример 2. Вызов команды из группового чата:

{"userWmid":"***","commandName":"translate","ctx":1,"request":{"message":"***", "parentMessageId": 123, "chatUid": "uid"},"lng":"ru-RU","token":"***","requestType":"2"}
  • "userWmid" - wmid пользователя, который вызвал команду;
  • "commandName" - имя команды;
  • "message" - текст, который ввел пользователь после непосредственно самой команды (в данном случае все, кроме "/translate:translator");
  • "parentMessageId" - идентификатор сообщения, на которое отвечает пользователь (может быть null);
  • "chatUid" - идентификатор чата;
  • "lng" - язык пользователя на сайте в момент вызова команды ("ru-RU" или "en-US");
  • "token" - токен, выданный при создании бота;
  • "ctx" - контекст вызова команды (1 - личная переписка, 2 - дискуссия, 4 - лента событий);
  • "requestType":"2" - тип запроса "команда".

Пример 3. Вызов команды из ленты событий:

{"userWmid":"***","commandName":"translate","ctx":4,"request":{"groupUid":"***","message":"***"},"lng":"ru-RU","token":"***","requestType":"2"}

где groupUid - идентификатор группы или бизнес-страницы, в рамках которой вызвана команда; остальные поля - см в примере 1.

Пример 4. вызов команды из дискуссии:

{"userWmid":"***","commandName":"translate","ctx":2,"request":{
    "parentId":null,"eventId":***,"groupUid":"***","message":"имя" 
},"lng":"en-US","token":"***","requestType":"2"}

где "parentId" - идентификатор родительского комментария (если команда создается не как ответ на комментарий, то поле будет равно null); "eventId" - идентификатор события, в рамках которого вызвана команда; остальные поля - см. в примерах выше.

Важно! Если вы не ответите на запрос с HTTP STATUS 200 в течении 3 секунд, то пользователь увидит сообщение об ошибке при выполнении команды.

Варианты ответов на запросы

1. Сообщение о состоянии выполнения команды

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

{"respType":0,"response":{"message":"success","state":[0,1]},"token":"***"}

где "respType" - обозначает, что это сообщение о состоянии команды; "message" - сообщение, которое будет показано пользователю; "state" - состояние команды (0 - успех, 1 - ошибка); token - токен, выданный при создании бота.

Примечание. Если поле "message" не передавать, то пользователю отобразиться стандартное сообщение либо об ошибке, либо об успешном выполнении, в зависимости от поля "state".

2. Создание события, комментария, личного сообщения.

Этот вариант мы рекомендуем использовать, если вы хотите, чтобы результатом команды было личное сообщение, событие или комментарий (в зависимости от контекста вызова команды).
Примером может служить команда отображения погоды в группе. Например, в форме создания события группы вы вызываете команду /weather:weather_bot (покажи погоду), в результате чего появляется событие от имени бота с информацией о погоде.

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

Описание ответов, в зависимости от контекста вызова команды.

1. Личное сообщение ("ctx" = 1)

{"respType":1,"response":{ "postText": "sample string 2", "files": ["sample string 1", "sample string 2"],
"attachedActions":[{"actions":[
  {"data":{"text":"Yes","style":1},"uid":"uid_accept","type":0},
  {"data":{"text":"Not now","style":0},"uid":"uid_cancel","type":0}
],"uid":"Uid","title":"Хотите получать от бота новости?","type":0}]}, "token":"***"}

Описание параметров (исключая corsWmid, так как корреспондентом выступает инициатор команды)

2. Комментарий ("ctx" = 2) 

{"respType":1,"response":{  
    "author":null,"sharer":null,"directedAccess":null,"subscribe":false,
    "actions":null,"files":null,"shortUrl":false,"postText":"test message" 
, "attachedActions":[{"actions":[
  {"data":{"text":"Yes","style":1},"uid":"uid_accept","type":0},
  {"data":{"text":"Not now","style":0},"uid":"uid_cancel","type":0}
],"uid":"Uid","title":"Хотите получать от бота новости?","type":0}]}, "token":"***"}

Описание параметров (исключая параметры eventId и parentId)

3. Событие ("ctx" = 4) 

{"respType":1,"response":{
    "author":null,"subscribe":false,"actions":null,"sharer":null,"task":null,"voting":null,"geo":null,
    "shortUrl":false,"postText":"test event","files":null
, "attachedActions":[{"actions":[
  {"data":{"text":"Yes","style":1},"uid":"uid_accept","type":0},
  {"data":{"text":"Not now","style":0},"uid":"uid_cancel","type":0}
],"uid":"Uid","title":"Хотите получать от бота новости?","type":0}]}, "token":"***"}

Описание параметров (исключая groupUid)