<abstract>This document defines an XMPP protocol extension that enables a user to communicate with a representative of an organization, department, or workgroup.</abstract>
<remark><p>Editorial revision; defined XML schema.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2005-02-28</date>
<initials>mt/is</initials>
<remark><p>General re-organization, refined agent status protocol, removed queue-notification element from join request replies, user status pushes now use a message instead of IQ.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2004-08-10</date>
<initials>mt/is</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<section2topic='Overview'anchor='intro-over'>
<p>The protocol defined herein enables users to contact a representative of an organization or workgroup without knowing the address of a particular member of that organization or workgroup. This functionality is similar to an 'email alias' with the addition of queuing pending communication requests and quality of service negotiation to accommodate the real-time nature of IM/chat. Although this protocol is generic enough to handle many use cases, specific features have been added that make it particularly suitable for customer support environments.</p>
</section2>
<section2topic='Motivation'anchor='intro-motive'>
<p>This protocol addresses the need of starting a private XMPP conversation with a qualified member of a workgroup. In a standard XMPP exchange of messages, users either connect directly to another user for a one on one conversation, or connect to a chat room for a conversation between many people. The current protocols do not allow users to initiate a private conversation with any person playing a particular role in an organization or workgroup.</p>
<p>For example, a customer has a question and needs to talk to a support representative. The conversation is private and therefore cannot be conducted in a well-known chat room. Using the workgroup protocol, the user requests a chat with support@workgroup.example.com. The chat request is put into a queue and the server routes the chat request to individual support representatives in the support@workgroup.example.com workgroup. The support representative can accept or reject the chat request. Once the request is accepted, the conversation takes place through standard XMPP messaging protocols.</p>
</section2>
<section2topic='Concepts'anchor='intro-concepts'>
<p>The namespace governing this protocol is "http://jabber.org/protocol/workgroup". This namespace relies on the &IQ; element for execution, and uses the &PRESENCE; element for announcing status updates.</p>
<p>This protocol depends on &xep0030; for reporting and announcing available workgroup services. However, support for service discovery is entirely optional and workgroup services may be made known through other means (e.g. web pages or word of mouth .</p>
<p>The end result of a workgroup interaction is to negotiate and route a user and workgroup member (a.k.a. agent) to an appropriate chat room for a chat conversation using the multi-user chat (MUC) protocol. However, multi-user chat essentially 'takes over' when the workgroup protocol successfully completes so there is no overlap between the two protocols. It is RECOMMENDED that groupchat implementations support basic groupchat (a.k.a. Groupchat 1.0) for maximum client compatibility.</p>
<p>There are no requirements for supporting the workgroup protocol beyond &xmppcore; and &xep0045;. Support for &xep0004; is optional if users need to submit additional data before joining (see User Join section of this document).</p>
<section1topic='Roles and Responsibilities'anchor='roleresp'>
<p>This protocol has clearly defined roles and responsibilities for its participants.</p>
<section2topic='Roles'anchor='roles'>
<p>The workgroup protocol involves three distinct participants that fill the following roles:</p>
<ul>
<li><strong>User</strong> - The user requests a private conversation with a member of a workgroup.</li>
<li><strong>Service</strong> - The workgroup service receives and sends messages using the workgroup address. The workgroup address represents a general contact address which allows users to find workgroup members to talk to without the need to know any particular workgroup member's individual address. The workgroup service manages the interactions between users and agents.</li>
<li><strong>Agent</strong> - The agent is a member of the workgroup and can carry out conversations with users on behalf of their workgroup organization or company.</li>
</ul>
<p>In the examples shown throughout this document, the user address <user@example.net/home>, the service address is <support@workgroup.example.com>, and the agent addresses are <alice@example.com/work> and <bob@example.com/work>.</p>
<p>Note: A service MAY contain several queues to help organize, route and handle incoming user chat requests. Implementations supporting multiple queues in a workgroup will respond differently to requests, and send different status information for each queue. Workgroup queues are identified by a unique resource name: e.g. support@workgroup.example.com/platinum-plan or support@workgroup.example.com/xmpp-products. Implementations should gracefully handle services with only one queue (using support@workgroup.example.com) or multiple queues. Users should only be aware of one workgroup (users should never see workgroup queue resource names).</p>
<p>Each participant is responsible for certain behaviors in the workgroup protocol.</p>
<p>Users should:</p>
<ul>
<li>Know the status of the workgroup queue before requesting a conversation. This information allows users to see if the workgroup is available, and how long a wait they may have before a chat is initiated.</li>
<li>Know the status of their request while in the request queue.</li>
<li>Be able to cancel a chat request at any time.</li>
</ul>
<p>Workgroup agents should:</p>
<ul>
<li>Know the status of the workgroup queue(s).</li>
<li>Be able to accept or reject chat requests.</li>
<li>Indicate their availability for handling workgroup chats.</li>
</ul>
<p>The workgroup service:</p>
<ul>
<li>Controls the workgroup request queue(s).</li>
<li>Manages the updating of queue status information.</li>
<li>Determines how users are queued and how queue requests are routed to workgroup
members. The queue routing algorithm is beyond the scope of this document and left to
<p>Users join the workgroup queue to wait for a chat with an agent. Once they have joined the queue, they may receive zero or more status updates from the workgroup service informing them of their status in the queue. Users have the option to cancel their chat request at any time.</p>
<p>When an agent is ready to chat with the user, the user MUST be sent a standard XMPP groupchat invitation to a chat room. Receipt of the invitation indicates that the user is no longer in the queue and that they should join the chat room using the standard XMPP groupchat protocol in order to converse with an agent. Groupchat is used because it offers several advantages in workgroup conversations including:</p>
<ul>
<li>Allowing more than one agent to join the conversation (useful for bringing in experts to join the conversation).</li>
<li>Allowing managers to monitor conversations for quality of service.</li>
<li>Creating a simple way of determining what is in a 'conversation' for logging and gathering other statistical information about the conversation.</li>
<li>Allowing a convenient mechanism for bringing 'chatbot' services into the conversation (e.g. answering FAQs).</li>
</ul>
<p>The user's states and packet exchanges that cause state transitions are shown below:</p>
<p>This section describes the packet exchange allowing users to join a workgroup service queue. This protocol MUST be supported by compliant implementations.</p>
<p>The request may contain application-specific metadata to help the service determine queuing of the user or Data Forms data when submitting form information (definition of such data is out of scope for this document). In addition, the <join-queue> element MAY contain a standard <queue-notifications/> element, which indicates that the user would like to receive user status updates about their state in the queue.</p>
<p>If the user indicated interest in their queue status information, the supported status updates MUST be sent by the server. Compliant implementations do not have to support any status update types. Status updates requested by the user and supported by the server MUST be pushed to the user by the service until the user departs or is invited to a chat room.</p>
<td>The user is not authorized to join the queue. A determination of who has permission to join a queue is left to implementations.</td>
</tr>
<tr>
<td>&e404;</td>
<td>The address the user requests a chat with does not exist or is not a workgroup. Compliant workgroup service implementations MUST NOT return this error if the requested address is a valid workgroup.</td>
</tr>
<tr>
<td>&e406;</td>
<td>The user must submit valid form data before joining the queue. Note that this error is sent when the user tries to join, or if the user submits form data that is not filled out correctly.</td>
</tr>
<tr>
<td>&e409;</td>
<td>The user has already joined the queue.</td>
</tr>
<tr>
<td>&e503;</td>
<td>The workgroup is valid but not accepting new join-queue requests.</td>
<p>The following XML is another example where metadata is sent by the user to assist the workgroup server in queuing and routing (naturally, the custom namespace that qualifies the <crm/> element in this example would be defined outside the context of this specification).</p>
<p>Finally an example of a required form submission before a user is allowed to the workgroup queue for support@workgroup.example.com. The data form in this example is trivial; please see <cite>XEP-0004</cite> for a complete data form example. The example begins as normal, but the workgroup returns a &e406; error.</p>
<p>After presenting the form to the user and gathering the form data, the user submits the form data to the workgroup and the workgroup accepts it. The user is now in the queue.</p>
<p>This section describes the packet exchange allowing users to depart a workgroup service queue, or for a workgroup service to remove a user from the workgroup queue. This protocol MUST be supported by compliant implementations.</p>
<p>The user no longer wishes to be in the queue and issues a depart queue command.</p>
<p>In the typical case, the sender is the user departing the queue. However, it is possible for other users (system administrators for example) to request that another user be removed from the queue. In this case, the jid of the user who is departing is included in the depart request:</p>
<examplecaption='Depart Request With JID'><