# `im` — Instant Messaging Utilities and Services

This subpackage provides tools for Instant Messaging applications based on XMPP. The tools are meant to be useful for both user-facing as well as automated IM applications.

Warning

`aioxmpp.im` is highly experimental, even more than `aioxmpp` by itself is. This is not a threat, this is a chance. Please play with the API, try to build an application around it, and let us know how it feels! This is your chance to work with us on the API.

On the other hand, yes, there is a risk that we’ll restructure the API massively in the next release, even though it works quite well for our applications currently.

## Terminology

This is a short overview of the terminology. The full definitions can be found in the glossary and are linked.

Conversation
  Communication context for two or more parties.
Conversation Member
  An entity taking part in a Conversation.
Conversation Implementation
  A Service which provides means to create and manage specific `AbstractConversation` subclasses.
Service Member
  A Conversation Member which represents the service over which the conversation is run inside the conversation.

## `im.p2p` — One-on-one conversations

class `aioxmpp.im.p2p.``Service`(client, **kwargs)

  Manage one-to-one conversations.

  See also

  `AbstractConversationService`
    for useful common signals

  This service manages one-to-one conversations, including private conversations running in the framework of a multi-user chat. In those cases, the respective multi-user chat conversation service requests a conversation from this service to use.

  For each bare JID, there can either be a single conversation for the bare JID or zero or more conversations for full JIDs. Mixing conversations to bare and full JIDs of the same bare JID is not allowed, because it is ambiguous.

  This service creates conversations if it detects them as one-on-one conversations. Subscribe to `aioxmpp.im.ConversationService.on_conversation_added()` to be notified about new conversations being auto-created.

  `get_conversation`(peer_jid, *, current_jid=None)

    Get or create a new one-to-one conversation with a peer.

    Parameters:

    - peer_jid (`aioxmpp.JID`) – The JID of the peer to converse with.
    - current_jid (`aioxmpp.JID`) – The current JID to lock the conversation to (see RFC 6121).

    Return type: | `Conversation`
    Returns: | The new or existing conversation with the peer.

    peer_jid must be a full or bare JID. See the `Service` documentation for details.

    Changed in version 0.10: In 0.9, this was a coroutine. Sorry.

class `aioxmpp.im.p2p.``Conversation`(service, peer_jid, parent=None)

  Implementation of `AbstractConversation` for one-on-one conversations.

  See also

  `im.conversation.AbstractConversation`
    for documentation on the interface implemented by this class.

class `aioxmpp.im.p2p.``Member`(peer_jid, is_self)

  Member of a one-on-one conversation.

  `direct_jid`

    The JID of the peer.

## `aioxmpp.muc` — Multi-User-Chats (XEP-0045)

See also

`aioxmpp.muc`
  has a Conversation Implementation for MUCs.

## Core Services

class `aioxmpp.im.``ConversationService`(client, **kwargs)

  Central place where all `im.conversation.AbstractConversation` subclass instances are collected.

  It provides discoverability of all existing conversations (in no particular order) and signals on addition and removal of active conversations. This is useful for front ends to track conversations globally without needing to know about the specific conversation providers.

  signal `on_conversation_added`(conversation)

    A new conversation has been added.

    Parameters: | conversation (`AbstractConversation`) – The conversation which was added.

    This signal is fired when a new conversation is added by a Conversation Implementation.

    Note

    If you are looking for a “on_conversation_removed” event or similar, there is none. You should use the `AbstractConversation.on_exit()` event of the conversation.

  `on_message(conversation,`
  `*args, **kwargs)`

    Emits whenever any active conversation emits its `on_message()` event. The arguments are forwarded 1:1, with the `AbstractConversation` instance pre-pended to the argument list.

  `conversations`

    Return an iterable of conversations in which the local client is participating.

  `get_conversation`(conversation_address)

    Return the `im.AbstractConversation` for a given JID.

    Raises: | KeyError – if there is currently no matching conversation

  For Conversation Implementations, the following methods are intended; they should not be used by applications.

  `_add_conversation`(conversation)

    Add the conversation and fire the `on_conversation_added()` event.

    Parameters: | conversation (`AbstractConversation`) – The conversation object to add.

    The conversation is added to the internal list of conversations which can be queried at `conversations`. The `on_conversation_added()` event is fired.

    In addition, the `ConversationService` subscribes to the `on_exit()` event to remove the conversation from the list automatically. There is no need to remove a conversation from the list explicitly.

## Enumerations

class `aioxmpp.im.``ConversationState`

  State of a conversation.

  Note

  The members of this enumeration closely mirror the states of XEP-0085, with the addition of the internal `PENDING` state. The reason is that XEP-0085 is a Final Standard and is state-of-the-art for conversation states in XMPP.

  `PENDING`

    The conversation has been created, possibly automatically, and the application has not yet set the conversation state.

  `ACTIVE`

    > User accepts an initial content message, sends a content message, gives focus to the chat session interface (perhaps after being inactive), or is otherwise paying attention to the conversation.

    > —from XEP-0085

  `INACTIVE`

    > User has not interacted with the chat session interface for an intermediate period of time (e.g., 2 minutes).

    > —from XEP-0085

  `GONE`

    > User has not interacted with the chat session interface, system, or device for a relatively long period of time (e.g., 10 minutes).

    > —from XEP-0085

  `COMPOSING`

    > User is actively interacting with a message input interface specific to this chat session (e.g., by typing in the input area of a chat window).

    > —from XEP-0085

  `PAUSED`

    > User was composing but has not interacted with the message input interface for a short period of time (e.g., 30 seconds).

    > —from XEP-0085

  When any of the above states is entered, a notification is sent out to the participants of the conversation.

class `aioxmpp.im.``ConversationFeature`

  Represent individual features of a Conversation of a Conversation Implementation.

  See also

  The `AbstractConversation.features` provides a set of features offered by a specific Conversation.

  `BAN`

    Allows use of `ban()`.

  `BAN_WITH_KICK`

    Explicit support for setting the request_kick argument to `True` in `ban()`.

  `INVITE`

    Allows use of `invite()`.

  `INVITE_DIRECT`

    Explicit support for the `DIRECT` invite mode when calling `invite()`.

  `INVITE_DIRECT_CONFIGURE`

    Explicit support for configuring the conversation to allow the invitee to join when using `DIRECT` with `invite()`.

  `INVITE_MEDIATED`

    Explicit support for the `MEDIATED` invite mode when calling `invite()`.

  `INVITE_UPGRADE`

    Explicit support and requirement for allow_upgrade when calling `invite()`.

  `KICK`

    Allows use of `kick()`.

  `LEAVE`

    Allows use of `leave()`.

  `SEND_MESSAGE`

    Allows use of `send_message()`.

  `SEND_MESSAGE_TRACKED`

    Allows use of `send_message_tracked()`.

  `SET_NICK`

    Allows use of `set_nick()`.

  `SET_NICK_OF_OTHERS`

    Explicit support for changing the nickname of other members when calling `set_nick()`.

  `SET_TOPIC`

    Allows use of `set_topic()`.

class `aioxmpp.im.``InviteMode`

  Represent different possible modes for sending an invitation.

  `DIRECT`

    The invitation is sent directly to the invitee, without going through a service specific to the conversation.

  `MEDIATED`

    The invitation is sent indirectly through a service which is providing the conversation. Advantages of using this mode include most notably that the service can automatically add the invitee to the list of allowed participants in configurations where such restrictions exist (or deny the request if the inviter does not have the permissions to do so).

## Abstract base classes

### Conversations

class `aioxmpp.im.conversation.``AbstractConversation`(service, parent=None, **kwargs)

  Interface for a conversation.

  Note

  All signals may receive additional keyword arguments depending on the specific subclass implementing them. Handlers connected to the signals must support arbitrary keyword arguments.

  To support future extensions to the base specification, subclasses must prefix all keyword argument names with a common, short prefix which ends with an underscore. For example, a MUC implementation could use `muc_presence`.

  Future extensions to the base class will use either names without underscores or the `base_` prefix.

  Note

  In the same spirit, methods defined on subclasses should use the same prefix. However, the base class does not guarantee that it won’t use names with underscores in future extensions.

  To prevent collisions, subclasses should avoid the use of prefixes which are verbs in the english language.

  Signals:

  Note

  The member argument common to many signals is never `None` and alwyas an instance of a subclass of `AbstractConversationMember`. However, the member may not be part of the `members` of the conversation. For example, it may be the `service_member` object which is never part of `members`. Other cases where a non-member is passed as member may exist depending on the conversation subclass.

  signal `on_message`(msg, member, source, tracker=None, **kwargs)

    A message occured in the conversation.

    Parameters:

    - msg (`aioxmpp.Message`) – Message which was received.
    - member (`AbstractConversationMember`) – The member object of the sender.
    - source (`MessageSource`) – How the message was acquired
    - tracker (`aioxmpp.tracking.MessageTracker`) – A message tracker which tracks an outbound message.

    This signal is emitted on the following events:

    - A message was sent to the conversation and delivered directly to us. This is the classic case of “a message was received”. In this case, source is `STREAM` and member is the `AbstractConversationMember` of the originator.
    - A message was sent from this client. This is the classic case of “a message was sent”. In this case, source is `STREAM` and member refers to ourselves.
    - A carbon-copy of a message received by another resource of our account which belongs to this conversation was received. source is `CARBONS` and member is the `AbstractConversationMember` of the originator.
    - A carbon-copy of a message sent by another resource of our account was sent to this conversation. In this case, source is `CARBONS` and member refers to ourselves.

    Often, you don’t need to distinguish between carbon-copied and non-carbon-copied messages.

    All messages which are not handled otherwise (and for example dispatched as `on_state_changed()` signals) are dispatched to this event. This may include messages not understood and/or which carry no textual payload.

    tracker is set only for messages sent by the local member. If a message is sent from the client without tracking, tracker is `None`; otherwise, the tracker is always set, even for messages sent by other clients. It depends on the conversation implementation as well as timing in which state a tracker is at the time the event is emitted.

  signal `on_state_changed`(member, new_state, msg, **kwargs)

    The conversation state of a member has changed.

    Parameters:

    - member (`AbstractConversationMember`) – The member object of the member whose state changed.
    - new_state (`ConversationState`) – The new conversation state of the member.
    - msg (`aioxmpp.Message`) – The stanza which conveyed the state change.

    This signal also fires for state changes of the local occupant. The exact point at which this signal fires for the local occupant is determined by the implementation.

  signal `on_presence_changed`(member, resource, presence, **kwargs)

    The presence state of a member has changed.

    Parameters:

    - member (`AbstractConversationMember`) – The member object of the affected member.
    - resource (`str` or `None`) – The resource of the member which changed presence.
    - presence (`aioxmpp.Presence`) – The presence stanza

    If the presence stanza affects multiple resources, resource holds the affected resource and the event is emmited once per affected resource.

    However, the presence stanza affects only a single resource, resource is `None`; the affected resource can be extracted from the `from_` of the presence stanza in that case. This is to help implementations to know whether a bunch of resources was shot offline by a single presence (resource is not `None`), e.g. due to an error or whether a single resource went offline by itself. Implementations may want to only show the former case.

    Note

    In some implementations, unavailable presence implies that a participant leaves the room, in which case `on_leave()` is emitted instead.

  signal `on_nick_changed`(member, old_nick, new_nick, **kwargs)

    The nickname of a member has changed

    Parameters:

    - member (`AbstractConversationMember`) – The member object of the member whose nick has changed.
    - old_nick (`str` or `None`) – The old nickname of the member.
    - new_nick (`str`) – The new nickname of the member.

    The new nickname is already set in the member object, if the member object has an accessor for the nickname.

    In some cases, old_nick may be `None`. These cases include those where it is not trivial for the protocol to actually determine the old nickname or where no nickname was set before.

  signal `on_topic_changed`(member, new_topic, **kwargs)

    The topic of the conversation has changed.

    Parameters:

    - member (`AbstractConversationMember`) – The member object who changed the topic.
    - new_topic (`LanguageMap`) – The new topic of the conversation.

  signal `on_uid_changed`(member, old_uid, **kwargs)

    This rare signal notifies that the `uid` of a member has changed.

    Parameters:

    - member (`AbstractConversationMember`) – The member object for which the UID has changed.
    - old_uid (`bytes`) – The old UID of the member.

    The new uid is already available at the members `uid` attribute.

    This signal can only fire for multi-user conversations where the visibility of identifying information changes. In many cases, it will be irrelevant for the application, but for some use-cases it might be important to be able to re-write historical messages to use the new uid.

  signal `on_enter`()

    The conversation was entered.

    This event is emitted up to once for a `AbstractConversation`.

    One of `on_enter()` and `on_failure()` is emitted exactly once for each `AbstractConversation` instance.

    See also

    `aioxmpp.callbacks.first_signal()` can be used nicely to await the completion of entering a conversation:

        conv = ... # let this be your conversation
        await first_signal(conv.on_enter, conv.on_failure)
        # await first_signal() will either return None (success) or
        # raise the exception passed to :meth:`on_failure`.

    Note

    This and `on_failure()` are the only signals which must not receive keyword arguments, so that they continue to work with `AdHocSignal.AUTO_FUTURE` and `first_signal()`.

    New in version 0.10.

  signal `on_failure`(exc)

    The conversation could not be entered.

    Parameters: | exc (`Exception`) – The exception which caused the operation to fail.

    Often, exc will be a `aioxmpp.errors.XMPPError` indicating an error emitted from an involved server, such as permission problems, conflicts or non-existant peers.

    This signal can only be emitted instead of `on_enter()` and not after the room has been entered. If the conversation is terminated due to a remote cause at a later point, `on_exit()` is used.

    One of `on_enter()` and `on_failure()` is emitted exactly once for each `AbstractConversation` instance.

    Note

    This and `on_failure()` are the only signals which must not receive keyword arguments, so that they continue to work with `AdHocSignal.AUTO_FUTURE` and `first_signal()`.

    New in version 0.10.

  signal `on_join`(member, **kwargs)

    A new member has joined the conversation.

    Parameters: | member (`AbstractConversationMember`) – The member object of the new member.

    When this signal is called, the member is already included in the `members`.

  signal `on_leave`(member, **kwargs)

    A member has left the conversation.

    Parameters: | member (`AbstractConversationMember`) – The member object of the previous member.

    When this signal is called, the member has already been removed from the `members`.

  signal `on_exit`(**kwargs)

    The local user has left the conversation.

    When this signal fires, the conversation is defunct in the sense that it cannot be used to send messages anymore. A new conversation needs to be started.

  Properties:

  `features`

    A set of features supported by this Conversation.

    The members of the set are usually drawn from the `ConversationFeature` `enumeration`; Conversation Implementations are free to add custom elements from other enumerations to this set.

    Unless stated otherwise, the methods of `AbstractConversation` and its subclasses always may throw one of the following exceptions, unless support for those methods is explicitly stated with an appropriate `ConversationFeature` member in the `features`.

    - `NotImplementedError` if the Conversation Implementation does not support the method at all.
    - `RuntimeError` if the server does not support the method.
    - `aioxmpp.XMPPCancelError` with `feature-not-implemented` condition.

    If support for the method is claimed in `features`, these exceptions must not be raised (for the given reason; of course, a method may still raise an `aioxmpp.XMPPCancelError` due for other conditions such as `item-not-found`).

  `jid`

    The address of the conversation.

  `members`

    An iterable of members of this conversation.

  `me`

    The member representing the local member.

  `service_member`

    The member representing the service on which the conversation is hosted, if available.

    This is never included in `members`. It may be used as member argument in events to make it clear that the message originates from the service and not an unknown occupant.

    This may be `None`.

    New in version 0.10.

  Methods:

  Note

  See `features` for discovery of support for individual methods at a given conversation instance.

  coroutine `ban`(member, reason=None, *, request_kick=True)

    Ban a member from re-joining the conversation.

    Parameters:

    - member – The member to ban.
    - reason (`str`) – A reason to show to the members of the conversation including the banned member.
    - request_kick (`bool`) – A flag indicating that the member should be removed from the conversation immediately, too.

    If request_kick is true, the implementation attempts to kick the member from the conversation, too, if that does not happen automatically. There is no guarantee that the member is not removed from the conversation even if request_kick is false.

    Additional features:

    `BAN_WITH_KICK`
      If request_kick is true, the member is kicked from the conversation.

    See also

    The corresponding feature for this method is `ConversationFeature.BAN`. See `features` for details on the semantics of features.

  coroutine `invite`(address, text=None, *, mode=<InviteMode.DIRECT: 0>, allow_upgrade=False)

    Invite another entity to the conversation.

    Parameters:

    - address (`aioxmpp.JID`) – The address of the entity to invite.
    - text – A reason/accompanying text for the invitation.
    - mode (`InviteMode`) – The invitation mode to use.
    - allow_upgrade (`bool`) – Whether to allow creating a new conversation to satisfy the invitation.

    Raises:

    - NotImplementedError – if the requested mode is not supported
    - ValueError – if allow_upgrade is false, but a new conversation is required.

    Returns: | The stanza token for the invitation and the possibly new conversation object
    Return type: | tuple of `StanzaToken` and `AbstractConversation`

    Note

    Even though this is a coroutine, it returns a stanza token. The coroutine-ness may be needed to generate the invitation in the first place. Sending the actual invitation is done non-blockingly and the stanza token for that is returned. To wait until the invitation has been sent, unpack the stanza token from the result and await it.

    Return the new conversation object to use. In many cases, this will simply be the current conversation object, but in some cases (e.g. when someone is invited to a one-on-one conversation), a new conversation must be created and used.

    If allow_upgrade is false and a new conversation would be needed to invite an entity, `ValueError` is raised.

    Additional features:

    `INVITE_DIRECT`
      Support for `DIRECT` mode.
    `INVITE_DIRECT_CONFIGURE`
      If a direct invitation is used, the conversation will be configured to allow the invitee to join before the invitation is sent. This may fail with a `aioxmpp.errors.XMPPError`, in which case the error is re-raised and the invitation not sent.
    `INVITE_MEDIATED`
      Support for `MEDIATED` mode.
    `INVITE_UPGRADE`
      If allow_upgrade is `True`, an upgrade will be performed and a new conversation is returned. If allow_upgrade is `False`, the invite will fail.

    See also

    The corresponding feature for this method is `ConversationFeature.INVITE`. See `features` for details on the semantics of features.

  coroutine `kick`(member, reason=None)

    Kick a member from the conversation.

    Parameters:

    - member – The member to kick.
    - reason (`str`) – A reason to show to the members of the conversation including the kicked member.

    Raises: | aioxmpp.errors.XMPPError – if the server returned an error for the kick command.

    See also

    The corresponding feature is `ConversationFeature.KICK`. See `features` for details.

  coroutine `leave`()

    Leave the conversation.

    See also

    The corresponding feature is `ConversationFeature.LEAVE`. See `features` for details.

  `send_message`(body)

    Send a message to the conversation.

    Parameters: | msg (`aioxmpp.Message`) – The message to send.
    Returns: | The stanza token obtained from sending.
    Return type: | `StanzaToken`

    The default implementation simply calls `send_message_tracked()` and immediately cancels the tracking object, returning only the stanza token.

    There is no need to provide proper address attributes on msg. Implementations will override those attributes with the values appropriate for the conversation. Some implementations may allow the user to choose a `type_`, but others may simply stamp it over.

    Subclasses may override this method with a more specialised implementation. Subclasses which do not provide tracked message sending must override this method to provide untracked message sending.

    See also

    The corresponding feature is `ConversationFeature.SEND_MESSAGE`. See `features` for details.

  `send_message_tracked`(msg, *, timeout=None)

    Send a message to the conversation with tracking.

    Parameters:

    - msg (`aioxmpp.Message`) – The message to send.
    - timeout (`numbers.RealNumber`, `datetime.timedelta` or `None`) – Timeout for the tracking.

    Raises: | NotImplementedError – if tracking is not implemented
    Returns: | The stanza token obtained from sending and the `aioxmpp.tracking.MessageTracker` tracking the delivery.
    Return type: | `StanzaToken`, `MessageTracker`

    There is no need to provide proper address attributes on msg. Implementations will override those attributes with the values appropriate for the conversation. Some implementations may allow the user to choose a `type_`, but others may simply stamp it over.

    Tracking may not be supported by all implementations, and the degree of support varies with implementation. Please check the documentation of the respective subclass.

    timeout is the number of seconds (or a `datetime.timedelta` object which defines the timespan) after which the tracking expires and is closed if no response has been received in the mean time. If timeout is set to `None`, the tracking never expires.

    Warning

    Read General Remarks about Tracking and Memory Consumption.

    See also

    The corresponding feature is `ConversationFeature.SEND_MESSAGE_TRACKED`. See `features` for details.

  coroutine `set_nick`(new_nickname)

    Change our nickname.

    Parameters: | new_nickname (`str`) – The new nickname for the member.
    Raises: | ValueError – if the nickname is not a valid nickname

    Sends the request to change the nickname and waits for the request to be sent.

    There is no guarantee that the nickname change will actually be applied; listen to the `on_nick_changed()` event.

    Implementations may provide a different method which provides more feedback.

    See also

    The corresponding feature for this method is `ConversationFeature.SET_NICK`. See `features` for details on the semantics of features.

  coroutine `set_topic`(new_topic)

    Change the (possibly publicly) visible topic of the conversation.

    Parameters: | new_topic (`str`) – The new topic for the conversation.

    Sends the request to change the topic and waits for the request to be sent.

    There is no guarantee that the topic change will actually be applied; listen to the `on_topic_chagned()` event.

    Implementations may provide a different method which provides more feedback.

    See also

    The corresponding feature for this method is `ConversationFeature.SET_TOPIC`. See `features` for details on the semantics of features.

  Interface solely for subclasses:

  `_client`

    The client as passed to the constructor.

class `aioxmpp.im.conversation.``AbstractConversationMember`(conversation_jid, is_self)

  Represent a member in a `AbstractConversation`.

  While all implementations will have their own additional attributes, the following attributes must exist on all subclasses:

  `conversation_jid`

    The `JID` of the conversation member relative to the conversation.

  `direct_jid`

    If available, this is the `JID` address of the member for direct contact, outside of the conversation. It is independent of the conversation itself.

    If not available, this attribute reads as `None`.

  `is_self`

    True if the member refers to ourselves in the conversation, false otherwise.

  `uid`

    This is a unique ID for the occupant. It can be used across sessions and restarts to assert equality between occupants. It is guaranteed to be equal if and only if the entity is the same (up to a uncertainty caused by the limited length of the unique ID, somewhere in the order of `2**(-120)`).

    The identifier is always a `bytes` and must be treated as opaque by users. The only guarantee which is given is that its length will be less than 4096 bytes.

### Conversation Service

class `aioxmpp.im.conversation.``AbstractConversationService`

  Abstract base class for Conversation Services.

  Useful implementations:

  `aioxmpp.im.p2p.Service`(client, **kwargs) | Manage one-to-one conversations.
  `aioxmpp.muc.MUCClient`(client, **kwargs) | Conversation Implementation for Multi-User Chats (XEP-0045).

  In general, conversation services should provide a method (not a coroutine method) to start a conversation using the service. That method should return the fresh `AbstractConversation` object immediately and start possibly needed background tasks to actually initiate the conversation. The caller should use the `on_enter()` and `on_failure()` signals to be notified of the result of the join operation.

  Signals:

  signal `on_conversation_new`(conversation)

    Fires when a new conversation is created in the service.

    Parameters: | conversation (`AbstractConversation`) – The new conversation.

    See also

    `ConversationService.on_conversation_added()`
      is a signal shared among all Conversation Implementations which gets emitted whenever a new conversation is added. If you need all conversations, that is the signal to listen for.
  signal `on_spontaneous_conversation`(conversation)

    Like `on_conversation_new()`, but is only emitted for conversations which are created without local interaction.

    Parameters: | conversation (`AbstractConversation`) – The new conversation.

    New in version 0.10.