This document describes the first step to access the Business Talk API and proceed to your first voicesite order.

Introduction

Prerequisite

Business Talk API requires an access_token. This authentication method is described here.

Terminology:

• client: your application that will make Orange API calls
• api key: the token needed to access your customer data through the API
• endpoint: the url to access, in REST, to a function of the API
• header: a user defined HTTP header used to carry information in a REST call

Use cases:

• [Get your API KEY](#api-key)
  

• [Basic API request](#basic-request)
  

• [Get your customer code](#getting-vpns)
  

• [Get your VPNs](#getting-vpns-1)
  

• [Get country coverage information](#getting-country)
  

• [Create your voicesite order](#creating-voicesite-order)
  

• [Consult your new voicesite](#getting-voicesite)
  

API Setup

Before starting

In order to be able to make calls to the Business Talk API, you need credentials for your application. To get these credentials, you need to create an account and register your application on the Orange Developer Portal. You will be able to proceed to full registration step only if your company is a Business Talk customer.

Here are the steps of this registration process :

• Log in / create an account on Orange Developer (if you have an Orange Partner account you can use the same login credentials)
• Validate your email (if you're creating a new account)
• Go to 'My Apps' and register an app
• Click 'Add API' and select 'Business Talk OBS'
• You will be prompted to enter your 'API contract ID'. You can get this information from you Business Talk Online selfcare portal.

At the end of this registration process, you will be provided with :

• client identifier: a unique ID provided by the Orange backend server to identify your application
• client secret: it is used to get a token for initial access

Get your API KEY

To access the API, the first step is to create an 'api key'. To get this 'api key', go to your Business Talk Online portal, on the 'Developer' tab. Create an api key with the right profile that you need. The api key takes the form of a 40-characters string. Once you have created the api key, you shall note it as it will be required for all API requests.

An api key is a key information to access your account, so you shall not communicate it to untrusted persons. If needed, you can revoke any api key by deleting it on your Business Talk Online portal.

The api key must be provided in all API requests into the X-BT-API-KEY header.

Basic API request

The '/me' request is a basic request which allows you to check if your access to the API is valid, and the rights profile associated to the api key.

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
	 -H "X-BT-API-KEY: a84ber884cd...99dd" \
     https://api.orange.com/btalk/v1/me 

This request returns JSON data containing the rights profile.

{
  "rightsProfile": "readonly"
}

API Basic Usage

Get your customer code

For many request, you need to use your 'customerCode'. This is an invariable integer which identifies your customer account in the system. To get your own customerCode, you can use the following request:

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     -H "X-BT-API-KEY: a84ber884cd...99dd" \
     https://api.orange.com/btalk/v1/customers

This request returns JSON data containing the customers that you are allowed to manage (typically, one customer entry).

[
  {
    "name": "My Customer",
    "customerCode": "9999",
    "contractNumber": "123456",
    "apiContractId": "ar45dv5s",
    "pricingApprovalNumber": "A123456789",
    "type": "direct"
  }
]

Get your VPNs

Before creating your first voicesite order, you need to define on which voice VPN this voicesite will be created. To get your VPNs, you can use the following request:

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     -H "X-BT-API-KEY: a84ber884cd...99dd" \
     https://api.orange.com/btalk/v1/customers/9999/vpns

Note the path in the request contains your 'customerCode', 9999 in the example above.

This request returns JSON data containing all VPNs of your customer account.

[
  {
    "vpnId": "aa76e66dfc63",
    "name": "My VPN 1",
    "vpnCode": "1"
  },
  {
    "vpnId": "3a45b33edf3",
    "name": "My VPN 2",
    "vpnCode": "2"
  }
]

Get country coverage information

The voicesite order can be created only on covered country. Assuming that you want to create a voicesite in France (FR), you can check the Business Talk Online availability with the following request:

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     -H "X-BT-API-KEY: a84ber884cd...99dd" \
     https://api.orange.com/btalk/v1/countries/FR

This request returns JSON data containing all coverage information of France.

{
  "name": "France",
  "coverage": {
    "businessTalkOnline": "Yes",
    "comment": "(1) Fax are supported only with VISIT certified fax designs. Contact Product for further information ",
    "domesticEmergency": "Yes",
    "enquiryDB": "Yes",
    "nonGeographicDest": "Yes",
    "modemISDNCall": "No",
    "faxISDNCall": "No",
    "voiceISDNCall": "No",
    "modemAnalogCall": "No",
    "faxAnalogCall": "Yes",
    "voiceAnalogCall": "Yes",
    "onnet": "Yes",
    "offnetIntenationalDest": "Yes",
    "offnetDomesticDest": "Yes",
    "didNumber": "Yes",
    "didNumberZone": "Zone1"
  },
  "iso2": "FR",
  "countryCode": "33"
}

The coverage information is provided by the 'businessTalkOnline' information.

Create your voicesite order

To create your voicesite order, you have to make a POST request to /customer/{customerCode}/orders/voicesite URI, specifying the basic parameters of your voicesite. This URI is used to create explicitly an order for the productReference 'voicesite'. For example:

curl -X POST \
     -H "Authorization: Bearer {access_token}" \
     -H "Content-Type: application/json"
     -H "X-BT-API-KEY: a84ber884cd...99dd" \
	 -d '{ \
	  "customerOrderReference": "myOrder", \
	  "parameters": { \
		"technicalSiteName": "MY_VOICESITE", \
		"customerSiteLabel": "My Voicesite in France", \
		"country": "FR", \
		"vpnId": "aa76e66dfc63" \
	  } \
	 }' \
     https://api.orange.com/btalk/v1/customers/9999/orders

In the response, you will get a JSON document with all details of the order and in particular the voiceSiteId which has been delivered for this order.

Consult your voicesites

You can consult all your voicesites, including the new one, by issuing a GET request as follows:

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     -H "X-BT-API-KEY: a84ber884cd...99dd" \
     https://api.orange.com/btalk/v1/voicesites

This request returns JSON data with all voicesites existing for your customer account.

Address management

Overview

The Business Talk service requires to provide a valid address to have access to local voice services. The address management is country dependent, however it is based on four possible (non exclusive) mechanisms:

• Address schema validation
• Address fields validation based on emergency services
• Full address validation
• Dialzone verification

The address in Business Talk relies on a standard schema (inspired for IEFT PIDFLO standard) with the following fields:

This schema is specialized on a per-country bases based on country specific schema, as described in the next sections.

Address schema validation

This mechanism is applicable to all countries. The API /countries/{iso2}/addressconstraints allows to retrieve the address for a given country.

This API provides a schema definition for each address element. When an address is pushed to a voicesite via the API /customers/{customerCode}/voicesites/{voiceSiteId}/voiceaddress, the address is verified with this schema. The sections below describe some examples of schema usage.

Free string or numerical element

A string address element is expected to be filled by the the customer with any string value (all UTF-8 characters are accepted).

A numerical address element is expected to be filled by the the customer with any numerical value (only digits 0 to 9 characters are accepted).

It is possible to define more advanced constraints:

• Minimum length
• Maximum length
• Regular expression

The typical configuration is:

• String with at least 1 character and at most 100 characters

{
  "a1": {
    "usage": "mandatory",
    "defaultLabel": "State",
    "defaultDescription": "Enter the state where your site is located",
    "referenceUrl": "",
    "valueType": "freestring",
    "minLength": 1,
    "maxLength": 100,
    "valueRegexp": "",
    "position": 10
  }
}

• Numerical value with at most 100 characters

{
  "a1": {
    "usage": "optional",
    "defaultLabel": "State",
    "defaultDescription": "Enter the state where your site is located",
    "referenceUrl": "",
    "valueType": "freenumerical",
    "minLength": 0,
    "maxLength": 100,
    "valueRegexp": "",
    "position": 10
  }
}

• String value with 5 characters and only letters and numbers (regular expression)

{
  "pc": {
    "usage": "mandatory",
    "defaultLabel": "Postal code",
    "defaultDescription": "Enter the postal code where your site is located",
    "referenceUrl": "",
    "valueType": "freestring",
    "minLength": 5,
    "maxLength": 5,
    "valueRegexp": "^[a-z0-9]{5}$",
    "position": 10
  }
}

Simple list of possible values

The configuration allows to define a list of possible values that will be displayed to customer. The element will only accept one of these values. If the element is optional, the empty values is also implicitly part of the possible values.

The possible values correspond both that list of possible values as displayed to the customer, and list of possible values as syntaxically verified and stored in the BL.

The typical configuration is:

{
  "a1": {
    "usage": "mandatory",
    "defaultLabel": "State",
    "defaultDescription": "Choose the state where your site is located",
    "referenceUrl": "",
    "valueType": "enumeration",
    "minLength": 1,
    "maxLength": 100,
    "valueRegexp": "",
    "possibleValues": [
        "New York",
        "Washington",
        "Alabama"
    ],
    "position": 10
  }
}

List of possible values with custom display

The configuration allows to define a list of possible values with:

• the list of possible values as syntaxically verified and stored in the BL
• for each value, a display string used of for display purpose

The typical configuration is:

{
  "sts": {
    "usage": "mandatory",
    "defaultLabel": "Street suffix",
    "defaultDescription": "Choose the street suffix where your site is located",
    "referenceUrl": "",
    "valueType": "enumerationAssociative",
    "minLength": 1,
    "maxLength": 100,
    "valueRegexp": "",
    "possibleValues": [
        {"value": "AVE", "display": "Avenue"},
        {"value": "RD", "display": "Road"},
        {"value": "DR", "display": "Drive"}
    ]
    "position": 10
  }
}

Address fields validation based on emergency services

It can be required that some address fields must match an existing geographical area which allows to determine the area for emergency services. This constraint is setup on a per country basis, not used for all countries and by definition is used only for countries where Business Talk provides access to emergency services.

This constraint relies on two APIs:

• /countries/{iso2}/geographicalconstraints: to retreive the country configuration
• /countries/{iso2}/geoareas: to retrieve the available geographical areas

Geographical constraint

This API provides a document with all geogrphical rules. Among those, we check here the parameter emergencyAreaRules which provides the mapping between an address element and a geographical area. For example, consider the following case:

{
    ...,   
    "emergencyAreaRules": {
        "area1_pidflo": "a2",
        "area2_pidflo": "a3",
        "area3_pidflo": "notUsed",
        "area4_pidflo": "notUsed"
    }
}

This configuration defines that:

• a2 address element is constrainted by area1 of geographical areas
• a3 address element is constrainted by area2 of geographical areas

Geographical areas

Geographical areas are defined by 1 to 4 hierarchical layers: area1, area2, area3, area4.

• For a given value of area1, one to several values of area2 are available.
• For a given value of area2, one to several values of area3 are available.
• For a given value of area3, one to several values of area4 are available.

The API allows to reatrieve the values of each element with this hierarchy:

• /countries/{iso2}/geoareas/area1 allows to retrieve possible values of area1
• /countries/{iso2}/geoareas/area1/{area1}/area2 allows to retrieve possible values of area2 for a given value of area1
• /countries/{iso2}/geoareas/area1/{area1}/area2/{area2}/area3 allows to retrieve possible values of area3 for a given value of area1 and area2
• /countries/{iso2}/geoareas/area1/{area1}/area2/{area2}/area3/{area3}/area4 allows to retrieve possible values of area4 for a given value of area1, area2 and area3

When an address is pushed to a voicesite via the API /customers/{customerCode}/voicesites/{voiceSiteId}/voiceaddress, the address is verified againts the fields constrained by geographical areas, if applicable for the country.

Full address validation

For some countries, Business Talk provides an API to get address candidates and verify the real validity of an address. This is available by the API /countries/{iso2}/addresses. For some countries (like Portugal), some additional APIs are available to get other part of the address (postal codes, ...).

These address APIs are designed to return an address in the exact format that must be pushed to the API /customers/{customerCode}/voicesites/{voiceSiteId}/voiceaddress.

Dialzone verification

The dialzone is part of the address to be provided to a voicesite. However two cases exist:

• manual selection: the dialzone is provided manually, and not verified by Business Talk. It is the responsability of the customer to provide the dialzone local to the voicesite address
• automatic selection: the dialzone is always determined automatically based on the address.

The API /countries/{iso2}/geographicalconstraints allows to retrieve the country configuration, with the parameter dialZoneSelection.

Country configuration status

The table below provides the current situation of country configuration. This is for information only, and the actual reference for this information is the API itself which provides all country configuration at any point of time.