In Prosody the session object is used to represent a user session, more specifically a connection, a stream pair, and anything else associated with them.

This page describes the properties and methods a session may have during its lifetime. Note that a session may not always have a particular method or property. It may be dependent on session type, or the state of that session. More specific details will be given where applicable.

All sessions


type stores the type of the session. A current list of defined types:

  • c2s - A client-to-server session
  • c2s_unauthed - A client-to-server session, which is not yet authenticated
  • s2s - A server-to-server session
  • s2s_unauthed - A server-to-server session, which has not yet been authenticated (via SASL/TLS/dialback or otherwise)
  • local - A local host, which the current server is serving
  • component - A component, local to this running server


conn is the underlying TCP connection for the session. It is rare you need to use this, though it is used to initiate TLS handshaking, etc.


The notopen flag is initially true on newly-created sessions, and is set to nil when the client sends an opening stream header. It is reset to true when the client needs to send a new stream header to continue (i.e. stream restarts after TLS, SASL negotiation).


Sends a stanza to the session. Note that while x may currently be a string, this may be deprecated in the future.


Closes the session, for the given reason, if any.

reason may be:

  • A string, in which case it is the name of one of the defined stream errors.
  • A table, which must have 2 fields; 'condition' (as the string above) and 'text', which will be additional text provided to the remote user.
  • A stanza, which will simply be sent before closing the stream, session, and connection.

nil or no reason will simply cleanly close and disconnect the session.


secure specifies whether the session's connection is currently protected by any form of encryption, SSL/TLS/etc..

Client-to-server sessions


username holds the username of the user, and only exists when the session is authenticated.


host contains the hostname of the server which the client connected to. Present from stream-opening onwards, although will change if the client authenticates to a new host afterwards.


resource has the resource for the connection, and is present from resource-binding onwards.


full_jid is the full, authenticated JID of the user. It is only present for connected resources (i.e. after resource-binding has been successful).


The client's IP address as a string in either IPv4 or IPv6 form. For BOSH sessions Prosody will attempt to use the client's real IP here if they are connecting through a trusted proxy (see the 'trusted_proxies' option).


priority records the priority last pushed via presence from this session.


presence is the last non-directed "available" presence stanza. Initially nil, and reset to nil on unavailable presence.


interested is true if the resource requested the roster. Interested resources receive roster updates.


roster is the user's Roster objects. Loaded as soon as the resource is bound (session becomes a connected resource).

Server-to-server sessions


direction is either 'incoming' or 'outgoing' depending on the direction of the stream.


to_host is the domain of the server that the stream is connected *to*. For incoming sessions, this will be a local host, for outgoing it will be a remote host.


from_host is the domain of the server that the stream is from. For incoming sessions, this will be a remote host, for outgoing it will be a local host.