POST graph.chat.messages ✎ Дополнить на GitHub

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

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

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

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

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

https://api.ok.ru/graph/chat:C3ecb9d02a600/messages
   ?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":{"ref":"fileId"}                                    /* Временный 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 сообщения, ответом на которое является текущее сообщение */
  }
}

Аттачменты

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

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

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

IMAGE

Обычное изображение. Такой аттачмент можно создать двумя способами:

  • загрузить картинку с помощью метода GET graph.user.fileUploadUrl;
  • указать ссылку на уже загруженную ранее картинку.

Формат AttachmentPayload (указывать надо одно поле из двух):

{
  "id": "uploadedImageId",  /* идентификатор, полученный при загрузке изображения через метод graph.user.fileUploadUrl */
  "url": "https://image.url" /* адрес ранее загруженного на внешний источник изображения */
}

VIDEO

Видео. Такой аттачмент можно указать двумя способами:

  • загрузить видео с помощью метода GET graph.user.fileUploadUrl;
  • указать ссылку на уже загруженное ранее видео.
{
  "id": "uploadedVideoId",         /* идентификатор, полученный при загрузке видео через метод graph.user.fileUploadUrl */
  "token": "uploadedVideoToken",   /* токен, полученный при загрузке видео через метод graph.user.fileUploadUrl */
  "url": "https://video.url"       /* ссылка для скачивания файла */
}

AUDIO

Аудиофайл. Такой аттачмент можно указать двумя способами:

  • загрузить файл с помощью метода GET graph.user.fileUploadUrl;
  • указать ссылку на уже загруженный ранее файл.
{
  "id": "uploadedAudioId",         /* идентификатор, полученный при загрузке файла через метод graph.user.fileUploadUrl */
  "token": "uploadedAudioToken",   /* токен, полученный при загрузке файла через метод graph.user.fileUploadUrl */
  "url": "https://audio.url"       /* ссылка для скачивания файла */
}

SHARE

Решара какого-либо контента, уже опубликованного в ОК.

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

{
  "id": "123456789",                                        /* идентификатор объекта */
  "url": "https://ok.ru/group123456789/topic/123456789"     /* ссылка на объект */
}

FILE

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

{
  "id": "uploadedFileId",         /* идентификатор, полученный при загрузке файла через метод graph.user.fileUploadUrl */
  "token": "uploadedFileToken",   /* токен, полученный при загрузке файла через метод graph.user.fileUploadUrl */
  "url": "https://file.url"       /* ссылка для скачивания файла */
}

CONTACT

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

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

LOCATION

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

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

MUSIC

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

{
  "id": "23486020457601",                           /* идентификатор трека */
  "url": "https://ok.ru/music/track/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"     /* ссылка на стикер */
}

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