Supported Environments 

At this stage Mitel supports MacOS, iOS, Android, and Windows based applications on the CloudLink API.

Development Environments

See Getting Started - Development Environments

Best Practices

Authentication

While basic API calls can be made for development and test purposes using the OAuth 2.0 grants to obtain a bearer token, production applications will need to utilize the OpenID Connect Flow which first obtains an authorization code that can in turn be exchanged for a bearer token. The purpose of this is to ensure that your application/integration is properly identifying itself through the use of a 'clientId'. Failure to do so may result in your application/integration being throttled or otherwise blocked on the CloudLink platform.

The easiest way to use the OpenID Connect Flow is to make use of the Mitel Auth Portal however you can create your own flow as well.

Logging

One of the most important aspects of your application will be ensuring that logging is captured to facilitate future troubleshooting. You may wish to automatically retain client and/or server side logging for your application, or include the ability to enable logging for troubleshooting purposes. While the specific logging requirements will vary depending on the nature of your application and what information you need to capture to best support your customers, when contacting Mitel Product Support there are several pieces of information which will commonly be requested:

• HTTP errors - Your application should log 4xx series and 500 HTTP errors, including the response body and headers. This information will be useful as a starting point for any troubleshooting.

• x-mitel-correlation-id - More commonly simplified as the 'CorrelationId', this header is included in every response from an API call. This unique value is used by CloudLink to tie together activities on the platform related to your API call and is extremely valuable for Mitel Product Support.

• CallId - When working with the /endpoint routes on the Media API, every call will have it's own unique 'callId'. This unique identifier is important to help track down relevant logging. When initiating your own call with the Media API, the callId will be included in the response body or you can obtain it with a GET query on the relevant endpoint(s). When subscribed to events on endpoints, the callId will be included in notifications generated through the Notification API.

• x-amzn-requestid - This response header is a unique value created by Amazon service that uniquely identifies the API request. If there is a problem with AWS, Mitel Product Support will need this in order to work with Amazon to troubleshoot the problem.

HTTP 429 Errors

In certain conditions when under abnormally high load, the CloudLink platform will block API calls and return an HTTP 429 error. This error will often occur because an application deployed on your CloudLink account is making too many requests in a short period of time. When receiving an HTTP 429 error, a 'retry-after' header will be included in the response that contains a value in milliseconds. Any application that receives an HTTP 429 error in response to a valid API call should take the value of the retry-after header, add a random value to it, then use that as a retry timer/interval for your API call.

An example of managing 429 errors and retry intervals can be found in the 'Authentication - OIDC' sample code.

Performance Benchmarks

To ensure the safe operation of your application and reduce the risk that it will cause performance issues that require it to be blocked from using the API, Mitel will be outlining the benchmarks that applications utilizing the API will need to meet in order to be approved for deployment into production. These benchmarks are currently being assessed and will be published as soon as they are finalized.

Registration & Deployment Process

To deploy your application or integration into a production account, the following steps will need to be taken.

IMPORTANT: The process described below is not currently available. Please see this post on the Community Forums for information about registering and deploying an application or integration.

Mitel Partners

Application Registration (not currently available)

All custom applications/integrations that utilize Mitel's CloudLink API's or environment must register them through the CloudLink Accounts Portal and undergo a review process before it can be deployed in any CloudLink account. On approval, you will be apply to add the application/integration to any Mitel customer account that you own.

1. Login to the CloudLink Accounts Portal.

2. Click on Developer in the navigation menu, then click the 'Register a new app' button.

3. Complete the registration form and click 'Request Approval'

You will be notified when your application has been reviewed. You can also monitor the status in the Developer menu. On final approval, you will receive a unique clientId or "application identifier" that is required for API authorization and authentication anywhere the application/integration has been deployed.

Application Deployment (not currently available)

Once your application/integration has been registered and approved, login to the CloudLink Accounts Portal and:

1. Go to the account where you wish to deploy the app.

2. Navigate to the Integrations menu and choose to add a new integration.

3. Select "Third Party" and your application should be available to select.

4. Complete the form and click 'Submit'

Important: It is imperative that the "x-mitel-app" header provided in the form be adhered to by the application, otherwise it may be subject to rate limiting or be blocked entirely.

Mitel Customers

If you are a customer, any custom application will need to be deployed through a Mitel Authorized Partner. To locate a Mitel Authorized Partner or service provider in your area click here or call us at one of our regional offices throughout the world.