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

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

Чтобы создать новое сообщение, надо передать в 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

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

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

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

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

{
    "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"                              /* Текст сообщения */
    }
}

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

В данный момент функционал кнопок в сообщениях находится на этапе бета-тестирования. При наличии вопросов и предложений вы можете обратиться на api-support@ok.ru.
Также обратите внимание, что в данный момент при нажатии на кнопку на платформе m.ok.ru вместо callback payload вам будет отправлено новое сообщение от лица пользователя

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