Skip to content

Threads (Groupchats)

Jump to bottom Edit New page
leecher1337 edited this page May 3, 2015 · 2 revisions

Groupchats are supported with VER 2 of the protocol, so you need to send <ver>2</ver> in BND command, otherwise, groupchats will be disabled and you receive a notification that they are not available at this endpoint.

Creation of groupchat

Initiate

Send

PUT 21 MSGR\THREAD 649
Registration: ...base64 registration...

<thread>
  <id></id>
  <members>
    <member>
      <mri>8:live:user1</mri>
      <role>admin</role>
    </member>
    <member>
      <mri>8:live:user2</mri>
      <role>user</role>
    </member>
    ....
  </members>
</thread>

mri is Windows live ID (prefixed with network prefix), i.e. 1:[email protected] or 8:live:user

role can be one of:

Value Description
admin Administrator, like IRCop
user A normal chat user

Receive

The initiator receives the Chat ID of the new chat as PUT notification. He can however also acquire it from later NFY:

PUT 21 MSGR 591
UtcTime: 1430577279
Set-Registration: ...base64 registration...
Registration-Token-Expiry: 1430663628
Context: 1B8D4AA7AD8F8D02

<thread><id>19:[email protected]</id></thread>

Notifications

All users that are in that groupchat receive a notification about the new groupchat and the added members. See "Adding users to groupchat" for the notifications being sent.

Adding users to groupchat

Initiate

A user with role admin can add another user to the chat. The user has to send the following command. This is similar to creating a groupchat, except that the id of the existing groupchat is already given and only the user to be added is given in the <members> list:

PUT 21 MSGR\THREAD 649
Registration: ...base64 registration...

<thread>
  <id>19:[email protected]</id>
  <members>
    <member>
      <mri>8:live:user3</mri>
      <role>user</role>
    </member>
  </members>
</thread>

Notifications

  • All users that are in that groupchat receive a notification about the updated groupchat so that they can update their data structures:
NFY 0 MSGR\THREAD 588
Context: 1B8D4AA7AD8F8D02

<thread>
  <id>19:[email protected]</id>
  <version>1430577278672</version>
  <capabilities>2047</capabilities>
  <properties>
    <createdat>1430577278375</createdat>
    <creatorcid>0</creatorcid>
    <creator>8:live:user1</creator>
  </properties>
  <options />
  <members>
    <member>
      <mri>8:live:user2</mri>
      <capabilities>2</capabilities>
      <role>user</role>
    </member>
    <member>
      <mri>8:live:user1</mri>
      <capabilities>1</capabilities>
      <role>admin</role>
     </member>
    <member>
      <mri>8:live:user3</mri>
      <capabilities>1</capabilities>
      <role>user</role>
    </member>
     ...
  </members>
</thread>
  • All users get notifications about the fact that new users were added to the chat.
SDG 0 MSGR 746
Context: 118D40A718818F22

Routing: 1.0
To: 19:[email protected]
From: 19:[email protected]
Service-Channel: IM

Reliability: 1.0

Messaging: 2.0
Message-ID: 1430567277914
Message-Type: ThreadActivity/AddMember
Thread-Topic: live:user1, live:user2
Relationship-Type: Explicit
Is-Active: true
Original-Arrival-Time: 2015-05-01T00:01:02.300Z
Content-Type: text/plain; charset=UTF-8
Content-Length: 191
X-MMS-IM-Format: FN=MS%20Shell%20Dlg; EF=; CO=0; CS=0; PF=0

<addmember>
  <eventtime>1430434923320</eventtime>
  <initiator>8:live:user1</initiator>
  <target>8:live:user1</target>
  <target>8:live:user2</target>
  <target>8:live:user3</target>
</addmember>

Sender and receiver of the message are the Thread-ID (as can also be identified by Network ID 19).

Value Description
eventtime unix timestamp in ms when event occured.
initiator The WLID of the use who added the targets
target WLID of the users being added.

On a new groupchat the initiator is also added, of course. So the example above shows how an initial add message looks like after creating a new groupchat. If you would just add user3 like in the example above, only this user will show up as target in the list.

Removing a user from a groupchat

Initiate

A user with role admin can remove another user from the chat. Or a user can leave a groupchat by removing itself from the chat. The user has to send the following command:

DEL 27 MSGR\THREAD 560
Registration: ...base64 registration...

<thread>
  <id>19:[email protected]</id>
  <members>
    <member>
      <mri>8:live:user2</mri>
    </member>
  </members>
</thread>

So the members to remove with their WLIDs are sent here to the groupchat with given ID.

Notifications

  • All users get notified of the changed groupchat. The new notification message doesn't contain the removed user anymore:
NFY 0 MSGR\THREAD 588
Context: 1B8D4AA7AD8F8D02

<thread>
  <id>19:[email protected]</id>
  <version>1430577278672</version>
  <capabilities>2047</capabilities>
  <properties>
    <createdat>1430577278375</createdat>
    <creatorcid>0</creatorcid>
    <creator>8:live:user1</creator>
  </properties>
  <options />
  <members>
    <member>
      <mri>8:live:user1</mri>
      <capabilities>1</capabilities>
      <role>admin</role>
     </member>
    <member>
      <mri>8:live:user3</mri>
      <capabilities>1</capabilities>
      <role>user</role>
    </member>
     ...
  </members>
</thread>
  • All users get notifications about the fact that users were removed from the chat:
SDG 0 MSGR 746
Context: 118D40A718818F22

Routing: 1.0
To: 19:[email protected]
From: 19:[email protected]
Service-Channel: IM

Reliability: 1.0

Messaging: 2.0
Message-ID: 1430567277914
Message-Type: ThreadActivity/DeleteMember
Thread-Topic: live:user1, live:user3
Relationship-Type: Explicit
Is-Active: true
Original-Arrival-Time: 2015-05-01T00:01:02.300Z
Content-Type: text/plain; charset=UTF-8
Content-Length: 191
X-MMS-IM-Format: FN=MS%20Shell%20Dlg; EF=; CO=0; CS=0; PF=0

<deletemember>
  <eventtime>1430438462218</eventtime>
  <initiator>8:live:user1</initiator>
  <target>8:live:user2</target>
</deletemember>

So this is the same as addmember but with deletemember as tag and Message-Type: ThreadActivity/DeleteMember

Setting Chat topic

Initiate

The user who wants to set the topic sends:

PUT 21 MSGR\THREAD 608
Registration: ...base64 registration...

<thread>
  <id>19:[email protected]</id>
  <properties>
    <topic>This is our chat topic</topic>
  </properties>
</thread>

Notifications

  • All users receive notifications about the updated groupchat to update their internal structures:
NFY 0 MSGR\THREAD 671
Context: 4895C4F756987C34

<thread>
  <id>19:[email protected]</id>
  <version>1430577278672</version>
  <capabilities>2047</capabilities>
  <properties>
    <createdat>1430577278375</createdat>
    <creatorcid>0</creatorcid>
    <creator>8:live:user1</creator>
    <topic>This is our chat topic</topic>
  </properties>
  <options />
  <members>
    <member>
      <mri>8:live:user2</mri>
      <capabilities>2</capabilities>
      <role>user</role>
    </member>
    <member>
      <mri>8:live:user1</mri>
      <capabilities>1</capabilities>
      <role>admin</role>
     </member>
    <member>
      <mri>8:live:user3</mri>
      <capabilities>1</capabilities>
      <role>user</role>
    </member>
     ...
  </members>
</thread>

So this is the same as with other NFY, but this time, the <topic> in <properties> is also set.

  • All users get notifications about the fact that topic has been set:
SDG 0 MSGR 746
Context: 118D40A718818F22

Routing: 1.0
To: 19:[email protected]
From: 19:[email protected]
Service-Channel: IM

Reliability: 1.0

Messaging: 2.0
Message-ID: 1430567277914
Message-Type: ThreadActivity/TopicUpdate
Thread-Topic: This is our chat topic
Relationship-Type: Explicit
Is-Active: true
Original-Arrival-Time: 2015-05-03T12:47:18.975Z
Content-Type: text/plain; charset=UTF-8
Content-Length: 191
X-MMS-IM-Format: FN=MS%20Shell%20Dlg; EF=; CO=0; CS=0; PF=0

<topicupdate>
  <eventtime>1430657239224</eventtime>
  <initiator>8:live:user1</initiator>
  <value>This is our chat topic</value>
</topicupdate>

Promote a user to a certain role

Initiate

A user with role admin can promote the role of another user in the chat. The user has to send the following command:

PUT 21 MSGR\THREAD 608
Registration: ...base64 registration...

<thread>
  <id>19:[email protected]</id>
  <members>
    <member>
      <mri>8:live:user2</mri>
      <role>admin</role>
    </member>
  </members>
</thread>

So the role of the given user gets updated to the new role given.

Notifications

  • All users receive notifications about the updated groupchat to update their internal structures:
NFY 0 MSGR\THREAD 671
Context: 4895C4F756987C34

<thread>
  <id>19:[email protected]</id>
  <version>1430577278672</version>
  <capabilities>2047</capabilities>
  <properties>
    <createdat>1430577278375</createdat>
    <creatorcid>0</creatorcid>
    <creator>8:live:user1</creator>
    <topic>This is our chat topic</topic>
  </properties>
  <options />
  <members>
    <member>
      <mri>8:live:user2</mri>
      <capabilities>2</capabilities>
      <role>admin</role>
    </member>
    <member>
      <mri>8:live:user1</mri>
      <capabilities>1</capabilities>
      <role>admin</role>
     </member>
    <member>
      <mri>8:live:user3</mri>
      <capabilities>1</capabilities>
      <role>user</role>
    </member>
     ...
  </members>
</thread>
  • All users get notifications about the fact of a role update:
SDG 0 MSGR 746
Context: 118D40A718818F22

Routing: 1.0
To: 19:[email protected]
From: 19:[email protected]
Service-Channel: IM

Reliability: 1.0

Messaging: 2.0
Message-ID: 1430567277914
Message-Type: ThreadActivity/RoleUpdate
Thread-Topic: live:user1, live:user3
Relationship-Type: Explicit
Is-Active: true
Original-Arrival-Time: 2015-05-03T13:59:09.201Z
Content-Type: text/plain; charset=UTF-8
Content-Length: 191
X-MMS-IM-Format: FN=MS%20Shell%20Dlg; EF=; CO=0; CS=0; PF=0

<roleupdate>
  <eventtime>1430661581741</eventtime>
  <initiator>8:live:user1</initiator>
  <target>
    <id>8:live:user2</id>
    <role>admin</role>
  </target>
</roleupdate>

Getting informations about a thread

Initiate

On startup, the application can fetch the structure of groupchats that ie. gets in recentconversations-response to sync and reassemble all open groupchats:

GET 14 MSGR\THREADS 593
Registration: ...base64 registration...

<threads>
  <thread><id>19:[email protected]</id></thread>
  <thread><id>19:[email protected]</id></thread>
</threads>

Response

This will result in a response resembling the groupchat structure:

GET 14 MSGR 1601
UtcTime: 1430661459
Set-Registration: ...base64 registration...
Registration-Token-Expiry: 1430747857
Context: 1B8D4AA7AD8F8D02

<threads-response>
  <threads>
    <thread>
      <id>19:[email protected]</id>
      <version>1430657437454</version>
      <capabilities>0</capabilities>
      <properties>
        <createdat>1430657183688</createdat>
        <creatorcid>0</creatorcid>
        <creator>8:live:user1</creator>
        <topic>This is our chat topic</topic>
      </properties>
      <options />
      <members>
        <member>
          <mri>8:live:user2</mri>
          <capabilities>2</capabilities>
          <role>admin</role>
        </member>
        <member>
          <mri>8:live:user1</mri>
          <capabilities>1</capabilities>
          <role>admin</role>
        </member>
        <member>
          <mri>8:live:user3</mri>
          <capabilities>1</capabilities>
          <role>user</role>
        </member>
         ...
      </members>
    </thread> 
    <thread>
      <id>19:[email protected]</id>
      ...
    </thread> 
  </threads>
  <errors />
</threads-response>

Error handling

If a given command fails, the sender receives a notification about the operation failed:

241 34 MSGR 696
UtcTime: 1430657395
Set-Registration: ...base64 registration...
Registration-Token-Expiry: 1430743535
Context: 1B8D4AA7AD8F8D02

<thread>
  <id>19:[email protected]</id>
  <errors>
    <error>
      <code>209</code>
      <details>operation denied</details>
      <mri>8:live:user2</mri>
    </error>
  </errors>
</thread>
Add a custom footer
Add a custom sidebar
Clone this wiki locally