Now that you've mastered OpenZoep's basic methods, it's time to open the stream and make a phone call.
To open the stream, the following stanza should be sent:
<?xml version='1.0' encoding='UTF-8' standalone='yes' ?> <stream:stream to='jabber.voipster.com' xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams'>
There are two things to notice here. The first is the mandatory UTF-8 encoding, and the second is the host name of the Jabber server. Just replace
jabber.voipster.com with your own Jabber server.
The following steps outline the lifecycle of a Jabber stream:
- Start a session by calling
- Set up the stream as described above.
- Inform the OpenZoep engine about your configuration settings by sending the
configuration:iqstanza (see trac.web1.openzoep.org/main/wiki/MoipApiSubsystemPresence3 for details).
- Request the authorization method (see www.openzoep.org/docs/api/primer/311.htm).
- Log in (see www.openzoep.org/docs/api/primer/312.htm).
- Send a presence notification (see www.openzoep.org/docs/api/primer/314.htm).
- (Recurring) Send and receive messages during the lifetime of the application.
- Log out (see www.openzoep.org/docs/api/primer/313.htm).
- Close the stream (see www.openzoep.org/docs/api/primer/310.htm).
- Close the session by calling
The action happens in step 7. Here are some examples of stanzas (XML messages) you can send during step 7.
Making Phone Calls
The OpenZoep client-side engine can be instructed to establish a peer-to-peer phone call to Joe by sending this stanza:
<voice id="phonecall_3cb5c86c-b40c-4e89-956b-f07d80650109" to="email@example.com/Zoep" type="join"> <call_id>show</call_id> <private>yes</private> </voice>
id attribute of the
voice element should contain a globally unique ID (most programming languages offer a library for generating a GUID). The
to attribute contains the address of the Jabber contact you want to talk to. The
private attributes are defined by XMPP but are not used by OpenZoep.
Making a call to a "normal" phone (land line or mobile) goes as follows:
<voice id="phonecall_93a7ba89-4a99-45da-ac82-62f0ee6b4cad" to="unknown/#003110123456" type="join"> <call_id>show</call_id> <private>yes</private> </voice>
Notice that the Jabber ID should be set to
unknown and the number you wish to dial should be preceded by a hash sign (
#) and a fully qualified international number. You also need to establish a call credit account with an OpenZoep PSTN provider in order to make phone calls to PSTN numbers (currently the only provider is zoep.com).
Answering Phone Calls
Answering an incoming call from Suzan is just as easy:
<voice firstname.lastname@example.org/Zoep' id='phonecall_3cb5c86c-b40c-4e89-956b-f07d80650109' email@example.com/Zoep' type='join'> </voice>
Send a message with the
type attribute set to
joined to accept the call. The
to attribute specifies the Jabber ID of the callee:
<voice id="phonecall_3cb5c86c-b40c-4e89-956b-f07d80650109" to="firstname.lastname@example.org/Zoep" type="joined"/>
After sending this message, you get the following response from Suzan:
<voice email@example.com/Zoep' id='phonecall_3cb5c86c-b40c-4e89-956b-f07d80650109' firstname.lastname@example.org/Zoep' type='joined'> </voice>
Suzan receives a similar message, only with the
to attributes reversed:
<voice email@example.com/Zoep' id='phonecall_3cb5c86c-b40c-4e89-956b-f07d80650109' firstname.lastname@example.org/Zoep' type='joined'> </voice>
By the way, the
joined terms originate from the fact that OpenZoep is fully prepared to handle multi-person conferences. Although technically not implemented yet, internally even two-person calls are handled as conferences.