Web Services
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:
Log in to the Workspace
Goto the Integration Menu
Select 'Web Services'
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: 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
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:
Sign up for a free account at https://numverify.com/ - take note of your API key
Open the Workspace go to Integration>Web Services
Add a new Web service with the following settings (see above for more information)
Test your connection by going to the to the 'Test' tab, enter a phone number including the IDD and press send:
Verify that the connection has been a success:
Create the Campaign where you would like the call to terminate. add Agents and Wrap Codes
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:
Add 'Play Sound' object
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 script, which you will see below
Add 'Join Queue' object, save
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
Go to Channels > Voice, select a number, and associate it with the Workflow created in step 7
Log in to the agent toolbar as an agent who is assigned to the Campaign we created in step 6
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.
Create an Outbound Campaign
Create a Lead List for that campaign, and add the numbers you would like to block (one by one or importing a spreadsheet)
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=1CODE
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.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
We now need to create the Workflow that will use these Web services:
