POST graph.chat.messages ✎ Edit on GitHub

Create new messages, modify chats, dialogs and their participants

This method allows you to do following actions:

  • create new chat messages;
  • modify chat / dialog state;
  • chat participants management;
  • notify other chat participants about your actions and state.

Request example

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

Actions over chat state

You can edit following chat data:

  • chat title;
  • chat logo.

Example request to edit chat title:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},           /* Chat ID in a chat:id format */
  "chat_control":{
    "title":"This is our chat now"                        /* New chat title */
  }
}

Example request to edit chat icon:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                 /* Chat ID in a chat:id format */
  "chat_control":{
    "icon":{"url":"https://and.su/tamtam/icon128.png"}          /* New icon image URL. Png or img formats only */
  }
}

Participants management

Following actions can be done with / or by chat participants:

  • add new chat participant;
  • remove chat participant;
  • leave chat by current user

Example request to add new chat participant:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},         /* Chat ID in a chat:id format */
  "chat_control":{
    "add_members":[                                     /* Array of user to add */
      {"user_id":"user:123456789012"},                  /* User ID in a user:id format */
      {"user_id":"user:123456789021"}
    ]
  }
}

Example request to remove chat participant:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},             /* Chat ID in a chat:id format */
  "chat_control":{
    "remove_member":{"user_id":"user:123456789012"}         /* User ID in a user:id format */
  }
}

Example request to leave chat by user:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},             /* Chat ID in a chat:id format */
  "chat_control":{
    "leave":"true"                                          
  }
}

Sending messages

This is a key feature of this method.

To create a new message you need to send a POST-payload data with a message object which is similar to an object that you can get with me/messages/get method.

Text message example:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},         /* Chat ID in a chat:id format */
  "message":{                                           /* Message content */
    "text":"Привет"                                     /* Message text */
  }
}

Sending messages with attachments

A message with image and file attachments can be sent.

A message with an IMAGE attachment can be sent like this:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                     /* Chat ID in a chat:id format */
  "message":{                                                       /* Message content */
    "attachment":{
      "type":"IMAGE",
      "payload":{"url":"https://st.mycdn.me/res/i/ok_logo.png"}     /* Resource URL */
    }
  }
}

A message with a FILE attachment can be sent like this:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},                     /* Chat ID in a chat:id format */
  "message":{                                                       /* Message content */
    "attachment":{
      "type":"FILE",
      "payload":{"ref":"fileId"}                                    /* Temporary file identifier */
    }
  }
}

More info about file uploading can be found here - graph.user.fileUploadUrl

Current user state

Current user can inform other chat participant about some of his actions or his state:

  • mark all messages as seen - mark_seen;
  • user us typing a new message - typing_on;
  • user is sending new file (video, audio, image) - sending_photo.

Example request:

{
  "recipient":{"chat_id":"chat:C3ecb9d02a600"},     /* Chat or dialog id */
  "sender_action":"mark_seen"                       /* Possible values: sending_photo, sending_video, sending_audio */
}

Direct user messages

It is possible to send a message from group to a single or multiple users at once.

User must allow to receive group messages before it can be sent to him.

Following message syntax is used for this purpose:

{
    "recipient":{
        "user_ids":[                                /* List of user ids in user:id or id format*/
            "user:123456789012",                    
            "210987654321"
        ]
    },
    "message":{                                     /* Message content */
        "text":"Hello"                              /* Message text */
    }
}

Each user from the list will get a message in his own group-to-user chat.

API will respond with two corresponding list of values: * boolean type values list that indicate if message was or was not successfully sent; * list of user-to-group chat ids in which messages where sent.

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

To send a message directly to one user you can use a simplified message syntax:

{
    "recipient":{
        "user_id": "user:123456789012"              
    },
    "message":{                                     
        "text":"Hello"                              
    }
}

Message format

{
  "message": {
    "text": "String", /* Message text */
    "attachment": { 
      "type": "IMAGE|VIDEO|AUDIO|SHARE|FILE|CONTACT|INLINE_KEYBOARD|LOCATION|MUSIC|CALL|PRESENT|STICKER", /* attachment type */
      "payload": AttachmentPayload /* attachment body, depends on type */
    }, /* single message attachment */
    "attachments": [{
      "type": "IMAGE|VIDEO|AUDIO|SHARE|FILE|CONTACT|INLINE_KEYBOARD|LOCATION|MUSIC|CALL|PRESENT|STICKER",
      "payload": AttachmentPayload
    }], /* multiple message attachments */
    "privacyWarning": "SCREENSHOT|SCREENCAST",
    "reply_to": "MID:" /* responded message id */
  }
}

Attachments

Message can contain a single or multiple attachments of following type:

  • IMAGE - image;
  • VIDEO - video;
  • AUDIO - audio;
  • SHARE - OK content reshare;
  • FILE - file of any extension;
  • CONTACT - user contact;
  • INLINE_KEYBOARD - action buttons structure;
  • LOCATION - user location;
  • MUSIC - OK music tracj;
  • CALL - information about video / audio call;
  • PRESENT - OK present;
  • STICKER - OK sticker.

Attachment’s payload depends on it’s type and can differ.

IMAGE

A simple image attachment. There are two ways to send such attachment to a chat:

AttachmentPayload format:

{
  "id": "uploadedImageId",  /* identifier acquired with graph.user.fileUploadUrl method */
  "url": "https://image.url" /* URL of a previously uploaded file */
}

VIDEO

A simple video attachment. There are two ways to send such attachment to a chat:

{
  "id": "uploadedVideoId",         /* identifier acquired with graph.user.fileUploadUrl method */
  "token": "uploadedVideoToken",   /* token acquired with graph.user.fileUploadUrl method */
  "url": "https://video.url"       /* URL of a previously uploaded file */
}

AUDIO

A simple audio attachment. There are two ways to send such attachment to a chat:

{
  "id": "uploadedAudioId",         /* identifier acquired with graph.user.fileUploadUrl method */
  "token": "uploadedAudioToken",   /* token acquired with graph.user.fileUploadUrl method */
  "url": "https://audio.url"       /* URL of a previously uploaded file */
}

SHARE

Reshare of a content previously published on OK.

This attachment can contain a link to a group, video, group / user topic, image, etc.

{
  "id": "123456789",                                        /* object identifier */
  "url": "https://ok.ru/group123456789/topic/123456789"     /* link to an object */
}

FILE

File of any format.

{
  "id": "uploadedFileId",         /* identifier acquired with graph.user.fileUploadUrl method */
  "token": "uploadedFileToken",   /* token acquired with graph.user.fileUploadUrl method */
  "url": "https://file.url"       /* URL of a previously uploaded file */
}

CONTACT

OK’s user contact.

{
  "name": "firstName lastName"      /* username */
  "phone": "79493344555",           /* user phone number */
  "photoUrl": "https://photo.url",  /* link to user's avatar */
}

LOCATION

User’s location.

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

MUSIC

OK music track.

{
  "id": "23486020457601",                           /* track identifier */
  "url": "https://ok.ru/music/track/23486020457601" /* link to a track */
}

CALL

Video/audio call info.

{
  "id": "23486020457601",                           /* call identifier */
  "type": "AUDIO|VIDEO"                             /* call type */
  "hangupType": "CANCELED|REJECTED|HUNGUP|MISSED"   /* call hangup type */
  "duration": 10                                    /* call duration */
}

PRESENT

This type of attachment is currently not supported

OK present.

{
  "id": "23486020457601",            /* present identifier */
  "status": "SENT"                   /* present status */
  "receiverId": "USER:12345678901"   /* receiver id */
  "senderId": "USER:12345678902"     /* sender id */
}

STICKER

OK sticker.

{
  "id": "c23a918ef4",                                         /* sticker identifier */
  "url": "https://i.mycdn.me/getSmile?smileId=c23a918ef4"     /* link to a sticker */
}

INLINE_KEYBOARD

REQUEST_GEO_LOCATION and REQUEST_CONTACT type buttons are currently not supported

Buttons structure.

{
    "keyboard": {
        "buttons": [
            [
                {
                    "type": "CALLBACK",                     /* button type */
                    "text": "someText",                     /* button text */
                    "intent": "DEFAULT|POSITIVE|NEGATIVE",  /* button color scheme */
                    "payload": "callbackPayload"            /* payload text */
                }
            ],
            [
                {
                    "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"   /* callback identifier */
}

Buttons list is a two dimensional array where buttons can be placed one on a single line or as a group.

There are following buttons types supported:

  • CALLBACK - main type of a button. When pressed by a user a new message is sent to a chat (called callback message);
  • LINK - a button that contains a link to another URL;
  • REQUEST_CONTACT - request of current user’s contact info;
  • REQUEST_GEO_LOCATION - request of current user’s location info.