PhoneGnome API >> phonegnome.remotePromptSound

phonegnome.remotePromptSound

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 to deliver an audio clip. This RPC is similar to phonegnome.remoteSound except this call also provides a customized prompt requiring the user to press '1' before the audio clip is played. When the called user answers the phone, a user-supplied prompt audio clip is played. This clip should instruct the user to press '1' if they want to hear the clip. If that user does press '1', then play the given sound file (audio clip). At the conclusion of the clip, 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. prompt_url (string): A URL for the WAV or MP3 file to be used as the customized prompt, instructing the user to press '1' to hear the audio clip. This custom prompt can be used to introduce or announce the specific audio content. Optionally, the user can be instructed to press '2' to reject the file. This will cause the RPC to deliver the value Rejected to the post_url. The file MUST be named either .wav or .mp3
5. 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
6. request_id (string): A unique identifier for the request. Valid characters are digits 0-9
7. post_url (string): A URL to which PhoneGnome will provide the final disposition of the sound file delivery. This URL will be invoked 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. The returned result value will be the string Rejected if the user pressed '2' before the file was delivered (in response to the initial prompt), in which case the audio clip HAS NOT been delivered. Use the value null as the post_url parameter to indicate to the PhoneGnome API that no HTTP POST is to be performed.
8. 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.remotePromptSound</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.mysite.org/wavs/fileprompt.wav</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