Updates and Fixes to User & Site Streams

We've been doing some work to fix behavior on User & Site Streams to better conform to the documentation and to developer expectations. As some of the changes may potentially break your applications, we're rolling out in two phases: Phase 1 will include only the addition of new messages, and Phase 2 will include the removal of erroneous messages and those replaced by Phase 1's new messages.

Phase 1 is targeted to roll out over April 8-9, and Phase 2 is targeted to roll out over April 29-30.

Here's what you can expect:

• On User Streams, when the user on behalf of whom the connection was established revokes their access token
  • NO CHANGE: an access_revoked message will be sent

    {
        "target": <ID of user performing revocation>,
        "source": <ID of user performing revocation>,
        "event": "access_revoked",
        "target_object": "client_application",
        "created_at": "Mon Mar 14 09:47:02 +0000 2014"
    }
     

  • NEW (Phase 1): a disconnect message will be sent

    {
        "disconnect":{
            "code": 6,
            "stream_name": "<connection identifier>",
            "reason": "Token revoked"
        }
    }
     

  • NO CHANGE: the connection will be terminated
• On Site Streams, when a user on a connection revokes their access token
  • NO CHANGE: an access_revoked message will be sent on the connection from which the user is to be removed, and that user will be removed from the stream

    {
        "target": <ID of user performing revocation>,
        "source": <ID of user performing revocation>,
        "event": "access_revoked",
        "target_object": "client_application",
        "created_at": "Mon Mar 14 09:47:02 +0000 2014"
    }
     

  • NO CHANGE: if the user was the last/only user on a connection, a disconnect message will be sent on that connection and the connection will be terminated

    {
        "disconnect":{
            "code": 6,
            "stream_name": "<connection identifier>",
            "reason": "Token revoked"
        }
    }
     

  • NEW (Phase 2): if the user was NOT the last/only user on the connection, then NO disconnect message will be sent (and, as is presently the case, the connection will not be terminated)
• On Site Streams, when a user on a connection unrevokes their access token
  • NO CHANGE: that user will NOT be automatically re-added to any connection for the app
  • NEW (Phase 1): an access_unrevoked message will be sent and will be sent on every connection for the app, if there are any open at the time of unrevocation

    {
        "target": <ID of user performing unrevocation>,
        "source": <ID of user performing unrevocation>,
        "event": "access_unrevoked",
        "target_object": "client_application",
        "created_at": "Mon Mar 14 09:47:02 +0000 2014"
    }
     

• On User & Site Streams, when a user on a connection deletes their Twitter account or is suspended
  • NEW (Phase 1): a user_delete or user_suspend message (respectively) will be sent on the connection from which the user is to be removed

    {
        "target": <ID of deleted user>,
        "source": <ID of deleted user>,
        "event": "user_delete",
        "target_object": "client_application",
        "created_at": "Mon Mar 14 09:47:02 +0000 2014"
    }
     

    {
        "target": <ID of suspended user>,
        "source": <ID of suspended user>,
        "event": "user_suspend",
        "target_object": "client_application",
        "created_at": "Mon Mar 14 09:47:02 +0000 2014"
    }
     

  • NO CHANGE: the user will be removed from the stream
  • NEW (Phase 1): on User Streams or if the user is the last/only user on a Site Streams connection, a disconnect message will be sent on the connection (and, as is presently the case, the connection will be terminated)

    {
        "disconnect":{
            "code": 13,
            "stream_name": "<connection identifier>",
            "reason": "User deleted"
        }
    }
     

    {
        "disconnect":{
            "code": 14,
            "stream_name": "<connection identifier>",
            "reason": "User suspended"
        }
    }
     

• Note that there is no change for a user undeleting their account or being unsuspended: no messages are streamed in these cases, and no users are automatically re-added to any existing connections.
• On Site Streams, when a user that is part of a connection is added to the same connection
  • NEW (Phase 1): the connection will receive a user_reconnected message
    

    {
        "target": <ID of disconnected user>,
        "source": <ID of disconnected user>, 
        "event": "user_reconnected",
        "target_object": "client_application",
        "created_at": "Sat Sep 4 16:10:54 +0000 2010"
    }
     

  • NEW (Phase 2): the connection will NOT receive a disconnect message (with code 2, "Duplicate stream")
• Note that there is no change for a user that is part of one connection being added to another connection for the same authorizing app: both connections will stream on behalf of the user, and no message will be sent to indicate the redundancy.
• On Site Streams, when the connection is being shut down for any reason
  • NEW (Phase 2): the disconnect message sent will not include the username of any of the users on the connection

    Current (old) behavior example:

    {
        "disconnect":{
            "code": 1,
            "stream_name": "AppUsername-sitestream1234567890123456789-FirstUsername",
            "reason": "Shutdown"
        }
    }
     

    New behavior example:

    {
        "disconnect":{
            "code": 1,
            "stream_name": "AppUsername-sitestream1234567890123456789",
            "reason": "Shutdown"
        }
    }