Proximus FlexIO Main Features

All features below are included in the FlexIO subscription and can be used in pure Pay-as-you-Go.

Getting Started with FlexIO

Overview

Get started in 3 simple steps:

1. Subscribe to Proximus FlexIO
2. Reserve at least one phone number
3. Access the Proximus FlexIO console to create your first Visual Designer Application or
4. Start developing with our REST APIs

Subscribe to Proximus FlexIO

To get started with Proximus FlexIO, activate your subscription by choosing the FlexIO Premium Plan from our pricing tab. In order to subscribe, you need to ensure your Proximus API Solutions account is configured with a payment method. You can add your credit card information under the billing section of your user's dashboard:

Businesses with a VAT number requiring invoicing may have this payment method configured by contacting our support team.

Customers who expect to reach a large number of phone call reservations or a very high monthly voice traffic may contact the sales team to have their situation investigated.

Reserve your first phone number

Once subscribed to Proximus FlexIO you can immediately order your first phone number. This can be done:

• using the Number Management REST APIs if you are a developer, or

• using our Number Manager microsite (web-based graphical user interface) whose link has become active in the marketplace as soon as your subscription was complete.

To learn how to use the Number Management APIs or the Number Management microsite, refer to section Number Management.

Access the Proximus FlexIO console

Upon completion of your registration, you will receive an email with your FlexIO console credentials (userid and password). Go to https://proximusflexio.enco.io and login with these credentials. The console consists of 4 main sections:

• Applications: An Application tells our platform where to retrieve instructions for managing inbound calls to any of your numbers. Applications can be self-hosted (a "URL application") or created using our Visual Designer. The Visual Designer can also be used to create applications that will create outbound calls. For more information on the concept of Applications, please refer to the section Getting Started with Applications.

• Numbers: Lists the numbers assigned to your account using our Number Management API or microsite. By selecting a number, you can associate it to any of your applications and define fallback and callback URLs in case needed. Multiple numbers can be assigned to the same application. Such association operation can also be automated by using REST API.

• Clients: A Client represents a user agent that can make and receive calls using Proximus FlexIO. This means that you can configure any software VoIP phone with the Client Username and Password in order to register with Proximus FlexIO

• Logs: Retrieve and consult the list of all your inbound & outbound calls and messages, recordings and important notifications.

All documentations related to the REST APIs -- except for Number Management APIs -- and usage of the Visual Designer can be found on our dedicated FlexIO Documentation website.

Start developing with our REST APIs

There are 2 distinct API endpoints and documentations. Refer to section API Credentials to understand the API credentials to use for each of these two scopes.

Number Management

Introduction to Number Management

For your applications to handle inbound or outbound calls, you need to have a least one phone number. Please note:

• a number can only be bound to one application at a time to process inbound calls, but several applications can use the same number for outbound calls

• multiple phone numbers can be linked to the same application for inbound calls. Your application could apply different call logics based on the called number, as it is one of the parameters it receives when triggered by the platform. For instance, number A would have your application deal with the call in English while number B would have the call be served in French.

Phone numbers that you acquire via our NUmber Management capability are invoiced by the month, even if used for a short period of time than released back to the pool. The subscription to the phone numbers you acquire will auto-renew every month until you release them back to the pool.

Once you have acquired your number(s) and intend to process inbound calls, you will need to create an application and link your number to that application.

Type of phone numbers

At product launch, Proximus will offer regular fixed Belgian phone numbers associated to Belgian telephony zones. Zones are also referred to as prefix areas, as illustrated in the picture below:

Please note that numbers might not be available directly for all zones straight away. In case you require numbers in a specific zone, please reach out to our team.

Over time, we will offer additional categories, such as:

• Mobile phone numbers

• Premium Price Tier : numbers such as "+3222222222" that might have a higher value

Using the Number Management microsite

Once logged into proximusapi.enco.io and subscribed to Proximus FlexIO, you can access the number management microsite by clicking on the "Microsite" link under the FlexIO asset, or direct your browser to https://flexionumbers.enco.io

Click on the "+" icon to request a new number. You can filter your search by number type (fixed / mobile) and filter down the list of available phone numbers to contain only a specific substring of characters. Select the number you wish to reserve by clicking on it, then select "Register number".

For fixed number reservation, the law in Belgium about telecommunication services impose that you have a valid personal or business adress in the zone in which you request a fixed number. Select "I confirm" if you match this requirement.

The main microsite interface will show the list of numbers that you have currently reserved. The only available operation on a reserved number is to release it, using the trash icon.

Mind that a number that is released to the pool will not be immediately available for any users to use - including you - as we impose a "freezing" period of 15 days between subsequent uses of a number by users across the platform.

Using the Number Management REST API

The REST API for Number Management are described in this swagger. To use these APIs, you will need your Proximus API Solutions account credentials. Refer to section API Credentials to learn more on this topic.

Finding available phone numbers

You may first want to check which phone numbers are available for rental by Proximus and use therefore the GET /phonenumbers/available API. As documented in the swagger, you can narrow down your search by including filters on zones, type (fixed/mobile) & price tier. The API sends back an array of json structure, each json structure describing available numbers in our pool.

[
 {
   "phonenumber": "3222060746",
   "type": "FIXED",
   "smsSupported": false,
   "priceTier": "REGULAR"
 },
 {
   "phonenumber": "3222060745",
   "type": "FIXED",
   "smsSupported": false,
   "priceTier": "REGULAR"
 },
 {
   "phonenumber": "3222060742",
   "type": "FIXED",
   "smsSupported": false,
   "priceTier": "REGULAR"
 }
]

Reserving a phone number

Once you have identified a number that suits your needs in the list of available number, issue a POST /phonenumbers/{phonenumber} request to have that number reserved for you and associated to your account on the Proximus FlexIO platform.

curl -X POST \
  'https://api.int.enco.io/cpaas-mgmt/1.0.0/phonenumbers?addressInZoneConfirmed=true' \
  -H 'authorization: Bearer <your bearer token>' \
  -H 'content-type: application/json' \
  -d '{
  "supportsSMS": false,
  "type": "FIXED",
  "filter": "3222060744",
  "zone": "02",
  "pricingTier": "REGULAR"
}'

Please note the use of the mandatory query parameter addressInZoneConfirmed=true in the request, by which you confirm that you have a valid reason to select a number in that zone. The Telecom laws in Belgium require that you confirm having a business or personal address in the same region as the number you want to use.

Releasing a phone number

To release one of your number back to the pool, simply use the DELETE /phonenumbers/{phoneNumber} API call.

Mind that a number that is released to the pool will not be immediately available for any users to use -- including you - as we impose a "freezing" period of 15 days between subsequent uses of a number by users across the platform.

Getting Started with Applications

Visual Designer or own development?

You can consume FlexIO communication capabilities in two different ways:

• For developers & integrators: handling voice calls on FlexIO is performed by your applications using a combination of REST API calls and giving instructions to the FlexIO platform using a mark-up language called "RCML" (REST Communications Markup Language). Your application needs to expose HTTP endpoints that Proximus FlexIO will query to fetch these RCML instructions for handling the call(s).
• For process and business owners: using the Proximus FlexIO Visual Builder with zero-coding to build your applications supporting inbound or outbound communications. This tool is using the same API calls and generating the same RCML instructions as a programmer would do when creating his own applications, but you do not need to care about this complexity as it's automatically handled for you by our systems. If you do not plan to develop your own applications using our APIs and only use the Visual Designer, you can safely skip to the section Building Your First Visual Designer Application.
  
  

Inbound call principles

Let's assume you already have a phone number on the Proximus FlexIO platform, and as a developer you want your application to be able to handle inbound calls to that number.

When a call is received from the telephone network for this specific number (1), FlexIO needs to know that you have an application for it and where to find it. Knowing this, it will be able to query your application (2), which in turn will tell FlexIO what do in the call (3) such as using text-to-speech to say a welcome message to the caller (4):

For Proximus FlexIO to know that you have created an application that will handle inbound calls to one of your number, you will need to create a specific object called an Application instance resource, which creates that specific binding. This Application instance tells FlexIO which is the endpoint URL that it must query (via a POST request) to retrieve the very first set of RCML instructions to handle the call it just received.

An Application instance can be created from the Proximus FlexIO console under the Application menu ("+Add new app") or using REST APIs. Experienced users will find the Application API on our dedicated FlexIO Documentation website.

Let us suppose that your endpoint URL is http://myserver.onthe.internet/incomingcall and let's take a look at a typical call sequence:

• The platform gets a call for your number. It makes a POST request to your /incomingcall endpoint URL, including call information in the request (which number is called, which number is calling, ID of that specific call leg, etc.)

• Your application answers to the POST request by sending a RCML structure with the first step of instructions. The instructions in the example above are:

  • Use text-to-speech to play a welcome message (<Say></Say> action)

  • Enunciate a menu to the caller in order to capture 1 digit and, once that digit is collected, ask my application for the next instructions via a POST request to my /inputdigits endpoint (<Gather></Gather> action)

• Proximus FlexIO receives these instructions and uses text-to-speech and DTMF tone collection as requested. Once it has collected the caller's input via digit, FlexIO makes a POST request to the /inputdigits endpoint of your application. That request includes the results of the input collection (the collected digit), as well as all needed call references.

• Your application implements whatever logic is needed to handle that user input and answers to the request of FlexIO with a new set of RCML instructions, this time asking the platform to play another voice message than to hang up the call.

During all that process, if instructed to do so, Proximus FlexIO can also send status events about what's happening with the call to a designated callback URL (another endpoint exposed by your application server, shown as "/status" on the flow above). Using the status callback events, your application will know who is calling in, the status of the call (initiated, ringing, in-progress, …) and might even decide not to answer calls from unknown callers.

Outbound call principles

Outbound calls happen when your application requests Proximus FlexIO to initiate a new call leg. In this case, it is not necessary to create an Application instance on FlexIO nor is it needed to associate such instance to a phone number on the platform. Instead, your application is going to use the /Calls API to create this call leg, providing all necessary information such as the From and To numbers.

Let us check a sample call sequence:

• Your application makes a POST request to the /Calls API of FlexIO, stating the From number (callerID), the destination number, a status callback URL endpoint (to catch call status progress) as well as the endpoint URL that FlexIO will need to query to fetch the first set of instructions once the call is established. Please note that it is mandatory to set the callerID to a number that you have reserved. Setting the callerID to a number that is not assigned to your account will result in a call failure.

• FlexIO tries to call that destination number, and once the call is established it queries the "/step1" endpoint URL of your application to receive its instructions, in a RCML structure.

• Your application responds to that request on its "/step1" endpoint with the set of instructions (say something, then collect some input with DTMF dial tones, then ask for more instructions on the /inputdigits endpoint URL once done)

• FlexIO executes the text-to-speech, collects the user input, then as instructed sends that input to the /inputdigits URL and expects thereby to receive the next instructions to execute

• My application responds to that request on its /inputdigits endpoint to conclude the call.

Controlling calls principles

Any inbound or outbound call has its own unique ID, designated as "callSID". The /Calls API can be used together with that callSID to modify real time calls, such as interrupting an in-progress call and terminating it or having it begin processing RCML from a new URL. This is useful for any application where you want to asynchronously change the behavior of a running call. For example: hold music, call queues, transferring calls, forcing hang-up, etc.

For more information, please consult our dedicated Proximus FlexIO documentation website.

API and RCML documentation

The FlexIO REST API and RCML structures and action verbs are fully described in our dedicated FlexIO documentation website. This documentation also describes the authentication methods for using the API.

Building your first Visual Application

Inbound call application

To implement this first application you will need to have a least one available reserved number, not yet associated to any other inbound application.

In this simple scenario, the application will answer the phone, play a greeting in 3 different languages using text to speech, then will hang-up the line.

In the Proximus FlexIO console:

• click on "Applications"
• click on "+ Add a New App"
• select "Create a Visual Designer Application"
• select "Blank"

Give a name to your application, make sure "Voice" is selected, then click on "Create". A new browser tab opens to the Visual Designer:

We can see several components in this window:

• Building blocks on the left: these are all action types that you can execute in your scenario, like “Play” for playing an audio file, “Say” to use text to speech, “Collect” to gather input from the caller, etc
• These action blocks can be dragged in the main screen, one below the other. They can be reordered on the screen and will be executed in sequence.
• Modules are ways to regroup action blocks together. There is always a startup module that will execute first. Modules can be linked together

When creating a new blank application, a first action is already added by default to your application canvas. You can remove it if not needed but we will keep it for our scenario. This "Say" action will use text to speech to tell whatever text you enter in the action input box. Let's enter "Welcome to my first inbound application on Proximus FlexIO". Notice the little cogwheel icon at the bottom left of this "Say" action ? Clicking on it will allow to define additional parameters, specific to each action. In our case, we'll select the "Google English British Wavenet A" voice and click on the man icon (man voice). Notice all the possible voices and text to speech engines that can be used in your scenarios. You are free to use any of the listed TTS engine and voice. Recommending specific TTS engines versus others is not in scope of this documentation.

Now simply add another "Say" action by dragging the action from the left menu under the first Say action. Notice the thick velvet bar that appears to show you where the dragged action will be inserted.

Add the same text as above, but this time in French ("Bienvenue sur ma première application réalisée sur Proximus FlexIO") and select the French voice of your liking after clicking on the cogwheel. Finally do the same in order to add a Dutch announcement ("Welkom bij mijn eerste toepassing op Proximus FlexIO"). Now save your application:

You may now close the Visual Designer window. We need now to associate one of your phone numbers to this application so that Proximus FlexIO will now which application to start when that number is called. In the Proximus FlexIO console, click on the "Number" menu on the top, then click on any unused number from your list. If no phone number is shown, make sure to reserve one by following the instructions on Using the number management microsite.

After selecting your number, in the new screen that appears, select your newly created application from the dropdown list then click save.

That's it ! You can now call your phone number and listen to the announcements.

Please remember that charges for usage of the Visual Designer are applied as soon as you keep at least one Visual Designer application on your account for a duration of 24h.

Outbound call application

In this scenario, you want your application to initiate an outbound call to an external phone number and play some content in that call, like text to speech or an audio file. To make it easier, we are going to use the same Visual Designer application we just created for inbound calls, but instead of calling our number to have the application pick up the phone and answer, we will do the opposite.

Go back to your Applications list on the FlexIO console, select the application you had created previously and click on “Design”. The Visual Designer window opens. In that Visual Designer window, click on the top right menu arrow, and select “Account settings”:

Make sure your FlexIO userid and password are both correctly set in the window that appears, then press OK to close that window.

Click again on the top right menu arrow, and this time selects “Web trigger”. We are going to create a simple URL that can be used to trigger this application, for outgoing calls, to any number we want to call. Click on the “enable” checkbox to activate this Web Trigger feature - the window gets a bit bigger and shows a number of additional information and parameters:

You may want to share the unique URL shown in this window with external parties but prevent to expose your Proximus FlexIO credentials with these people. Therefore, you can create an “Application-specific token”, which basically is a password that would be used only to authenticate with this specific application. Click on “Application-specific token”, then fill in a password of your liking (one continuous word with no spaces nor special characters):

Copy the URL shown in this dialog box and paste it in some text editor, then click “Save”, and again click “Save” to capture all changes to the settings of your application. Edit the application URL you have copy/pasted in a text editor:

• change the "mysecret" text after "token=" to replace it with your unique application password
• change "to=+1231231231" to "to=%2B32xxxxxxxxx" where 32xxxxxxxxx is the phone number to be called
• change "from=12345" to "from=%2B32aaaaaaaaa" where 32aaaaaaaaa is any phone number that you have reserved on Proximus FlexIO. Note that to prevent call spoofing, you can only set your From number to a number that you have reserved on your account. Should you try to use another number, the call will not get executed. See the FAQ section for more info.

Once the URL is edited, just copy and paste that URL in a browser and press enter. Your target phone should start to ring, and the following be displayed in your browser:

The “Web trigger applications” capability is very useful, it makes it extremely simple to integrate callout capabilities into a website, an application or even an Excel sheet macro! With simple variable substitution the same URL can be used to call any number. Variables can also be added to the URL to pass additional information to the application, such as the firstname and lastname of the person you wish to call.

Visual Designer internal variables

Here is a quick summary of the most common internal variables available in the Visual Designer. Each variable can be invoked using the "$" prefix, such as "$core_From".

Visual Designer advanced topics

To learn more about the Visual Designer capabilities, please consult our advanced topics on the Proximus FlexIO documentation site.

Find more tutorials about using the Proximus FlexIO Visual Designer on the API Solutions blog.

SMS Messaging with Proximus FlexIO

Proximus FlexIO supports outbound SMS messages from a shared short number only (8640). To be able to send SMS using the FlexIO SMS API or using the FlexIO Visual Designer, you need to own at least one number on the platform (see Number Management) - this is the number that you will specify as the "From" number. This is mandatory as the sending of the SMS will fail if you don't specify such number for that field. When the SMS goes out of our systems, this "From" number will be overwritten automatically to our shared sort number.

Customers who require to send SMS from a regular "long" mobile number, or that require a dedicated short number on which they would also be able to receive inbound SMS, please check our dedicated SMS API or get in touch with our support team.

Customers who require to send large number of SMS on short periods of time, please reach out to our commercial team.

API Credentials

There are 2 distinct sets of API credentials in use when working with Proximus FlexIO:

API Solutions Credentials

Obtaining your OAuth2 Application Keys

Each project you create through the API Solutions Market will result in the creation of a unique pair of OAuth2 application keys. To retrieve your keys, proceed as follows:

• First, log in and visit your dashboard on the portal. Click the "TOKEN" menu.
• This will result in your application keys to be shown. These keys can be used to access API resources exposed by any API asset to which you subscribed, within the scope of the selected project.

Your application keys are sensitive information; keep them private at all time!

Make sure to store your application keys in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case your application keys would become compromised, contact us through support and we'll revoke them to block access, and provide you with a new pair. This is also the reason why all API traffic should pass through secured HTTP, and why we do not support plain HTTP.

Generating a fresh bearer access token

A bearer access token is a self-contained unique identifier through which you can gain access to API resources. Before elaborating on how you can obtain such type of token, please note that these tokens are valid for a limited time span of 1 hour (or less, if explicitly revoked).

You can obtain a new token by issuing the following request against the server https://api.enco.io :

/token POST

Issue a request to https://api.enco.io/token, adding the following headers and body:

Request

curl -X POST \
  'https://api.enco.io/token?grant_type=client_credentials&scope=openid&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&Accept=application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' 

Response payload

{ 
  "scope": "openid", 
  "token_type": "Bearer", 
  "expires_in": {number}, 
  "access_token": {string}
}

The field accesstoken in the response contains your token. The field expiresin will show you the remaining validity of your token, in seconds.

Single active access token
Within the context of a single application, you will only have a single active access token at any time. If you would request a new token using the above request message while the previously issued token has not yet expired, you will get back the previous token. To obtain a new one, revoke the old token; then generate a new one.

Code Samples
To help you getting started on implementing this authentication in your code, you can find some samples on our Github.

Revoking an access token

This procedure should be used when your token has been compromised (leaked, stolen, etc.), or if you want to generate another token, but your old token is still valid.

/revoke POST

Issue a request to https://api.enco.io/revoke, adding the following headers and payload:

Request payload

token=<old-access-token-to-be-revoked>&client_id=<app-consumer-key>&client_secret=<app-consumer-secret>

Creating permanent token

You can create permanent tokens from the "TOKEN" menu of your profile's dashboard. Just click on "Add a new token" to create a new permanent token. Several permanent tokens can be created for the same account.

Your permanent token is sensitive information; keep it private at all time!

Make sure to store your permanent tokens in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case a permanent token would become compromised or not needed anymore, delete this token from your "TOKEN" dashbload by clicking on the red cross next to it.

All set to call your API!

Once a valid access token has been generated, it should be added to request messages. The token should be passed in an HTTP header named Authorization, which should be assigned the value of Bearer, followed by a single space, and immediately followed by the access token. Note the single space between ‘Bearer’ and the token.

curl -i -X GET -H "Accept:application/json" -H "Authorization: Bearer <active-access-token>" https://api.enco.io/lora4maker/0.0.1/device

Proximus FlexIO API credentials

See Authentication on our dedicated Proximus FlexIO documentation website :

Terms & Conditions

Proximus FlexIO Terms and Conditions document.

FAQ

Can I use Proximus FlexIO to call emergency services?

• As per the Terms & Conditions, Proximus FlexIO may not be used to access or allow access to emergency Services (meaning, an official government-sponsored emergency telephone number (such as 112 and 101 in Belgium and other locations worldwide) which is used to dispatch professional emergency responders

Can I call or send messages to international numbers?

• At product launch we restrict all outbound communications to Belgian numbers only and will introduce international destinations at a later stage. Should you have an urgent need, for a business use case, to reach international destination numbers please contact us at enco@proximus.com. Please note that the API Solutions SMS API, currently available as a standalone API capability, does support international destinations.

How does voice pricing work for inbound and outbound calls?

• Pricing is defined per minute. Any inbound or outbound call is always rounded up to the next minute

• Calls to or from (SIP) Clients are counted as regular inbound or outbound calls, charged with the same pricing.

How and where can I track my usage of Proximus FlexIO?

• Go to Proximus FlexIO's pricing tab. After loading the initial content, the page will be updated a second time with a table on the top showing your usage in the current billing period. This information is updated once a day and is thereby not real time. The view reflects the metrics, their usage and current incurred costs as counted by the marketplace. We are aware of a small issue on number reporting, which will be fixed soon.
• For (near) real time logs on calls, messages and recordings, you can always use the Proximus FlexIO console's log view
• Proximus FlexIO comes with a number of APIs that can report on call, messaging, conferencing, recordings, 2FA, etc.

How long do you keep my (audio) recordings and do you charge me for that storage?

• Audio recordings that you trigger via API or RCML are kept for one (1) year before being automatically deleted. You can retrieve these recordings at any time and store these at any other location of your choice for long time archival if needed. There is currently no fee for recording storage on our platform.

Am I free to set any caller ID on my outgoing communications?

• When you reserve numbers, your account will be configured to only allow outbound communications from those numbers that you own. Trying to use any other number will result in the outbound call to fail. When using the Calls API to create calls, or when using the Visual Designer, please ensure that you define the "From" number based on a number that you own on the platform (+32xxxxxxxxxx). If you fail to properly define your "From" number, please note that Proximus may assign a default callerID to your call that does not match any number that you own.

• When sending a SMS, you must define the "From" number based on any number that you own, although the callerID has seen by the recipient of the SMS will always be our shared short code number. Failure to set the "From" number accordingly will result in the SMS send operation to fail.

Can I assign a callerID for outbound calls initiated from a SIP Client (via a soft phone for instance) ?

• The main objective of the Proximus FlexIO platform is to trigger applications (Visual Designer or your hosted application) when receiving incoming calls. If you have created a FlexIO Client and configured a SIP phone or application with that Client's credentials, although you can make outbound calls to external parties (external fixed or mobile phone numbers) it is not possible to enforce a specific callerID. The callerID shown to the callee will be a generic fixed number on which you have no control.

Can a SIP Client call another SIP Client ?

• Although the SIP call request will be correctly routed and the call be established, we have no control over the RTP connection that must be established directly between the 2 clients. If these clients are behind firewalls and/or NAT, the audio stream will most likely fail to be setup correctly.

I own numbers that I would like to port in and use from within Proximus FlexIO. Can I do this?

• Please reach out to the Proximus API Solutions team at enco@proximus.com.

I'm using numbers provided by Proximus on the FlexIO platform and would like to port out these numbers. Can I do this?

• Please reach out to the Proximus API Solutions team at enco@proximus.com.

Does Proximus propose anything like volume discounts on Proximus FlexIO?

• Please reach out to the Proximus API Solutions team at enco@proximus.com for volume discount requests.

Blog articles

Find all articles about Proximus FlexIO on the API Solutions blog for additional articles and tutorials.