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:
- XML-RPC API
- HTTP POST XML Controls API
- Simple HTTP-based third party call control
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 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.
The available methods are:
- phonegnome.Dial: Dials a given number using your PhoneGnome phone
- phonegnome.deliverSound: Delivers an audio clip (WAV file) to PhoneGnome
- phonegnome.addContact: Add a contact to the on-line PhoneBook
- phonegnome.getContact: Retrieve on-line PhoneBook Records
- phonegnome.setContact: Modify an on-line PhoneBook Record
- phonegnome.delContact: Delete an on-line PhoneBook Record
- phonegnome.cdrQuery: Query Call Logs
- phonegnome.Vmsg: Send a voice message using your PhoneGnome phone
- phonegnome.getConfig: Retrieve PhoneGnome parameter value
- phonegnome.setConfig: Set PhoneGnome parameter value
- phonegnome.getProfile: Retrieve user profile string
- phonegnome.setProfile: Set user profile string
- phonegnome.indirectDial: Specify an indirect dialing event
- phonegnome.remoteSound: Deliver a sound file to a specified destination and collect digits pressed by the user in response
- phonegnome.remotePromptSound: Deliver a sound file to a specified destination, only if the user first presses '1'.
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
- A list of your friends and their current update
- Updating your PhoneGnome profile/status
- Done with a HTTP POST using the "status" parameter.
status=Working on my car.
Display Public Profile on Webpage:
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
phone=number instead of the 'id'
Display automatically updated most recent event of PhoneGnome on webppage
Public Profile (no authentication required)
- Two forms permitted (specify by username or 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
- The country-code of your PhoneGnome phone number
- Your PhoneGnome phone number
- 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.
Below are some examples of how to use these URLs from various programming/markup languages
A call could also be initiated via a simple HTML form such as the following:
By default, a generic PhoneGnome HTML page is returned. You can
direct the user's browser to your own page by specifying the additional
url by adding the following:
<input type="hidden" name="url" value="http://yoursite">
You can also handle input errors by providing the additional
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.
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.