AVANSER Telco API - Product Outline and Examples

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 Classes

GEO

Geographical numbers, also known as Landline numbers or Local numbers

TOLLFREE

Toll Free numbers provide the same rate for the calling party independent from the area

FREECALL

Free Call numbers provide free of charge landline calls for the calling party1

MOBILE

Mobile numbers

AVANSER stocks are managed on a per demand basis, this means AVANSER will order a specific amount of numbers in specific areas based on the demand.

Of course, it is possible to request specific numbers from AVANSER support when needed, but if you are planning to automate a provisioning system you may want to look at two private stock options that may better suit your needs.

Private Stock Model

Having a private stock allows you to manage your private number selection based on your business requirements forecast.

Private stock is not a restrictive option, rather you can choose to have private stock for a specific number class (Eg. Australia, Mobile) but use AVANSER public stock for all other Countries/Number Classes. 

Private stock can be configured with two options; Private and Strict Private. 


PRIVATE

You can order your numbers freely and if you run out of Private stock, you will be provided with numbers from the Public stock.

STRICT PRIVATE

Once the private stock is empty the system will not provide any public numbers automatically. Further contact with AVANSER support is required to order new numbers.

If your demand for numbers is considerably high, AVANSER suggests switching to Private stock.

Please note, private stock has a different pricing model; get in contact with your  AVANSER Account Manager for more details.

Using the Telco API

AVANSER’s Telco API is designed to ease interaction with your stock and provide a flexible JSON API.

The API provides access to a request based number provisioning model; each request change is reported using a HTTP GET callback mechanism as well as a per-call event model that allows call reporting, making it easier to automate actions on your side.

Each request carries the initial configuration for the number. If a number matching the provided criteria is found in the client’s stock or the public stock, the number is immediately activated and ready to be used within minutes. The request list and request status is available with the API, providing real time request monitoring.

The AVANSER Telco API unifies several technologies already available to the AVANSER support team such as target number changes, email notification updates, per-call HTTP callbacks (if supported by the number) and SMS HTTP GET forwards to desired addresses.

You can configure your numbers and how they interact with you or your customers. You also have three different ways to report your calls back to you or your customers -  sms, email and HTTP callback.

The Telco API gives you access to an HTML templating system that allows you to customise your customer's experience.

Changes to your services can be performed in complete autonomy.

The Telco API can help you manage your customers’ numbers in a more clear manner. Using an account based system, your clients can simply sign up and AVANSER will do all the work while you directly manage your customers’ numbers, making the Telco API an essential tool to optimise your workflow and let you focus only on your customers.


The contents of this document are intended for explame purposes only, for a extensive and updated documentation please refer to to the online documentation available at: http://docs.avansertapi.apiary.io

Road Map and future changes

AVANSER’s Telco API is under active development, the current road map includes (but is not limited to):


Call Request

Initiate calls between two parties using AVANSER. Add call tracking to your desired tool.

SMS capabilities

Send SMS and manage your inbound SMS4.

Call Reports

Access your call log or export it to your desired dashboard/3rd Party tool.

Dynamic Numbers

Manage your dynamic numbers configuration and automate installation of the AVANSER code with our Google Tag Manager-friendly tool set.

The road map is demand based; if you would like to request a new feature or have a planned feature prioritised, please inform us as we would like to know about your request.

Development tools

When interacting with an API it is important to use the right tools. To that end we have ensured our API documentation is available in API Blueprint format in conjunction with PostMan, allowing you to have documentation and a test environment on your desktop.

PostMan supports Windows, Linux and MacOS and offers multiple “code convert” options to ease integration of the API with your prefered technology. 

AVANSER offers a sandbox environment to help you through your first steps with the Telco API. The sandbox environment address is available in the documentation. Apiary offers the same advanced features of PostMan, minus the local storage to cache the requests and replies.

We suggest you create your own Telco API collection for PostMan. Download the blueprint from apiary and we will keep you informed about changes.

We can also provide a PostMan collection if needed. Please submit us a request.

References

  1. Telco API, blueprint

  2. API Blueprint outline

  3. PostMan

  4. Apiary - Postman converter tool

Workflow examples

These examples are designed to give you a quick look into the potential of the Telco API.

The examples use the cURL command line interface but you can use your desired tools.

Please note, the “dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm” authentication token is a sample one. To know more about how to generate a http basic authorisation token, you can read the Wikipedia article here.

Search your inventory stock

Perform a search request to your inventory, the response depends on number availability and the numbers currently in stock.

Note: all cURL commands are single lines.

Request available numbers for Sydney

curl -X GET 'https://tapi.avanser.com/v1/numbers?country=AU&szu=sydney'  - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm’


Response Reply

{

    "@transaction": {

        "id": "9b9ee53663816df8eb66d694383f3ef9e2ee8ddf",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "GET",

            "path": "/v1/numbers?country=AU&szu=sydney",

            "time": "2017-06-14T10:19:24+10:00",

            "ms": "0.711"

        }

    },

    "response": {

        "61280740802": {

            "country": "AU", "region": "NSW: Sydney", "type": "GEO",

            "national": "0280740802", "calling_code": "+61", "pool": "private"

        },

        "61280740805": {

            "country": "AU","region": "NSW: Sydney","type": "GEO",

            "national": "0280740805","calling_code": "+61","pool": "private"

        }

    }

}

Request a new service

When creating a new service there are many options available. The following examples show how to create a service with the Call Recording feature enabled.

When creating or updating a Service Number you can pick from your available numbers using the following criteria:

  • by Location

  • by Coordinates

  • by Matching prefix

  • by Number Type

  • by SZU (Australia Only)

When creating or updating a Service Number you can also configure:

  • Missed Call Notification

    • Upon call completion a Mail and/or SMS will be sent to the desired recipients.

  • Call-URI Notifications

    • Upon call completion selected URI will be called with all call data information.

  • SMSForward-URI

    • (Mobile only) Upon SMS received selected URI will be called with all SMS information.

  • Customise

    • Call Greeting

    • Call Whisper

    • VoiceMail greeting

Request a new number from the inventory

Submit Request

curl -X POST https://tapi.avanser.com/v1/requests - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

 -d '{

 "name": "service #1",

 "custom_id": "custom_id #1",

 "custom_group": "custom_group #1",

 "service_number": {

 "country": "AU",

 "search_type": "number",

 "number": "61280740801"

 },

 "service": {

 "type": "transfer",

 "answer_point": "61401603859",

 "answer_point_name": "answerpoint #1",

 "record_call": true

 },

 "call_uri": "http://desired.uri.to/debug.php?call_uri=service1",

 "callback_uri": "http://desired.uri.to/debug.php?callback_uri=service1"

}'


Acknowledgment Reply

{

    "@transaction": {

        "id": "a852650ae8689da0b0632f0c6c276e919d7a7b6e",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/requests",

            "time": "2017-06-14T10:29:49+10:00",

            "ms": "0.622"

        }

    },

    "response": {

        "request_id": "a852650ae8689da0b0632f0c6c276e919d7a7b6e",

        "message": "Success",

        "code": 200,

        "service_number": "61280740801"

    }

}


When the process is complete you will receive a HTTP Post with a JSON Body.

Confirmation Callback
Received on specified URI-endpoint
{

  "account_id": "7xxx",

  "request_id": "3b9b2298b519cef79c6c1638f4d54ddae19ba034",

  "custom_id": "custom_id #1",

  "custom_group": "custom_group #1",

  "service_number": "61280740801",

  "answer_point": "61401603859",

  "message": "Request completed successfully",

  "status": "completed"

}

You can use the automated search functionality to perform a search and automatically configure the number as specified upon a successful search.

TIP: “number” search_type allows you to pass your answer point as a number field; this way our system will try to find the closest match to the answer point.
Please note, search is performed according to client's inventory stock options.

Submit Request

curl -X POST https://tapi.avanser.com/v1/requests - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

 -d '{

 "name": "service #3",

 "custom_id": "custom_id #3",

 "custom_group": "custom_group #3",

 "service_number": {

  "country": "AU",

  "search_type": "szu",

  "szu": "sydney"

 },

 "service": {

 "type": "transfer",

 "answer_point": "61401603859",

 "answer_point_name": "answerpoint #3",

 "record_call": true

 },

 "call_uri": "http://desired.uri.to/debug.php?call_uri=service1",

 "callback_uri": "http://desired.uri.to/debug.php?callback_uri=service1"

}'


Acknowledgment Reply
{

    "@transaction": {

        "id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/requests",

            "time": "2017-06-14T10:37:56+10:00",

            "ms": "0.587"

        }

    },

    "response": {

        "request_id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

        "message": "Success",

        "code": 200,

        "service_number": "61280740805"

    }

}


When the process is complete you will receive a HTTP Post with a JSON Body.

Confirmation Callback
Received on specified URI-endpoint

{

  "account_id": "7xxx",

  "request_id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

  "custom_id": "custom_id #3",

  "custom_group": "custom_group #3",

  "service_number": "61280740805",

  "answer_point": "61401603859",

  "message": "Request completed successfully",

  "status": "completed"

}

Submit a service update

The Telco API allows you to modify each service previously created as shown in this example.

Submit Request

curl -X POST https://tapi.avanser.com/v1/services/61280740801 - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

  -d '{

  "service": {

    "answer_point": "61132307"

  },

  "call_uri": "https://desired.uri.to/debug.php?call_uri=service1&new-call-uri=1",

  "callback_uri": "https://desired.uri.to/debug.php?callback_uri=service1&updated=true"

}'


Acknowledgment Reply
{

    "@transaction": {

        "id": "c05977971a1d9fbe8eaa3a410f63d02ea5375c04",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/services/61280740801",

            "time": "2017-06-14T10:56:42+10:00",

            "ms": "0.166"

        }

    },

    "response": {

        "request_id": "c05977971a1d9fbe8eaa3a410f63d02ea5375c04",

        "message": "Success",

        "code": 200,

        "service_number": "61280740801"

    }

}


When the process is complete you will receive a HTTP Post with a JSON Body

Confirmation Callback
Received on specified URI-endpoint
{

  "account_id": "7xxx",

  "request_id": "43b1fbeec99581407cfe31908930c43fec066d3c",

  "custom_id": "",

  "custom_group": "",

  "service_number": "61280740801",

  "answer_point": "6113008786264",

  "message": "Request completed successfully",

  "status": "completed"

}


Call-URI reports

Upon call completion all information about the call is sent to the selected “Call-URI”. This feature is configured upon service creation and the desired URI can be updated with an “Update” request.

What follows is an example:


METHOD

GET

REMOTE URI

http://desired.uri.to

REQUEST PARAMETERS

call_uri = service1

clientid = 7xxx

callid = 36012012

uniqueid = ECS1-1497163757.20486

bnum = +61-0280740801

adname = service #1

target = +61-0401603859

targetname = answerpoint #1

ani = +61-0405061663

tzdate = 2017-06-11T16:49:17+10:00

duration = 15

callstatus = avanser_answered_call

callcode = 1

clocation = Mobile

cstate = MOB

ccountry = AU

custom_id = custom_id #1

custom_group = custom_group #1




    • Related Articles

    • 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 ...
    • 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 ...
    • 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 ...
    • Dynamic Numbers: Installing jQuery - Required by AVANSER Tag Manager

      Installing jQuery Library is not required if you are using Dynamic Numbers' Automated Number Replacement or you are not using AVANSER Tag Manager. The AVANSER Tag Manager allows you to set rules for your website that dynamically adds span tags to 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 ...