Since the public beta release of Ribbit Phone's VoIP web services, it is now really easy to add voice over IP capabilities to any Flex application.

This tutorial goes through the process of getting started and shows how little code is necessary to get going. The code sample in this tutorial will be able to phone a telephone number from Flex using your computer’s microphone and speakers.

Step 1: Sign up for a developer account

To use the Ribbit Phone API you need to sign up for a developer account. After filling out the sign up form you will receive an email within 24 hours with your username and password.

Step 2: Download the Ribbit Phone Component

Login to developer.ribbitphone.com with your username and password.

Click on the "Download the Ribbit Phone Component" button to download a ZIP file, which includes the component file as well as some code samples.

Step 3: Set up the Flex Project

Create a new project in Flex Builder and add the RibbitAPI.swc file.

You will need to edit the project's properties to add the component as a library path. One easy way of doing this is right-click on the project in the Navigator and click Properties. Then select Flex Build Path, go to the Library Path tab, and click Add SWC.

Step 4: The Code

Add the following code to your Flex project. You will need to fill in the username and password that was emailed to you.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:ribbit="com.ribbit.*" applicationComplete="init();" width="324" height="162" layout="absolute">
	<mx:Script>
		<![CDATA[
			import com.ribbit.objects.CallObject;

			private var username:String = "xxxxxxxxxxxx";
			private var password:String = "xxxxxxxxxxxx";
			
			private var activeCall:CallObject;
			
			private function init():void {
				request.socketDebug = true;
				request.login(username, password, '', '');
			}
			
			private function handleServerConnected():void {
				callStatus.text = 'Ready';
			}

			private function handleCallConnected(call:CallObject):void {
				activeCall = call;
				callStatus.text = 'Call active';
			}
			
			private function makeCall():void {
				request.makeCall(number.text);
			}
			
			private function hangup():void {
				request.hangup(activeCall);
			}

		]]>
	</mx:Script>
	
	<ribbit:RibbitRequest id="request"
		ribbitServerConnected="handleServerConnected()"
		callRinging="callStatus.text='Ringing'" 
		callDisconnected="callStatus.text='Disconnected'" 
		callHungup="callStatus.text='Hung up'" 
		callConnected="handleCallConnected(event.data as CallObject)" 
		error="callStatus.text = event.data as String" />

	<mx:Panel x="16" y="10" width="292" height="141" layout="absolute" title="VoIP in Flex">
		<mx:Label text="Number to Call:"  x="10" y="12"/>
		<mx:TextInput text="" id="number"  x="109" y="10" width="153"/>
		<mx:Button id="callButton" label="Call" click="makeCall()" x="109" y="40"/>
		<mx:Button id="hangUpButton" label="Hang Up" click="hangup()" x="163" y="40"/>
		<mx:Label id="callStatus" text="Please wait"  x="109" y="73"/>
		<mx:Label x="10" y="73" text="Call Status:"/>
	</mx:Panel>

</mx:Application>

Step 5: Launch and test the application

Compile and run this application and you will see a screen that looks like this:

Before clicking anything wait for the call status to be "Ready." This means that the Flex application has successfully logged into the Ribbit Phone service and is ready to make calls.

Try typing in your phone number and click Call. Depending on your Flash security settings you may need to click allow microphone access.

At some point after your call connects and you are talking to yourself, click the Hang up button to end the call.

Step 6: Conclusion

Getting started with this API was really easy. Ribbit Phone has a few other code examples available that show how to use the more powerful and complex features of the service.

Learn more about what you can do with the Ribbit Phone API by reading their documentation and by keeping an eye on their blog for announcements about new features.