Conversation endpoints

GET https://client-s.gateway.messenger.live.com/v1/users/ME/conversations

This returns an array of conversations that the current user has most recently interacted with. The lastMessage field holds a message object in the same format as retrieved from /v1/users/ME/conversations/(id)/messages.

Note

This endpoint is paginated.

Query Parameters:

• startTime – 0

• view – msnp24Equivalent

• targetType – Passport|Skype|Lync|Thread

{"_metadata": {"backwardLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations?syncState=...&view=msnp24Equivalent",
               "forwardLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations?syncState=...&view=msnp24Equivalent",
               "syncState": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations?syncState=...&view=msnp24Equivalent",
               "totalCount": 10},
 "conversations": [{"id": "8:joe.4",
                    "lastMessage": {"clientmessageid": "1451606399999",
                                    "composetime": "2016-01-01T00:00:00.000Z",
                                    "content": "Hi!",
                                    "conversationLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/8:joe.4",
                                    "from": "https://client-s.gateway.messenger.live.com/v1/users/ME/contacts/8:joe.4",
                                    "id": "1451606400000",
                                    "messagetype": "Text",
                                    "originalarrivaltime": "2016-01-01T00:00:00.000Z",
                                    "type": "Message",
                                    "version": "1451606400000"},
                    "messages": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/8:joe.4/messages",
                    "properties": {"clearedat": "1451606400000", "consumptionhorizon": "..."},
                    "targetLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/contacts/8:joe.4",
                    "type": "Conversation",
                    "version": 1451606400000},
                   {"id": "19:a0b1c2...d3e4f5@thread.skype",
                    "lastMessage": {"clientmessageid": "1451606399999",
                                    "composetime": "2016-01-01T00:00:00.000Z",
                                    "content": "A message for the team.",
                                    "conversationLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype",
                                    "from": "https://client-s.gateway.messenger.live.com/v1/users/ME/contacts/8:anna.7",
                                    "id": "1451606400000",
                                    "messagetype": "Text",
                                    "originalarrivaltime": "2016-01-01T00:00:00.000Z",
                                    "type": "Message",
                                    "version": "1451606400000"},
                    "messages": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages",
                    "properties": {"consumptionhorizon": "..."},
                    "targetLink": "https://client-s.gateway.messenger.live.com/v1/threads/19:a0b1c2...d3e4f5@thread.skype",
                    "threadProperties": {"lastjoinat": "1451606400000", "topic": "Team chat", "version": "1451606400000"},
                    "type": "Conversation",
                    "version": 1451606400000},
                   ...]}

GET https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/(string: id)

Retrieve details about a conversation.

Parameters:

• id – chat thread identifier

{"id": "19:a0b1c2...d3e4f5@thread.skype",
 "lastMessage": {"clientmessageid": "1451606399999",
                 "composetime": "2016-01-01T00:00:00.000Z",
                 "content": "A message for the team.",
                 "conversationLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype",
                 "from": "https://client-s.gateway.messenger.live.com/v1/users/ME/contacts/8:anna.7",
                 "id": "1451606400000",
                 "messagetype": "Text",
                 "originalarrivaltime": "2016-01-01T00:00:00.000Z",
                 "type": "Message",
                 "version": "1451606400000"},
 "messages": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages",
 "properties": {"consumptionhorizon": "..."},
 "targetLink": "https://client-s.gateway.messenger.live.com/v1/threads/19:a0b1c2...d3e4f5@thread.skype",
 "threadProperties": {"lastjoinat": "1451606400000", "topic": "Team chat", "version": "1451606400000"},
 "type": "Conversation",
 "version": 1451606400000}

Group conversations

GET https://client-s.gateway.messenger.live.com/v1/threads/(string: id)

Fetch additional group-specific information, including the members and admins of the chat, topic, and join permissions.

Parameters:

• id – chat thread identifier

{"id": "19:a0b1c2...d3e4f5@thread.skype",
 "members": [{"capabilities": [],
              "cid": 0,
              "friendlyName": "",
              "id": "8:anna.7",
              "linkedMri": "",
              "role": "Admin",
              "type": "ThreadMember",
              "userLink": "https://client-s.gateway.messenger.live.com/v1/users/8:anna.7",
              "userTile": ""},
             {"capabilities": [],
              "cid": 0,
              "friendlyName": "",
              "id": "8:joe.4",
              "linkedMri": "",
              "role": "User",
              "type": "ThreadMember",
              "userLink": "https://client-s.gateway.messenger.live.com/v1/users/8:joe.4",
              "userTile": ""},
             ...],
 "messages": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages",
 "properties": {"capabilities": ["AddMember",
                                 "ChangeTopic",
                                 "ChangePicture",
                                 "EditMsg",
                                 "CallP2P",
                                 "SendText",
                                 "SendSms",
                                 "SendFileP2P",
                                 "SendContacts",
                                 "SendVideoMsg",
                                 "SendMediaMsg",
                                 "ChangeModerated"],
                "createdat": "1451606400000",
                "creator": "8:anna.7",
                "creatorcid": "0",
                "historydisclosed": "true",
                "joiningenabled": "true",
                "picture": "URL@https://api.asm.skype.com/v1/objects/0-.../views/avatar_fullsize",
                "topic": "Team chat"},
 "type": "Thread",
 "version": 1451606400000}

POST https://client-s.gateway.messenger.live.com/v1/threads

Create a new group conversation.

Each member object consists of an id (user thread identifier), and role (either Admin or User).

Request JSON Object:

• members – array of member objects

Response Headers:

• Location – URL for the new conversation

PUT https://client-s.gateway.messenger.live.com/v1/threads/(string: id)/properties

Update properties of a group conversation. Only one property can be set at a time, which should be the value of the name field, and key for the field holding the new value.

Parameters:

• id – chat thread identifier

Request JSON Object:

• name – name of parameter to be updated (from the rest of this list)

• topic – new conversation topic

• joiningenabled – whether users can join by URL

• historydisclosed – whether newly-joining users can see past message history

Join URLs

POST https://api.scheduler.skype.com/threads

Retrieve the join URL for a group conversation, if it is currently public.

Request JSON Object:

• baseDomain – https://join.skype.com/launch/

• threadId – chat thread identifier

{"Blob": "AzByCx...XcYbZa",
 "Id": "Za0Yb1...By2Az3",
 "JoinUrl": "https://join.skype.com/<join-code>",
 "ThreadId": "19:a0b1c2...d3e4f5@thread.skype"}

POST https://join.skype.com/api/v2/conversation/

Convert a join URL into standard identifiers.

Note

No authentication is required for this endpoint.

Request JSON Object:

• shortId – join identifier from the URL

• type – wl

{"Action": "Chat",
 "ChatBlob": "AzByCx...XcYbZa",
 "FlowId": "1",
 "Id": "Za0Yb1...By2Az3",
 "Resource": "19:a0b1c2...d3e4f5@thread.skype"}

Messages

GET https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/(string: id)/messages

Retrieve the most recent messages from the conversation.

Note

This endpoint is paginated.

Parameters:

• id – chat thread identifier

{"_metadata": {"backwardLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages?syncState=...&view=msnp24Equivalent",
               "forwardLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages?syncState=...&view=msnp24Equivalent",
               "syncState": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype/messages?syncState=...&view=msnp24Equivalent",
               "totalCount": 10},
 "messages": [{"clientmessageid": "1451606399999",
               "composetime": "2016-01-01T00:00:00.000Z",
               "content": "A message for the team.",
               "conversationLink": "https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/19:a0b1c2...d3e4f5@thread.skype",
               "from": "https://client-s.gateway.messenger.live.com/v1/users/ME/contacts/8:anna.7",
               "id": "1451606400000",
               "messagetype": "Text",
               "originalarrivaltime": "2016-01-01T00:00:00.000Z",
               "type": "Message",
               "version": "1451606400000"},
              ...]}

POST https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/(string: id)/messages

Send a message to the conversation. There are several additional parameters that can be passed in for different message types.

Parameters:

• id – chat thread identifier

Request JSON Object:

• contenttype – text

• messagetype – base message type

• content – raw content for the message

{"OriginalArrivalTime": 1451606400000}

DELETE https://client-s.gateway.messenger.live.com/v1/users/ME/conversations/(string: id)/messages

Delete all message history for this client.

Parameters:

• id – chat thread identifier

Message types

• Text: A plain text message.

• RichText: A text message with rich formatting.

• RichText/Contacts: A message containing an embedded contact.

  <contacts><c t="s" s="joe.4" f="Joe Bloggs"/></contacts>
  

• RichText/Location: A message containing the user’s location.

  <location latitude="51000000" longitude="-10000" altitude="0"
            horizontalAccuracy="0" verticalAccuracy="0"
            speed="0" course="0" timeStamp="1451606400"
            address="Unknown address" pointOfInterest="">
      <a href="https://www.bing.com/maps/...">Unknown address</a>
  </location>
  

• RichText/Media_GenericFile: A message representing a shared file.

  <URIObject type="File.1" uri="https://api.asm.skype.com/v1/objects/0-..."
             url_thumbnail="https://api.asm.skype.com/v1/objects/0-.../views/thumbnail">
      <Title>Title: file.txt</Title>
      <Description>Description: file.txt</Description>
      <FileSize v="84"/>
      <OriginalName v="file.txt"/>
      <a href="https://login.skype.com/...">https://login.skype.com/...</a>
  </URIObject>
  

• RichText/UriObject: A shared image file.

  <URIObject type="Picture.1" uri="https://api.asm.skype.com/v1/objects/0-..."
             url_thumbnail="https://api.asm.skype.com/v1/objects/0-.../views/imgt1">
      <Title/><Description/>
      <OriginalName v="photo.jpg"/>
      <a href="https://api.asm.skype.com/s/i?0-...">https://api.asm.skype.com/s/i?0-...</a>
      <meta type="photo" originalName="photo.jpg"/>
  </URIObject>
  

• RichText/Files: Multiple file attachments in one message.

  <files alt="sent files &quot;file1.txt&quot;, &quot;file2.txt&quot;">
      <file size="84" index="0" tid="1000000000">file1.txt</file>
      <file size="105" index="1" tid="2000000000">file2.txt</file>
  </files>
  

• Control/Typing, Control/ClearTyping: A user starts or stops typing in a conversation.

• Event/Call: Call-related notifications.

  <partlist type="started" alt="">
      <part identity="joe.4"><name>Joe Bloggs</name></part>
  </partlist>
  

• ThreadActivity/TopicUpdate: A group conversation topic change.

  <topicupdate>
      <eventtime>1451606400000</eventtime>
      <initiator>8:joe.4</initiator>
      <value>Team chat</value>
  </topicupdate>
  

• ThreadActivity/JoiningEnabledUpdate: A change to joining a group conversation by link.

  <joiningenabledupdate>
      <eventtime>1451606400000</eventtime>
      <initiator>8:anna.7</initiator>
      <value>true</value>
  </joiningenabledupdate>
  

• ThreadActivity/HistoryDisclosedUpdate: A group conversation topic change.

  <historydisclosedupdate>
      <eventtime>1451606400000</eventtime>
      <initiator>8:joe.4</initiator>
      <value>false</value>
  </historydisclosedupdate>
  

• ThreadActivity/AddMember: A user was added to the group conversation.

  <addmember>
      <eventtime>1451606400000</eventtime>
      <initiator>8:anna.7</initiator>
      <target>8:joe.4</target>
  </addmember>
  

• ThreadActivity/RoleUpdate: A user’s admin status was changed.

  <roleupdate>
      <eventtime>1451606400000</eventtime>
      <initiator>8:anna.7</initiator>
      <target><id>8:joe.4</id><role>admin</role></target>
  </roleupdate>
  

• ThreadActivity/DeleteMember: A user was removed from the group conversation.

  <deletemember>
      <eventtime>1451606400000</eventtime>
      <initiator>8:anna.7</initiator>
      <target>8:joe.4</target>
  </deletemember>
  

Message formatting

Different clients seem to support varying amounts of HTML formatting tags, as shown in this compatibility table:

Code	Web	Windows	Mac	Android
<b>Bold</b>	✔	✔	✔	✔
<i>Italic</i>	✔ [1]	✔	✔	✔
<u>Underline</u>		✔
<s>Strikethrough</s>	✔ [1]	✔	✔	✔
<font color="#ff0000">Colour</font>	✔	✔		✔
<font size="24">Size</font>		✔
<blink>Blink</blink>		✔
<center>Centre</center>		✔	✔
<a href="http://google.com">http://google.com</a>	✔	✔	✔	✔
<a href="http://google.com">Custom link</a> [2]	✔	✔	✔	✔
<pre>Preformatted</pre>	✔ [1]	✔	✔	✔

[1] (1,2,3)

Only works if the correct raw_pre and raw_post attributes are specified.

[2]

Skype may block sending the message at server level (error message “Failure due to: BlockedContent”) if it impersonates another link, e.g. <a href="http://youtube.com">http://google.com</a>.