PhoneGnome API

Welcome to the PhoneGnome API. This site is for PhoneGnome owners who are interested in interacting with PhoneGnome from other programs, interfaces, or environments.

The PhoneGnome API provides several types of Telephony Web Services. These include:

The interfaces and APIs provide third-party call control, contact list management, access to on-line call logs, API-based management of PhoneGnome account settings and features, fixed/mobile convergence, and more.


Deep Integration of Third-party Applications

The APIs outlined below are free and open to anyone to use, They provide light integration with third party sites and services. PhoneGnome also offers Deep Integration of Third-party Applications through the Extensions API which enables thrid-parties to deliver tightly integrated applications and services to PhoneGnome customers or build customized products based on the PhoneGnome platform.

To learn more about these opprtunities, see the PhoneGnome Developer Program for an overview, or download the Extensions API Overview (PDF) for an overview of the partner application integration capabilities of the PhoneGnome platform.


User-Contributed Files Library

The User-Contributed Library is your tool for sharing code, images, data, and even technical white papers with other members of the PhoneGnome owner/developer community. Submitting and retrieving files is a very simple process.


XML-RPC

XML-RPC is a spec for doing remote procedure calls via HTTP. It uses XML as the encoding for the request. It's lightweight, simple, and easy to implement.

Methods

The available methods are:


HTTP Post Controls

The HTTP Post controls provide another mechansm to access PhoneGnome services via XML.

All of the methods require user authentication via Basic Auth. The username is the username you have stored on PhoneGnome (the username used to access the Support forums), the password, your PIN/password. You may also use the email address associated with the account as the username in the Basic Auth authentication if the email address is unique to a specific PhoneGnome account.

Public Profile
http://my.phonegnome.com/controls/public.xml
A list of your friends and their current update
http://my.phonegnome.com/controls/friends.xml
Updating your PhoneGnome profile/status
Done with a HTTP POST using the "status" parameter. status=Working on my car.


http://my.phonegnome.com/controls/update.xml



Javascript Website Widgets

The following Javascript tools permit simple CSS formatting of PhoneGnome status information on a web page or blog.

Display Public Profile on Webpage:

<span id="my_gnome_status"></span> <span id="my_gnome_status_time"></span> <br/>

<script type="text/javascript">
function gnomeCallback(obj) {
document.getElementById('my_gnome_status').innerHTML = obj.text;
document.getElementById('my_gnome_status_time').innerHTML = obj.relative_created_at;
}
</script> <script type="text/javascript" src="http://my.phonegnome.com/tools/status.js?id=yourid&callback=gnomeCallback">
</script>

Insert the above HTML/script into any web page to display your public profile. Replace yourid above with your PhoneGnome username. You can use your phone number (including country code) instead of username, if you prefer, by specifying the paramter phone=number instead of the 'id' parameter.

Display automatically updated most recent event of PhoneGnome on webppage

<span id="my_gnome_status"></span> call <span id="my_gnome_status_time"></span> <br/>

<script type="text/javascript">
function gnomeCallback(obj) {
document.getElementById('my_gnome_status').innerHTML = obj.event;
document.getElementById('my_gnome_status_time').innerHTML = obj.relative_created_at;
}
</script> <script type="text/javascript" src="http://my.phonegnome.com/tools/autostatus.js?id=yourid&callback=gnomeCallback">
</script>

Public Profile (no authentication required)

Two forms permitted (specify by username or phone number)
http://my.phonegnome.com/tools/public.xml?id=username
http://my.phonegnome.com/tools/public.xml?phone=number



Simple HTTP-based third party call control

Third party call control allows third party developers to write their own software applications to initiate a call from their PhoneGnome phone to any other phone in the world.

For example, an Outlook plug-in could be created that would initiate a call by clicking on a phone number in the Outlook contact list. Another example would be a browser plug-in that would place a call to a phone number on any web page.

You will need your PhoneGnome phone number and PIN to use this feature.

Initiate the call from your PhoneGnome number to any number in the world
http://my.phonegnome.com/tools/callout?cc=country-code&phone=your-number&callto=number-to-call Where
country-code
The country-code of your PhoneGnome phone number
your-number
Your PhoneGnome phone number
number-to-call
The number you wish to call

HTTP POST is recommended, but HTTP GET will also work. Be advised that your PhoneGnome PIN will be exposed in the browser URL when using GET.

When executed, a call will first be placed to your PhoneGnome box (or currently active remote click-to-dial location, if set). The system will dial the outbound number after the PhoneGnome phone is answered. The PhoneGnome customer will hear ringing as if the number was dialed from their phone and the two parties will be connected.

Examples

Below are some examples of how to use these URLs from various programming/markup languages

HTML
A call could also be initiated via a simple HTML form such as the following:

<form action="http://my.phonegnome.com/tools/callout" method="post">
<input type="hidden" name="cc" value="country-code">
<input type="hidden" name="phone" value="your-number">
<table>
<tr>
<td align="right">Number to call:</td>
<td><input type="text" size="20" name="callto"></td>
</tr>
<tr>
<td align="right">PIN:</td>
<td><input type="password" size="20" name="pin"></td>
</tr>
<tr>
<td colspan="2" align="middle">
<input type="submit" name="submit" value="Dial"/>
<input type="button" name="submit" value="Cancel"/ onclick="javascript:history.back()">
</td>
</table>
</form>

By default, a generic PhoneGnome HTML page is returned. You can direct the user's browser to your own page by specifying the additional parameter url by adding the following:

<input type="hidden" name="url" value="http://yoursite">

You can also handle input errors by providing the additional optional parameter errurl. If an error occurs (such as invalid PIN), then the callout control will redirect the browser to the url specified by errurl passing the parameter errmsg which is an explanation of the error.

PHP
A server side script could be written to allow users to call you for free, by allowing them to initiate a call from you to their phone. The server side script would contain your PhoneGnome country-cody, phone number, and PIN, which you would not want the caller to have access to.

In the following PHP example, your PhoneGnome phone country-code and phone number would be hardcoded in the script, and the user would submit their phone number to the URL for the script as the parameter callto.

<?php
$cc = urlencode("country-code");
$phone = urlencode("your-number");
$pin = urlencode("your-pin");

$callto = $_REQUEST['callto'];

$ch = curl_init("http://my.phonegnome.com/tools/callout");
curl_setopt($ch, CURLOPT_MUTE, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "cc=$cc&phone=$phone&pin=$pin&callto=$callto&submit=Dial");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$output = curl_exec($ch);
curl_close($ch);

if (ereg("^\s*<p>Failed:", $output))
    echo "Sorry, an error has occurred: $output";
else
    echo "Calling $callto, please answer your phone when it rings.";
?>



Help us create the API you want

This API will be continously improving. Please contact us to tell us about features you'd like to see.