POST graph.chat.messages

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

Внимание! 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":"Привет"                                     /* Текст сообщения */
  }
}

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

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

Пример сообщения с изображением:

{
  "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":"fileToken"}                                    /* Временный 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"                              /* Текст сообщения */
    }
}

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

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