Expand information on presence update event about discord-api-docs

[jhgg]

Sure. PRs are always welcome. Documenting things is hard, and sometimes we don't explain everything 100%. I'll leave this issue open so we can clean up these sections when we get a chance.

[jhgg]

1. Presence is a pretty standard term in online chat apps. It refers to their status. (in the case of Discord, Online/Idle/Offline & their playing game)
2. When their presence is updated (and also whenever we feel like it) - the server may decide to send presences to the client to ensure it's in sync.
3. Presences and roles are per-guild, whereas the user object is global.
4. The user object can be partial. The only field that it must contain is the "id" - every other field is optional, and won't be sent if they aren't updated.

[gdude2002]

I'm still confused; are online/idle/offline and current game not global? Are you saying that this event may be fired when a user changes role?

[jhgg]

online/idle/offline and current game not global?

No. They are not. Each guild manages user presence individually. A user can be online in one guild but offline in another. Although this isn't exposed currently to regular users, our infra supports this. One example would be a bot that's using gateway sharding and is only connected to one shard. They'd only be online in a fraction of their total guilds.

[jhgg]

Are you saying that this event may be fired when a user changes role?

No. That will be fired as GUILD_MEMBER_UPDATE - the roles is just in there for the sake of ensuring that the client is in sync. Please see this section on eventual consistency https://discordapp.com/developers/docs/reference#consistency.

[gdude2002]

No. That will be fired as GUILD_MEMBER_UPDATE - the roles is just in there for the sake of ensuring that the client is in sync.

Alright, fair enough, I can always use it for that as well.

A user can be online in one guild but offline in another. One example would be a bot that's using gateway sharding and is only connected to one shard.

Is this something that will likely happen in the actual client in the future? Handling this in my bot for the sake of completeness might be something to do, but is that something that should really be happening with well-behaved clients?

[jhgg]

Is this something that will likely happen in the actual client in the future?

Yes it's on the road-map. Well-behaved clients may also be partially offline at times during a netsplit scenario. (The client would see an "unavailable guilds" message.) Additionally, your bot may have unavailable guilds from time to time too. This shouldn't be too often, and usually only happens when we're experiencing internal issues such as a netsplit between our nodes caused by internal networking issues.

[gdude2002]

Yeah, I'm already handling unavailable guilds at the moment. My system is really not designed for users with multiple online/offline/away statuses though, that's going to take some lateral thinking... I'll figure something out.

By the by, does this mean I'll receive a presence update for every guild my bot is in if a user shares multiple guilds with it?

[jhgg]

Ultimately, we may deliver the presence update event once, multiple times or not at all. For those purposes, if you want to fire an event when a presence updates, you should compare it to the previous presence update known by the bot, and only bubble up the event if something actually changes.

By the by, does this mean I'll receive a presence update for every guild my bot is in if a user shares multiple guilds with it?

Yes. The way our client structures this data is to have global user objects - and guild member objects per guild which hold the status.

[gdude2002]

Hmm.. Okay, thanks, I think I can work with that. It might be worth adding some of this to the presence update part of the docs, though, so you don't keep getting people with these questions :P