AVANSER API Services Quick Reference Summary

AVANSER API Services Quick Reference Summary

Summary

The Objective of this document is to outline the various APIs AVANSER offers for both collection of data and remote service interaction.

Individual documentation for all APIs is available in the table below:

API

Link

Telco API

Enables the customer to provision and maintain numbers through a restful API.

https://avansertapi.docs.apiary.io/

HTTP Callback

HTTP url is called upon call completion providing all required information for that call.

https://avansertapi.docs.apiary.io/#introduction/call-uri-functionality

SMS Forward

HTTP url is called upon receiving an sms from an sms enabled number.

https://avansertapi.docs.apiary.io/#introduction/sms-forward-functionality

WebAPI

A restful API for reporting purposes, reports the call data according to request parameters.

https://avanserwebapi.docs.apiary.io/#

UserAPI

Restful ApI designed to interact with our system "as a user" allowing integration with 3rd party services providing a framework for integration.

https://avanseruserapi.docs.apiary.io/#

ARTIC API

ARTIC API allows customer to retrieve all ARTIC data via the ARTIC Reporting API and perform Agent operations using the ARTIC Actions API

https://avanserarticapi.docs.apiary.io/#

Data Feed

Custom JSON/XML/CSV feed API, "feed" urls are provided for remote systems to download the most recent data set.

This integration is currently available for call records only, example json and csv examples are provided with this document. Due to the custom nature of the integration

a dedicated document is required.

Number Provisioning

Through the TelcoAPI it is possible to create services in the AVANSER System.

The Telco API is designed to automate the process of managing client number inventory.
Once the numbers are assigned to a client’s private pool of numbers, the client will be able to:

  • List their available numbers.

  • Configure a new service.

  • Update an existing service.

  • Decommission an existing service.

An important feature of the Telco API is the "Custom ID" and "Custom Group". These two IDs are available for the client to set at the number level and will automatically populate each call with the applicable value. AVANSER Reporting APIs will then report the values for each call record that the client retrieves.

The Telco API uses HTTP Basic Authentication over Secure Socket Layer (HTTPS).

It has an asynchronous model to submit the requests:

  1. Submit the request with an HTTP callback URL.

  2. Callback URL is called when the request is completed.

  3. Request status can also be polled via a dedicated API request.


It allows the client to create the following service types:

  1. VoiceMail: A recording is played to the caller, after which they can leave a voice message.

  2. Prompt: A recording is played to the caller. Is generally used for notification purposes.

  3. Transfer: The answer point phone the call is transferred to.

  4. Additional service features are available upon request.


Each Service Type can be configured with the following options:

  • Email and SMS Notifications: Emails and/or SMS are sent to the desired recipients depending on call status (refer to API reference document).

  • HTTP Call Back: A URL is called each time a call is completed.

  • SMS Forward: A URL is called each time an sms is received - Requires a Virtual Mobile Tracking Number.


Provisioning Model


This is the model that is currently implemented, with orange numbers denoting processes at the client’s side and blue numbers processes at AVANSER's side.
  1. A NEW AD is requested and a NEW NUMBER REQUEST is submitted to the AVANSER Telco API. This request specifies both "custom_id" and "custom_group" for attribution purposes.

  2. The number selected from the available number list is returned in real-time.

  3. The AVANSER System configures the service on the phone network.

  4. The AVANSER System reports the service has been configured. On average it takes 7 minutes for the change to propagate to all servers of AVANSER's Network.

  5. A test call is automatically conducted and the data sent via HTTP Callback. (Requires Subscription)

  6. Client receives the data.

  7. Ad Number is live.

Reporting

Call Data reporting is available via through the following methods:
  • HTTP Callback: URI reporting method which is configured autonomously via the Telco API. This method calls a URL for every call received by the AVANSER system. 

  • Data Feed URL that provides the Client with the most recent data according to a predefined format. For example calls can be reported by year, month, day but also calling number, call status, custom_id and custom_group. Feeds are available in CSV, JSON and XML format. 

  • WebAPI to build the Client’s own request parameters and get the results in JSON and XML format. Rate limits apply.

  • ARTIC API to fetch ARTIC Call Center data similarly to the WebAPI but with in-depth access to call center specific reporting.

Reporting Model

  1. AVANSER System receives a call.

  2. AVANSER connects the caller to the desired answering number.

  3. Call completes.

  4. AVANSER system reports depending on the configuration.

  5. Data is ready for the client to use.


HTTP Callback

AVANSER can will send an HTTP Callback to the customer as soon as the call is completed and the Post-Call processing is done. HTTP Callback can be configured automatically via the TelcoAPI or manually through the AVANSER Portal.

An example HTTP Callback URL is as follows:

https://www.client.com.au/avanser/call?clientid=[[clientid]]&callid=[[callid]]&uniqueid=[[uniqueid]]&bnum=[[bnum]]&adname=[[adname]]&target=[[target]]&targetname=[[targetname]]&ani=[[ani]]&tzdate=[[tzdate]]&duration=[[duration]]&callstatus=[[callstatus]]&callcode=[[callcode]]&clocation=[[clocation]]&cstate=[[cstate]]&ccountry=[[ccountry]]&custom_id=[[tag]]&custom_group=[[curl]]



Query Parameter

Tag

Description

clientid

[[clientid]]

AVANSER's Client ID

callid

[[callid]]

Unique Call ID

uniqueid

[[uniqueid]]

Unique Call Tag

bnum

[[bnum]]

Tracking Number - This is the number activated through the API or through our Support

adname

[[adname]]

Tracking Number Name - Friendly name assigned to the Tracking Number

target

[[target]]

Answer Point Number - This is the number you requested the calls to be transfered

targetname

[[targetname]]

Answer Point Name - Friendly name assigned to the Answer Point Number

ani

[[ani]]

Caller Party - This is the number of the Caller Party, your clients' customer number - ANI : Automatic Number Identification.

tzdate

[[tzdate]]

Date with timezone

duration

[[duration]]

Call Duration

callstatus

[[callstatus]]

Call Status

callcode

[[callcode]]

Call Status Code

clocation

[[clocation]]

Caller Location

cstate

[[cstate]]

Caller State

ccountry

[[ccountry]]

Caller Country

custom_id

[[tag]]

custom_id, managed by the Telco API

custom_group

[[curl]]

custom_group, managed by the Telco API


Tags are replaced with the relevant values from the call data.

HTTP Callback: Full Parameter List

Parameter

Tag

Description

AVANSER's ClientID

[[clientid]]

Unique for each account

AVANSER's CallID

[[callid]]

Unique for each call

Call Status

[[callstatus]]

Descriptive text of the call status

Call status code

[[callcode]]

Call status code 0,1,2,3,4,7,8

Avanser's UniqueId

[[uniqueid]]

Unique id for each call

adSource Name

[[adname]]

As configured in the Portal

Avanser's Bnum

[[bnum]]

Service Tracking Number (format +CC-LOCAL)

Call duration

[[duration]]

Call Duration in seconds

Unixtime, now

[[unixtime]]

Unix timestamp of the call

ISO 8601 date

[[tzdate]]

ISO 8601 format string

Call Date (d/m/Y)

[[calldate]]

day/month/year format

Call Date (seconds)

[[ucalldate]]

UTC timestamp of the call

Calling number

[[ani]]

Calling Number (format +CC-LOCAL) or "Private"

Target number

[[target]]

Answer Point the call was sent to

Call location

[[clocation]]

Detected call location

Call state

[[cstate]]

Detected call state

Call country

[[ccountry]]

Detected call country

Target name

[[targetname]]

Answer Point name as configured in the Portal

Call label

[[label]]

Call Label set through the dialler

Call parameter #1

[[cd_cp01]]

Feature Tracking: Feature value

Feature #1

[[feat01]]

Feature Tracking: Feature1 name

Call parameter #2

[[cd_cp02]]

Feature Tracking: Feature value

Feature #2

[[feat02]]

Feature Tracking: Feature1 name

Call parameter #3

[[cd_cp03]]

Feature Tracking: Feature value

Feature #3

[[feat03]]

Feature Tracking: Feature1 name

Call parameter #4

[[cd_cp04]]

Feature Tracking: Feature value

Feature #4

[[feat04]]

Feature Tracking: Feature1 name

Call parameter #5

[[cd_cp05]]

Feature Tracking: Feature value

Feature #5

[[feat05]]

Feature Tracking: Feature1 name

Call parameter #6

[[cd_cp06]]

Feature Tracking: Feature value

Feature #6

[[feat06]]

Feature Tracking: Feature1 name

Call parameter #7

[[cd_cp07]]

Feature Tracking: Feature value

Feature #7

[[feat07]]

Feature Tracking: Feature1 name

Call parameter #8

[[cd_cp08]]

Feature Tracking: Feature value

Feature #8

[[feat08]]

Feature Tracking: Feature1 name

Call parameter #9

[[cd_cp09]]

Feature Tracking: Feature value

Feature #9

[[feat09]]

Feature Tracking: Feature1 name

Call parameter #10

[[cd_cp10]]

Feature Tracking: Feature value

Feature #10

[[feat10]]

Feature Tracking: Feature1 name

IVR Selections

[[ivr]]

IVR selections

User's visited page

[[dl:url]]

Dynamic Numbers: website hit

Search Source

[[dl:source]]

Dynamic Numbers: source

Search Medium

[[dl:medium]]

Dynamic Numbers: medium

Search Keywords

[[dl:term]]

Dynamic Numbers: keywords

Search Campaign

[[dl:campaign]]

Dynamic Numbers: campaign

Web, location

[[dl:location]]

Dynamic Numbers: user's location

Web, state

[[dl:state]]

Dynamic Numbers: user's state

Web, country

[[dl:country]]

Dynamic Numbers: user's country

GA User Code

[[web:usercode]]

Google Analytics: User Code

GA Session Code

[[web:sessioncode]]

Google Analytics: Session Code

GA Client Id

[[web:usercode]].[[web:sessioncode]]

Google Analytics: Client ID

Google Click Id

[[web:gclid]]

Google Analytics: Click ID

Downloadable Audio URL

[[audio]]

Audio download url

A-Party E.164 Phone

[[aparty:e164]]

Caller/Callee Number E164 format

A-Party State

[[aparty:state]]

Caller/Callee Number state 

A-Party Country

[[aparty:country]]

Caller/Callee Number country 

B-Party E.164 Phone

[[bparty:e164]]

Service Number E164 format

C-Party E.164 Phone

[[cparty:e164]]

Caller/Callee Number E164 format

C-Party Country

[[cparty:country]]

Caller/Callee Number country 

Call Disposition

[[call:disposition]]

Hangup: IVR, BUSY, ANSWERED, NO ANSWER, FAILED

UTC Date

[[call:utcdate]]

UTC call timestamp

Call Direction

[[call:direction]]

Call Direction, call-in or call-out

Sentiment Score

[[sentiment:score]]

Sentiment Analysis: summary score

Agent Sentiment

[[sentiment:agent]]

Sentiment Analysis: agent score

Caller Sentiment

[[sentiment:caller]]

Sentiment Analysis: caller score

Talk Most

[[sentiment:talkMost]]

Sentiment Analysis: who talked the most

Communication

[[sentiment:communication]]

Sentiment Analysis: communication score

Conduct

[[sentiment:conduct]]

Sentiment Analysis: conduct score

Agent Politeness

[[sentiment:politeness]]

Sentiment Analysis: agent politeness score

High Risk Call

[[sentiment:highRisk]]

Sentiment Analysis: call marked as high risk

Call Attitude

[[sentiment:badAttitude]]

Sentiment Analysis: bad agent attitude detected

Slang Used

[[sentiment:slangUsed]]

Sentiment Analysis: slang was used

Profanity Used

[[sentiment:profanityUsed]]

Sentiment Analysis: profanities were used


Data Feeds

Data feeds are static feeds that can be called and cached as desired. The default configuration sets the feed as a "catch-all" for all call records and organises them in a structured manner. The feeds can be accessed via HTTPS request and HTTP Basic Authentication can be enabled to access such data as well as call recording data.

Multiple methods of authentication can be configured:

  • IP Address Whitelisting.

  • Static HTTP Basic password.

  • HTTP Digest (available on request, scoping is required).

Data output can be customised to match the Client’s specific needs.

Below is an example of the data returned by AVANSER’s standard feed. Data is aggregated by Year, Month and Day.


[{

call_audio_url: "",call_connection_duration: 1,call_direction: "call-in",

call_duration: 17,call_end_time: "2020-05-26 17:00:18",call_has_audio: 0,

call_id: 67643772,call_is_artic: 0,call_local_time: "2020-05-26 17:00:01",

call_param_0[1-7]: 0,call_param_08: "",call_param_09: "",call_start_time: "2020-05-26 17:00:01",

call_status: "Missed",call_status_code: 1,call_talk_duration: 16,

call_timezone: "Australia/Sydney",call_tz_end_time: "2020-05-26T17:00:18+1000",

call_tz_start_time: "2020-05-26T17:00:01+1000",call_u_end_time: 1590476418,

call_u_start_time: 1590476401,call_unique_id: "ECS8-1590476401.423578",

caller_country: "AU",caller_location: "Sydney",caller_number: "+61-0290088888",caller_state: "NSW",

client_id: 5995,

custom_group: "",custom_id: "",

private_reference: null,

target_name: "Target Name",target_number: "+61-0289995916",

tracking_master_id: 0,tracking_name: "Tracking Service Name",tracking_notes: "",

tracking_number: "+61-0289996235",tracking_wpc_id: 0

}]


Data feeds can be set up concurrently with other reporting methods (HTTP Callback/Web API). AVANSER recommends the download and storing of the dudata at Client’s side to ensure a quicker response on larger data sets. Data feeds are available in JSON, CSV and XML format.
Highlighted in blue are the custom_id and custom_group which are to be used for attribution at the Client’s side.

Data feeds can be automatically uploaded to a desired destination on a daily basis.

Number Inventory

When managing an inventory of numbers there are some guidelines that AVANSER suggests be followed when it comes to number recycling and handling of the number inventory.

For regular clients AVANSER automatically handles the inventory, ensuring that any numbers made available for provisioning have already passed rigorous quarantine procedures. This incorporates checks to determine that the number is no longer "noisy".

A “noisy” number is a number that still receives calls for the previous owner after it has been cancelled. Only numbers that have been proven not to still be receiving calls for the previous owner are released to the public number pool. This process usually takes from three to six months.

For use cases that involve a large quantity of numbers (1000+), the public pool may be insufficient to guarantee the numbers are always available in the quantity required. Therefore an alternative solution is available.

AVANSER can provide a "Private Inventory", configured with its own customised rules which can be tailored to suit the Client’s business rules. This will not only ensure availability of numbers in the quantity required, but also allow the Client to choose when and how to safely recycle the numbers. These rules must be defined by the Client and discussed before the Inventory can be made available. They can be fully automated to minimise inventory maintenance and the Telco API can be customised to allow for recycling of a number upon request.

Once the Client and AVANSER agree on the exact volume of numbers required, AVANSER will assist in determining the size of the inventory and will provide feedback on ways to optimise the number usage to reduce inventory bloat and cost.




    • Related Articles

    • AVANSER Telco API - Product Outline and Examples

      Understanding AVANSER number stock When automating number provisioning it is important to know your inventory configuration. Your inventory is managed by Country; each Country has different number classes available for your tracking needs. Number ...
    • AVANSER API and Third Party Integration

      There are two main ways to integrate with 3rd Party APIs: 1. WebAPI: The documentation is available here: https://avanserwebapi.docs.apiary.io/ Test system information: The test environment isavailable at https://api.test.avanser.com/JSON/ 2. HTTP ...
    • Call Evaluation Overview

      Call evaluation tool allows businesses to rate all calls and give insight into the content of calls. You will have tangible evidence on which key areas need improvement and what your clients are calling about.  This tool provides the user with the ...
    • Dynamic Numbers: Service Summary

      AVANSER Dynamic Numbers is a service designed to replace the Phone Numbers in your Website with an AVANSER Tracking Number, this process does not change the source code of your Website, but, instead, process your Website when is displayed to ...
    • Dynamic Numbers: Reactive Websites, Responsive Web Applications or Progressive Web Applications

      When presenting contact details in Reactive Websites, Responsive Web Applications (RWA) or Progressive Web Applications (PWA) it is important to always display the correct number. In the past years the trend of using RWA or PWA technologies to build ...