Ringful is a productivity booster additive for web sites. Ringful enhanced online services can be so sophisticated in telephone interaction that they would appear to be run by Fortune 500 enterprises.

Ringful.com provides a set of simple and powerful RESTful web services APIs for voice and mobile messaging applications such as Phone Alias, Instant Group Calling, Mobile ID Verification, Push Conference, and Facebook Voicetag . As a developer or web master, you can use these RESTful APIs to develop widgets that can be embedded into your own application to enable voice and messaging services. For example you can let your users leave a voice comment on a forum post, or be notified when a purchase order is in and then approve the shipment over the phone. You can even run a customer satisfaction survey via voice or text interaction.

Server initiated calls and messaging are supported as well as inbound calls via DID and messages via SMS MO codes. You can use your own DID for inbound call handling or we can help you obtain DID in virtually any country. Similarly you can plug in your own SMS MO long/short codes and keywords or we can help you obtain new ones.

Following is a reference guide to the Ringful API. Please contact info@ringful.com for any questions regarding the API.



The Interactive Voice API


The basic usage of the voice phone call API is as follows:

  1. The application invokes the Call API to initiate a phone call to a phone number. The Call API returns immediately with a call ID.
  2. The application can then use the call ID to queue tasks that needs to happen after the user answers her phone. For instance, you can queue up to make two audio files in a row, and then make a recording of what the user says. There are a variety of events you can queue for each call.
  3. Each Ringful API call can be associated with a callback url. Ringful server will report back all events associated with a call ID. For instance, your application will get notified when the user picks up the phone, the start / end of audio file playbacks, touch tones the user generates, and when the user hangs up phone.

The task queue in step #2 is a particularly important concept. Instead of having your application waiting for call events from the Ringful server and decide what to do next, you can build a queue of events as a script, and have Ringful server automatically run through the script for you. That approach greatly reduces the complexity and latency introduced by the more traditional callback based programming models.

An example sequence of API calls from the user application would be:

  1. /Call/apikey/1234?callee=15125551234&callbackUrl=http://host/call_notify.php&seq=1234&sig=abcd -- returns CALLID
  2. /Play/apikey/1234?callId={$CALLID}&announcement=http://host/welcome_message.wav&seq=1234&sig=abcd
  3. /Play/apikey/1234?callId={$CALLID}&announcement=http://host/please_press_1.wav&seq=1234&sig=abcd
  4. /WaitForTone/apikey/1234?callId={$CALLID}&tone=1&seq=1234&sig=abcd
  5. /Record/apikey/1234?callId={$CALLID}&callbackUrl=http://record_notify.php&seq=1234&sig=abcd
  6. /StartToneDetector/apikey/1234?callId={$CALLID}&callbackUrl=http://host//tone_notify.php&seq=1234&sig=abcd

All those calls can be made in a synchronous fashion -- meaning that all those API calls return immediately, and you can call one API immediately after another in a single client side method. Ringful server will just queue up the tasks and process them one by one.

The above sequence of API calls first places a phone call to 15125551234; It plays the "welcome" and "please press 1" audio files one after the other, once the user answers the phone; It then waits for the user to press the "1" touch tone key; Once the touch tone is detected, Ringful starts recording whatever the user says, and sends all touch tones the user generates from now on to the application. All the events that happen during the call are sent back to the application via callback URLs.

  1. The detected touch tones are POSTed back to the http://host/tone_notify.php callback URL. The web application behind the http://host/tone_notify.php callback URL can make additional Ringful API calls to play more announcements in response to specific touch tones the user generates.
  2. The recorded file URL is sent back to the application via the http://host/record_notify.php callback URL once the recording is finished. In this case, the callback is invoked when the call hangs up.
  3. The Call API callback http://host/call_notify.php is notified when the call is started (i.e., when the user picks up), when the call is hang up by the user, and when the call is hang up by the server.

The API specifications are as follows.

Call


The Call API rings a phone, and establishes a audio connection between Ringful server and the phone once the user answers the phone. Once the call is connected, Ringful server moves down the task queue for this call ID to perform any call tasks required (e.g., Play an audio file, wait for a tone, or record the user's voice).

Example: /Call/apikey/1234?callee=15123006828&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • callee: The number to call

Optional parameters:

  • callbackUrl: The URL to receive events
  • callerId: The caller ID to show on the callee's incoming call

Return value: A string value of the unique call ID is returned immediately


Callback actions:

  • action: CallEstablished | CalleeHangUp | ServerHangup.
  • callId: the callId of the call leg
  • billAmount: The bill amount for this call leg if the action is CalleeHangUp or ServerHangup.

Hangup


This API hangs up a specified leg of call. You can optionally specify whether the call should be terminated right now, or the termination should be queued as a task (e.g., to hang up after playing an audio file). All the unprocessed tasks for this call ID will be discarded. If audio recording is currently in progress for this call, it will stop too.

Example: /Hangup/apikey/1234?callId=1234-5678-9012-3456&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg

Optional parameters:

  • immediate: true | false. This value defaults to true, meaning that the call leg is immediately terminated once Ringful receives this API invocation.

Return value: none


Callback actions: none. But the Call API's callback will be called.


Play


This method queues an announcement for playback in the specified call leg. By default, Ringful waits for the announcement to complete before it moves on to the next task in the queue. But you could also instruct the server to start the next task as soon as the announcement starts (e.g., to start recording as soon as an announcement starts).

Example: /Play/apikey/1234?callId=1234-5678-9012-3456&announcement=file:///opt/some.wav&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg
  • announcement: The media file to play. Right now, it has to be 16 bit, 8kHz sample rate.

Optional parameters:

  • waitComplete: true | false; Default to true. It specifies whether Ringful server should wait for the announcement to complete before it moves onto the next task in the queue.
  • callbackUrl: The URL to receive the play start or complete event for this announcement

Return value: none


Callback actions:

  • action: PlayStart | PlayComplete
  • announcement: The announcement being played
  • callId: The callId of the call leg


Record


This method queues to start a recorder in the specified call leg. The recorder only starts after all queued tasks before it has been cleared. The recorded audio is saved in the callId.wav file. The recorder could be stopped by the user hangup or via a RecordStop API call.


Example: /Record/apikey/1234?callId=1234-5678-9012-3456&callbackUrl=http://host/notify.php&seq=1234&sig=abcd


Required parameters:

  • callId: The id of this call leg
 

Optional parameters:

  • callbackUrl: The URL to receive the record start / complete events


Return value: none


Callback actions:

  • action: RecordStart | RecordComplete
  • callId: The callId of the call leg
  • recordFile: the full URL of the recorded file


StopRecord

 
This method stops the recorder. Like the Hangup API, you can specify whether the recorder should be immediately stopped or after other queue tasks have been cleared. This method does not a callback of its own. But the Record API's callback will be invoked when the call is stopped.
 
Example: /RecordStop/apikey/1234?callId=1234-5678-9012-3456&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg

Optional parameters:

  • immediate: true | false. This value defaults to true, meaning that the call leg is immediately terminated once Ringful receives this API invocation.


Return value: none


Callback actions: none. But the Record API's callback will be called.



WaitForTone


This method causes the server to wait for the user to punch the required touch tone. It will only move along the task queue after the requested tone is detected.

Example: /WaitForTone/apikey/1234?callId=1234-5678-9012-3456&tone=1&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg
  • tone: the tone that the user is asked to enter. It can be a comma delimited list of multiple tones. If any of these is detected, the task is considered finished.

Optional parameters:

  • callbackUrl: The URL to send back tone events.

Return value: none


Callback actions:

  • action: WaitForToneDetected | WaitForToneMisfire
  • callId: The callId of the call leg
  • tone: the tone as it is detected


StartToneDetector


This method queues to start a tone detector in the specified call leg. Each detected tone is sent back to the callbackUrl.

Example: /StartToneDetector/apikey/1234?callId=1234-5678-9012-3456&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg
  • callbackUrl: The URL to receive the DTMF events

Optional parameters: none


Return value: none


Callback actions:

  • action: ToneDetectorStart | ToneDetected
  • callId: The callId of the call leg
  • tone: the tone as it is detected

StopToneDetector


This method stops a tone detector in the specified call leg. It could be stopped immediately or after the task queue is cleared.

Example: /StopToneDetector/apikey/1234?callId=1234-5678-9012-3456&seq=1234&sig=abcd

Required parameters:

  • callId: The id of this call leg

Optional parameters: none

  • callbackUrl: the event for the success stop of the tone detector.
  • immediate: true | false. This value defaults to true, meaning that the call leg is immediately terminated once Ringful receives this API invocation.

Return value: none


Callback actions:

  • action: ToneDetectorStop
  • callId: The callId of the call leg





The Conference Call API


The conference call APIs are used to connect and manage conference calls across multiple call legs established by the previously mentioned Call API. The StartConf and JoinConf APIs creates events that can be queued for the call ID. They can be used as part of your call "script" to start or join a conference after playing an announcement or after detecting a touch tone from the user.

Still, to make a moderated conference call from the Call / StartConf / JoinConf APIs, you need to make several API calls and listen for several callbacks. For instance, you typically only want to call the conference participants after the moderator has joined. To make life easier for developers who just want to create a moderated conference call, we created a composite ConfCall API that internally uses our own public APIs to streamline the conference connection process.

The ConfCall and StartConf API calls return immediately with a conference call ID, even though the conference it self will start some time later. As with the call ID, each conference call ID maintains its own event queue. You can queue up events to play / record / generate tone to the entire conference just as you would do to a individual call leg.



ConfCall


This method immediately starts a conference call with a moderator and a number of attendees.

Example: /ConfCall/apikey/1234?moderator=15125551234&waitConnectAudio=http://host/ringful.wav&attendees=18185551234,17135551234&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • moderator: The phone number of the moderator of the conference.
  • attendees: A coma separated list of phone numbers to join to the conference once the moderator answers.

Optional parameters:

  • waitToneAudio: Audio to prompt the moderator to enter a key to avoid voice mail pick up
  • expectedTone: The key moderator is supposed to enter
  • waitConnectAudio: The announcement the moderator hears while waiting for attendees to join
  • callbackUrl: The URL to receive conf call events

Return value: The conf call ID of this conference call.


Callback actions: The callbackUrl is passed to the Call function of each attendee. So, the callbackUrl receives a notification whenever someone joins or hangs up. Since the CallDisconnected callback action contains the conference ID and the duration of this call leg, you can use those values to bill users.


StartConf


This method queues to start a conference call with a moderator. The method returns immediately with the conference call ID although the conference will start sometime in the future. If the waitForParticipant parameter is "true", the server will just create the conference but wil only join the moderator to the conference when the first participant joins.

Example: /StartConf/apikey/1234?moderator=15125551234&callbackUrl=http://host/notify.php&seq=1234&sig=abcd

Required parameters:

  • moderator: The phone number of the moderator of the conference.

Optional parameters:

  • waitForParticipant: true | false; Default to true. Indicates whether to join the moderator even when the conference is empty (the moderator will hear silence until the first participant joins)
  • callbackUrl: The URL to receive conf call events

Return value: The conf call ID of this conference call.


Callback actions:

  • action: ConfCallStarted | ConfCallCompleted
  • confCallId: The conference call ID 


JoinConf


This method queues a task for the specified call leg to join a conference. If the joinModerator parameter is "true", the server will join the moderator to the conference if she has not joined -- it is used together with the waitForParticipant parameter in the StartConf API.

Example: /JoinConf/apikey/1234?confCallId=1234-abcd&participantCallId=3145-mjyt&seq=1234&sig=abcd

Required parameters:

  • confCallId: the conference call created by StartConf, which we are now joining.
  • participantCallId: the call leg to be joined

Optional parameters:

  • joinModerator: true | false; Default to true. Indicates whether to join the moderator when this participant joins
  • callbackUrl: The URL to receive conf call events

Return value: None


Callback actions:

  • action: ConfCallJoined | ConfCallLeft
  • confCallId: The conference call ID
  • participantCallId: The call leg just joined 


LeaveConf


This method causes the specified call leg to leave the specified conference. It can happen immediately or be queued in the task queue for the call leg. This API only has effect if the call leg is NOT the moderator of the call. For moderator, please use HangupConf API.

Example: /LeaveConf/apikey/1234?confCallId=1234-abcd&participantCallId=3145-mjyt&seq=1234&sig=abcd

Required parameters:

  • confCallId: the conference call ID
  • participantCallId: the call leg to leave the conference

Optional parameters:

  • immediately: true | false; Default to true. Indicates whether to leave immediately or queue the task for later.

Return value: None


Callback actions: None. But the JoinConf callback will be invoked


HangupConf


This method hangs up a conference call, and hangs up all the call legs in the conference. It takes effect immediately.

Example: /HangupConf/apikey/1234?confCallId=1234-abcd&seq=1234&sig=abcd

Required parameters:

  • confCallId: the conference call ID

Optional parameters: None


Return value: None


Callback actions: None. But the StartConf callback, and the Call callback for each leg will be invoked


QueryConf


This method returns XML data on the current moderator and active participants of a conference call

Example: /QueryConf/apikey/1234?confCallId=1234-abcd&seq=1234&sig=abcd

Required parameters:

  • confCallId: the conference call ID

Optional parameters: None


Return value:

<conference>

    <moderator>

        <phone>15125551234</phone>

        <id>1234-abcd</id>

    </moderator>

    <participants>

        <participant>

            <phone>15125551235</phone>

            <id>1234-xyzf</id>

        </participant>

        ... ...

    </participants>

</conference>


Callback actions: None


Play / Record / WaitForTone / StartToneDector / StopToneDetector


Those API calls queue tasks for the conference call ID. The usage is the same as corresponding API calls for the regular call ID. You just need to replace the callId parameter with the confCallId.





The SMS API


The SMS API allows users to send SMS messages to mobile phones. There are two APIs. The SendReciveSms sends a SMS message to phones world wide. The mobile user will be able to reply to the message, and Ringful server will send the reply back to the callback URL specified by the application. 

The SendSms API is primarily used for one-off SMS notification for users in North America. The application has to know which mobile operator the target phone number is associated with, and there is no way for the mobile user to reply to the message.


SendReceiveSms


This method sends SMS messages to a specified phone number, and receives the user reply via a callback.

Example: /SendReceiveSms/apikey/1234?callee=15125551234&message=hello+world&callbackUrl=http://host/SmsReply/15125551234/&seq=1234&sig=abcd

Required parameters:

  • callee: the mobile number to send the message to
  • message: the URL encoded message to send. If the message is longer than 160 char, we will break up the message into multiple SMS messages

Optional parameters:

  • callbackUrl: The URL to POST the user reply to

Return value: None


Callback actions:

  • from:<phone number>
  • reply:<message>

SendSms


This method sends an one-off SMS message to a north american phone number.

Example: /SendSms/apikey/1234?callee=15125551234&message=hello+world&operator=1&seq=1234&sig=abcd

Required parameters:

  • callee: the mobile number to send SMS to
  • operator: the carrier of the target phone: 1. ATT; 2. Verizon; 3. Sprint; 4. T-Mobile
  • message: the message to send. Must be less than 140 chars

Optional parameters: none


Return value: None


Callback actions: None.






We welcome your questions, feedback and requests for improvement about the Ringful API at info@ringful.com