POST graph.user.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/me/messages/chat:C3ecb9d02a600?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"                                          
  }
}

New message creation

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":"Hello"                                      /* Message text */
  }
}

A message with an IMAGE attachment can be sent:

{
  "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 */
    }
  }
}

Support for other attachment types (VIDEO, SHARE, AUDIO) will be added in future.

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
  ]
}