Getting started

This page describes how to use the Orange programmable Voice API.

• Url Namespace
• Before starting
• Concepts and resources overview
• API Reference
  • Contract resource
  • File resource
  • Call resource
  • InboundCallRule resource
  • Conference resource
  • Participant resource
  • ThirdPartyConnector resource
• How-to Guides
  • I want to... store files on the Voice API platform and play them
  • I want to... generate an outbound call
  • I want to... handle inbound calls
  • I want to... automate a clic to call behind a button
  • I want to... manage a conference
  • I want to... create a callbot
  • I want to... browse/search calls
  • I want to... get information about my contract
• Use OML scripts
  • prompt/loop
  • digit
  • record
  • recognize
  • hangup
  • join
  • autopilot
  • noInput
  • OML json schema
• Manage callbacks on your server side
  • To serve media files
  • To receive action results and give next action
  • To receive notifications about a call
  • To receive live stream from conference

Url Namespace

Resource urls are composed as follows :

https://{host}/{basepath}/path

The values of host and basepath depend on the specific VaaS offer your application subscribes to. You can find it in the API Reference tab, in the swagger spec.

Before starting

In order to use the Orange programmable Voice API, you need credentials for your application. You get these credentials when you register your application with a valid contract number.

If you do not have a valid registration and contract number for the API, please contact the support

Once you have subscribed to Voice API on Orange developer / Orange Developer Inside, log to your dedicated online space on the portal, and pick up the "Authorization header" (format as follow : "Basic xxxx...xxxx==")

Then use the Authorization header to request a valid access token:

curl -X POST \
    -H "Authorization: Basic xxxxx_YOUR_HEADER_xxxx==" \
    -d "grant_type=client_credentials" \
     https://${host}/oauth/v3/token

        
        Copied 
      

In the response, you get your Voice API token as follow "Bearer " + access_token (e.g. your token="Bearer v8AaIenw6....")

See Orange Developer 2 legged OAuth section for more details on how to get an access_token.

Concepts and resources overview

Here is a list of basic concepts and terms:

• OML : this simple, json-based language is used to describe vocal pages. Vocal pages are played during calls, in order to interact with participants on the call (play audio or text-to speech, collect DTMF, record, etc...);
• IVR (Interactive Voice Response) : allows a human to interact with a computer through the use of his voice and his telephone keypad;
• contracts : it's the contract you've got to use the Voice API, with its usage thresholds, the numbers you can use, etc.
• calls : to establish and control one leg calls (meaning calling - outbound - or being called - inbound - by a end-user)
• files : WAV or OML files that can be uploaded directly in our platform, and used as announcements when creating a call. They can also be stored on your own server and our platform will retrieve them using http
• conferences with its participants : multi legs conferences, where each leg represents a participant of the conference.

API Reference

The main objects you can manage with the Voice API are :

• Contract object
• File object
• Call object
• InboundCallRule
• Conference
• Participant

Contract

This is the main resource to describe the contractual items negociated, and provisionned, for your usages of the Voice API.

You can manage a few of these parameters - via the PATCH method - which do not have impacts on contractual terms (e.g. notificationCallbackUrl or ringingTimeout).

The contract resource contains the following fields :

Your contract also contains phonenumbers, a list of phone numbers linked to your contract in our platform, these numbers have to be compliant with E.164 pattern, international standard (ITU-T Recommendation). There are 2 types of phone numbers :

• ALLOCATED : these are the ones completly allocated to your contract, you can use them to receive (inbound) or place (outbound) calls.
• ADDITIONAL : these are phone numbers that may be authorized beyond the allocated ones to use as a from, in outbound calls. It's typically useful if you already own phone numbers on another voice infrastructure independant from our platform. This can use wildcard if you've got a consecutive range of phone numbers (e.g. +3312121****). Nota : you are legally bound to be the owner of these numbers.

File

Files are a cloud storage you can use on our platform to store audio files (WAV only for the moment). There are 2 common use cases for files :

1. if your application only needs to play audio messages to your customers, you can upload these files on our server. It will optimize performances, saving network time to fetch files elsewhere.
2. whenever you'll record calls, the result will be stored in this storage

File size is limited to 10Mo.

The file resource contains the following fields :

Nota : For WAV files, the audio message must be a file in wav 16-bit PCM signed format.

Call

The call object represents a leg within our system. It can be an outbound or inbound leg depending if the platform starts the call or if the end-user calls our platform.

To illustrate in a brief schema these concepts :

The call resource contains the following fields :

So this resource allows you to start outbound calls, and/or to fetch calls detail whether they are inbound or outbound.

Once a call is connected, meaning connected to an end-user, who can be either be a caller or a callee, you can play scripting logic to him using Orange Markup Language.

Please look at the How To guides below on how to manage outbound and inbound calls.

States for Call resource

Here below you can see all the states a call can be in :

For the completed state, we can have different terminationCause explaining why the call ended :

• "noAnswer": the callee didn't answer the call
• "busy": the callee was busy
• "notReachable": the callee could not been reached
• "hangup": the end-user hung up
• "platformHangup": the end-user hung up
• "announcementPlayed": the platform played an OML scenario and then hung up ("hangup" directive)
• "maxCallDurationReached": call max duration reached
• "mediaError": the media could not been played - unreachable
• "mediaMalformedError" : the OML media given by the consumer app was malformatted
• "mediaUnreachableError" : the OML media URL given by the consumer app was unreachable
• "mediaNotFoundError" : a local media id asked in an OML did not exist
• "mediaIncompatibleContractError" : the OML media given by the consumer was incompatible with the options on contract (tts or asr not enabled while trying to use them, join with a display number you don't own, ...)
• "mediaFullStorageError" : a record has been tried while the quota of files allowed on the contract is reached
• "otherError": a technical error occured
• "noInput": when the call was hangup because of a timeout during a digit collection ("digit" directive)
• "rejected": when the call was rejected because of a reached quota (maxSimultaneousCalls, maxMonthlyTotalDuration)

Details on voicemail detection

The voicemail detection process allows you to detect voicemails when calling someone (outbound calls) while you are playing a scenario.

Nota : this detection is only possible if you are asking to play a prompt or hangup OML verb to the callee.

This detection is based on the recognition of a "bip" sound at the end of a voicemail welcome message.

It's preconfigured to detect duration, frequency and volume of the bips in a specific country / set of countries. Here for this instance, it's configured to detect french voicemail for the 4 telco operators.

The detection process starts whenever the callee - in this case his voicemail - pickups the call.

If a bip is detected, it will send you a notification for this call ("status" : "connectedToVoicemail") allowing you to decide what to do (replay, hangup, ...).

InboundCallRule

The inboundCallRule object represents a listener behind a phone number, or a range of phone numbers, on our platform. This listener waits for inbound calls to the phone number (or range), and plays a scenario. Its typical use case is an IVR (Interactive Voice Response) service to welcome calling end-users.

The inboundCallRule resource contains the following fields :

Conference

The conference object represents the assembly of multiple calls (legs) within a same mixed audio entity : every call represent a participant, and they can hear each other.

The conference contains the following fields :

Participant

The participant represents a party connected to a conference, and contains the following fields :

ThirdPartyConnector

The third party connector represents a configuration to a backend. These could be for text-to-speech, speech-to-text, or a virtual agent / chatbot, that you want to use during your calls.

You'll be able to configure only one backend for speech-to-text and text-to-speech.

We do have connectors pre configured for speech recognition, speech synthesis and bots.

For the moment, we do support as "provider" :

• for speech synthesis :
  • "piper" = embedded Piper servers : an open source coming from Meta ecosystem, more information here https://github.com/rhasspy/piper
  • "voxygen" = embedded On premise licensed Voxygen servers : more information here https://www.voxygen.fr/home
• for speech recognition :
  • "orange_media_analysis" = Orange internal SaaS solution : Cobalt Media Analysis, more information here https://developer-inside.sso.infra.ftgroup/apis/mediaanalysis
  • "kiss" = embedded Orange internal small model, highly optimized for performances and RSE (trained only on few words)
• for virtual agents and bots :
  • "rasa_3.X" = embedded RASA servers : an open source virtual agent, more information here https://rasa.com/
  • "smartly" = cloud Smartly solution : more information here https://www.smartly.io/

Some specificParameters are mandatory for some bot connectors :

• for smartly (provider="smartly") - See smartly documentation to fill these fields :

  • skillId, representing the botId within smartly
  • language, to force the interaction language needed to interact with this bot

• exitKeywords to specify words that will be interpreted to get out of the bot interaction. They will be used to call your actionUrl during OML autopilot.

At last, depending on what TTS and ASR are configured on your contract, you will be able to list the available languages using GET /thirdpartyconnectors/languages. These are the ones you will be able to use in prompt text (tts), recognize (asr) and autopilot (tts+asr) OML verbs.

How-To guides

Here are described the common use cases you may want to achieve.

Note : In the following CURL examples, replace <token> with your Voice API token : see Before Starting

Store files on Voice API platform

Our Voice API platform allows you to store files within your contract.

It's a handy solution if you don't have a lot of different audio files to play to your customers, bypassing potential network problems for accessing callbacks on your servers (latency, security, etc.)

Step 1 - Create or fetch the WAV file you want to use

You can use TTS API to create your wav file using a synthesis voice.

Store it in your tmp directory for example.

Step 2 - upload your file

Upload it on our platform via a POST request to the API

curl -v -X POST \
    -H "Authorization: Bearer Enc0d...T0keN" \
    -F "file=@/<myDirectory>/<myFileName>" \
    https://${host}/${basepath}/files?filename=theFileName

        
        Copied 
      

In the curl request above, replace / by the path where your file is located (if you followed Step1, it would be tmp/myFile.wav).

Once the file is stored on server side, you will receive in the answer the id to use the file :

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contractId": "7gh12f11-6214-5748-b4t2-4c8rtd554ra7",
  "name": "theFileName",
  "format": "WAV",
  "type": "stored"
}

        
        Copied 
      

Step 3 - Use the file

The file content can now be checked using :

curl -v -X GET \
    -H "Authorization: Bearer Enc0d...T0keN" \
    https://${host}/${basepath}/files/{id}/download

        
        Copied 
      

And can be used for service logic during call management, targeting it in oml prompts :

"prompt": {
   "audio": {
     "ref": "the_file_id",
     "type": "LOCAL"
   }
}

        
        Copied 
      

Generate an outbound call

One of the first basic use case of the programmable Voice API is to perform outbound calls to an end-user so as to play him a vocal script.

In this example, here below, we will assume all the scripts are hosted on your app server :

Step 1 - Prepare first an OML script

Example below - that will :

• welcome the end-user,
• ask him to tell something,
• and translate what he said, then send the result to a callback on your side

{
    "recognize" {
       "language" : "en-EN",
       "actionUrl" : "https://yourDns/nextStepCallback",
       "prompt": {
           "text": "Welcome to the vocal application, please tell me something..."
       }
    }
}

        
        Copied 
      

Make sure your callback Url (https://yourDns/yourCallback) renders this application/json OML script (see dedicated chapter

Also make sure to prepare what to script to the end-user behind the /nextStepCallback to continue the interaction ! It's up to you to choose the logic.

Step 2 - start the outbound call

Then let's ask the Voice API to call the end-user +33123456789, playing the script hosted on your server.

curl -v -X POST \
    -H "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    -d '{
            "to": "+33123456789",
            "oml": {
               "ref": "https://yourDns/yourFilePath",
               "type": "REMOTE"
            }
        }' \
   https://${host}/${basepath}/calls

        
        Copied 
      

Here it is : you are now calling the end-user, and asking our platform to fetch the voice interaction scripted before on your server.

Step 3 - the voice API platform sends you the result

When the end user has been joined, asked to say something, and told something back.

Our platform uses our speech recognition system, and sends you back the result as text :

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionRecognize",
          "result" : "That is what I wanted to say to you",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "outbound",
          "terminationCause" : ""
    }'   

        
        Copied 
      

Handle inbound calls

This is the second most common use case of the programmable Voice API : to handle inbound calls from end-users so as to welcome them with a vocal scenario.

In this example, here below, we will assume all the scripts are hosted on the platform (see. How to store files on our platform) and they automate an OML scenario for a IVR vocal menu (DTMF to broswe menus).

Let's also assume you've been allowed to use the +33123456789, as a phone number allocated in your contrat.

In this case, the only action you'll have to perform on the platform is to declare the inboundCallRule, as below :

curl -v -X POST \
    -H "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    -d '{
            "phoneNumber": "+33123456789",
            "oml": {
               "ref": "123e4567-e89b-12d3-a456-426614174000",
               "type": "LOCAL"
            }
        }' \
   https://${host}/${basepath}/inboundcallrules

        
        Copied 
      

You've completed your job : you are now listening on phone number +33123456789 for inbound calls, ready to play a vocal scenario.

Click to call

For this example, let's have a look at how can we handle a click to call button on your web portal. Behind this button you'll callback the customer (who lets his phone number in the GUI) and put him in contact with your contact center phone number.

Step 1 - Perform the outbound call towards the customer

See Generate an outbound call playing him a call waiting music for example.

Step 2 - Play a join scenario, setting the call center as the endpoint to join

See OML Join verb.

Conferencing

Let's assume you want to develop a conferencing solution, wherein the callers are directly welcomed in a conference, and a tone is played whenever a new participant joins in.

Step 0 - Prepare the inboundCallRule for the phone number of you conference

As a preliminary task, you will have to create the inboundCallRule (see dedicated how-to) to get a listener associated to a phone number.

Step 1 - Initialize the conference

Then you can initialize the conference, activating the tone whenever a new participant enters the conference. AutoShutdown will be disabled because you want to manage when this conference is stopped.

curl -v -X POST \
    -H "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    -d '{
            "autoShutdown" : false,
            "toneActivated" : true
        }' \
   https://${host}/${basepath}/conferences

        
        Copied 
      

Step 2 - Handle the notifications of the new incoming calls

Whenever someone is calling the phone number associated to you inboundCallRule, you will receive notifications on your notification callback Url (see also dedicated chapter to manage callbacks) :

POST https://yourDns/yourNotificationCallback
    -H "Content-Type: application/json"
    -d '{
          "type" : "notification",
          "from" : "+33601020304",
          "to" : "+33565432100",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connectedAndIdle",
          "direction" : "inbound",
          "terminationCause" : ""
    }'

        
        Copied 
      

Here above, the +33601020304 is calling your platform +33565432100 where you've set in inboundCallRule to welcome the callers in the conference.

Step 3 - Put the incoming calls in the conference

Use the callId that you receive in the notifications (see previous step), and put them in the conference :

curl -v -X POST \
    -H "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    -d '{
            "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8"
        }' \
   https://${host}/${basepath}/conferences/{conferenceId}/participants

        
        Copied 
      

With this command, the participants already in the conference will all hear a tone, and the new participant will join them.

Browse or search calls

You can look for the calls you've performed (outbound) / handled (inbound) or the even searrch the ones that are still ongoing.

You can search them using different criterias :

• its status (see States diagram)
• its direction (INBOUND / OUTBOUND)

curl -v -X GET \
    -H  "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    https://${host}/${basepath}/calls?status=completed&direction=OUTBOUND

        
        Copied 
      

The response will contain the list of calls matching the search criterias.

In the example above >> all outbound completed calls.

  [{
    "id": "c5v85f64-5717-4562-b3fc-2c963f66afa6",
    "contractId": "7gh12f11-6214-5748-b4t2-4c8rtd554ra7",
    "to": "+33123456789",
    "from": "+33322145699",
    "displayedName": "A good name",
    "direction": "OUTBOUND",
    "oml": {
        "ref": "https://dns/aSuperFile",
        "type": "REMOTE"
    },
    "startTime": "2022-10-01T14:58:21.691Z",
    "endTime": "2022-10-01T14:59:21.691Z",
    "duration": 12,
    "status": "completed",
    "terminationCause": "success",
    "creationTime": "2022-10-01T14:58:21.691Z",
    "updateTime": "2022-10-01T14:59:21.691Z"
  }]

        
        Copied 
      

Create a callbot

Let's assume you want to develop a call bot, to ensure customer welcome and call qualification.

Step 0 - Create/Configure/Train your bot

This step is a prerequisite. You have to have prepared your bot on one of the provider we support (rasa or smartly). This could be a bot you already use for customer request qualification on a chat channel.

Example here below of a simple bot tree on Smartly :

Note that your bot will have to "say" specific exit keywords when you reach a leaf of the dialog tree, here "SERVICE" and "COMMERCE".

Step 1 - Configure your third party connector on the platform

You can configure your connector to the virtual agent very easily :

curl -v -X POST \
    -H  "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    -d '{
            "url": "https://apis.smartly.ai/dialog/",
            "security": {
               "securityType": "BEARER",
               "token": "eyJhbGciOiJIU......voSXG5Y3Y"
            },
            "provider": "smartly",
            "specificParameters": [
              {
               "name": "exitKeywords",
               "value": "SERVICE, COMMERCE"
              },
              {
               "name": "skillId",
               "value": "649d5615c9ea10cd1ded7812"
              },
              {
               "name": "language",
               "value": "fr-fr"
              }
            ]
        }' \
    https://${host}/${basepath}/thirdpartyconnectors

        
        Copied 
      

Step 2 - Prepare the OML to autopilot the interaction with the customer (with a bot obviously !) and associate it to an incoming rule :

Storing it on your app server or directly on our platform. The botId is the id of the third party connectro created in the previous step.

{
   "autopilot": {
      "actionUrl":"https://myServer/myCallBackUrlForBotInteractionEnd",
      "botId":"735cc656-ca48-4379-ab8c-95f4d545e0c2",
      "prompt":{
         "text":"Welcome, I am Djingo, the Orange virtual assistant. What can I do for you ?",
         "language": "en-US"
      }
   }
}

        
        Copied 
      

To associate this OML to an incoming rule, see the how-to dedicated to handle inbound calls

Step 3 - Manage callbacks when the bot has welcomed and qualified the customer request

See the autopilot callbacks

In these callbacks, you will be able to explain to our platform what to do next, depending on the exitKeyword on your bot exit case : for example join the caller/callee to a customer service representative, ask him to press digits, etc.

Browse or search calls

You can look for the calls you've performed (outbound) / handled (inbound) or the even searrch the ones that are still ongoing.

You can search them using different criterias :

• its status (see States diagram)
• its direction (INBOUND / OUTBOUND)

curl -v -X GET \
    -H  "Authorization: Bearer Enc0d...T0keN" \
    -H "Content-Type: application/json" \
    https://${host}/${basepath}/calls?status=completed&direction=OUTBOUND

        
        Copied 
      

The response will contain the list of calls matching the search criterias.

In the example above >> all outbound completed calls.

  [{
    "id": "c5v85f64-5717-4562-b3fc-2c963f66afa6",
    "contractId": "7gh12f11-6214-5748-b4t2-4c8rtd554ra7",
    "to": "+33123456789",
    "from": "+33322145699",
    "displayedName": "A good name",
    "direction": "OUTBOUND",
    "oml": {
        "ref": "https://dns/aSuperFile",
        "type": "REMOTE"
    },
    "startTime": "2022-10-01T14:58:21.691Z",
    "endTime": "2022-10-01T14:59:21.691Z",
    "duration": 12,
    "status": "completed",
    "terminationCause": "success",
    "creationTime": "2022-10-01T14:58:21.691Z",
    "updateTime": "2022-10-01T14:59:21.691Z"
  }]

        
        Copied 
      

Get information about my contract

This API enables you to retrieve all the information about your contract : what numbers you can use, usage thresholds in place, etc.

curl -v -X GET \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Enc0d...T0keN" \
    https://${host}/${basepath}/contracts

        
        Copied 
      

Response :

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Your super contract",
    "maxSimultaneousCalls": 5,
    "maxCallDuration": 3600,
    "maxMonthlyTotalDuration": 200000,
    "trunkGroupIdentifier": "9120156",
    "ringingTimeout": 0,
    "defaultDisplayedPhoneNumber": "+33123456789",
    "allocatedPhoneNumbers": [
      "+33123456789"
    ],
    "additionalPhoneNumbersForDisplay": [
      "+33810303000"
    ],
    "namesForDisplay": [
      "ASuperName"
    ],
    "textToSpeechEnabled": true,
    "automatedSpeechRecognitionEnabled": false,
    "callAuthorization": {
      "type": "WHITELIST",
      "pattern": "+33*"
    },
    "notificationCallbackUrl": "https://www.example.com/callback",
    "applicationId": "fGd87ax45Tg",
    "applicationGateway": "ODI"
}

        
        Copied 
      

You can update some of them via the PATCH operation.

Use OML scripts

You can use the OML scripting language to create vocal applications. An OML script is a simple JSON document describing actions to process when a number is called. You can see an OML script as the vocal equivalent of a simple html page.

You can easily use this script during your calls.

Here are the action verbs available in OML:

• prompt/loop to prompt something to the end-user, a pre recorded audio file, or using "on the fly" text to speech
• digit to ask the end user to press on digits on his phone
• record to record what the end-user says
• recognize to recognize with a speech recognition system what the end user says, and translate it as text.
• hangup to hangup the call. If not done in the service logic, our platform will wait that the end user hangs up.
• join to join an existing leg to another endpoint (callee).

The noInput verb is not an action verb : it's a nested verb you can use in the digit or recognize.

prompt/loop

The prompt verb can be used to play audio files or to read text via text-to-speech. The loop verb is quite the same but for looping a prompt multiple times (maximum 13 times), and is limited to audio files.

A prompt has the following parameters :

A loop has the following parameters :

Example to play an uploaded oml file (see previous chapters for details file and url):

{
    "prompt": {
        "audio": {
            "type": "LOCAL",
            "ref": "f56g5f2d211-c1g12fd1-45f4f5"
        }
    }
}

        
        Copied 
      

And the same that you want to loop multiple times :

{
    "loop": {
        "audio": {
            "type": "LOCAL",
            "ref": "f56g5f2d211-c1g12fd1-45f4f5"
        }
    }
}

        
        Copied 
      

Example to play text-to-speech:

{
    "prompt": {
        "text": "Please call our Hotline at <say-as interpret-as='telephone' format='44'>12 3456 7890</say-as> and leave a message with your name and phone number.",
        "language" : "en-GB",
        "voice" : "female"
    }
}
    

        
        Copied 
      

This text to speech function is only available upon subscription, and validated in your contract.

SSML tags can be used in text part, for example :

{
    "prompt": {
        "text": "The acronym <say-as interpret-as='characters'>VaaS</say-as> stands for Voice As A Service."
    }
}

        
        Copied 
      

In a prompt, you can't have both "audio" and "text". However, you can provide several texts or audio files, as a json array. Elements will be played in the order provided in the array:

{
    "prompt": [
        { "text": "Welcome to the vocal application !", "language" : "en-GB"},
        { "pause": true },
        { "text": "Bienvenido a la aplicacion vocal !", "language" : "es-ES" },
        { "text": "Bienvenue sur l'application vocale !", "language" : "fr-FR" }
    ]
}

        
        Copied 
      

As shown in the above example, you can include a pause between two prompts : a break will be produced by the processor with a prosodic strength greater than that which the processor would otherwise have used.

digit

The digit verb is used to play a prompt and collect keypad input from the user. This can be used to build audio menus or enter data expressed as a series of keys.

A digit has the following parameters :

{
    "digit": {
        "actionUrl": "http://path_to_your_server/callbackurl.oml",
        "numDigits": 1,
        "bargeIn": true,
        "prompt": {
             "audio": {
                  "ref": "http://path_to_your_server/instructionsMessage.wav",
                  "type": "REMOTE"
             }
        }
    }
}

        
        Copied 
      

Given the previous oml digit example, the platform :

• will play an audio message InstructionsMessage.wav;
• will interrupt the message if there is a key entry;
• will collect only one digit;
• and will send the result to the URL http://path_to_your_server/callbackurl.oml

The following example accepts a sequence of digits ending with pound (#).

{
    "digit": {
        "actionUrl": "http://path_to_your_server/callbackurl.oml",
        "bargeIn": true,
        "prompt": {
            "text": "Enter the conference ID, finish by pressing the pound key"
        }
    }
}

        
        Copied 
      

Note that there is a timeout of 8 seconds between 2 digits : if the user takes more than 8 seconds to type a digit (after having typed the first one) the digit callback is invoked and only the first digit is sent in the "result" field

The digit verb also supports multiple prompt elements, in the same way as the simple prompt verb:

{
  "digit": {
    "actionUrl: "http://path_to_your_server/callbackurl.oml",
    "numDigits": 1,
    "prompt": [
      {
        "text": "Welcome to the vocal application !"
      },
      {
        "audio": { 
            "ref" : "http://path_to_your_server/welcomeMessage.wav",
            "type" : "REMOTE"
        }
      }
    ]
  }
}
    

        
        Copied 
      

record

Record allows you to record what the end user is saying.

The parameters of the record verb are :

Here is an example :

{
    "record": {
        "actionUrl": "https://path_to_your_server/callbackurl.oml",
        "prompt": { 
             "audio": {
                  "ref": "78gd454zx11c-dg1212s5-r454t11",
                  "type": "LOCAL"
             }
        },
        "replayPrompt": { 
             "text": "Listen to what you've recorded :", "language" : "en-EN" 
        },
        "beep":true,
        "terminateByKey":true,
        "maxTime":180,
        "audioType": "audio/x-wav"
    }
}

        
        Copied 
      

Given the previous oml record example, the platform :

• will play the audio message,
• will play a beep
• will record what the user says, until the user strikes a key or until the maxTime is elapsed
• will play the text-to-speech message : "Listen to what you've recorded :"
• will play what has been recorded
• will send the result in the body of a POST http request http://path_to_your_server/callbackurl.oml - cf. Receive record action result

The result is depending on the "audioType" chosen in the directive :

• For "audio/basic", the result will be a RAW (headerless) 8kHz 8-bit mono µ-law [PCM] single channel. (G.711). The file extension is .u8k
• For "audio/x-wav", the result will be a WAV (RIFF header) 8kHz 8-bit mono A-law [PCM] single channel. The file extension is .wav.
• For "audio/x-alaw-basic", the result will be a RAW (headerless) 8kHz 8-bit mono A-law [PCM] single channel. (G.711). The file extension is .a8k.

recognize

The recognize verb is used to transform an utterance into a text. So far only translation from speech to text in French is supported.

The parameters of the recognize verb are :

Below is an example of a recognize oml verb :

{
    "recognize": {
        "actionUrl": "http://myURL",
        "language": "fr-FR",
        "prompt": 
        {
                "text": "I listen to you..."
        }

    }
}

        
        Copied 
      

This automated speech recognition function is only available upon subscription, and validated in your contract.

hangup

The hangup directive has to be used whenever you want to hangup on platform side the call. If you do not hangup with you service logic, th call remains opened and idle, waiting for an end-user (caller/callee) hangup.

The parameters of the hangup directive are :

Example here below :

{
  "hangup": {
    "prompt": {
      "text": "Goodbye"
    }
}

        
        Copied 
      

In the above example, the platform will say "Goodbye" then hang up.

The last prompt is optional, you can choose to hang up directly without saying anyhting.

join

The join verb is used to join an existing leg (inbound or outbound call) with another endpoint. A typical use case for join verb is to connect a customer who has called its service desk, and is welcomed by an IVR, with the service desk.

The parameters of the join verb are :

Below is an example of a join oml verb :

{
    "join": {
        "actionUrl": "http://myURL",
        "from": "+33512345678",
        "endpoints": [{
          "type" : "phoneNumber",
          "value" : "+33601020304"
        }],
        "prompt": 
        {
          "text": "Please wait ! We are connecting you to your contact..."
        }

    }
}

        
        Copied 
      

Given the above oml example, the platform :

• will play the prompt message to the existing leg caller/callee
• will perform an outbound call to join the endpoint, using the "from" as the displayed phone number
• once the endpoint picks up his phone, will join the existing leg with this new endpoint leg
• if the endpoint is unreachable, will call the actionUrl to know what to do next on the existing leg

autopilot

The autopilot verb is used to delegate the vocal scenario played on a leg (inbound or outbound call) to a bot. This bot must have been configured in your bot connectors.

The parameters of the join verb are :

Below is an example of an autopilo oml verb :

{
    "autopilot": {
        "actionUrl": "https://myURL",
        "botId": "f56g5f2d211-c1g12fd1-45f4f5",
        "language": "fr-FR",
        "prompt": 
        {
          "text": "Bienvenue, nous allons vous mettre en relation avec un bot vocal, que recherchez-vous ?"
        }

    }
}

        
        Copied 
      

Given the above oml example, the platform :

• will play the prompt message to the existing leg caller/callee
• will connect the end user (caller/callee) with the bot configured for a specific business case
• once the bot scenario is fully realized, will send to the actionUrl the exit keyword reached in the bot scenario

noInput

The no input directive allows you to customize the interaction if the end-user does not press any key when a digit is asked. The no input logic is started once the timeout value defined on the digit verb is reached. It's a recursive directive you can use multiple times.

The parameters of the no input directive are :

Example here below :

{
  "digit": {
    "actionUrl": "http://path_to_your_server/nextActionUrl.oml",
    "timeout": 4,
    "prompt": {
      "text": "Please enter a digit"
    },
    "noInput": {
      "prompt": {
        "text": "I did not understand you. Please enter a digit."
      },
      "noInput": {
        "prompt": [
          {
            "text": "I do not understand you"
          },
          {
            "text": "Can you repeat again, please ?"
          }
        ],
        "noInput": {
          "noInputActionUrl": "http://customerDns/no-input-action"
        }
      }
    }
  }
}

        
        Copied 
      

In the above example, if the user never presses a key, the behavior will be :

• the platform will play the text "Please enter a digit" and wait for 4 seconds
• the platform will play the text "I did not understand you. Please enter a digit." and wait for 10 seconds
• the platform will play the prompts "I do not understand", ... and then wait for 10 more seconds
• the platform will play a new OML, located at the url http://customerDns/no-input-action

Don't forget to put a noInputActionUrl in the last embedded noInput, returning an "hangup" verb so as to be sure not to wait too long for a pressed digit !

OML json schema

You can use it the /check endpoint to validate your JSON OML files (cf. swagger file for more details).

Callbacks on your customer app side

As you've seen before in the previous chapter about OML scripting, the callbacks on your side are clue to manage the voice interaction.

For example, whenever you ask for an end-user action, our platform will send you the result and will need to know what to do next.

There are 3 main type of callbacks that you may have to manage on your app :

1. be ready for http GET operations to render audio files or OML scripts to play
2. be ready for http POST operations to receive an action verb result, and give the next action to play
3. be ready for http POST operations to receive notifications about a call

All callbacks can be invoked in http or https. If you expose your files through https, you must use a certificate signed by a valid certification authority.

The callbacks can be access on Internet, or via Orange Intranet (may be dependent to networks interoperability, and may need flows openings).

The OML files have to be encoded in the standard UTF-8 encoding.

A last type of different callback exists : it's a websocket server url you can expose on your side to receive a raw live stream from a conference.

You will receive payloads of this live stream that you can retreat.

This websocket must be exposed as a secured websocket (wss), and the payloads you will receive are explained here after.

Urls to get media files

These urls are called whenever you set a "fileUrl" parameter to start outbound calls or manage inbound calls.

These urls are summoned with a http GET method, and call information will be sent via request parameters :

https://yourURL?callId=c5fcd14e-a5e9-4426-b1e8-660a3f78ab3a&to=%2B33969770813&from=%2B33601020304&direction=inbound

Nota: All files have to be exposed with an appropriate content-type : "application/json" for the OML files.

Action Callbacks to receive action result

These callbacks are called when you've asked for an OML action directive : digit, record, recognize, join or autopilot. Or when a noInput process has to be performed.

They are summoned with a http POST method.

Be careful, even if these callbacks are called with a POST method, the Voice API platform will wait for a response 200 OK, with a response body. This body will have to give the following OML directive to continue the voice interaction.

The resource that you will receive on your callback contains the following fields (it's the same model as in notfication callbacks) :

Example for Digit action

Example of request you receive on your callback after a digit action (here the end user pressed '2587'):

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionDigit",
          "result" : "2587",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q",
             "diversion" : "+33601020304"
          }
    }'   

        
        Copied 
      

Example for Record action

Example of request you receive on your callback after a record action. The result contains the file id : regarding the example below, you can retrieve the recorded file performing a GET /files/b4ty774g5-4571-6evu-c11a-897432vbtty7

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionRecord",
          "result" : "b4ty774g5-4571-6evu-c11a-897432vbtty7",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q",
             "diversion" : "+33601020304"
          }
    }'   

        
        Copied 
      

Example for Recognize action

Example of request you receive on your callback after a recognize action. The result contains the recognized text spelled by the called/calling end-user.

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionRecognize",
          "result" : "Hello, I am really glad to talk to a bot so funny",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q" 
          }]
    }'   

        
        Copied 
      

Example for Join action

Example of request you receive on your callback after a join action. This notification is sent only when the joining process fails : for example, the joined endpoint was busy. The result contains the reason of the error : "noAnswer", "busy", "notReachable", "otherError".

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionJoin",
          "result" : "notReachable",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q" 
          }
    }'   

        
        Copied 
      

Example for Autopilot action

Example of request you receive on your callback after an autopilot action. This notification is sent only at the end of the bot scenario (exit cases) or in case of an error. The result contains the exit case (botExitKeyword) or the label for errors : "botInteractionError". This "botInteractionError" is raised in case speech recognition or bot scenario fails 3 times in a row.

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionAutopilot",
          "result" : "botInteractionError",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q" 
          }
    }'   

        
        Copied 
      

Example for NoInput action

Example of request you receive on your callback if a noInput is triggered :

POST https://yourDns/yourCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "actionNoInput",
          "result" : "",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "connected",
          "direction" : "inbound",
          "terminationCause" : "",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q" 
          }
    }'   

        
        Copied 
      

Notification Callbacks to receive notifications

These callbacks are called when you've set a notificationCallbackUrl within your contract.

They are summoned with a http POST method, whenever a status change on the call.

The resource that you will receive on your callback contains the following fields (it's the same model as in action callbacks) :

Example of request you can receive on your notification callback about the call 1b089d93-4827-4cdf-b6ce-175775e2aac8 when the end-user hangs up :

POST https://yourDns/yourNotificationCallback
    -H "Content-Type: application/json" 
    -d '{
          "type" : "callNotification",
          "from" : "+33601020304",
          "to" : "+33609080706",
          "callId" : "1b089d93-4827-4cdf-b6ce-175775e2aac8",
          "status" : "completed",
          "direction" : "inbound",
          "terminationCause" : "hangup",
          "startTime": "2023-10-16T08:33:36.232Z",
          "endTime": null,
          "sipHeaders" : {
             "uui" : "hj454g1-gfdqcbj114rzszq-ezaef411q" 
          }
    }'   

        
        Copied 
      

Live stream from conference

These websocket callbacks are called when you've set a mixedStreamOutUrl on a conference conference.

They are summoned with a http POST method, whenever a status change on the call.

The resource that you will receive on this callback contains a JSON object with the following fields :

In case of a "startStream" event, to notify you that the stream out is starting :

Example of a startStream event

'{ 
  "event": "startStream",   
  "start": { 
    "streamId": "12354451212313", 
    "mediaFormat": { 
      "encoding": "audio/l16", 
      "sampleRate": 16000, 
      "channels": 1 
    } 
  }
}'   

        
        Copied 
      

In case of a "mediaStream" event, to notify you a chunck of the RAW payload :

Example of a mediaStream event :

'{ 
  "event": "mediaStream",
  "media": { 
    "timestamp": "5",
    "payload": "no+JhoaJj57/HgiIyXrywioeGiA=="
  }
}'   

        
        Copied 
      

In case of a "stopStream" event, to notify you that the stream out is stopped :

Example of a startStream event

'{ 
  "event": "startStream",   
  "stop": { 
    "streamId": "12354451212313" 
  }
}'

        
        Copied