xeps/xep-0482.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
        <!ENTITY % ents SYSTEM 'xep.ent'>
        %ents;
        ]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
  <header>
    <title>Call Invites</title>
    <abstract>
      This document defines how to invite someone to a call and how to respond to the invite.
    </abstract>
    &LEGALNOTICE;
    <number>0482</number>
    <status>Experimental</status>
    <type>Standards Track</type>
    <sig>Standards</sig>
    <dependencies/>
    <supersedes/>
    <supersededby/>
    <shortname>call-invites</shortname>
    <author>
      <firstname>Natalie</firstname>
      <surname>Wirth</surname>
      <email>nataliew@laposte.net</email>
    </author>
    <author>
      <firstname>Marvin</firstname>
      <surname>Wissfeld</surname>
      <email>xsf@larma.de</email>
      <jid>jabber@larma.de</jid>
    </author>
    <revision>
      <version>0.1.0</version>
      <date>2023-05-04</date>
      <initials>XEP Editor: ks</initials>
      <remark>
        <p>Promoting to Experimental.</p>
      </remark>
    </revision>
    <revision>
      <version>0.0.1</version>
      <date>2022-01-01</date>
      <initials>nw/mw</initials>
      <remark>
        <p>First draft.</p>
      </remark>
    </revision>
  </header>

  <section1 topic='Introduction' anchor='intro'>
    <p>
      A call can take place between two or more parties and can be initiated and conducted via various protocols. This
      specification defines a way to invite someone to a call providing one or more ways in which to join.
    </p>
    <p>
      &xep0353; provides partially overlapping functionality. It allows to initiate any kind of Jingle session, for
      example calls but also file transfers. However, it is not suitable for inviting someone to any kind of call, since
      a call can also be established through other means than a simple Jingle session-initiate.
    </p>
    <p>
      This specification defines a way to invite someone to a call. The call can for example be initiated via &xep0167;
      or via an external URI. It also allows to define multiple ways to join the same call. Furthermore, it defines how
      to retract, accept and reject the call invite and how to indicate that a client left the call.
    </p>
  </section1>

  <section1 topic='Use Cases' anchor='usecases'>

    <section2 topic='Proposing a call'>
      <p>
        To invite someone to a call, a message containing an &lt;invite&gt; element in the urn:xmpp:call-invites:0
        namespace is sent. The element has an optional 'video' attribute that indicates if the call is intended to be
        joined with participants sending video ("true") or not ("false", default). An 'audio' attribute is defined
        analogously, defaulting to "true". The &lt;invite&gt; element contains one sub-element for each way to join the
        call.
      </p>
      <p>
        In order to invite someone to a &xep0167; call, a &lt;jingle&gt; element is placed in the &lt;invite&gt;
        element. The &lt;jingle&gt; element has a 'sid' attribute specifying the ID of the Jingle session. It can
        optionally also contain a 'jid' element, to indicate the JID the Jingle session will be initiated from. If no
        'jid' element is provided, the default is the sender of the message stanza.
      </p>
      <example caption="Invite to a Jingle video call"><![CDATA[
<message to='mara@example.com' id='id1' type='chat'>
  <invite video='true' xmlns='urn:xmpp:call-invites:0'>
    <jingle sid='sid1'/>
  </invite>
</message>]]></example>

      <p>
        External ways to join the call can be specified via an &lt;external&gt; element placed in the &lt;invite&gt;
        element with an 'uri' attribute that contains a URI. The URI can for example contain a URL to a browser
        webclient or a dial-in telephone number.
      </p>

      <example caption="Invite to a mixer groupcall with webclient and dial-in fallback"><![CDATA[
<message to='mara@example.com' id='id2' type='chat'>
  <invite xmlns='urn:xmpp:call-invites:0'>
    <jingle sid='sid2' jid='mixer@example.com/uuid' />
    <external uri='https://example.com/uuid' />
    <external uri='tel:+12345678' />
  </invite>
</message>]]></example>

      <p>
        Specifications that describe further ways to join a call define their own sub-elements to the &lt;invite&gt;
        element containing all necessary information for joining.
      </p>
    </section2>

    <section2 topic='Retracting a call'>
      <p>
        A call invite can be retracted by sending a message containing a &lt;retract&gt; element with an 'id' attribute
        containing the id of the invite message qualified by the urn:xmpp:call-invites:0 namespace.
      </p>
      <example caption="Retracting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
  <retract id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
    </section2>

    <section2 topic='Accepting a call'>
      <p>
        A call invite can be accepted by sending a message containing an &lt;accept&gt; element with an 'id' attribute
        containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
      </p>
      <p>
        The element describing the connection method used by the accepting client (e.g. &lt;jingle&gt; or &lt;external&gt;)
        including all of its attributes and children is placed in the &lt;accept&gt; element.
      </p>
      <example caption="Accepting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
  <accept id='id1' xmlns='urn:xmpp:call-invites:0'>
    <jingle sid='sid1' jid='mixer@example.com/uuid' />
  </accept>
</message>]]></example>
      <p>
        After the &lt;accept&gt; was sent, the initiating or accepting client continues to establish the call depending
        on the selected connection method: If an &lt;external&gt; method was selected, the accepting client handles the
        URI. The exact behaviour of opening the URI is implementation specific. If a &lt;jingle&gt; method was selected,
        the initiating client triggers a Jingle session-initiate from the JID and with the session ID specified in the
        'jid' and 'sid' attributes of the &lt;jingle&gt; element, respectively.
      </p>
    </section2>

    <section2 topic='Rejecting a call'>
      <p>
        A call invite can be rejected by sending a message containing a &lt;reject&gt; element with an 'id' attribute
        containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
      </p>
      <example caption="Rejecting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
  <reject id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
    </section2>

    <section2 topic='Leaving a call'>
      <p>
        When a client leaves a call, it sends a message containing a &lt;left&gt; element with an 'id' attribute
        containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
      </p>
      <example caption="Leaving a call"><![CDATA[
<message to='mara@example.com' type='chat'>
  <left id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
    </section2>

  </section1>
  <section1 topic='Business Rules' anchor='rules'>
    <p>
      Clients must ensure that they will receive the accept or reject responses of other resources by the same user (if
      any) when implementing this specification. This can be achieved by implementing &xep0280;.
    </p>
    <section2 topic='Using the correct ID' anchor='business-id'>
      <p>
        For messages of type 'groupchat', the stanza's 'id' attribute MUST NOT be used for call retracts, accepts,
        rejects or lefts. Instead, in group chat situations, the ID assigned to the stanza by the group chat itself must
        be used. This is discovered in a &lt;stanza-id&gt; element with a 'by' attribute that matches the bare JID of
        the group chat, as defined in &xep0359;.
      </p>
      <p>
        This implies that invite messages should only be sent in group chats that attach a &xep0359; stanza-id.
      </p>
      <p>
        For other message types the sender should use the 'id' from a &xep0359;
        &lt;origin-id&gt; if present, or the value of the 'id' attribute on the
        &lt;message&gt; otherwise.
      </p>
    </section2>
  </section1>

  <section1 topic="Security Considerations" anchor="security">
    <p>
      None.
    </p>
  </section1>

  <section1 topic='IANA Considerations' anchor='iana'>
    <p>This document requires no interaction with &IANA;.</p>
  </section1>

  <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
    <p>This document requires no interaction with &REGISTRAR;.</p>
  </section1>

</xep>