Business Talk - Beta
A global voice solution to rationalize telephony services carrying any domestic and international calls [Beta - Sandbox]

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

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:



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 'Developper' 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/beta/v1/me

This request returns JSON data containing the rights profile.

{
  "rightsProfile": "readonly"
}

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/beta/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/beta/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/beta/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/beta/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/beta/v1/voicesites

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