Connecting Calls

Example scenario:

1. somebody calls in and Verboice initiates a new session, invoking your application.
2. your application replies back with a command with some welcome message and background music
3. at the same time, your application notifies the operators that an incoming call is waiting
4. the operator clicks on the "answer" button on the web site
5. your application uses the new "call redirect" feature to stop the command and start with a to the operator
6. the operator's soft phone or cell phone rings

At the same time, during all these steps, your application will be receiving callbacks from Verboice notifying about the status of the Verboice session. So for example if the user hangs up before an operator picks up the call, you can stop showing the message on the website. For outgoing calls you can also use these status notifications to know about the result of the call.

Table of Contents Call Status Notification Dynamic Call Status Notification URL Dial command Call Redirect

Call Status Notification

A callback URL can be specified in the application (there is a new text field on the application page). Verboice will perform a GET request to the specified URL every time the session changes its status, with the following parameters in the query string:

• CallSid: the session id
• From: the caller id (only for incoming calls)
• CallStatus: one of these values:
  • ringing: the remote end is ringing (only for outgoing calls)
  • in-progress: the session has started
  • completed: the session has successfully finished
  • failed: the session has terminated with an error
  • busy: the remote end is busy (only for outgoing calls)
  • no-answer: the remote end do not answer in time

Dynamic Call Status Notification URL

The callback URL can also be specified or overwritten when performing an outgoing call, adding the ##status_callback_url## parameter to the ##api/call## request. In this case, the ##status_callback_url## parameter can't have a query string. If you need to add query string parameters to the status callback url you can specify them with ##callback_params## parameters, like this:

callback_params[param1]=value1&callback_params[param2]=value2

Assuming the ##status_callback_url## is "http://example.com", the final status callback url would be:

http://example.com?param1=value&param2=value&...

Dial command

The Dial command can be used to perform an outgoing call and connect with the current user in the session. This command can be specified in the responses to Verboice in the callbacks or in the XML posted to the api/call.

Example:

</response>


The Dial command can also receive some parameters:
  * channel: specifies the channel name for the outgoing call. If this parameter is not present, Verboice will use the same channel of the current session.
  * callerId: if this parameter is present, Verboice will try to use this value as the Caller ID for the outgoing call. It could be a number, a number of a combination with the format: "John Doe" <123123>
  * action: a callback URL to be invoked once the Dial finishes
  * method: the HTTP method to be used to perform the action callback. If not specified, the callback is performed with a POST request.

If the 'action' parameter is not specified, Verboice will continue with the following commands once the Dial command finishes (succesfully or not). In the next example, the message "Good bye!" will be played once the Dial is completed:

<Response>
  <Dial>8888888</dial>
  <Say>Good bye!</say>
</response>

Otherwise, if an 'action' is given, once the Dial completes a HTTP callback will be performed and Verboice will continue with the commands returned in the response. Any other command following the Dial will be ignored. The callback will contain the following parameters:

* CallSid: the session id * From: the caller id * Channel: the current channel name * DialCallStatus: the status of the Dial command that has just finishes, with one of these values: ** completed: the other end answered in time and the Dial command completed successfully ** busy: the other end is busy ** no-answer: the other end didn't answer in time (30 seconds) ** failed: the Dial command failed (check the logs for more information)

== Call Redirect ==

With this new Verboice API, a current session can be redirected to a new flow of commands, stopping whatever it's currently doing. The URL for this api is '/api/call/<sessionid></sessionid>/redirect' and it can be used in three different ways:

1) POST call with the new XML flow

the XML with the new flow can be specified in the body of the request and Verboice will start immediately with the new instructions.

2) GET call with application_id parameter

the session will be redirected or restarted with the application specified by its ID.

3) GET call with callback_url parameter

Verboice will perform a POST request to the specified url to get the next actions for the session.