Teaming (1.0) API – Getting started

Prerequisite authentication
Base URL
Terminology
Before starting
Resources
Errors

Prerequisite authentication

This API is an access protected resource using OAuth protocol. It requires an access_token.
You get it with a token API from the token endpoint:
https://api.orange.com/openidconnect/b2b/v1/token To know how to get OAuth access tokens: read the detailed authentication method .

Important

Code a proper management of the error responses in your application. See the section Errors

Base URL

The Base URL is the root URL for all of the API. If you make a request to this API and get back a 404 NOT FOUND response then check the Base URL first.

The Base URL for this API is:

https://api.orange.com/teaming

The documentation below assumes you are prepending the Base URL to the endpoints in order to make requests.

Terminology:

client: your application that will make Orange API calls
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

Before starting

In order to be able to make calls to Teaming 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. In addition, the user that will use your application needs a Teaming account (GLOBAL or CALL).

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 'Teaming'

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

Then, your application shall retieve the explicit consent of the user to use the Teaming account information (reception of authorization code). Here are the available scopes for user consent:

b2b:teaming:user:callManagement
b2b:teaming:user:notifications
b2b:teaming:user:configuration

The same kind of scopes are also available only for administrators accounts. They give access to resources for all users of the company

b2b:teaming:admin:callManagement
b2b:teaming:admin:notifications
b2b:teaming:admin:configuration

Finally, your application shall obtain tokens based on authorization code. To know how to get OAuth access tokens: read the detailed authentication method.

Resources

Get your telephony profile

The GET '/users?/myTelephonyProfile' request is a basic API which allows you to check your telephony information

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/myTelephonyProfile

This request returns JSON data containing information of the user (firstName, lastName, didNumber, ...). Detailled information can be found in the API reference here

{
  "userId": "string",
  "impId": "string",
  "countryCode": "string",
  "didNumber": "string",
  "shortNumber": "string",
  "firstName": "string",
  "lastName": "string"
}

As an administrator, it is also possible to view information about any user in the enterprise

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{userId}/telephonyProfile

Subsribe to your phone line activity

The section *Subscription * in the API reference presents API to manage the subscriptions on the telephony platform. The subsciptions are useful for applications that need to be notified of activity on the telephony line (call alerting, call answered, call released), or on the voice messaging (new message, message deleted)

To subscribe to notifications

curl -X POST \
     -H "Authorization: Bearer {access_token}" \
     -d '{ \
          "applicationId": "your_application_name", \
          "callBackUrl": "https://your_call_back_url", \
          "eventType": "Basic Call", \
          "expires": 3600, \
          "targetId": "{userId}", \
          "targetType": "User" \
          }' \
     https://api.orange.com/teaming/users/{id}/calls

This request returns JSON data containing a parameter "subscriptionId" that is used as a subscription identifier on all other API to manage the subscriptions.

{
    "subscriptionId": "b2600ee4-a755-42c4-85a6-e2c651a50797",
    "expires": 3600
}

It is recommended to update the subscriptions periodically (before the expiry) using the following API:

curl -X PUT \
     -H "Authorization: Bearer {access_token}" \
     -d '{ \
             "expires": 3600 \
         }'\
     https://api.orange.com/teaming/users/{id}/calls

This request returns a 204 OK without any body in case of success

You can also list all subscriptions or one subscription to retrieve information

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/susbcriptions

This request returns JSON data containing

{
    "subscriptionId": "3d6994a4-13cc-4537-99c3-a7834b35f6cd",
    "expires": 3561,
    "applicationId": "your_application_name",
    "eventType": "Basic Call",
    "callBackUrl": "https://your_call_back_url"
}

Manage your calls

The section Call Control in the API reference presents API to manage your calls on the telephony platform. For example, it is possible to perform a call from the following API

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{id}/calls

This request returns JSON data containing a parameter "callId" that is used as a call identifier on all other API to manage the call. The parameter "externalTrackingId" is an interesting information to be given to Orange support in case of problem on the telephony for this specific call.

{
    "callId": "callhalf-27512595:0",
    "externalTrackingId": "19e3604e-7353-4769-abd0-b7e388d61306"
}

An example to answer a call (same for action=HOLD and action=UNHOLD) :

curl -X PUT \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{id}/calls/{callId}?action=ANSWER

This request returns a 204 OK without any body in case of success

In order to release a call (ie hangup a call), the following API is used

curl -X DELETE\
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/v1/users/{id}/calls/{callId}

This request returns a 204 OK without any body in case of success

Manage your voice messages

The section Voice Mail in the API reference presents API to manage the messages of your voice mail.

The following API can be used to list all the voice messages in your voice mail

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{id}/voiceMessages

This request returns JSON data containing a parameter "messageId" that is used as a message identifier on all other API to manage the vocie mail.

[
    {
        "duration": "3020",
        "callingPartyInfo": {
            "name": "Unavailable",
            "phoneNumber": "+33123456789"
        },
        "read": false,
        "time": "2019-08-01 13:20:24Z",
        "messageId": "d6759a98-a4d4-4e79-ae8a-5a9de9f42d98"
    }
]

You can have additionaly the media associated to a voice message.

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{id}/voiceMessages/{messageId}

This request returns JSON data containing

{
    "duration": "3020",
    "callingPartyInfo": {
        "name": "Unavailable",
        "phoneNumber": "+33123456789"
    },
    "read": false,
    "time": "2019-08-01 13:20:24Z",
    "messageId": "d6759a98-a4d4-4e79-ae8a-5a9de9f42d98"
    "mediaContent": {
        "mediaType": "WAV",
        "content": "....omitted..."
    }
}

You can apply several actions to your voice messages

delete a message
put one message as read/ unread
put all messages as read / unread

Configure your Call Forward

The section Call Forward in the API reference presents API to configure the call forward on the telephony platform. You can configure the following features :

Call Forwarding Always
Call Forwarding Busy
Call Forwarding No Answer
Call Forwarding Not Reachable
Do Not Disturb

For example, to check the configuration of feature "call forwarding always" :

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{user}/services/callForwardingAlways

This request returns JSON data containing

{
    "active": true,
    "forwardToPhoneNumber": "0123456789",
    "ringSplash": false
}

You can modify the configuration using a PUT API :

curl -X GET \
     -H "Authorization: Bearer {access_token}" \
     https://api.orange.com/teaming/users/{user}/services/callForwardingAlways

This request returns a 204 OK without any body in case of success

Pagination

After each resquest, explore the http headers to retrieve the number of results

X-Result-Count: Number of items in the JSON response
X-Total-Count: Total number of reply available

If X-Total-Count is bigger than X-Result-Count, you need to request again by incrementing the offset with the X-Result-Count value.

Errors

Your application must parse the returned HTTP response to check if an error is returned instead of a 200 OK.

Errors 401

If you get a status code 401 with the error code 42 (such as below), then request a new access token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided 
  were out-of-date."
}

Important

Each access_token has a lifetime validity period. This validity period may change overtime to comply with security rules.
The token server has a maximum hourly quota per client application to prevent from misuse.
Therefore,
DON'T request an access_token each time you invoke the service API.
DON'T hard-code a validity duration in your application.
Instead, your application must parse the returned status code and error code to check if it needs to request a new access token.

For other 401 errors: check that you provide the right Autorization header with the right Bearer

Errors 400

In case of invalid request to the API, you will receive a 400 error code with detailed information in the body message, such as:

HTTP/1.1 400 Bad Request 
{
  "code": 25,
  "description": "Missing header",
  "message": "...."
}

Consult the other errors.

Teaming - Getting started

Integrate Teaming, our telephony global solution including chat, calling, conferencing into your enterprise - Getting started

Table of Contents

Prerequisite authentication

Important

Base URL

Terminology:

Before starting

Resources

Get your telephony profile

Subsribe to your phone line activity

Manage your calls

Manage your voice messages

Configure your Call Forward

Errors

Errors 401

Important

Errors 400

APIs

API Catalogue

Resources

About us and Contact