Fragen? 0800 55400300
View Categories

Call Control Spec

18 min read

Call Control API specification

Here you will find the specific attributes and examples for each block type.

  1. BRIDGE block | Call forwarding to target number, SIP account or SIP trunk
  2. ANNOUNCEMENT block | Playback an announcement
  3. SAY block | Playback announcement via Text-to-Speech
  4. ROUTINGPLAN block | Dynamic routingplan integration
  5. COLLECT DIGITS block | Entry of digits via DTMF
  6. COLLECT SPEECH block | Speech Recognition (ASR)
  7. HANGUP block | Cancellation of a call
  8. CALL SETTINGS block | Changing call parameters
  9. REFER block | SIP trunk Call Handling

BRIDGE block

Initiates Call Forward via external target number, SIP account or SIP trunk.

bridgeMode Can be SEQUENTIAL or PARALLEL . The destinations will be called sequentially (one after the other, each with individual timeout), or in parallel (with one total block timeout)
destinations A list of destinations. Each destination has:

  • a “destinationType” attribute:
    • EXTERNALNUMBER
    • SIP_USER
    • or SIP_TRUNK
  • a “destination” attribute (a String)
    • for EXTERNALNUMBER, this must be in international format “+….”, without any spaces or other special characters, e.g. “+49221987654321”
    • for SIP_USER,this must be the username configured under “SIP Accounts” in the TENIOS customer portal
    • for SIP_TRUNK, this must be the name of the SIP Forwarding Profile configured under “SIP Trunks” in the TENIOS customer portal
  • a “timeout” attribute ( Only in SEQUENTIAL mode)

SEQUENTIAL BRIDGE example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "BRIDGE",
         "destinations": [
            {
               "destination": "1001",
               "destinationType": "SIP_USER",
               "timeout": 25
            },
            {
               "destination": "+4978787878",
               "destinationType": "EXTERNALNUMBER",
               "timeout": 30
            }
         ],
         "bridgeMode": "SEQUENTIAL"
      }
   ]
}

PARALLEL BRIDGE example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "BRIDGE",
         "blockTimeout": 50,
         "destinations": [
            {
               "destination": "1001",
               "destinationType": "SIP_USER"
            },
            {
               "destination": "+4978787878",
               "destinationType": "EXTERNALNUMBER"
            }
         ],
         "bridgeMode": "PARALLEL"
      }
   ]
}

ANNOUNCEMENT block

Using this block, announcements that were loaded in the TENIOS customer portal can be played.

standardAnnouncement true or false

  • true to use standard announcements provided by TENIOS
  • false to use announcements uploaded (and named) by you via the TENIOS customer portal
announcementName The name of the announcement. Please use the TENIOS customer portal to look up the announcements available to you

ANNOUNCEMENT example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "ANNOUNCEMENT",
         "standardAnnouncement": false,
         "announcementName": "MySpecialAnnouncement"
      }
   ]
}

SAY block

text The text which should be spoken.
voiceName The name of the voice with which the text is transmitted. The syntax looks like this: <language>. <gender>. <n> The following languages are available: en, en-au, en-gb, de, da, nl, fr, it, ja, ko, nb, pl, pt, ro, ru, es, sv, tr gender indicates whether the voice is male or female. n can take the values ​​1 or 2, where 2 is an alternative voice variant (not available in all languages). example: de.female.1, de.male.1 List of the available languages: en.female.1)*, en.female.2, en.female.3)*, en.male.2, de.female.1, de.female.2)*, de.female.3, de.female.4, de.female.5, de.female.6 (Swiss), de.male.1 de.male.2, de.male.3, de.male.4, a.male.1, a.female.1, nl.female.1, nl.female.2, nl.male.1, en-gb.female.1, en-gb.female.2, en-gb.male.1, en-gb.male.2, fr.female.1, fr.female.2, fr.female.3, fr.female.4 (Swiss), fr.male.1, fr.male.2, fr.male.3, it.female.1, it.female.2, polly.carla, it.male.1, ja.female.1, ja.female.2, ja.male.1, ko.female.1, ko.female.2, nb.female.1, pl.female.1, pl.male.1, pt.female.1, pt.male.1, ro.female.1, ru.female.1, ru.male.1, es.female.1, es.female.2, es.male.1, sv.female.1, sv.female.2, tr.female.1, tr.female.2, hi.female.1
useSsml true or false SSML can be used to enhance voice generation by inserting special tags. See: https://www.w3.org/TR/speech-synthesis11/ or the full specification. For a simpler introduction, we would recommend Amazon’s page on SSML https://docs.aws.amazon.com/polly/latest/dg/supported-ssml.html Please note, that TENIOS does not support Amazon-specific tags. Do not wrap the entire text in tags (it is automatically wrapped by our system)..

* Voices with a higher quality

SAY example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "SAY",
         "text": "Hello, how are you doing?",
         "voiceName": "de.female.3",
         "useSsml": false
      }
   ]
}

ROUTINGPLAN block

This block can be used to integrate pre-defined routingplans in the call flow.

routingplanName The name of the Named_Routing Please use the TENIOS customer portal to look up the Named_Routingplan available to you. Please make sure to use the exact name (including upper/lower case) as is used on the portal.

ROUTINGPLAN example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "ROUTINGPLAN",
         "routingplanName": "MySpecialRouting"
      }
   ]
}

COLLECT_DIGITS block

standardAnnouncement true or false

  • true to use standard announcements provided by TENIOS
  • false to use announcements uploaded (and named) by you via the TENIOS customer portal
announcementName The name of the announcement. Please use the TENIOS customer portal to look up the announcements available to you
standardErrorAnnouncement true or false For the error announcement, but analogous to “standardAnnouncement “.
errorAnnouncementName The name of the error announcement For the error announcement, but analogous to “announcementName”.
variableName The name of the variable. Only lowercase alphanumeric and _ characters are allowed.
allowSpeechInput Optional true or false (Default is false) Allows detection of speech input, in addition to detecting DTMF input.
language Optional The language of the speech input (default is en-US) See COLLECT_SPEECH Block
asrProvider Optional Automatic speech recognition provider (Default is “GOOGLE”). It can be either “GOOGLE”, “MICROSOFT” or “OPENAI”.
minDigits The minimum number of digits to be entered via DTMF. You can allow between 1 and 32 digits.
maxDigits The maximum number of digits to be entered via DTMF. You can allow between 1 and 32 digits.
terminator The terminator for ending the DTMF input It can be either * or # benutzt werden.
maxTries The maximum number of retries on invalid or missing DTMF input You can allow up to 10 tries
timeout The timeout (in seconds) per try The maximum timeout is 300 seconds. (Please don’t confuse this with the “blockTimeout” parameter of some other blocks.)

COLLECT_DIGITS example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "COLLECT_DIGITS",
         "standardAnnouncement": false,
         "announcementName": "MySpecialAnnouncement",
         "standardErrorAnnouncement": false,
         "errorAnnouncementName": "MySpecialErrorAnnouncement",
         "variableName": "my_var",
         "allowSpeechInput": true,
         "asrProvider": "GOOGLE",
         "language": "de-DE",
         "minDigits": 1,
         "maxDigits": 5,
         "terminator": "#",
         "maxTries": 3,
         "timeout": 10
      }
   ]
}

 

COLLECT_SPEECH block

This block provides automatic speech recognition (ASR – Automatic Speech Recognition). For example, this block can be used to request the caller to formulate his or her request or information using natural language. The speech is recorded and sent in the background to the Speech-to-Text Cloud services from Google, Amazon or Microsoft, depending on the option selected. The recognized text is stored in a variable and delivered with the subsequent HTTPS POST-Requests of the API.

standardAnnouncement Defines if the (main) announcement is a sytem announcement provided by tenios or a custom one. Can be true or false

    • true to use standard announcements provided by TENIOS
    • false to use announcements uploaded (and named) by you via the TENIOS customer portal
announcementName Optional The name of the announcement. Please use the TENIOS customer portal to look up the announcements available to you. If you use the TTS function with the parameter “text”, playback of existing announcements is not possible. Please do not set this parameter, otherwise you will receive an error.
standardMissingInputAnnouncement Optional Defines if the announcement which is played when no speech input is recognized is a sytem announcement provided by tenios or a custome one. Can be true or false, analogous to “standardAnnouncement ” Only use with parameter “announcementName”.
missingInputAnnouncementName Optional The name of the missing input announcement-For the missing input announcement, but analogous to “announcementName”. Only use with parameter “announcementName”.
text Optional The text which should be spoken. (Text-to-Speech / TTS function) If TTS is used, please delete “announcementName”, “standardMissingInputAnnouncement” und “missingInputAnnouncementName” in your json-request.
voiceName Optional The name of the voice with which the text is transmitted. The syntax looks like this: <language>. <gender>. <n> Only use with TTS and parameter “text”. see SAY-block
useSsml Optional true or false SSML can be used to enhance voice generation by inserting special tags. Only use with TTS and parameter “text”. see SAY-block
asrProvider Automatic speech recognition provider (Default is “GOOGLE”). It can be either “GOOGLE”, “MICROSOFT” or “OPENAI”.
asrProviderConfigurationName Optional The name of one of your ASR provider configurations. This is an advanced option. If specified, an ASR provider configuration which you can define in the Tenios Customer Portal will be used instead of our integrated ASR provider setups. Please note:

    • This option cannot be used together with the “dataType” option.
    • the name/type of ASR provider configuration (“GOOGLE”, “MICROSOFT” or “OPENAI”) must match the setting in the “asrProvider” option
language The language of the speech input Must be in the format of “xx-YY”, where xx is a two-letter language code (ISO 639), and YY is a two-letter country code (ISO 3166). Examples would be “en-GB” for British English, or “de-DE” for German (Germany).Not every language/country combination is supported. Our current list is:ar-ar-AE, ar-BH, ar-DZ, ar-EG, ar-IL, ar-IQ, ar-JO, ar-KW, ar-LB, ar-MA, ar-OM, ar-PS, ar-QA, ar-SA, ar-TN, bg-BG, ca-ES, cs-CZ, da-DK, de-DE, de-CH (Swiss), el-GR, en-AU, en-CA, en-GB, en-GH, es-CR, es-DO, es-EC, es-ES, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE, fi-FI, fr-CA, fr-FR, fr-CH (Swiss), he-IL, hi-IN, hr-HR, hu-HU, id-ID, is-IS, it-IT, ja-JP, ko-KR, lt-LT, lv-LV, ms-MY, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sr-RS, sv-SE, th-TH, tr-TR, uk-UA, vi-VN
alternativeLanguages Optional Alternative language codes as a list, with each value in format “xx-YY”, see the language parameter. This uses the Multiple Language Recognition feature, which Google offers Multiple Language Recognition Note: This feature is currently not supported when “asrProvider”:“MICROSOFT” is selected Note: Google currently allows a maximum of 3 alternativeLanguages.
variableName The name of the variable. Only lowercase alphanumeric and _ characters are allowed. The value of the COLLECTED-Variable is available in subsequent call control requests (as well as other external posts), prefixed with „collected_“. So if your variable name is “my_var”, then it will be available under the name “collected_my_var”.
datatype Optional The name of the data type. dataType allows you to specify a specific expected data type to be used. The list can be expanded in the future. The following values are currently allowed:

  • datatype-address
  • datatype-number
  • datatype-any
  • datatype-person
  • datatype-last-name
  • datatype-given-name
  • datatype-date-time
  • datatype-date
  • datatype-time
  • datatype-email
  • datatype-phone-number
  • datatype-language
  • datatype-yesno

Please note: If a datatype is specified, setting the asrProvider has not effect. Also setting the parameter audioPushUrl will have no affect, because the audio file is not available when the parameter datatype is set.
maxTries The maximum number of retries on invalid or missing DTMF input You can allow up to 10 tries.
keywordHints Optional A list of strings that contain words and phrases as “clues” to improve recognition. These are then passed to the Google API (see SpeechContext)
timeout Optional The maximum time for recording, it can be a maximum of 59s. Note, this is the maximum recording time, if the caller says nothing more and “silence” is recognized, the recording can be stopped earlier.
audioPushUrl Optional A URL to which the audio file recorded for speech recognition should be posted. The file is transferred with the content type “audio/wav” in WAV format. Only URLs with the HTTPS protocol are supported. The parameter will have no affect when the parameter datatype is also set, because the audio file is not available in that case.
asrStart Optional It is possible to start the recording for ASR before the played announcement ends. In the request you can define if this functionality should be enabled. Choose the parameter “END_OF_OUTPUT”, if ASR should start before the end of the announcement. With “BEGINNING_OF_OUTPUT” you choose to trigger ASR after the start of the announcement.
asrStartOffsetMs Optional Defines the value in ms when the recording for ASR should start before the played announcement ends. If you have selected “END_OF_OUTPUT” you can set eg. -500. ASR will startet 500ms before the announcement ends. With “BEGINNING_OF_OUTPUT” you can set eg. 3000, ASR will trigger 3 seconds after the announcement has started.
eventUrl Optional A URL to post events that occur during the execution of the COLLECT_SPEECH block. At the moment only DTMF events are implemented, which are generated as soon as an input is made via the telephone keypad.

COLLECT_SPEECH example

HTTP Status Code: 200 (OK)

{ 
  "blocks" : [ 
     { 
        "blockType": "COLLECT_SPEECH", 
        "standardAnnouncement": false, 
        "announcementName": "MySpecialAnnouncement", 
        "standardMissingInputAnnouncement": false, 
        "missingInputAnnouncementName": "MySpecialMissingInputAnnouncement", 
        "text": "Hello, how are you doing?", 
        "missingInputText": "Sorry, can you please repeat?",
        "voiceName": "en.female.3", 
        "useSsml": false, 
        "asrProvider":"GOOGLE", 
        "asrProviderConfigurationName": "MYASRprovider", 
        "language": "de-DE", 
        "alternativeLanguages": ["en-US","fr-FR"], 
        "variableName": "myvar", 
        "datatype": "datatype-address", 
        "maxTries": 3, 
        "keywordHints": [ "word1", "word2" ],
        "audioPushUrl": "https://mein_collect-speech_service.de",
        "asrStart": "END_OF_OUTPUT" or "BEGINNING_OF_OUTPUT", 
        "asrStartOffsetMs": -500 or 3000 
     }
  ] 
}

HANGUP block

It can be used to terminate a call.

hangupCause The following list of reason-codes contains detailed information about the underlying reason for hanging up a call:

  • UNALLOCATED_NUMBER: This cause indicates that the called party cannot be reached because, although the called party number is in a valid format, it is not currently allocated (assigned).
  • NO_ROUTE_TRANSIT_NET: This cause indicates that the equipment sending this cause has received a request to route the call through a particular transit network, which it does not recognize. The equipment sending this cause does not recognize the transit network either because the transit network does not exist or because that particular transit network, while it does exist, does not serve the equipment which is sending this cause..
  • NO_ROUTE_DESTINATION: This cause indicates that the called party cannot be reached because the network through which the call has been routed does not serve the destination desired. This cause is supported on a network dependent basis.
  • USER_BUSY: This cause is used to indicate that the called party is unable to accept another call because the user busy condition has been encountered. This cause value may be generated by the called user or by the network. In the case of user determined user busy it is noted that the user equipment is compatible with the call.
  • NO_USER_RESPONSE: : This cause is used when a called party does not respond to a call establishment message with either an alerting or connect indication within the prescribed period of time allocated.
  • NO_ANSWER: This cause is used when the called party has been alerted but does not respond with a connect indication within a prescribed period of time. Note – This cause is not necessarily generated by Q.931 procedures but may be generated by internal network timers.
  • SUBSCRIBER_ABSENT: This cause value is used when a mobile station has logged off, radio contact is not obtained with a mobile station or if a personal telecommunication user is temporarily not addressable at any user-network interface. Sofia SIP will normally raise USER_NOT_REGISTERED in such situations..
  • CALL_REJECTED: This cause indicates that the equipment sending this cause does not wish to accept this call, although it could have accepted the call because the equipment sending this cause is neither busy nor incompatible. The network may also generate this cause, indicating that the call was cleared due to a supplementary service constraint. The diagnostic field may contain additional information about the supplementary service and reason for rejection.
  • NUMBER_CHANGED: This cause is returned to a calling party when the called party number indicated by the calling party is no longer assigned, The new called party number may optionally be included in the diagnostic field. If a network does not support this cause, cause no: 1, unallocated (unassigned) number shall be used.
  • REDIRECTION_TO_NEW_DESTINATION: This cause is used by a general ISUP protocol mechanism that can be invoked by an exchange that decides that the call should be set-up to a different called number. Such an exchange can invoke a redirection mechanism, by use of this cause value, to request a preceding exchange involved in the call to route the call to the new number.
  • EXCHANGE_ROUTING_ERROR: This cause indicates that the destination indicated by the user cannot be reached, because an intermediate exchange has released the call due to reaching a limit in executing the hop counter procedure. This cause is generated by an intermediate node, which when decrementing the hop counter value, gives the result 0.
  • DESTINATION_OUT_OF_ORDER: This cause indicates that the destination indicated by the user cannot be reached because the interface to the destination is not functioning correctly. The term “not functioning correctly” indicates that a signal message was unable to be delivered to the remote party; e.g. a physical layer or data link layer failure at the remote party, or user equipment off-line.
  • INVALID_NUMBER_FORMAT: This cause indicates that the called party cannot be reached because the called party number is not in a valid format or is not complete.
  • FACILITY_REJECTED: This cause is returned when a supplementary service requested by the user cannot be provide by the network.
  • NORMAL_UNSPECIFIED: This cause is used to report a normal event only when no other cause in the normal class applies..
  • NORMAL_CIRCUIT_CONGESTION: This cause indicates that there is no appropriate circuit/channel presently available to handle the call.
  • NETWORK_OUT_OF_ORDER: This cause indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time e.g. immediately re-attempting the call is not likely to be successful.
  • NORMAL_TEMPORARY_FAILURE: This cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g. the user may wish to try another call attempt almost immediately.
  • SWITCH_CONGESTION: This cause indicates that the switching equipment generating this cause is experiencing a period of high traffic.
  • REQUESTED_CHAN_UNAVAIL: This cause is returned when the other side of the interface cannot provide the circuit or channel indicated by the requesting entity.
  • OUTGOING_CALL_BARRED: This cause indicates that although the calling party is a member of the CUG for the outgoing CUG call, outgoing calls are not allowed for this member of the CUG..
  • INCOMING_CALL_BARRED: This cause indicates that although the called party is a member of the CUG for the incoming CUG call, incoming calls are not allowed to this member of the CUG.
  • BEARERCAPABILITY_NOTAUTH: This cause indicates that the user has requested a bearer capability that is implemented by the equipment which generated this cause but the user is not authorized to use.
  • BEARERCAPABILITY_NOTAVAIL: This cause indicates that the user has requested a bearer capability which is implemented by the equipment which generated this cause but which is not available at this time.
  • BEARERCAPABILITY_NOTIMPL: This cause indicates that the equipment sending this cause does not support the bearer capability requested.
  • FACILITY_NOT_IMPLEMENTED: This cause indicates that the equipment sending this cause does not support the requested supplementary services.
  • SERVICE_NOT_IMPLEMENTED: This cause is used to report a service or option not implemented event only when no other cause in the service or option not implemented class applies.
  • INCOMPATIBLE_DESTINATION: This cause indicates that the equipment sending this cause has received a request to establish a call which has low layer compatibility, high layer compatibility or other compatibility attributes (e.g. data rate) which cannot be accommodated.
  • RECOVERY_ON_TIMER_EXPIRE: This cause indicates that a procedure has been initiated by the expiration of a timer in association with error handling procedures. This is often associated with NAT problems. Ensure that “NAT Mapping Enable” is turned on in your ATA. If it is not NAT related it can sometimes be provider related, make sure to ensure another outbound provider does not solve the problem.
  • ORIGINATOR_CANCEL: The calling party hung up the call.

HANGUP example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "HANGUP",
         "hangupCause": "USER_BUSY"
      }
   ]
}

CALL_SETTINGS block

forwardAni Optional CallerID. “ANI” property, which allows to override the ANI for all following bridge/originate commands (until another CALL_SETTINGS block overrides this again).
acdPriority Optional In ACD blocks, if this flag is set to true, the call is given priority over other calls which do not have this flag set.
customSipVariables Optional Allows setting custom SIP headers for REFER and BRIDGE blocks. When passed to customer’s system the variable names get automatically the prefix “X-TCC”:

e.g.: “X-TCC-variable_A”

The maximum length of both variable names and values is restricted to 300 characters. The following characters can be used:

  • a-z
  • A-Z
  • 0-9
  • – (dash)
  • _ (underscore)

It is possible to remove custom SIP variables by setting them to null (see example 2 below).

CALL_SETTINGS example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "CALL_SETTINGS",
         "forwardAni": "+4930700",
         "acdPriority": true,
         "customSipVariables": [
            {
               "name": "variable_A",
               "value": "variable_A_value"
            },
            {
               "name": "variable_B",
               "value": "variable_B_value"
            }
         ]
      },
      {
         "blockType": "BRIDGE",
         "destinations": [
            {
               "destination": "CUSTOM_SIP_TRUNK",
               "destinationType": "SIP_TRUNK",
               "timeout": "25"
            }
         ],
         "bridgeMode": "SEQUENTIAL"
      }
   ]
}

 

Example 2: Change customSipVariables for further Call Control blocks

The custom headers get passed to the customer’s system on every request. However, if you are using multiple blocks and you want that only a single header or no header to be passed for a specific block (e.g.: “blockType” : “REFER”) then you can remove it by setting the variable value to null.
In the following example, the variables A and B are both sent to the BRIDGE block, but only variable A gets passed to the REFER block, because B has been set to null and thereby removed.
{
   "blocks": [
      {
         "blockType": "CALL_SETTINGS",
         "forwardAni": "+495555555",
         "customSipVariables": [
            {
               "name": "variable_A",
               "value": "variable_A_value"
            },
            {
               "name": "variable_B",
               "value": "variable_B_value"
            }
         ]
      },
      {
         "blockType": "BRIDGE",
         "destinations": [
            {
               "destination": "CUSTOM_SIP_TRUNK",
               "destinationType": "SIP_TRUNK",
               "timeout": 25
            }
         ],
         "bridgeMode": "SEQUENTIAL"
      },
      {
         "blockType": "CALL_SETTINGS",
         "customSipVariables": [
            {
               "name": "variable_B",
               "value": null
            }
         ]
      },
      {
         "blockType": "REFER",
         "phoneNumber": "+49221987654321"
      }
   ]
}

REFER block

This block sends a SIP REFER message with the configured SIP URI back to the SIP Trunk and terminates the call.

uri

The sip uri which will be put into the the Refer-To header in the related REFER message.

REFER block example

HTTP Status Code: 200 (OK)

{
   "blocks": [
      {
         "blockType": "REFER",
         "uri": "sip:+49221554003005@tenios.com"
      }
   ]
}

The REFER block may only be used, if the call came in via your registered SIP Trunk in TENIOS Portal. If the block is accidentally used outside of Trunk Routing, the call will be hung up immediately.

 

TOP