The Wayback Machine - https://web.archive.org/web/20130818191236/http://xmpp.org/extensions/xep-0327.html
`
`XEP-0327: Rayo
`
`Abstract:
`
`This specification defines an XMPP protocol extension for the third-party control of telephone calls and other similar media
`sessions. The protocol includes support for session management/signaling, as well as advanced media resources such as speech
`recognizers, speech synthesizers and audio/video recorders. The protocol serves a different purpose from that of first-party
`protocols such as Jingle or SIP, and is compatible with those protocols.
`Authors:
`Ben Langfeld, Jose de Castro
`Copyright:
`© 1999 - 2013 XMPP Standards Foundation. SEE LEGAL NOTICES.
`Status:
`Experimental
`Type:
`Standards Track
`Version:
`0.2
`Last Updated: 2013-06-10
`
`WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal
`by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but
`production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a
`status of Draft.
`
`Table of Contents
`
`
`
`1. Introduction
`
`2. How it works
`
`3. Requirements
`4. Terminology
`
`4.1. Glossary
`
`4.2. Conventions
`
`5. Concepts and Approach
`5.1. Actors
`
` 5.1.1. Server
`
` 5.1.2. Client(s)
` 5.1.3. Calls
`
` 5.1.4. Mixers
`
` 5.1.5. Commands
`
` 5.1.6. Components
`
` 5.2. Addressing Scheme
`
` 5.3. Delivery Mechanism
`6. Session Flow
`
`6.1. Client Registration
`
`6.2. Session Establishment
` 6.2.1. Outbound Call
` 6.2.1.1. Errors
`
` 6.2.1.2. Nested join
` 6.2.2. Inbound Call
` 6.3. Joining Calls
`
` 6.3.1. Errors
`
` 6.3.2. Unjoin Command
` 6.3.2.1. Errors
`
` 6.3.3. Unjoined Event
` 6.3.4. Multiple Joins
` 6.4. Mixers
`
` 6.5. Component Execution
` 6.5.1. Initial Errors
` 6.5.2. Command Errors
`
` 6.5.3. Output Component
`
` 6.5.3.1. Join considerations
` 6.5.3.2. Commands
` 6.5.3.3. Events
`
` 6.5.3.4. Completion
`
` 6.5.4. Input Component
`
` 6.5.4.1. Join considerations
` 6.5.4.2. Commands
` 6.5.4.3. Events
`
` 6.5.4.4. Completion
`
` 6.5.5. Prompt Component
`
` 6.5.5.1. Join considerations
` 6.5.5.2. Commands
` 6.5.5.3. Events
`
` 6.5.5.4. Completion
`
` 6.5.6. Record Component
`
` 6.5.6.1. Join considerations
` 6.5.6.2. Commands
` 6.5.6.3. Events
`
` 6.5.6.4. Completion
`
` 6.6. Session Termination
`
` 6.6.1. Call Redirection
`
` 6.6.2. Call Rejection
`
` 6.6.3. Call Hangup
`
` 6.6.4. Call End Notification
` 6.7. Headers
`
`7. Formal Definition
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 1 of 53
`
`

`

` 7.1. Header Element
` 7.2. Offer Element
`
` 7.3. Ringing Element
`
` 7.4. Answered Element
`
` 7.5. End Element
`
` 7.5.1. End Reason Element
`
` 7.6. Accept Element
`
` 7.7. Answer Element
`
` 7.8. Redirect Element
`
` 7.9. Reject Element
`
` 7.9.1. Reject Reason Element
`
` 7.10. Hangup Element
`
` 7.11. Dial Element
`
` 7.12. Join Element
`
` 7.13. Unjoin Element
`
` 7.14. Joined Element
`
` 7.15. Unjoined Element
`
` 7.16. Started Speaking Element
`
` 7.17. Stopped Speaking Element
`
` 7.18. Ref Element
`
` 7.19. Components
`
` 7.19.1. Stop Element
`
` 7.19.2. Complete Element
`
` 7.19.2.1. Complete Reason Element
`
` 7.19.3. Media Output
`
` 7.19.3.1. Output Element
`
` 7.19.3.2. Pause Element
`
` 7.19.3.3. Resume Element
`
` 7.19.3.4. SpeedUp Element
`
` 7.19.3.5. SpeedDown Element
`
` 7.19.3.6. VolumeUp Element
`
` 7.19.3.7. VolumeDown Element
`
` 7.19.3.8. Seek Element
`
` 7.19.3.9. Finish Element
` 7.19.3.10. MaxTime Element
`
` 7.19.4. Media Input
`
` 7.19.4.1. Input Element
`
` 7.19.4.2. Match
`
` 7.19.4.3. Noinput
`
` 7.19.4.4. Nomatch
`
` 7.19.5. Prompt
`
` 7.19.5.1. Prompt Element
`
` 7.19.6. Media Recording
`
` 7.19.6.1. Record Element
`
` 7.19.6.2. Pause Element
`
` 7.19.6.3. Resume Element
`
` 7.19.6.4. Recording Element
`
` 7.19.6.5. Max Duration Element
`
` 7.19.6.6. Initial Timeout Element
`
` 7.19.6.7. Final Timeout Element
`
`8. Use Cases
`
`9. Determining Support
`
`10. Extending Rayo
`
`11. Implementation Notes
`
`12. Security Considerations
`
` 12.1. Denial of Service
`
` 12.2. Communication Through Gateways
` 12.3. Information Exposure
`
`13. IANA Considerations
`
`14. XMPP Registrar Considerations
` 14.1. Protocol Namespaces
`
` 14.2. Namespace Versioning
`
` 14.3. Rayo Components Registry
`15. XML Schema
`
` 15.1. Rayo
` 15.2. Rayo Ext
`
` 15.3. Rayo Ext Complete
`
` 15.4. Rayo Output
`
` 15.5. Rayo Output Complete
`
` 15.6. Rayo Input
`
` 15.7. Rayo Input Complete
`
` 15.8. Rayo Prompt
`
` 15.9. Rayo Record
`
` 15.10. Rayo Record Complete
`16. History
`
`17. Acknowledgements
`
`
`
`
`
`
`
`
`
`Appendices
`
` A: Document Information
`
` B: Author Information
` C: Legal Notices
`
` D: Relation to XMPP
`
` E: Discussion Venue
`
` F: Requirements Conformance
`
` G: Notes
`
` H: Revision History
`
`
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 2 of 53
`
`

`

`1. Introduction
`
`Rayo is a protocol to allow third-party remote control over media sessions, audio/video mixers and a variety of advanced media resources such
`as speech recognizers, speech synthesizers and audio/video recorders. These capabilities can be combined to create a wide variety of
`applications such as menu-based phone systems, in-game conferencing and anonymous dating services. Unlike Jingle or even SIP, a Rayo client
`is not concerned with being a party to either the session negotiation or the media stream itself.
`
`A Rayo server takes on the role of negotiating a media session between itself and some other endpoint, or between two external
`endpoints, by way of an implementation-specific means, be that Jingle, SIP, the public-switched telephone network, or anything else. The
`server may even bridge multiple networks.
`The server then presents the Rayo protocol as an interface to a Rayo client, allowing it to monitor and/or exercise third-party control over
`the established media sessions.
`The client has the option to accept/reject/answer inbound session requests, request the creation of outbound sessions and monitor their
`progress, execute media operations such as speech synthesis, speech recognition & recording, and to end sessions.
`
`The relationship between the calling parties, the Rayo server and the Rayo client looks something like this:
`
` [caller] ----SIP---- [rayo server] ( -----Jingle---- [callee] ) optional
` |
` |
` rayo client
`
`
`This document defines the core Rayo protocol, and contains provisions for its extension by further specifications.
`2. How it works
`
`In order to understand the nature of a Rayo interaction, here we show a simple example of a control session.
`
`Example 1. New call announces itself to a potential controlling party
`
`<presence from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'>
` <c xmlns='http://jabber.org/protocol/caps'
` hash='sha-1'
` node='urn:xmpp:rayo:call:1'
` ver='QgayPKawpkPSDYmwT/WM94uAlu0='/>
` <offer xmlns='urn:xmpp:rayo:1'
` to='tel:+18003211212'
` from='tel:+13058881212'/>
`</presence>
`
`In this example, a call from 'tel:+13058881212' has reached the Rayo server 'shakespeare.lit' by calling 'tel:+18003211212', and been assigned
`an ID '9f00061'. The server has determined that 'juliet@capulet.lit' is a valid candidate to be the client to whom the server delegates control of
`the call, and so has directed an offer event to her 'balcony' resource.
`
`The client, 'juliet@capulet.lit', then decides that it is able to handle the incoming call, and so accepts it from the server, thus gaining exclusive
`control and indicating to the calling party that the call will be processed and that it should ring.
`
`Example 2. Potential controlling party attempts to become definitive controlling party by sending the call an accept command
`
`<iq from='juliet@capulet.lit/balcony'
` to='9f00061@call.shakespeare.lit'
` type='set'
` id='hd721'>
` <accept xmlns='urn:xmpp:rayo:1'/>
`</iq>
`
`Example 3. Call acknowledges accept command to the (now) definitive controlling party
`<iq from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='result'
` id='hd721'/>
`
`Following confirmation from the server that the attempt to gain control of the call was successful, the client proceeds to answer the call, opening
`up the media stream between the caller and the server.
`
`Example 4. Controlling party answers the call
`
`<iq from='juliet@capulet.lit/balcony'
` to='9f00061@call.shakespeare.lit'
` type='set'
` id='43jo3'>
` <answer xmlns='urn:xmpp:rayo:1'/>
`</iq>
`
`Example 5. Call acknowledges answer command to controlling party
`
`<iq from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='result'
` id='43jo3'/>
`
`Once the client has confirmation that the call has been answered, it triggers the start of a media output component in order to play a message
`to the caller using a Text-to-speech (TTS) engine.
`
`Example 6. Controlling party requests a new output component
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 3 of 53
`
`

`

`<iq from='juliet@capulet.lit/balcony'
` to='9f00061@call.shakespeare.lit'
` type='set'
` id='j9d3j'>
` <output xmlns='urn:xmpp:rayo:output:1'
` voice='allison'>
` <document content-type="text/plain">
` <![CDATA[
` You have no new messages. Goodbye!
` ]]>
` </document>
` </output>
`</iq>
`
`Example 7. Call acknowledges request for new output component and provides its ID
`
`<iq from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='result'
` id='j9d3j'>
` <ref xmlns='urn:xmpp:rayo:1' uri='xmpp:9f00061@call.shakespeare.lit/fgh4590'/>
`</iq>
`
`After confirmation that the output component was successfully created, the client then awaits notification of its completion.
`
`Example 8. Output component announces its completion, giving the reason
`
`<presence from='9f00061@call.shakespeare.lit/fgh4590'
` to='juliet@capulet.lit/balcony'
` type='unavailable'>
` <complete xmlns='urn:xmpp:rayo:ext:1'>
` <finish xmlns='urn:xmpp:rayo:output:complete:1' />
` </complete>
`</presence>
`
`The client then decides it has no further operations to perform on the call, and that the call should end. It instructs the server to hang up the call
`gracefully.
`
`Example 9. Controlling party hangs up the call
`
`<iq from='juliet@capulet.lit/balcony'
` to='9f00061@call.shakespeare.lit'
` type='set'
` id='f3wh8'>
` <hangup xmlns='urn:xmpp:rayo:1'/>
`</iq>
`
`Example 10. Call acknowledges hangup command to controlling party
`
`<iq from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='result'
` id='f3wh8'/>
`
`Example 11. Controlling party receives notification of the call being terminated
`
`<presence from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='unavailable'>
` <end xmlns='urn:xmpp:rayo:1'>
` <hangup-command/>
` </end>
`</presence>
`3. Requirements
`The protocol defined herein is designed to provide the following features:
`
`1. Call Control: Incoming calls are "offered" to clients at which point they can be answered, rejected, redirected to another destination, etc.
`Outbound calls may also be made and monitored. Every attempt is made to be shield the Rayo client from the low level telephony protocol
`(e.g. SIP, Jingle, PSTN, etc).
`2. Audio File Playback: A compatible Rayo server will fetch a file from a a specified URL and play the containing audio to the caller.
`3. Speech Synthesis / TTS: In cases where dynamic data must be spoken, a Speech Synthesis engine may be used to play computer
`generated speech to the caller.
`4. Touch-tone Events / DTMF: Rayo surfaces real-time event when the caller presses keys on their touch-tone keypad.
`5. Speech Recognition: Enables the phone application to take spoken queues allowing for sophisticated voice-driven menus and directory
`services.
`6. Call Recording: Can be used to capture the caller's voice (e.g. Voicemail) or both sides of the call for auditing and compliance purposes.
`7. Mixing: Typically referred to as an audio "conference"; calls can be joined together so that the participants can hear each other in real-
`time.
`
`Many third-party call control protocols have preceeded Rayo (see Asterisk's AGI/AMI, FreeSWITCH's eventsocket, Microsoft's TAPI, Java's JTAPI,
`Novell/AT&T's TSAPI, CSTA, etc). None of these protocols is ideal, and all have one or more of the following drawbacks:
`
`Totally ground-up wire protocol requiring implementation all the way down to the socket.
`Platform/vendor/hardware specific - each system implements its own proprietary protocol (in many cases, without a formal published
`specification) which does not allow easily porting an application from one back-end to another.
`Synchronous interface - Operations on calls or other entities are often blocking, and one must serialise all control messages.
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 4 of 53
`
`

`

`Inconsistent - evolved, rather than designed.
`Lacking in scalability - client/server sometimes tied one-to-one, servers rarely clustered, advanced message routing not possible.
`Poor security - lack of wire-level encryption, lack of or sub-standard authentication mechanisms, lack of or limited authorization
`mechanisms, lack of or poor sandboxing between multiple tenants on one system.
`Inextensible - The specification of extensions to the core protocol is either impossible or very difficult.
`
`Rayo has been designed with these failings in mind, and intends to address many concerns not addressed by these earlier attempts. The
`following considerations were made:
`
`Simple client library implementation - XMPP client libraries exist in all modern languages, and many are of a high standard of quality
`and maturity.
`Cross-platform standard - The protocol must not expose any platform specifics and all elements should be candidates for
`implementation on any suitable platform. Addiditionally, the protocol must be ratified as a standard following a community discussion.
`Asynchronous interface - The protocol should present an asynchronous interface for the purposes of performance and flexibility in
`performing parallel operations.
`Consistent - The protocol must provide a considered, unobtrusive, logically and philisophically consistent interface.
`Federated - The protocol must support communication between client and server entities on separately owned, operated and addressed
`networks.
`Flexible routing - The protocol must lend itself to routing across wide networks such as the internet, and to potential complex routing
`such as proxying or redirection. Additionally, the client and server should each be aware of the presence of the other and be able to use
`such information to make routing decisions.
`Extensible - The protocol must provide for the possibility of extra functionality being added by future specifications or an individual
`implementation.
`Secure - The protocol should include appropriate measures for authentication and authorization of participants, as well as preventing
`third-parties from intercepting control messages.
`
`Many of the features in the above list are available to Rayo at no specification or implementation cost, since they are core to XMPP itself and thus
`Rayo inherits these 'for free'.
`
`Additionally, the protocol is required to abstract away the complexity of the back-end negotiation, especially the details of the transport protocols
`such as SIP or Jingle, but to map conceptually to such protocols.
`4. Terminology
`4.1 Glossary
`
`Third-party call control (3PCC)
`The observation and/or control of a live media session by an entity which is not a direct party to the session.
`Command
`Commands instruct the receiving entity to perform some atomic action. Commands may be executed against a
`given call, component or mixer and can be considered completed as soon as they receive a response. Some
`commands create components, and return a reference to the component in their response.
`Component
`Components extend the Rayo protocol by providing additional media and call control functionality. Components
`are created by an appropriate command, which returns a reference to the component. Components are
`executed asynchronously, and have a lifecycle attached to them, with the ability to trigger events or have
`commands issued to it. Once a component is stopped or comes to an end naturally, it will issue a special
`<complete/> event, indicating that it has ceased executing and deliver any required data.
`Potential controlling party (PCP)
`An XMPP entity to which an offer to control an incoming call may be sent.
`Definitive controlling party (DCP)
`The XMPP entity which gains a lock on control of a session, either by requesting the session's creation, or being
`the first respondent to an offer.
`Security Zone
`A security zone is the conceptual border around a call which defines which parties may interact with the call's
`media or signaling. A security zone MUST contain the rayo server's internal implementation, the media server
`to which the call is joined, the DCP, and any JID whose bare form is the same as the DCP. A server MAY relax
`this definition further, for example to consider all JIDs at the same domain to be in the same security zone.
`4.2 Conventions
`
`In examples, the following JIDs are used:
`
`juliet@capulet.lit/balcony, romeo@montague.lit/orchard - Potential controlling parties
`shakespeare.lit - The root domain of the Rayo service
`5. Concepts and Approach
`
`A complete Rayo deployment has several elements and interacting entities which must be understood.
`5.1 Actors
`5.1.1 Server
`
`A Rayo server is an entity which is capable of receiving and initiating calls and being party to their media stream,
`while exposing a Rayo interface to a client in order to permit control over its calls. The Rayo server may handle calls
`in any way supported by the implementation, such as SIP, Jingle, etc, and should expose a full XMPP domain at the
`root level of the service deployment (eg shakespeare.lit).
`
`The Rayo server is responsible for keeping track of valid clients, routing calls to the correct potential controlling
`parties, performing authorization measures on received stanzas, etc.
`
`For the purposes of this specification, complex server-side deployments such as clusters, proxies, gateways, protocol
`translators, etc are not considered. Further details of such concepts may be found in their (present or future)
`relevant specifications.
`5.1.2 Client(s)
`
`A Rayo client is an entity which implements the Rayo protocol for the purpose of asserting control over calls made
`available by a Rayo server. The method by which such control measures are determined is outside the scope of this
`document, but may be the result of human interaction or some automated decision-making process.
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 5 of 53
`
`

`

`A Rayo client is responsible for indicating its availability to a Rayo server and responding to offer messages
`appropriately.
`5.1.3 Calls
`
`A Rayo call is a short-lived XMPP entity within the scope of the deployment's root domain, perhaps at a sub-domain,
`with the purpose of representing a single session. It is usually a simple alias for the main server process.
`
`A Rayo call is the entity with which most client interactions are made, and is responsible for sending its events to and
`receiving commands from a client. Calls may host components.
`
`Calls have separate presence from the root domain of the service and thus appear to be separate entities.
`5.1.4 Mixers
`
`A Rayo mixer is an XMPP entity within the scope of the deployment's root domain, perhaps at a sub-domain, with the
`purpose of representing a service for the linking of media streams from several calls. It is usually a simple alias for
`the main server process.
`
`A Rayo mixer is responsible for sending its events to and receiving commands from one or more clients, and can host
`components.
`
`Mixers have separate presence from the root domain of the service and its calls and thus appear to be separate
`entities.
`5.1.5 Commands
`
`A Rayo command is a simple combination of request and response and may be issued directly to the service domain,
`a call, a mixer or a component attached to any of the former. Commands are executed serially and are generally very
`short-lived.
`5.1.6 Components
`
`Components extend the Rayo protocol by providing additional media and call control functionality.
`
`Components have a lifecycle and are started by sending a specialized command to a call or mixer. Thus, a request for
`creation of a component will return a reference to the component's ID, and the component will continue to execute
`until it completes, potentially sending events and processing commands along the way (such as an instruction to
`pause or terminate), before finally issuing an event indicating its completion and thus unavailability. Multiple
`components may be active on a call or mixer at any one time, and commands may be executed on any entity during
`the execution of a component.
`5.2 Addressing Scheme
`
`All of the actors described in the previous section (with the exception of commands) are represented by XMPP entities with a JID
`of their own. Thus, a scheme for determining the JIDs of each of these entities is required. The following is the required naming
`scheme for Rayo deployments, where elements in square brackets are optional.
`
`Table 1:
`
`Actor
`Server
`Client
`Call
`Mixer
`Call
`Component
`Mixer
`Component
`Server
`Component
`
`JID format
`
`[service domain]
`any JID
`<call ID>@[<call sub-domain>.]<service domain>
`<mixer name>@[<mixer sub-domain>.]<service domain>
`<call ID>@[<call sub-domain>.]<service
`domain>/<component ID>
`<mixer name>@[<mixer sub-domain>.]<service
`domain>/<component ID>
`
`Example JID
`shakespeare.lit
`juliet@capulet.lit/balcony
`f88eh2@call.shakespeare.lit
`conf1@mixer.shakespeare.lit
`
`f88eh2@call.shakespeare.lit/8f83jf
`
`conf1@mixer.shakespeare.lit/932eu
`
`<service domain>/<component ID>
`
`shakespeare.lit/f3fg4
`
`Commands should be addressed to the entity on which they should be enacted. Individual commands only apply to certain object
`(for example instructing a component to hangup will return an error). In general, commands may be sent from a client to the
`service, a call, a mixer or a component. Events may be sent from a call, a mixer or a component to a client.
`5.3 Delivery Mechanism
`
`Rayo defines several events and commands which may be executed on one of the above actors. These payloads must be sent
`within an XMPP primitive element, and the rules are as such:
`
`Events: Sent as directed presence from the entity producing the event to a client.
`Commands: Sent as an <iq/> with the 'type' attribute 'set' from the client to the entity to be acted on. Responses returned
`as an <iq/> with the 'type' attribute either 'result' or 'error'.
`6. Session Flow
`This section describes the form, function and order of Rayo stanzas sent across the wire, and the circumstances in which they apply and/or may
`arise.
`
`6.1 Client Registration
`
`In order for a Rayo client to be considered a potential controlling party for incoming sessions, it MUST first notify the Rayo server
`that it is available for the receipt of calls. This is done by sending directed presence to the Rayo server with a <show/> element
`containing 'chat' as in the example:
`
`Example 12. Client presents itself as available to the Rayo server
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 6 of 53
`
`

`

`<presence from='juliet@capulet.lit/balcony'
` to='shakespeare.lit'>
` <c xmlns='http://jabber.org/protocol/caps'
` hash='sha-1'
` node='urn:xmpp:rayo:client:1'
` ver='QgayPKawpkPSDYmwT/WM94uAlu0='/>
` <show>chat</show>
`</presence>
`
`Conversely, when a Rayo client wishes not to be considered a potential controlling party, it SHOULD send directed presence to the
`Rayo server with a <show/> element containing 'dnd' as in the example:
`
`Example 13. Client presents itself as unavailable to the Rayo server
`
`<presence from='juliet@capulet.lit/balcony'
` to='shakespeare.lit'>
` <c xmlns='http://jabber.org/protocol/caps'
` hash='sha-1'
` node='urn:xmpp:rayo:client:1'
` ver='QgayPKawpkPSDYmwT/WM94uAlu0='/>
` <show>dnd</show>
`</presence>
`
`6.2 Session Establishment
`
`Sessions may be established either at the request of the Rayo client (an outbound call) or as a result of a 3rd party request (an
`inbound call). Each scenario differs in the Rayo protocol only up to the point at which the session is established and media begins
`to flow. First we shall examine the sequence of stanzas passed between server and client in each of these scenarios.
`6.2.1 Outbound Call
`
`In order for a client to establish a new outbound call, it MUST first send a dial command to the server, indicating the
`proposed target for the call, its apparent source, and any meta-data to send to the target as headers.
`
`Example 14. Client requests establishment of a new outbound session
`
`<iq from='juliet@capulet.lit/balcony'
` to='shakespeare.lit'
` type='set'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
`</iq>
`
`
`On successfully receiving and parsing the dial command, the server SHOULD perform its own proprietary
`authorization measures to ensure that only desirable outbound sessions are created. If it is established that the
`command should not be allowed, the server MUST return an error giving an authorization reason.
`6.2.1.1 Errors
`
`There are several reasons why the server might immediately return an error instead of acknowledging
`the creation of a new call:
`
`The client is unknown to the server and the server does not permit session creation by unknown
`clients.
`The client is not authorized to create this new session.
`The server does not support outbound calls.
`The server does not have sufficient resources to create a new session.
`The dial command was malformed.
`
`If the client is unknown to the server and the server does not permit session creation by unknown clients,
`the server MUST return a <registration-required/> error with a type of 'auth'.
`
`Example 15. Server indicates client is unknown and the server does not permit session
`creation by unknown clients
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='error'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
` <error type='auth'>
` <registration-required xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
` </error>
`</iq>
`
`
`If the client is not authorized (as determined by an implementation/deployment-specific algorithm) to
`create a new outbound session given the parameters provided, the server MUST return a <not-
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 7 of 53
`
`

`

`authorized/> error with a type of 'auth'.
`
`Example 16. Server indicates client is not authorized to create a new outbound session given
`the parameters provided
`
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='error'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
` <error type='auth'>
` <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
` </error>
`</iq>
`
`
`If the server does not support outbound calls, the server MUST return a <feature-not-implemented/>
`error with a type of 'cancel'.
`
`Example 17. Server indicates that it does not support outbound calls
`
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='error'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
` <error type='cancel'>
` <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
` </error>
`</iq>
`
`
`If the server does not have sufficient resources to create a new session, the server MUST return a
`<resource-constraint/> error with a type of 'wait'.
`
`Example 18. Server indicates that it does not have sufficient resources to create a new session
`
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='error'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
` <error type='wait'>
` <resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
` </error>
`</iq>
`
`
`If the dial command was malformed, the server MUST return a <bad-request/> error with a type of
`'modify'.
`
`Example 19. Server indicates the dial command was malformed
`
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='error'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='foo:bar'
` from='tel:+14152226789'>
` <header name="x-skill" value="agent" />
` <header name="x-customer-id" value="8877" />
` </dial>
` <error type='modify'>
` <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
` </error>
`</iq>
`
`
`If the command is successful and the call is queued, however, confirmation of such should be sent to the client,
`including a reference to the unique ID of the call. This call ID may be used to execute commands and filter events for
`the duration of the session.
`
`Ex. 1009
`CISCO SYSTEMS, INC. / Page 8 of 53
`
`

`

`Example 20. Confirmation of successful dial request and call ID
`
`<iq from='shakespeare.lit'
` to='juliet@capulet.lit/balcony'
` type='result'
` id='h7ed2'>
` <ref xmlns='urn:xmpp:rayo:1' uri='xmpp:9f00061@call.shakespeare.lit'/>
`</iq>
`
`
`Once the server receives notification that the session has been accepted by the third party, it should send a ringing
`event to the client to indicate such:
`
`Example 21. Call announces its ringing state (accepted by 3rd party but not yet answered).
`
`<presence from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'>
` <ringing xmlns='urn:xmpp:rayo:1'/>
`</presence>
`
`
`Similarly, once the server receives notification that the session has been answered, it should negotiate media
`between the dialed party and its local media server. Once media negotiation is complete, it should send an answered
`event to the client to indicate such:
`
`Example 22. Call announces its answered state (media connected).
`
`<presence from='9f00061@call.shakespeare.lit'
` to='juliet@capulet.lit/balcony'>
` <answered xmlns='urn:xmpp:rayo:1'/>
`</presence>
`
`
`6.2.1.2 Nested join
`
`When sending a dial request, a client MAY specify a join target within the dial element:
`
`Example 23. Client requests establishment of a new outbound session, with a nested join
`
`<iq from='juliet@capulet.lit/balcony'
` to='shakespeare.lit'
` type='set'
` id='h7ed2'>
` <dial xmlns='urn:xmpp:rayo:1'
` to='tel:+13055195825'
` from='tel:+14152226789'>
` <join call-uri='xmpp:e8u398d902i90@call.shakespeare.lit' />
` </dial>
`</iq>
`
`
`In this case, the server MUST treat the session creation in the same way as without the join element,
`until the point of media negotiation. Here, the server should negotiate media as specified by the join
`element, in accordance with the rules defined in joining calls. Media MUST NOT be negotiated with the
`local media server, unless the join specifies so. The join operation MUST behave as described in joining
`calls.
`6.2.2 Inbound Call
`
`When the system receives a call from one of its connected networks, it MUST then expose that requested session to
`Rayo clients. It SHOULD use an implementation-specific routing mechanism to map incoming calls to some set of
`registered JIDs which are considered appropriate controlling parties. From this set, it SHOULD then remove any
`parties whom it can identify as being temporarily inappropriate for control (either unavailable based on presence,
`under too much load, or any other metric which the server has available). If, as a result, the set of Potentially
`Controlling Parties is empty, the server MUST reject the call wit