PhoneGnome API >> phonegnome.remoteSound

phonegnome.remoteSound

Delivers a given audio clip (WAV or MP3 file) to a specified destination phone.

The RPC instructs the PhoneGnome system that the user of the PhoneGnome account wishes to dial a specific destination, and play the given sound file (audio clip) when the called user answers the phone. PhoneGnome will then wait for the called user to enter digits. If the user does not respond after 15 seconds, the call is terminated.

Each audio clip request should provide a unique request-id that will be used to identify the request. This RPC delivers an asynchronous event via HTTP POST to a specified url, returning the request-id and digits pressed by the user (if any) as HTTP POST parameters.

A successful response to the RPC indicates that the sound clip delivery process was successfully initiated and no errors were encountered. It does NOT mean the sound file has been delivered to the destination. The PhoneGnome API will invoke the user-supplied URL when the sound file has been delivered.

URI

All XML-RPC requests should go to the following URI: http://my.phonegnome.com/RPC2

Parameters

1. country_code (string): Country code of the PhoneGnome
2. phone_number (string): Telephone number of the PhoneGnome
3. md5_pin (string): MD5 hash of the PIN of the PhoneGnome account (PIN is same as that of the my.phonegnome.com dashboard)
4. audio_url (string): A URL for the WAV or MP3 file to be delivered (e.g. http://www.yoursite.com/alarm.wav). The file MUST be named either .wav or .mp3
5. request_id (string): A unique identifier for the request. Valid characters are digits 0-9
6. post_url (string): A URL to which PhoneGnome will provide the final disposition of the sound file delivery. This URL will be invokoked with HTTP POST, passing two parameters as follows: reqid the value of the request_id and result the digits pressed by the user, if any. The result parameter may also contain one of the strings Hangup if the user disconnected before pressing any keys or Timeout if the user pressed no keys within 15 seconds. Use the value null as the post_url parameter to indicate to the PhoneGnome API that no HTTP POST is to be performed.
7. number_to_call (string): the number to call, just as it would be dialed from the PhoneGnome. The call to deliver the sound file will be placed in the context of the authenticated PhoneGnome account (the account invoking the RPC).

Examples

Example XML-RPC request

<?xml version="1.0"?>
<methodCall>
 <methodName>phonegnome.remoteSound</methodName>
  <params>
   <param>
    <value><string>1</string></value>
   </param>
   <param>
    <value><string>3605551212</string></value>
   </param>
   <param>
    <value><string>844dda78e8a09008813020f47215e2a3</string></value>
   </param>
   <param>
    <value><string>http://www.nps.gov/fols/bugle/stablecall.wav</string></value>
   </param>
   <param>
    <value><string>7954086427886</string></value>
   </param>
   <param>
    <value><string>http://www.footfalls.org/audiostats.php</string></value>
   </param>
   <param>
    <value><string>16505553478</string></value>
   </param>
  </params>
</methodCall>

Successful Response

<?xml version="1.0"?>
<methodResponse>
 <params>
  <param>
   <value><string>ok</string></value>
  </param>
 </params>
</methodResponse>

Error Response

<?xml version="1.0"?>
<methodResponse>
 <fault>
  <value>
   <struct>
    <member>
     <name>faultString</name>
     <value><string>Soundfile delivery failed</string></value>
    </member>
    <member>
     <name>faultCode</name>
     <value><int>600</int></value>
    </member>
   </struct>
  </value>
 </fault>
</methodResponse>

© TelEvolution 2006