External Services

External Services are a feature of Verboice that allows you to integrate your existing applications with the voice interaction your users experience. Using external services, the data and core business logic stay in your application, and you expose enough information to be able to get user input and drive branching in Verboice without having to code.

Uses

External Services are useful for scenarios such as:

• Authenticating a user based on a PIN
• Getting data from another system to customize what the user hears (e.g. look up the result of a diagnostic and proceeding differently for "you are sick" or "you are not sick" results)
• Sending user input or results of user screening questions or surveys (e.g. you ask "press 1 if you've had headaches... press 1 if you've felt dizzy, etc., and at the end you want to store the results)

How to use existing External Services

To use an external service in Verboice you will need to know a link (URL) to a "Manifest" that tells Verboice what the other application exposes. You won't be able to add the service without this manifest.

1. Adding the External Service to your Project###

1. Log in to Verboice
2. See your projects http://verboice.instedd.org/projects
3. Select the desired project and go to the "External Services" tab
4. Click on Add External Service and enter the manifest address (The manifest address will look something like this: http://verboice.instedd.org/docs/sample_manifest.xml )
5. Click Save.

2. Using the External service in your call flow

You can see new icons for steps in the call flow designer that represent the different calls the External Service supports. You can add the icon to the call flow and Verboice will invoke the appropriate web service when that point in the flow is reached. You will need to map variables from your call flow to the Input variables required by the service. Optionally, you may want to save the results of the service calls as variables so you can branch on them later in the call flow.

How to expose an External Service from your application

You need to do two things to expose an external service from your application:

1. You need to have http endpoints for web service calls that take in input parameters and returns data.
2. You need to expose a special file on your service that declares which services you have, their URLs, and which input and parameters each one has.

The web service endpoint will accept GET or POST requests and returns either a JSON document, an XML with flow commands (in TwiML format) or nothing. Example POST data:

POST /results HTTP/1.1
Host: {service_domain}
Content-Type: application/x-www-form-urlencoded

pin=1234

Example return data (for variable return services):

{"result": "ok"}

Exposing a manifest

Your manifest can be static or dynamically generated.

An example manifest can be found here:

http://verboice.instedd.org/docs/sample_manifest.xml

A list of icons names that can be used in the "icon" attribute is here: http://static.instedd.org/verboice/external_services_icons.html

<verboice-service>
  <name>Health Center</name>
  <global-settings>
    <variable name="service_domain" display-name="Service Domain" type="string"/>
  </global-settings>
  <steps>
    <step name="results" display-name="Analysis Results" icon="medicalkit" type="callback" callback-url="http://{service_domain}/results">
      <settings>
        <variable name="pin" display-name="Patient pin" type="string"/>
      </settings>
      <response type="variables">
        <variable name="result" display-name="Result" type="string"/>
      </response>
    </step>
    <step name="available_dates" display-name="Available Appointment Dates" icon="medicalkit" type="callback" callback-url="http://{service_domain}/available_dates">
      <settings/>
      <response type="flow"/>
    </step>
  </steps>
</verboice-service>

Each step has:

• A unique technical name
• A display name
• A string describing an icon //need to expand here on what Icons are available or how to bring them in from elsewhere.
• A response type: Responses can be "variables","flow", or "none"
• The type of service. Only "callback" is supported at the time
• The callback URL: the whole URL for the web service (like http://your_server/etc/etc/youservice.php)

Settings Element

The Settings element is used to declare the parameters that will go to your web service

<variable name="pin" display-name="Patient pin" type="string"/>

Each variable has a unique technical name, a display name / label, and a type (only "string" is supported).

Response Element

The response element has a value called "type" which can be one of the following:

• "variables": Verboice expects a set of variables back from the external service in a JSON document. You should then add variable elements to declare all the results that will come back from the web service (can be multiple).
• "flow": The external service returns a sequence of flow commands to execute. The response must be a XML with the same format used for the callbacks
• "none": The call is just 'one way' to the external service and no response is needed