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:
  • startTime0

  • viewmsnp24Equivalent

  • targetTypePassport|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:
  • baseDomainhttps://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

  • typewl

{"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:
  • contenttypetext

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