Overview

This is an advanced feature that will require prior knowledge of Web Services/APIs. If you do not see this option enabled. Please contact the ipSCAPE support team or your account manager to enable it.

Web services is a powerful tool that enables Workspace users to connect a Workflow to any REST API enabled database or service via the 'Web Service Connector' object. This means that you can feed information gathered in your IVR to an external database and then return the response from the database into your IVR, for example, you could give callers a prompt to enter a reference number for their booking, and the Web Service would then query your booking system and return a status to your IVR which could be spoken by the 'Say Text' object or forwarded to an agent with the relevant skills using the 'Branch on Value' object. Here is an overview of the process.

1. Getting Started

You will need access to the API of the service you are trying to connect to and details of the endpoints that are exposed. Then:

  1. Log in to the Workspace

  2. Goto the Integration Menu

  3. Select 'Web Services' 

  4. Press the + button to add the details of the Service you are trying to connect to

The Web Services edit screen option presents you with 3 tabs:

  • Configuration - used to build your API  requests  

  • Test - send the request you built on the first tab and verify the response you get 

  • Used by - provides you a linked list of the Workflows that this Web Service is used by

Once you have tested your Web Service you can link it to a Workflow object which will pass values to the service and return the responses into your IVR.

2. General Configuration

Field

Description

Web service

Unique user defined name that can be used to call the service in the 'Web Service Connector' object

Description

A description of what the web service does

Request Method

We currently support the GET & POST methods PUT& DELETE are restricted at the moment

Request Content Type

This allows the server to parse the content correctly. Currently we support Simple HTML and JSON

HTTPS

This will be added to the beginning of the 'Domain' setting, if you do not select HTTPS the request will be sent over HTTP

Domain

This is the URL where you are sending the request (without the HTTP or HTTPS)

Timeout(seconds)

Enter how long you will wait for a response from the server

Require Authentication

Tick if your server requires authentication

Username

Username

Password

Password

 

Request

Field

Description

Input Path URL

Enter the api endpoint you will be using which will be added to the URL you added on in the Domain field

Path Variables

This is used if you need to insert a variable passed from the IVR into the path of the API request, for example the number the caller is dialling from or a reference number keyed in by the caller after a prompt in the IVR

To get this to show you need to enter the name of the variable enclosed by % signs. This will be referenced in the 'Webservice Connector' object in the IVR workflow.

For example this API provided by http://v0.postcodeapi.com.au/ returns the Australian suburb name based on the post code 2090

http://v0.postcodeapi.com.au/suburbs/2090.json

We need to change the 2090 to a dynamic value that can be entered on the caller's keypad. So in the 'Input Path URL' field above we need to enter:

/suburbs/%postcode%.json

The text entered between the percentage signs will then show in the 'Path Variables' section

Request Headers

Enter any Request headers that need to be added to the request. This is generally used to send Authentication information such as API keys

Header Description: this can be any string to describe what the header is used for

Header Name: this is the name of the header that is required by the server

Required Value: tick this if this is a mandatory Header

Static Value: enter a static value

Request Query Params

Some endpoints use path variables which you can add here. These act as a placeholder for variables passed from the IVR.

 

Param Description: this can be any string to describe what the variable is

Param path: this is the name of the variable on the server

Required Value: tick this if this is a mandatory variable

Static Value: enter a static value

 

Response

Field

Description

Param Description

Any string to describe the what the result is. This will be used to identify the response sent to the Web Service Connector object in the Workflow

Param Path

The response from the query above will come back as XML or JSON, you can parse or select part of that response using this field. To do that you need to enter the path to the parameter you need.

For example:

To get the name from the first array in the following JSON sample you will need to enter the following in this field:

0/name

To get the state name:

0/state/name

JSON Sample

[{"name": "Cremorne Junction", "postcode": 2090, "state": {"name": "New South Wales", "abbreviation": "NSW"}, "locality": "CHATSWOOD", "latitude": -33.829999999999998, "longitude": 151.22669999999999}, {"name": "Cremorne", "postcode": 2090, "state": {"name": "New South Wales", "abbreviation": "NSW"}, "locality": "CHATSWOOD", "latitude": -33.833300000000001, "longitude": 151.22499999999999}]
CODE

 

 
CODE

 

 

 


3. Presenting Web Service Information about a Caller to an Agent

Web services can be used to pass the caller number to a 3rd party database or service and then return some data about the caller that can be presented to the agent to use during the call.

In this article I am going to use an API called Numverify (it allows 250 calls per month for free) to demonstrate how you can use this feature, the same process can be used for any REST API.

Steps to Create:

  1. Sign up for a free account at https://numverify.com/ - take note of your API key

  2. Open the Workspace go to Integration>Web Services

  3. Add a new Web service with the following settings (see above for more information) 

  4. Test your connection by going to the to the 'Test' tab, enter a phone number including the IDD and press send:

  5. Verify that the connection has been a success:

  6. Create the Campaign where you would like the call to terminate. add Agents and Wrap Codes

  7. We now need to create the Workflow that will use this Web Service. To do that you need to go to the Workspace select Resources > Workflows and then add a new one:

    1. Add 'Play Sound' object

    2. Add 'Web Service Connector' object

      Workflow ObjectSelect the 'Web Service Connector objectWorkflow Object TitleGive the object a meaningful titleWeb Service ConnectorSelect the Web Service Connector you created in step 3Web Service Connector ParamsThese are the parameters you defined when you created the Web Service: Input Params: These are the variables that you send to the 3rd party. In this example we are sending the callers phone number which needs the following syntax %ivr:activity_source% Output Params: These are the results returned from the third party, in this example, we are getting the country, carrier, and line type. On the right, you need to add the label of the field which will be used to pull these details into the agent's call scriptwhich you will see below

    3. Add 'Join Queue' object, save 

  8. Create a Script associated with the campaign you created in step 6 which we are going to use to present the country name and carrier of the caller to the agent. We can do this using the HTML  editor  in the script designer:

    Ensure you submit and then publish your script

  9. Go to Channels > Voice, select a number, and associate it with the Workflow created in step 7

  10. Log in to the agent toolbar as an agent who is assigned to the Campaign we created in step 6

  11. Call the number you selected in step 9 and the agent should be presented with information about the caller when they answer the call


4. Using Web Services to Black or White List Numbers

Web Services can be used to reference a list of numbers that are either whitelisted or blacklisted, this is useful to block prank callers or only enable authorised phone numbers to a helpdesk. In this example, we are going to use the ipSCAPE API to reference numbers added to a list in ipSCAPE which contains numbers that we want to block. The API will return a 0 if the number is not on the list or a 1 if it is. Based on the result we will branch the Workflow to either add to a campaign or play a message asking them not to call again.

  1. Create an Outbound Campaign

  2. Create a Lead List for that campaign, and add the numbers you would like to block (one by one or importing a spreadsheet)

  3. Go to Integrations > Web Services add a new one called Authentication which will open a session that will allow subsequent API calls. You will need an API key (found in Integration>API keys) and the ipSCAPE Workspace user account with permission to use Web Services and access to the campaigns and lead list you added the blocked numbers to. The web service should have the following settings:

    ipSCAPE Endpoint parameters:

     /api/latest/user/login?apiKey=XXXXXXX&destinationState=Login&updateState=1
    CODE


    This needs to be modified to include an API key from your instance found in Integrations > API Keys

    Once all details entered go to the test tab and check that the API call works.

  4. Create a second web service that will 

    You will need to add the details to the right with some changes outlined below:Domain - needs to be your ipSCAPE DomainInput Path URL - this is the ipSCAPE API endpoint we are using Authorization - this comes from the ipSCAPE API console (see instructions on how to use the API console)X-Ipscape-org - needs to be your ipSCAPE DomaincampaignId - is from the campaign that you created in step 1. You will need to ask your local ipSCAPE provider to get the ID from the database

    Then go to the test tab and check a phone number that has been added to the Campaign lead list you created in step 1

     

  5. We now need to create the Workflow that will use these Web services: