POST graph.user.messages

Создание новых сообщений и действия над чатами и диалогами

Внимание! POST-запросы должны выполняться с заголовком Content-Type: application/json;charset=utf-8

С помощью данного метода можно совершить ряд действий над чатом / диалог, а именно:

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

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

https://api.ok.ru/graph/me/messages/chat:C3ecb9d02a600
?access_token=tkn18YdUJZe:CQABPOJKAKEKEKEKE

Управление состоянием чата

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

название чата;
иконка / логотип чата.

Пример запроса для изменения названия чата:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},           /* ID чата в формате chat:id */
  "chat_control":{
    "title":"Наш уютный чатик"                            /* Новый заголовок */
  }
}

Пример запроса для изменения иконки чата:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                 /* ID чата в формате chat:id */
  "chat_control":{
    "icon":{"url":"https://and.su/tamtam/icon128.png"}          /* URL иконки в формате jpg или png */
  }
}

Управление участниками

Для участников чата доступны следующие действие:

добавление участника в чат;
удаление участника из чата;
выход из чата

Пример добавления участника в чат:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},         /* ID чата в формате chat:id*/
  "chat_control":{
    "add_members":[                                     /* Массив пользователей для добавления */
      {"user_id":"user:123456789012"},                  /* ID пользователя для добавления в чат в формате user:id */
      {"user_id":"user:123456789021"}
    ]
  }
}

Пример удаления участника из чата:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},             /* ID чата в формате chat:id */
  "chat_control":{
    "remove_member":{"user_id":"user:123456789012"}         /* ID пользователя для удаления из чата в формате user:id */
  }
}

Пример запроса для выхода участником из чата:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},             /* ID чата в формате chat:id */
  "chat_control":{
    "leave":"true"                                          /* Действие выхода из чата */
  }
}

Создание новых сообщений

Создание новых сообщений - ключевое действие для данного метода.

Чтобы создать новое сообщение, надо передать в POST-payload метода объект сообщения, который соотвествует по структуре объекту сообщения из метода /me/messages/get.

Пример текстового сообщения:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},         /* ID чата в формате chat:id */
  "message":{                                           /* Содержание сообщения */
    "text":"Привет"                                     /* Текст сообщения */
  }
}

Отправка сообщений с приложениями

Также в данный момент можно отослать сообщение с изображениями и файлами.

Для отправки изображения в чат необходимо выполнить запрос с телом запроса вида (type = IMAGE):

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                     /* ID чата в формате chat:id */
  "message":{                                                       /* Содержание сообщения */
    "attachment":{
      "type":"IMAGE",
      "payload":{"url":"https://st.mycdn.me/res/i/ok_logo.png"}     /* URL изображения в формате jpg или png */
    }
  }
}

Для отправки файла в чат необходимо выполнить запрос вида:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                     /* ID чата в формате chat:id */
  "message":{                                                       /* Содержание сообщения */
    "attachment":{
      "type":"FILE",
      "payload":{"token":"tokenString"}                             /* Временный id файла, полученный на первом этапе */
    }
  }
}

Подробное описание процесса загрузки и отправки файла в чат описано здесь - graph.user.fileUploadUrl

Состояние текущего пользователя

Текущий пользователь может оповестить других участников о следующих действиях:

отметить все сообщения как прочитанные - mark_seen;
пользователь печатает новое сообщение - typing_on;
пользователь отсылает новый файл (видео, аудио, фото) - sending_photo.

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

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

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

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

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

Чтобы отослать такое сообщение, необходимо при вызове метода передать сообщение со следующим содержимым

{
    "recipient":{
        "user_ids":[                                /* Список id пользователей в формате user:id или id*/
            "user:123456789012",                    
            "210987654321"
        ]
    },
    "message":{                                     /* Содержимое сообщения */
        "text":"Hello"                              /* Текст сообщения */
    }
}

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

API в качестве ответа отдаст два списка значений:

список boolean-значений, определяющих то, было ли успешно отослано сообщение;
список идентификаторов чатов между пользователями и группой, в которые были отосланы сообщения. Если сообщение не было отослано, то вместо id чата указывается значение null.

Порядок этих значений соответствует порядку указания пользователей в запросе.

{
  "success": [
    true,
    false
  ],
  "chat_ids": [
    "chat:C401b13206b00",
    null
  ]
}

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

{
    "recipient":{
        "user_id": "user:123456789012"              /* Id пользователя-получателя в формате user:id или id*/
    },
    "message":{                                     /* Содержимое сообщения */
        "text":"Hello"                              /* Текст сообщения */
    }
}

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

{
  "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 - запрос шаринга локации пользователя.