Active-Calls Component

From OnSIP Developer Wiki
Jump to: navigation, search

Contents

Overview

The Active-Calls component is responsible for all third party call control (3PCC) requests for the XMPP API. Each command node of the Active Calls component performs a specific 3PCC function, see below for more information.

JID

commands.active-calls.xmpp.onsip.com

Command Nodes


create

The create commands provides a way to implement third party call setup between any two SIP addresses.

Authorization Requirements

none

Input Fields

from 
a text-single field containing the SIP URI from which to initiate a call
to 
a text-single field containing the SIP URI of the call recipient
call-setup-id 
OPTIONAL - an 8 character alphanumeric that will be passed through end to end identifying the legs of the call-setup. If a call-setup-id is not provided in the request one will be created and returned in the response.

Note: the from and to values are SIP URIs, they must be in the format sip:<user>@<domain>.

Single Stage Execution

To automate the process you will simply want to send a request prepopulated with X-Data form to initiate a call between two SIP addresses. The response returned from the server will alert you of the success or error condition.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" 
    from="alice@example.com" id="create-1" >
  <command xmlns="http://jabber.org/protocol/commands" node="create" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="from" >
        <value>sip:foo@example.onsip.com</value>
      </field>
      <field type="text-single" var="to" >
        <value>sip:bar@example.onsip.com</value>
      </field>
      <field type="text-single" var="call-setup-id" >
        <value>AbCd1234</value>
      </field>
    </x>
  </command>
</iq>

Multi-stage Execution

Multi-stage execution is meant for user interaction. The request allows you to present your user with a form to fill out that is then sent to the commands.active-calls.xmpp.onsip.com component as a response to the form request.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="create-2a" >
  <command xmlns="http://jabber.org/protocol/commands" node="create" />
</iq>

X-Data Response Form from commands.active-calls.xmpp.onsip.com

<iq from="commands.active-calls.xmpp.onsip.com" type="result" 
    to="alice@example.com" id="create-2a" >
  <command xmlns="http://jabber.org/protocol/commands" status="executing" 
           node="create" sessionid="9d17366d64a57a82614e7083fe00398a" >
    <actions execute="execute" >
      <cancel/>
      <execute/>
    </actions>
    <x xmlns="jabber:x:data" type="form" >
      <title>Create Call</title>
      <instructions>Enter the SIP addresses of the caller and callee</instructions>
      <field type="text-single" label="From" var="from" >
        <required/>
      </field>
      <field type="text-single" label="To" var="to" >
        <required/>
      </field>
      <field type="text-single" label="Call Setup ID" var="call-setup-id" />
    </x>
  </command>
</iq>

X-Data Form Submission to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="create-2b" >
  <command xmlns="http://jabber.org/protocol/commands" node="create" 
           sessionid="9d17366d64a57a82614e7083fe00398a" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="from" >
        <value>sip:foo@example.onsip.com</value>
      </field>
      <field type="text-single" var="to" >
        <value>sip:bar@example.onsip.com</value>
      </field>
      <field type="text-single" var="call-setup-id" >
        <value>aBcD4321</value>
      </field>
    </x>
  </command>
</iq>

Execute From Psi

Once you have your X-Lite configured and registered with our proxy beta SIP server you can go back to Psi and fill out the call create form.

  1. Open the Psi XML console for your jabber account so you can see the XML communication
  2. Open the service browser and enter commands.active-calls.xmpp.onsip.com into the address input.
  3. Double click Create Call
    1. in the from field enter your SIP address
    2. in the to field enter any other SIP address

This should create an incoming call to your X-Lite softphone from our call setup server. Upon answering the call you will be transfered to the SIP address you entered in the to field

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

Successful execution a create command indicates a call has been setup between the call setup server and the the SIP address provided as the from input.

Response Fields
call-setup-id 
The call setup ID allows an XMPP entity to associate a call setup request to incoming active call notifications. The call setup ID will also be present in the active call event XML for any call leg that is the result of a call create command. This is NOT the SIP call ID.
Successful Response
<iq from="commands.active-calls.xmpp.onsip.com" 
    type="result" 
    to="alice@example.com" id="create-2b" >
  <command xmlns="http://jabber.org/protocol/commands" 
           status="completed" 
           node="create" 
           sessionid="b7720992672820eeec1b898c5f54057d">
    <x xmlns="jabber:x:data" type="result" >
      <field type="fixed" var="call-setup-id" >
        <value>cqjOO99m</value>
      </field>
    </x>
  </command>
</iq>

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response
<iq from="commands.active-calls.xmpp.onsip.com" type="error" xml:lang="en" 
    to="alice@example.com" id="create-3" >
  <command xmlns="http://jabber.org/protocol/commands" node="create" 
           sessionid="9d17366d64a57a82614e7083fe00398a" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="from" >
        <value>sip:foo@example.onsip.com</value>
      </field>
      <field type="text-single" var="to" >
        <value>sip:bar@example.onsip.com</value>
      </field>
    </x>
  </command>
  <error type="modify" code="400" >
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      Execution Errors; Failed to create call: 'Bad Request: NO_ROUTE_DESTINATION'; missing response
    </text>
    <bad-payload xmlns="http://jabber.org/protocol/commands"/>
  </error>
</iq>

Additional Information

Calling the PSTN

If you would like to setup the call to a phone number on the PSTN be sure to enter the number in the to field as <11 digit number>@<your_onsip_domain>, e.g. 15555554567@example.onsip.com

XMPP/SIP Communication

The following diagram depicts the SIP user agents involved in the execution of a call setup request from bob@foo.com to alice@bar.com.

 ---------------       ------------------------                 -------                      ---------
 | XMPP Client |       | JN Call-Setup Server |                 | Bob |                      | Alice |
 ---------------       ------------------------                 -------                      ---------
  |                        (XMPP) | (SIP)                          |                              |
  | - XMPP Call Create Request -> |                                |                              |
  |                               |                                |                              |
 [1] <- XMPP Call Create Response | ----------- INVITE ----------> |                              |
  | <---- Active Call Event ----  |                                |                              |
  |       Publish (requested)     | <-- 1XX Response(s)/200 OK --- |                              |
  |                               |                                |                              |
  |                               | ------------ ACK ------------> |                              |
  |                               |                                |                              |
  |                               | ------ REFER (to Alice) -----> |                              |
  |                               |                                |                              |
  |                               | <------ 202 Accepted --------- |                              |
  |                               |                                |                              |
  |                               | <- NOTIFY Requests/Responses-> |                              |
  |                               |                                |                              |
  |                               | ------------ BYE ------------> |                              |
  | <---- Active Call Event ----  |                                |                              |
  |           Retract             | <---------- 200 OK ----------- |                              |
  |                               |                                |                              |
  |                               |                                | ---------- INVITE ---------> |
  | <---- Active Call Event ----  |                                |                              |
  |      Publish (created)        |                                | <- 1XX Response(s)/200 OK -- |
  |                               |                                |                              |
  |                               |                                |------------ ACK -----------> |
  |                               |                                |                              |
 ...                             ...                              ...                            ...
  |                               |                                |                              |

The above diagram highlights the summarizes a succesful call setup after a create request is issued.

[1] There is a race condition in the call creation process that all XMPP clients will see. Due to the nature of the call setup process we have implemented and the flow of packets through two different protocols (SIP/XMPP) the XMPP client may receive the requested active-call message event OR the call create response first. This is where the call-setup-id is useful, it allows the client to identify all legs of a call setup end to end.

As you can see from the diagram, a successful response from the create ad-hoc command does NOT indicate a successful call creation between the from and to addresses. A successful create response only indicates the request has been received and the call setup server is trying to create the call. All other indications of call setup success should be taken from Active-Calls Pubsub.


terminate

The terminate commands will tear down an active call.

Authorization Requirements

none

Input Fields

call-id 
the call-id of the call from an Active-Calls Pubsub item
from-tag 
the from-tag of the call from an Active-Calls Pubsub item
to-tag 
the to-tag of the call from an Active-Calls Pubsub item

Single Stage Execution

For implementing automated solutions you will want to send a single stage request populated with the X-Data form as follows.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="terminate-1" >
  <command xmlns="http://jabber.org/protocol/commands" node="terminate" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>a-valid-callid</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>a-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>a-to-tag</value>
      </field>
    </x>
  </command>
</iq>

Multi-stage Execution

Multi-stage execution is meant for user interaction. The request allows you to present your user with a form to fill out that is then sent to the commands.active-calls.xmpp.onsip.com component as a response to the form request.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="terminate-2a" >
  <command xmlns="http://jabber.org/protocol/commands" node="terminate" />
</iq>

X-Data Response Form from commands.active-calls.xmpp.onsip.com

<iq from="commands.active-calls.xmpp.onsip.com" type="result"
    to="alice@example.com" id="terminate-2a" >
  <command xmlns="http://jabber.org/protocol/commands" status="executing"
           node="terminate" sessionid="c24df0dfb26a6d2ab037eed3c7a77c0d" >
    <actions execute="execute" >
      <cancel/>
      <execute/>
    </actions>
    <x xmlns="jabber:x:data" type="form" >
      <title>Terminating a Call</title>
      <instructions>Fill out this from to terminate a call.</instructions>
      <field type="text-single" label="Call-ID" var="call-id" >
        <required/>
      </field>
      <field type="text-single" label="From Tag" var="from-tag" >
        <required/>
      </field>
      <field type="text-single" label="To Tag" var="to-tag" >
        <required/>
      </field>
    </x>
  </command>
</iq>

X-Data Form Submission to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="terminate-2b" >
  <command xmlns="http://jabber.org/protocol/commands"
           node="terminate" sessionid="c24df0dfb26a6d2ab037eed3c7a77c0d" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>a-valid-callid</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>a-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>a-to-tag</value>
      </field>
    </x>
  </command>
</iq>

Execute From Psi

Once you have your X-Lite configured and registered with our proxy SIP server you can go back to Psi and fill out the call terminate form.

  1. Open the Psi XML console for your jabber account so you can see the XML communication
  2. Open the service browser and enter commands.active-calls.xmpp.onsip.com into the address input.
  3. Double click Terminate Call and enter the following information:
    1. call-id
    2. from-tag
    3. to-tag

This should destroy the active call described by the the parameters.

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

Successful execution of a terminate command indicates an active call matching the call-id, from-tag, and to-tag has been found and an attempt is being made to tear the call down. A successful response from the command does not guarantee the call will be destroyed. Confirmation of the end of a call can be achieved through a subscription to one of the Active-Calls Pubsub nodes.

Response Fields

N/A

Successful Response
<iq from="commands.active-calls.xmpp.onsip.com" type="result"
    to="alice@example.com" id="terminate-2b" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed"
           node="terminate" sessionid="c24df0dfb26a6d2ab037eed3c7a77c0d" />
</iq>

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response
<iq from="commands.active-calls.xmpp.onsip.com" type="error" xml:lang="en"
    to="alice@example.com" id="terminate-3" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed"
           node="terminate" sessionid="0a9b61a5870ae91a76044ea634061517" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>an-invalid-callid</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>a-bad-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>a-bad-to-tag</value>
      </field>
    </x>
    <note type="error" >Execution Errors; terminate call failed</note>
  </command>
  <error type="modify" code="400" >
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">Execution Errors; terminate call failed</text>
    <bad-payload xmlns="http://jabber.org/protocol/commands"/>
  </error>
</iq>

Additional Information

N/A


transfer

The transfer command will transfer either the caller or the callee of an active call to another SIP UA

Authorization Requirements

none

Input Fields

call-id 
the call-id of the call from an Active-Calls Pubsub item
from-tag 
the from-tag of the call from an Active-Calls Pubsub item
to-tag 
the to-tag of the call from an Active-Calls Pubsub item
endpoint 
either caller or callee. Sending caller will transfer the endpoint that initiated the original call to the target-uri and the callee will be hung up on. Sending callee will transfer the receiver of the initial call and hang up on the caller.
target-uri 
the SIP URI to transfer the endpoint to

Single Stage Execution

For implementing automated solutions you will want to send a single stage request prepopulated with the X-Data for as follows.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="transfer-1" >
  <command xmlns="http://jabber.org/protocol/commands" node="transfer" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>a-valid-call-id</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>the-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>the-to-tag</value>
      </field>
      <field type="list-single" var="endpoint" >
        <value>caller</value>
      </field>
      <field type="text-single" var="target-uri" >
        <value>sip:bob@example.com</value>
      </field>
    </x>
  </command>
</iq>

Multi-stage Execution

Multi-stage execution is meant for user interaction. The request allows you to present your user with a form to fill out that is then sent to the commands.active-calls.xmpp.onsip.com component as a response to the form request.

Request to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="transfer-2a" >
  <command xmlns="http://jabber.org/protocol/commands" node="transfer" />
</iq>

X-Data Response Form from commands.active-calls.xmpp.onsip.com

<iq from="commands.active-calls.xmpp.onsip.com" type="result"
    to="alice@example.com" id="transfer-2a" >
  <command xmlns="http://jabber.org/protocol/commands" status="executing"
           node="transfer" sessionid="6bcc4d9767bfe46783eace22837c2e8b" >
    <actions execute="execute" >
      <cancel/>
      <execute/>
    </actions>
    <x xmlns="jabber:x:data" type="form" >
      <title>Transfer a Call</title>
      <instructions>Fill out this from to transfer a live call.</instructions>
      <field type="text-single" label="Call-ID" var="call-id" >
        <required/>
      </field>
      <field type="text-single" label="From Tag" var="from-tag" >
        <required/>
      </field>
      <field type="text-single" label="To Tag" var="to-tag" >
        <required/>
      </field>
      <field type="list-single" label="Endpoint" var="endpoint" >
        <option label="Callee" >
          <value>callee</value>
        </option>
        <option label="Caller" >
          <value>caller</value>
        </option>
        <required/>
      </field>
      <field type="text-single" label="Target SIP URI" var="target-uri" >
        <required/>
      </field>
    </x>
  </command>
</iq>

X-Data Form Submission to commands.active-calls.xmpp.onsip.com

<iq type="set" to="commands.active-calls.xmpp.onsip.com" id="transfer-2b" >
  <command xmlns="http://jabber.org/protocol/commands"
           node="transfer" sessionid="6bcc4d9767bfe46783eace22837c2e8b" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>a-valid-call-id</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>the-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>the-to-tag</value>
      </field>
      <field type="list-single" var="endpoint" >
        <value>caller</value>
      </field>
      <field type="text-single" var="target-uri" >
        <value>sip:bob@example.com</value>
      </field>
    </x>
  </command>
</iq>

Execute From Psi

Once you have your X-Lite configured and registered with our proxy SIP server you can go back to Psi and fill out the call terminate form.

  1. Open the Psi XML console for your jabber account so you can see the XML communication
  2. Open the service browser and enter commands.active-calls.xmpp.onsip.com into the address input.
  3. Double click Terminate Call and enter the following information:
    1. call-id
    2. from-tag
    3. to-tag
    4. choose either caller or callee from the endpoint select menu
    5. target-uri

This should transfer the endpoint of the active call described by the call-id, from-tag, and to-tag to the target-uri

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

Successful execution of a transfer command indicates an active call matching the call-id, from-tag, and to-tag has been found and an attempt is being made to transfer the endpoint to the target-uri. A successful transfer can only be determined from subsequent items published to the Active-Calls Pubsub nodes of the callee, caller, and target.

Response Fields

N/A

Successful Response
<iq from="commands.active-calls.xmpp.onsip.com" type="result"
    to="alice@example.com" id="transfer-2b" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed"
           node="transfer" sessionid="552d11b3c234bbb0d34aad81449f22a9" />
</iq>

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response
<iq from="commands.active-calls.xmpp.onsip.com" type="error" xml:lang="en" 
    to="alice@example.com" id="transfer-3" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed" 
           node="transfer" sessionid="a20c561c0cb43e73d6202af0c588d35b" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="call-id" >
        <value>bad-call-id</value>
      </field>
      <field type="text-single" var="from-tag" >
        <value>bad-from-tag</value>
      </field>
      <field type="text-single" var="to-tag" >
        <value>bad-to-tag</value>
      </field>
      <field type="list-single" var="endpoint" >
        <value>callee</value>
      </field>
      <field type="text-single" var="target-uri" >
        <value>sip:bar@example.com</value>
      </field>
    </x>
    <note type="error" >Execution Errors; transfer call failed</note>
  </command>
  <error type="modify" code="400" >
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">Execution Errors; transfer call failed</text>
    <bad-payload xmlns="http://jabber.org/protocol/commands"/>
  </error>
</iq>

Additional Information

N/A


cancel

The cancel command will attempt to cancel a create request BEFORE that call has been answered.

Authorization Requirements

none

Input Fields

TODO

Single Stage Execution

TODO

Request to commands.active-calls.xmpp.onsip.com

TODO

Multi-stage Execution

Multi-stage execution is meant for user interaction. The request allows you to present your user with a form to fill out that is then sent to the commands.active-calls.xmpp.onsip.com component as a response to the form request.

TODO

Execute From Psi

TODO

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

TODO

Response Fields

N/A

Successful Response

TODO

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response

TODO

Additional Information

N/A

Personal tools