GET graph.chat.messages

Получение сообщений в чате по ID

Название	Обязательный	Тип	Значение по умолчанию	Описание
chat:id	Да	String		ID чата в формате chat:id
from	Нет	Long	9223372036854775807	Время создания последнего запрашиваемого сообщения в чате (timestamp)
to	Нет	Long	0	Время создания первого запрашиваемого сообщения в чате (timestamp)
count	Нет	Integer	50	Количество запрашиваемых сообщений
include_deleted	Нет	Boolean		Получать ли удалённые сообщения. Если вам необходима эта возможность, требуется написать заявку на api-support@ok.ru, указав группу, которой необходимо выдать это право

Следует учесть, что сообщения идут в порядке убывания их времени появления. Т.е. сначала идут новые сообщения. Поэтому параметр from должен быть больше параметра to.

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

ID может указываться либо в PATH, либо в виде GET-параметра.

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

С указанием ID чата в PATH

https://api.ok.ru/graph/me/messages/chat:C3ecb9d02a600
?access_token=tkn18YdUJZe:CQABPOJKAKEKEKEKE
&from=1498581292941
&to=1498577000197
&count=2

С указанием ID чата в GET-параметре

https://api.ok.ru/graph/me/messages
?access_token=tkn18YdUJZe:CQABPOJKAKEKEKEKE
&chat_id=chat:C3ecb9d02a600
&from=1498581292941
&to=1498577000197
&count=2

Ответ

{
  "messages": [                                             /* Массив сообщений в чате */
    {
      "sender": {                                           /* Информация об отправителе сообщения (группа / пользователь) */
        "name": "Василий Васильев",                         /* Имя и фамилия пользователя */
        "user_id": "user:123456789012"                      /* ID пользователя в формате user:id */
      },
      "recipient": {                                        /* Информация о получателе сообщения (чат / диалог / пользователь)*/ 
        "chat_id": "chat:C3ecb9d02a600"                     /* ID чата в формате chat:id, либо ID пользователя в формате user:id */
      },
      "message": {                                          /* Информация о самом сообщении */
        "text": "text",                                     /* Текст сообщения */
        "seq": 98211023614189660,                           /* Возрастающий счётчик сообщения */
        "mid": "mid:C3ecb9d02a600.15cea67d78d2059"          /* ID сообщения в формате mid:id */
      },
      "timestamp": 1498581292941                            /* Время отправки сообщения (timestamp) */
    },
    {
      "sender": {
        "name": "Василий Васильев",
        "user_id": "user:123456789012"
      },
      "recipient": {
        "chat_id": "chat:C3ecb9d02a600"
      },
      "message": {
        "text": "https://ya.ru/",
        "seq": 98211018056672380,
        "attachments": [                                    /* Массив приложений сообщения */            
          {
            "type": "SHARE",                                /* Тип приложения [VIDEO, AUDIO, SHARE, IMAGE] */
            "payload": {                                    /* type-specific данные приложения. Сейчас одинаковые для всех типов приложений */
              "url": "https://ya.ru/"                       /* URL приложения к сообщению */
            }
          }
        ],
        "mid": "mid:C3ecb9d02a600.15cea668c4c2481"
      },
      "timestamp": 1498581208140
    }
  ]
}

Служебные сообщения

Кроме сообщений, которые посылаются участниками чатов, существует также ряд служебных сообщений:

выход пользователя из чата

      "message": {
        "text": "{\"ui\":1234567890123,\"ty\":\"EXIT\"}", /* ui - идентификатор пользователя, ty - действие */
        "seq": 1234567890123456,
        "mid": "mid:C3ecb9cd75b00.163caa4a35d2c93"
      }

Общий формат сообщения

{
  "message": {
    "text": "String", /* Текст сообщения */
    "attachment": { 
      "type": "IMAGE|VIDEO|AUDIO|SHARE|FILE|CONTACT|INLINE_KEYBOARD|LOCATION|MUSIC|CALL|PRESENT|STICKER", /* тип аттачмента */
      "payload": AttachmentPayload /* содержание аттачмента, зависит от типа аттачмента */
    }, /* единственный аттачмент в сообщении */
    "attachments": [{
      "type": "IMAGE|VIDEO|AUDIO|SHARE|FILE|CONTACT|INLINE_KEYBOARD|LOCATION|MUSIC|CALL|PRESENT|STICKER",
      "payload": AttachmentPayload
    }], /* список аттачментов в сообщении */
    "privacyWarning": "SCREENSHOT|SCREENCAST",
    "reply_to": "MID:" /* id сообщения, ответом на которое является текущее сообщение */
  }
}

Аттачменты

Сообщение может содержать как одно, так и несколько (до 5ти) аттачментов следующего типа:

IMAGE - изображение;
VIDEO - видео;
AUDIO - аудиозапись;
SHARE - решара контента в ОК;
FILE - файл любого формата;
CONTACT - контакт пользователя;
INLINE_KEYBOARD - список кнопок действий;
LOCATION - место;
MUSIC - музыкальный трек в ОК;
CALL - информация о видео-/аудиозвонке;
PRESENT - подарок в ОК;
STICKER - стикер.

В зависимости от типа аттачмента у него могут быть разные payload.

IMAGE

Изображение.

{
  "id": "imageId",
  "token": "imageToken",
  "url": "https://image.url"
}

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

указать токен полученный из данных существующего сообщения с аттачментом
указать токен полученный в процессе загрузки изображения с помощью метода GET graph.user.fileUploadUrl

{
  "token": "imageToken"
}

указать ссылку на изображение, но только 1 такое изображение может быть в запросе

{
  "url": "https://image.url"
}

VIDEO

Видео.

{
  "id": "videoId",
  "token": "videoToken",
  "url": "https://video.url"
}

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

указать токен полученный из данных существующего сообщения с аттачментом
указать токен полученный в процессе загрузки видео с помощью метода GET graph.user.fileUploadUrl

{
  "token": "videoToken"
}

AUDIO

Аудио.

{
  "id": "audioId",
  "token": "audioToken",
  "url": "https://audio.url"
}

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

указать токен полученный из данных существующего сообщения с аттачментом
указать токен полученный в процессе загрузки аудио с помощью метода GET graph.user.fileUploadUrl

{
  "token": "audioToken"
}

FILE

Файл любого формата.

{
  "id": "fileId",
  "token": "fileToken",
  "url": "https://file.url"
}

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

указать токен полученный из данных существующего сообщения с аттачментом
указать токен полученный в процессе загрузки аудио с помощью метода GET graph.user.fileUploadUrl

{
  "token": "fileToken"
}

Решара какого-либо контента, уже опубликованного в ОК. Это могут быть, например группы, публикации групп и пользователей, изображения и т.д.

{
  "id": "123456789",                                        
  "url": "https://ok.ru/group123456789/topic/123456789"     
}

Создание аттачмента этого типа через ботапи не поддерживается

CONTACT

Контакт пользователя ОК.

{
  "id": "123456789",                /* идентификатор пользователя */
  "name": "firstName lastName",     /* имя пользователя */
  "photoUrl": "https://photo.url",  /* ссылка на фото пользователя */
  "phone": "79493344555",           /* номер телефона пользователя */
  "vcfBody": "..."                  /* электронная визитная карточка vCard */
}

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

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

{
  "id": "123456789"
}

указать данные электронной визитной карточки vCard

{
  "vcfBody": "..."
}

LOCATION

Местоположение пользователя.

{
  "latitude": 59.928658,
  "longitude": 30.38113,
  "altitude": 1.0000,
  "epu": 1.0000,
  "heading": 1.0000,
  "speed": 1.0000,
  "zoom": 1.0000,
  "livePeriod": 600  /* время, в течение которого пользователь будет делиться живой локацией, в секундах */
}

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

указать координаты latitude и longitude (остальные поля опциональны)

{
  "latitude": 59.928658,
  "longitude": 30.38113
}

MUSIC

Музыкальный трек, загруженный в ОК.

{
  "id": "23486020457601",
  "url": "https://ok.ru/music/track/23486020457601"
}

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

указать идентификатор трека

{
  "id": "23486020457601"
}

CALL

Видео-/аудиозвонок в ОК.

{
  "id": "23486020457601",                           /* идентификатор звонка */
  "type": "AUDIO|VIDEO",                            /* тип звонка */
  "hangupType": "CANCELED|REJECTED|HUNGUP|MISSED"   /* тип завершения звонка */
  "duration": 10                                    /* длительность звонка */
}

Создание аттачмента этого типа через ботапи не поддерживается

PRESENT

В данный момент данный тип приложения не поддерживается

Подарок в ОК.

{
  "id": "23486020457601",            /* идентификатор подарка */
  "status": "SENT",                  /* статус подарка */
  "receiverId": "USER:12345678901",  /* id получателя */
  "senderId": "USER:12345678902"     /* id отправителя */
}

Создание аттачмента этого типа через ботапи не поддерживается

STICKER

Стикер в ОК.

{
  "id": "c23a918ef4",                                         
  "url": "https://i.mycdn.me/getSmile?smileId=c23a918ef4"     
}

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

указать идентификатор стикера

{
  "id": "c23a918ef4"
}

INLINE_KEYBOARD

Список кнопок действий.

В данный момент кнопки с типом REQUEST_GEO_LOCATION и REQUEST_CONTACT не поддерживаются на всех платформах ОК

{
    "keyboard": {
        "buttons": [
            [
                {
                    "type": "CALLBACK",                     /* тип кнопки */
                    "text": "someText",                     /* текст кнопки */
                    "intent": "DEFAULT|POSITIVE|NEGATIVE",  /* окрас кнопки */
                    "payload": "callbackPayload"            /* текст сообщения, отправляемого после нажатия на кнопку */
                }
            ],
            [
                {
                    "type": "LINK",
                    "text": "someText",
                    "intent": "DEFAULT|POSITIVE|NEGATIVE",
                    "url": "https://some.url"               /* ссылка, открываемая по нажатию на кнопку */
                }
            ],
            [
                {
                    "type": "REQUEST_CONTACT",
                    "text": "someText",
                    "intent": "DEFAULT|POSITIVE|NEGATIVE"
                },
                {
                    "type": "REQUEST_GEO_LOCATION",
                    "text": "someText",
                    "intent": "DEFAULT|POSITIVE|NEGATIVE",
                    "quick": true
                }
            ]
        ]

    },
    "callbackId": "16ef50d9a4e00c516ef50d9a4e00c516ef50d9a4e00c5"   /* идентификатор коллбека */
}

Список кнопок (или т.н. клавиатура) это достаточно сложная структура, позволяющая производить действия по нажатию на кнопку, а не через ручную отправку сообщения.

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

Есть несколько видов кнопок (параметр type):

CALLBACK - стандартный вид кнопки, предполагает, что по нажатию от лица пользователя будет отправлено сообщение;
LINK - кнопка-ссылка, по нажатию на неё открывается указанная ссылка;
REQUEST_CONTACT - запрос шаринга контакта пользователя;
REQUEST_GEO_LOCATION - запрос шаринга локации пользователя.