Bot API для групп

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

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

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

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

Для работы с Bot API от имени группы необходимо получить специальный ключ доступа.

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

Администратор группы может получить ключ доступа (токен) в разделе Настройки группы на полной версии сайта.

Откройте раздел «Настройки», выберите вкладку «Управление» и в строчке «Работа с API» нажмите «Получить ключ доступа» и подтвердите свой выбор.

Внимание! Если вы уже получали ранее ключ доступа для группы, то при генерации нового ключа - старый станет недействительным.

Внимание! Все возвращаемые айди могут быть строковыми.

Загрузка чатов и истории

Получить список чатов, в которых участвует бот

https://botapi.ok.ru/me/chats?access_token=TOKEN

Опциональные параметры GET запроса:

marker - позиция для постраничной загрузки

count - количество запрашиваемых чатов (не более 100)

Ответ:

{
    "chats":[                                                    /* Массив чатов той же структуры, что и в ответе на /me/chat */
        {
            "chat_id":"-68011111111111",                         /* ID чата */
            "type":"CHAT",                                       /* Тип чата */
            "status":"ACTIVE",                                   /* Ваш статус: ACTIVE, LEFT или REMOVED */
            "title":"Наш уютный чатик",                          /* Название чата */
            "icon":{"url":"https://st.mycdn.me/res/i/ok_logo.png"},  /* URL иконки в формате jpg или png */
            "participants":{                                     /* Список участников в виде таблицы user_id -> время последнего прочтения */
                "1112223334":1478100200314,
                "5556667778":1452435499000
            },
            "last_event_time":1478100200314                      /* Время последнего изменения чата или сообщений в этом чате */
        }
    ]
}

Получить чат по ID

https://botapi.ok.ru/me/chat?access_token=TOKEN&chat_id=ID

Ответ:

{
    "chat_id":"-68011111111111",                         /* ID чата */
    "type":"CHAT",                                       /* Тип чата */
    "status":"ACTIVE",                                   /* Ваш статус: ACTIVE, LEFT или REMOVED */
    "title":"Наш уютный чатик",                          /* Название чата */
    "icon":{"url":"https://st.mycdn.me/res/i/ok_logo.png"},  /* URL иконки в формате jpg или png */
    "participants":{                                     /* Список участников в виде таблицы user_id -> время последнего прочтения */
        "1112223334":1478100200314,
        "5556667778":1452435499000
    },
    "last_event_time":1478100200314                      /* Время последнего изменения чата или сообщений в этом чате */
}

Загрузить историю чата

https://botapi.ok.ru/me/messages?access_token=TOKEN&chat_id=ID

Опциональные параметры GET запроса:

from - время, начиная с которой загружать историю

to - до какого времени в прошлом загружать историю (to < from)

count - максимальное количество загружаемых сообщений (от 1 до 100)

Ответ:

{
    "messages":[                                   /* Массив сообщений в том же формате, что и в Webhooks */
        {
            "sender":{"user_id":"581111111111"},     /* ID пользователя или ID группы, отправившего сообщение */
            "recipient":{"chat_id":"-68011111111111"},  /* ID чата */
            "message":{
                "mid":"mid.000000e1e1e1e1e1e1e1e1e1e1e1e1e1",  /* Уникальный идентификатор сообщения */
                "text":"Привет",                               /* Текст сообщения */
                "seq":96111111111111111                        /* Возрастающий счётчик */
            },
            "timestamp":1478100200314              /* Время отправки сообщения в формате Java timestamp */
        },
        ...
    ]
}

Отправка сообщений

Для посылки сообщения необходимо отправить POST запрос в формате JSON на

https://botapi.ok.ru/me/messages?access_token=TOKEN

Отправка текстового сообщения

{
    "recipient":{"chat_id":"-68011111111111"},  // ID чата.
    "message":{
        "text":"Привет"
    }
}

Отправка сообщения с фото

{
    "recipient":{"chat_id":"-680111111111111"},  // ID чата
    "message":{
        "attachment":{
            "type":"image",
            "payload":{"url":"https://st.mycdn.me/res/i/ok_logo.png"}  // URL изображения в формате jpg или png
        }
    }
}

Состояния сообщений

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

Отметить все сообщения в чате как прочитанные

{
    "recipient":{"chat_id":"-68011111111111"},// ID чата
    "sender_action":"mark_seen"               // Прочитанными отмечаются все сообщения в чате на момент получения команды
}

Уведомить о наборе нового сообщения

{
    "recipient":{"chat_id":"-68011111111111"},// ID чата
    "sender_action":"typing_on"               // Обозначить для собеседников процесс набора сообщения
}

Уведомить о процессе отправки фото, видео, аудио

{
    "recipient":{"chat_id":"-68011111111111"},// ID чата или диалога
    "sender_action":"sending_photo"           // Возможные значения: sending_photo, sending_video, sending_audio
}

Статус набора/отправки сообщения действует в течение 10 секунд после соответствующего sender_action или до получения нового сообщения.

Управление подписками на Webhooks

Механизм Webhooks позволяет боту получать сообщения по HTTP протоколу на указанный URL. Webhooks нужны только для приёма сообщений. Отправлять сообщения через Bot API можно и без них.

Зарегистрировать новый Webhook

POST запрос на https://botapi.ok.ru/me/subscribe?access_token=TOKEN

{
    "url":"https://example.com/mywebhook.php"  /* http: или https: URL, куда будут доставляться сообщения группы, которой выдан указанный TOKEN */
}

Отписаться от получения сообщений через Webhook

POST запрос на https://botapi.ok.ru/me/unsubscribe?access_token=TOKEN

{
    "url":"https://example.com/mywebhook.php"  /* http: или https: URL, указанный при регистрации Webhook */
}

Посмотреть все Webhook подписки

GET запрос на https://botapi.ok.ru/me/subscriptions?access_token=TOKEN

В ответ придёт список подписок в формате JSON.

{
    "subscriptions":[
        {"time":1481046252897,"url":"https://example.com/mywebhook.php"},
        {"time":1481056345678,"url":"https://webhooks.example.com/secondhook"}
    ]
}

Получение сообщений

На зарегистрированные Webhook URL будут отправляться уведомления о входящих сообщениях методом POST в формате JSON.

{
    "sender":{
        "user_id":"581111111111",          /* ID пользователя или ID группы, отправившей сообщение */
        "name":"Иван Петров"               /* Имя и фамилия отправителя с сайта ok.ru */
    },
    "recipient":{"chat_id":"-68011111111111"},/* ID чата или диалога */
    "message":{
        "mid":"mid.000000e1e1e1e1e1e1e1e1e1e1e1e1e1",  /* Уникальный идентификатор сообщения */
        "text":"Привет",                               /* Текст сообщения */
        "seq":96111111111111111                        /* Возрастающий счётчик */
    },
    "timestamp":1478100200314              /* Время отправки сообщения в формате Java timestamp */
}

На каждый такой запрос скрипт должен в течение максимум 5 секунд вернуть HTTP ответ со статусом 200 OK. Если отправка уведомления не удалась, или если скрипт вернул ответ со статусом, отличным от 200, через некоторое время будет предпринята попытка повторной отправки уведомления. Если в течение 8 часов от скрипта не было получено положительного ответа, регистрация указанного Webhook может быть автоматически отменена.