<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2011 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <<linkurl='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
<p>This document defines a specification for real-time text transmitted in-band over an XMPP session.</p>
<p>Real-time text is text that is sent as it is created. The recipient can watch the sender type "as written words are typed" – similar to a telephone conversation where one listens to a conversation "as words are spoken". It provides a sense of contact in conversation, eliminates waiting times found in messaging, and is also favored by the deaf who prefer text conversation. For a visual animation of real-time text, see <spanclass="ref"><strong><linkurl="http://www.realjabber.org">RealJabber.org</link></strong></span>
<note>RealJabber.org is the author's web site containing work related to this specification, including animation examples of what real time text looks like. <<linkurl="http://www.realjabber.org">http://www.realjabber.org</link>>.</note>.</p>
<p>Real-time text has been around for decades in various implementations:</p>
<ul>
<li>The 'talk' command on UNIX systems since the 1970's.</li>
<li>ICQ had a split screen mode from 1996-1999 before this feature was removed.</li>
<li>In 2008, AOL AIM 6.8 gained the <spanclass="ref"><strong><linkurl="http://help.aol.com/help/microsites/microsite.do?cmd=displayKC&externalId=223568">AOL Real-Time IM</link></strong></span><note>AOL AIM Real Time Text: <<linkurl="http://help.aol.com/help/microsites/microsite.do?cmd=displayKC&externalId=223568">http://help.aol.com/help/microsites/microsite.do?cmd=displayKC&externalId=223568</link>>.</note> feature.</li>
<li>Hobby BBS chat programs from the 1990's.</li>
<li>TDD, TTY and text telephones for the deaf.</li>
<li>In SIP calls, real-time text is sent using an <spanclass="ref"><strong><linkurl="http://tools.ietf.org/html/rfc4103">IETF RFC 4103</link></strong></span><note>IETF RFC 4103: RTP Payload for Text Conversation. <<linkurl="http://tools.ietf.org/html/rfc4103">http://tools.ietf.org/html/rfc4103</link>>.</note> transport, with <spanclass="ref"><strong><linkurl="http://www.itu.int/rec/T-REC-T.140">ITU-T T.140</link></strong></span><note>ITU-T T.140: Protocol for multimedia application text conversation. <<linkurl="http://www.itu.int/rec/T-REC-T.140">http://www.itu.int/rec/T-REC-T.140</link>>.</note> presentation coding.</li>
<li>Allow transmission of real-time text with a low latency.</li>
<li>Support real-time message editing, including text insertions, deletions and cursor movements.</li>
<li>Support transmission of the original intervals between key presses, to preserve look-and-feel of typing independently of transmission intervals.</li>
<p><strong>edit action</strong>– A text modification of any kind, including text insertion or deletion. This may be as small as a single key press.</p>
<p><strong>presentation action</strong>– A presentation behavior such as the movement of a visible cursor, a pause, or a flash.</p>
</section1>
<section1topic="Protocol"anchor="protocol">
<section2topic="RTT Element"anchor="rtt_element">
<p>Real-time text is transmitted via an <rtt> child element of a <message> stanza. The <rtt> element is transmitted at regular intervals by the sender while a chat message is being composed, to allow the recipient to watch the sender type (and edit) the message before the full message is sent.</p>
<p>This is a basic example of a <em><strong>real-time message</strong></em> "Hello, my Juliet!", transmitted in three real-time text fragments, followed by a final message delivery:</p>
<p>The <rtt> element contains a series of one or more child elements representing <em><strong>real-time actions</strong></em> including <em><strong>edit actions</strong></em> and/or <em><strong>presentation actions</strong></em>. Example 1 illustrates only a single edit action, the <t><em><strong>action element</strong></em>, which simply adds text to the end of a message. For more information about action elements, see <linkurl="#realtime_actions">Real-Time Actions</link>.</p>
<p>If the recipient client does not support this real-time text standard, the sender SHOULD NOT transmit the <rtt> element. For more information, see <linkurl="#determining_support">Determining Support</link>.</p>
<p>This REQUIRED attribute indicates the sequence number, and MUST begin at 0 in the first <rtt> element sent at the start of a <em><strong>real-time chat session</strong></em>. This attribute MUST increment by 1 for every <rtt> element sent until the end of the session. This value may be used by the receiver to detect lost <message> elements, which affects the integrity of real-time text. For more information, see <linkurl="#error_recovery_of_realtime_text">Error Recovery of Real-Time Text</link>.</p>
<p>This attribute signals session events for real-time messages, such as the start of a new real-time message. The <strong>event</strong> attribute is omitted from the <rtt> element, when it is not needed.</p>
The sender MUST use this value on the first <rtt> element of a new real-time message. The recipient MUST initialize a blank real-time message for display, before processing the <rtt> payload, if any is provided.</p></li>
<li><p><strong>event='reset'</strong><br/>
The sender MAY use this value to retransmit a real-time message. The recipient MUST clear the existing real-time message, before processing the <rtt> payload. One use case is for error recovery. Another use case is where the recipient logs off and on, all while the sender is still composing a message. This allows the recipient re-display the real-time message.</p></li>
The sender MAY use this value to indicate the end of a real-time session. The recipient SHOULD clear or close the current real-time message, if any is still displayed. An example case is closing a chat window before a message is delivered. The <rtt> payload MUST be empty, with no real-time actions.</p></li>
<p>Only one <rtt> element is allowed per <message>. Therefore, to transmit multiple events, use multiple consecutive <message>'s.</p>
<p>To turn a real-time message into a permanent delivered message, the sender MUST transmit the whole message as a standard <body> child element within the <message> stanza.</p>
<p>The <body> element continues to follow the &xmppcore; standard. This keeps backwards compatibility with XMPP clients that do not support this specification. Such clients will continue to behave normally, displaying complete lines of messages as they are delivered.</p>
<p>Upon receipt of <body>, the recipient MUST replace the real-time message with the final delivered message from <body>. The message is thus becomes permanent and can not be edited any further.</p>
<p>In the ideal case, the message in a <body> is redundant since it simply repeats the entire contents of the real-time message. In the event that there are lost <messages>, the delivery of the <body> permits <linkurl="#error_recovery_of_realtime_text">Error Recovery of Real-Time Text</link>.</p>
<p>After sending a completed message as a <body>, the sender may begin a real-time message, using the <strong>event='new'</strong> attribute.</p>
<p>For the best balance between interoperability and usability, the interval of transmission of <rtt> for a continuously-changing real-time message SHOULD be once every <strong>1 second</strong>. If there has been no changes to the real-time message, no transmission should take place.</p>
<p>A much shorter interval may more frequently trigger the flooding protection algorithms in XMPP servers, leading to dropped <message> elements and/or <linkurl="#congestion_considerations">Congestion Considerations</link>. A longer interval will lead to a less optimal user experience. One second is a balance that meets the requirements of real-time text. This interval is mentioned in other real-time text standards, including section 5.4 of IETF RFC 4103 and section 5.2.2 of <spanclass="ref"><strong><linkurl="http://tools.ietf.org/html/rfc5194">IETF RFC 5194</link></strong></span><note>IETF RFC 5194: Framework for Real-Time Text over IP Using the Session Initiation Protocol (SIP). <<linkurl="http://tools.ietf.org/html/rfc5194">http://tools.ietf.org/html/rfc5194</link>>.</note>, used for SIP.</p>
<p>To smooth the output of text, this specification supports transmission of the sender's original <linkurl="#key_press_intervals">Key Press Intervals</link>. This allows the recipient software to display the sender's typing at the original speed, regardless of the transmission interval.</p>
<p>The <rtt> element is used to transmit a series of one or more real-time actions, including edit actions and presentation actions.</p>
<p>Most chat clients allow a sender to edit their message before sending (i.e. via a Send button, or hitting Enter). The inclusion of real-time functionality to existing chat client software must not degrade the sender's existing expectation of being able to edit their messages before sending. Thus, in a real-time chat session, the recipient can watch the sender compose and edit their message before it is delivered.</p>
<p>Edit actions include typing of text, backspacing, and blocks of text being inserted or deleted. In addition, a real-time chat session may also include presentation actions, including:</p>
<ul>
<li>Key press intervals, to smooth the flow of real-time text independently of the transmission interval;</li>
<li>Cursor movements, to make it easier for the recipient to watch edits being made by the sender;</li>
<li>Visual flash (beep) to allow the sender to catch the attention of the recipient.</li>
<p>Each real-time action is represented by an <em><strong>action element</strong></em><em>.</em> Examples can be found in <linkurl="#use_cases">Use Cases</link>.</p>
<td>RECOMMENDED. Execute a pause of <em><strong>n</strong></em> thousandths of a second.</td>
</tr>
<tr>
<td>Cursor Position</td>
<td><c p='#'/></td>
<td>OPTIONAL. Move cursor to position <em><strong>p</strong></em> in message.</td>
</tr>
<tr>
<td>Flash</td>
<td><g/></td>
<td>OPTIONAL. Execute a visual flash, beep, or buzz.</td>
</tr>
</table>
</section4>
<section4topic="Rules for Attribute Values"anchor="rules_for_attribute_values">
<ul>
<li>The <em><strong>n</strong></em> and <em><strong>p</strong></em> attributes are unsigned 32-bit integers, represented as a string.</li>
<li>If the <em><strong>n</strong></em> attribute is omitted, the default value for <em><strong>n</strong></em> is 1.</li>
<li>If the <em><strong>p</strong></em> attribute is omitted, the default value for <em><strong>p</strong></em> is the length of the current real-time message.</li>
<li>A <em><strong>p</strong></em> value of 0 represents the start of the message.</li>
<p>For interoperability of <em><strong>p</strong></em> and <em><strong>n</strong></em> values, processing MUST be done on the original Unicode real-time message. For both senders and receivers, this is the version of the Unicode message text without Unicode normalization, emoticon graphics images, display text formatting, processing of Unicode combining marks, etc. For recipients obtaining text from the <t> element, this is the Unicode text immediately after XML processing, and before any further processing. From the perspective of <em><strong>p</strong></em> and <em><strong>n</strong></em> values, a real-time message is treated as an editable array of Unicode code points.</p>
<p>Regardless of the original format of line breaks during XMPP transmission, line breaks are treated as a single code unit (LINE FEED U+000A) for the purposes of real-time message processing. Conversion of line breaks into a single U+000A character is REQUIRED for XML processors, according to section 2.11 of <spanclass="ref"><strong><linkurl="http://www.w3.org/TR/xml/">XML</link></strong></span><note>XML: Extensible Markup Language 1.0 (Fifth Edition). <<linkurl="http://www.w3.org/TR/xml/">http://www.w3.org/TR/xml/</link>>.</note>, so a compliant XML processor already do this automatically, and already provide the correct original Unicode text for interoperability.</p>
<p><strong>NOTE WELL</strong>: Extreme care MUST be taken to correctly calculate n and p values based on Unicode code points, to avoid corruption of the real-time message during real-time editing. For more information, see <linkurl="#internationalization_considerations">Internationalization Considerations</link>.</p>
<p>(Tier 1) REQUIRED. Supports the transmission of key presses, text block inserts, and text being pasted.<br/>
<em>Note:</em><em>Any text permitted in the <body> element of a <message> may be used, subject to the rules in XMPP Core. More examples can be found in <linkurl="#use_cases">Use Cases</link>.</em></p>
<p>(Tier 1) REQUIRED. Supports the behavior of Backspace key presses.<br/>
<em>Note: Direction 'left' represents the numeric direction. Thus, for right-to-left text (i.e. Arabic), numeric 'left' represents visible 'right'.</em></p>
<p>(Tier 1) REQUIRED. Supports the behavior of Delete key presses, text block deletes, and text being cut.<br/>
<em>Note: Direction 'right' represents the numeric direction. Thus, for right-to-left text (i.e. Arabic), numeric 'right' represents visible 'left'.</em></p>
<p>(Tier 2) RECOMMENDED. Allows the transmission of the original intervals between real-time actions, including the pauses between key presses. For more information, see <linkurl="#key_press_intervals">Key Press Intervals</link>.</p>
<p>Executes a pause of <em><strong>n</strong></em> thousandths of a second. The <em><strong>n</strong></em> value SHOULD NOT exceed the <linkurl="#transmission_interval">Transmission Interval</link>. Also, if a <linkurl="#body_element">Body Element</link> arrives, pauses SHOULD be interrupted to prevent message delivery delay.</p>
<p>(Tier 2) OPTIONAL. Allows the transmission of cursor positions. This allows the recipient to see the sender's cursor in their real-time message, and makes it easier to track the sender's message edits. For more information, see <linkurl="#remote_cursor">Remote Cursor</link>.</p>
<p><code><![CDATA[<c p='#'/>]]></code></p>
<p>Moves cursor (caret) to the character position <em><strong>p</strong></em> in message.</p>
<p>(Tier 2) OPTIONAL. Allows a flash/beep/buzz feature. This feature is the real-time version of &xep0224;, and MAY execute the same alerting method.<br/>
<em>Note: This supports real-time text interoperability with similar features in text telephones for the deaf (TTY / TDD), ITU-T T.140 implementations, and Control-G beep at consoles.</em></p>
<li>Recipients MUST process supported action elements in the same order as received within the <rtt> element. Unrecognized action elements MUST be ignored.</li>
<li>Real-time actions work only within the boundaries of the current real-time message, and MUST NOT affect previous messages.</li>
<li>Values for <em><strong>p</strong></em> and <em><strong>n</strong></em> attributes MUST be calculated according to <linkurl="#rules_for_attribute_values">Rules for Attribute Values</link>.</li>
<section2topic="Error Recovery of Real-Time Text"anchor="error_recovery_of_realtime_text">
<p>In a real-time chat session, it is critical that the real-time message is identical on both the sender and recipient ends. The loss of a single <rtt> transmission can represent missing text, or a missing edit. This leads to the real-time message getting out of sync, the message becoming different on the sender versus the recipient ends.</p>
<p>Transmissions of <message> elements may be lost for several reasons. One reason is that a recipient may disconnect and reconnect while a sender is still typing a message. Another reason is some XMPP servers may drop <message> elements automatically (i.e. flooding protection).</p>
<p>The sync is considered lost if the <strong>seq</strong> attribute of the <rtt> element does not increment as expected. Trying to process certain real-time edit actions after loss of sync, will result in scrambled text. Therefore, to avoid this situation:</p>
<li>The recipient MUST stop processing all subsequent real-time action elements, and freeze the current real-time message.</li>
<li>An indicator (i.e. reception bars, color code, missing text indicator) or a chat state message (i.e. “Typing Frozen...”) MAY be used by the recipient to indicate the loss of sync.</li>
<li>A message <body> is delivered. The frozen real-time message MUST be replaced with this delivered message.</li>
<li>The <strong>event</strong> attribute of <rtt> has a value of <strong>new</strong> or <strong>reset</strong>. Processing of real-time text MUST resume, with the new correct <strong>seq</strong> value obtained from this <rtt> element.</li>
<section3topic="Helping The Recipient Stay In Sync"anchor="helping_the_recipient_stay_in_sync">
<p>The sender MAY help the recipient stay in sync by automatically retransmitting the real-time message whenever the recipient status changes from offline to online. The entire contents of the real-time message, may be retransmitted using the <rtt> attribute <strong>event='reset'</strong> with a single Insert Text action.</p>
<p><code><