TENIOS allows to delegate the call control (partially) to a customer’s own server. This functionality is enabled by inserting an Call Control API block into a routing configuration.
Request parameters (from TENIOS to your server):
| requestType | The type of API request. This is always EXTERNAL_CALL_CONTROL for Call Control API requests |
| customerNumber | Your customer number (the same value you see in parentheses in the top right corner of the TENIOS customer portal) Please verify with every request. |
| accessKey | The accessKey you chose in the initial setup of the Call Control API block (via TENIOS customer portal) Please verify with every request. |
| variables | A key/value map with the keys you chose in the initial setup of the Call Control API block (via TENIOS customer portal) Can be used for anything, be it logging, or deciding the next steps. |
| loopCount | Starting from 0, counts the number of requests that have been made within this instance of the API Routing Control block In many simple applications, you will only want to send blocks, if loopCount is 0. Advanced applications may want to continue sending blocks in multiple iterations. |
| requestStatus | Possible Types are:
|
| blocksProcessingResult (only for loopCount > 0) | Contains the field validationErrors, which in turn contains a list of validation error messages. In the future, blocksProcessingResult will probably contain more information. |
Response parameters (from your server to TENIOS):
| blocks | An array of blocks. If this array is empty, the dialplan server will finish the Call Control API block, and continue the normal processing of the call. |
| blockType Mandatory | Type of block. Possible types are:
|
| blockTimeout | Timeout in seconds for the entire block. Some blocks require this attribute, others do not allow it:
|
Process flow:
When a call enters the Call Control API block, a POST request is sent from TENIOS to your server.
TENIOS POST-Request 0:
{
"requestType" : "EXTERNAL_CALL_CONTROL",
"customerNumber" : 200000,
"accessKey" : "XXXXX-XXXX-XXXXXX",
"variables" : {
"call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59",
"destination_number" : "+49800123456789",
"caller_id_number" : "+4989444444444"
},
"loopCount" : 0,
"requestStatus" : "REQUESTING_BLOCKS",
"blocksProcessingResult" : null
}
- loopCount: 0 means that this is the initial request for this Call Control API block (there will be more requests, see later)
- requestStatus: “REQUESTING_BLOCKS” means that you are allowed to send routing blocks in your response
- A blocksProcessingResult of null can be ignored for the initial request.
Sample response from your server to TENIOS:
You can respond to this HTTPS request as follows
Customer server response 0:
with one Block
{
"blocks" : [ {
"blockType" : "ANNOUNCEMENT",
"announcementName" : "Voicemail_Ansage",
"standardAnnouncement" : true
} ]
}
with more than one Block
Customer server response 0:
{
"blocks" :
[
{ "blockType" : "ANNOUNCEMENT",
"announcementName" : "Voicemail_Ansage",
"standardAnnouncement" : true
},
{ "blockType" : "SAY",
"text" : "Hello, how are you doing?",
"voiceName" : "de.female.3",
"useSsml" : false
},
{
"blockType" : "BRIDGE",
"destinations" : [ { "destination" : "1001",
"destinationType" : "SIP_USER",
"timeout" : 25 },
{ "destination" : "+4978787878",
"destinationType" : "EXTERNALNUMBER",
"timeout" : 30 }
],
"bridgeMode" : "SEQUENTIAL"
}
]
}
Upon receiving your response, our dialplan server will (try to) execute your blocks. Let’s assume in this case, that everything went well, and the announcement finished playing. Then after that, you will receive another request like:
TENIOS POST-Request 1:
{
"requestType" : "EXTERNAL_CALL_CONTROL",
"customerNumber" : 200000,
"accessKey" : "XXXXX-XXXX-XXXXXX",
"variables" : {
"call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59",
"destination_number" : "+49800123456789",
"caller_id_number" : "+4989444444444"
},
"loopCount" : 1,
"requestStatus" : "REQUESTING_BLOCKS",
"blocksProcessingResult" : {
"validationErrors" : [ ]
}
}
- loopCount has increased to 1 meaning this is the second request (we started to count at 0)
- requestStatus is again “REQUESTING_BLOCKS”, which means that you are allowed again to send routing blocks in your response (if you want)
- blocksProcessingResult contains an empty array of validationErrors – which is good: It means that your previous response didn’t result in any validation errors.
Customer-Response 1:
{
"blocks": []
}
Examples of invalid requests:
In case the blocks you sent e.g. in Response 0 contain an error:
Kundenserver-Response 0:
(with error)
{
"blocks" : [
{ "blockType" : "ANNOUNCEMENT",
"standardAnnouncement" : true
}
]
}
In this case the announcementName attribute is missing. As soon as one of the blocks you sent contains validation errors, the Call Control API block will be terminated, however, you will receive another request that will inform you about the error:
TENIOS POST-Request 1:
Information about the error
{
"requestType" : "EXTERNAL_CALL_CONTROL",
"customerNumber" : 200000,
"accessKey" : "XXXXX-XXXX-XXXXXX",
"variables" : { "call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59",
"destination_number" : "+49800123456789",
"caller_id_number" : "+4989444444444" },
"loopCount" : 1,
"requestStatus" : "VALIDATION_ERRORS",
"blocksProcessingResult" : {
"validationErrors" : [ "Validation error: blocks[0].announcementName may not be null" ]
}
}
- the requestStatus is not “REQUESTING_BLOCKS” anymore – which means you cannot send any more blocks (they would be ignored if you do). Instead, it now has the value “VALIDATION_ERRORS”, which means you should look into blocksProcessingResult
- blocksProcessingResult validation errors contains error messages, which should help a bit to pinpoint the error (Please note that for some errors on a lower JSON level, you will only receive the line and column number)