Fragen? 0800 55400300

Makecall API

The Makecall API allows to initiate a call to the PSTN.

Initiate a call to the PSTN:

Method to initiate a call to the PSTN. You have to provide two phone numbers. In the first step the destination_number will be called. As soon as this call is answered, the tenios_number will be called and the assigned routing plan is executed. If you have provided a callstate_info_url, a HTTPS POST request with callstate information we be sent on every call status change.

If you configure a routingplan with an API Routing Control Block for the tenios_number , you will see the id returned by the makecall/init request in the variable callback_id. Furthermore you will see the uuid of the call to the tenios_number in the variable callback_bleg_uuid.

Example:

{
    "requestType":"EXTERNAL_CALL_CONTROL",
    "customerNumber":200002,
    "accessKey":"twteztwzetzw",
    "variables":{
        "callback_bleg_uuid":"615dab09-1a48-4e61-8a0d-9244251cfe6d",
        "destination_number":"+492215540030",
        "callback_id":"66195",
        "correlation_id":"7bb824c4-cc20-11ea-90f0-57d7f6704fca",
        "call_uuid":"7bb824c4-cc20-11ea-90f0-57d7f6704fca",
        "caller_id_number":"+492215540030"
    },
    "callControlUuid":"46250866-066f-4226-85a4-4047270b32e9",
    "loopCount":0,
    "requestStatus":"REQUESTING_BLOCKS",
    "blocksProcessingResult":null
}

 

 

POST https://api.tenios.com/makecall/init

 

Request Parameter:

access_key
String		 The API Access Key. It can be found in the menu MY ACCOUNT -> General Settings in the section API in the customer portal
destination_number
String		 The destination number of the call you want to establish.
tenios_number
String		 The service number in your account where the call is bridged to after the call is connected to the destination_number.
caller_id
String
Optional		 The caller_id which should be signalled. It is possible to use all phone numbers which are assignes to your TENIOS account (plus max. 5-digit Extension).
callstate_info_url
String
Optional		 An URL (HTTPS) which is posted on call state changes with information about the current call status.
destination_origination_timeout
 Integer
Optional		 The number of seconds until the origination timeout (e.g. ring time) at the destination. This can be set from 5 to 120 seconds.

Example 2:
(incl. destination_origination_timeout)

{
    "requestType":"EXTERNAL_CALL_CONTROL",
    "customerNumber":200002,
    "accessKey":"XXXX-XXXX-XXXXX",
    "variables":{
        "callback_bleg_uuid":"615dab09-1a48-4e61-8a0d-9244251cfe6d",
        "destination_number":"+492215540030",
        "callback_id":"66195",
        "correlation_id":"7bb824c4-cc20-11ea-90f0-57d7f6704fca",
        "call_uuid":"7bb824c4-cc20-11ea-90f0-57d7f6704fca",
        "caller_id_number":"+492215540030",
        "destination_origination_timeout":"60"
    },
    "callControlUuid":"46250866-066f-4226-85a4-4047270b32e9",
    "loopCount":0,
    "requestStatus":"REQUESTING_BLOCKS",
    "blocksProcessingResult":null
}

 

Response Parameter:

id The Id of the makecall request. This Id will be provided in the call status information if an callstate_info_url was stated.

 

Parameter passed in the JSON of the requests to the callstate_info_url:

callback_id The id of the callback that generated this call.
call_uuid The uuid of the call.
callback_a_number The A number of the callback, e.g the call leg that is called first.
callback_b_number The B number of the callback, e.g. the call leg which is called when the A leg gets connected.
call_leg Indicates the leg of the callback. Can be A_LEG or B_LEG.
destination_number The destination number of the make call request.
callerid The callerid of this call leg
dialstatus The current status of the call. possible values are:

  • ANSWER – The call git answered / connected.
  • BRIDGE – The call leg got bridged.
  • HANGUP_COMPLETE – The call leg was hung up.

 

Example of a successful request:

Request:

{
    "access_key":"XXXXX-XXXX-XXXXXX", 
    "destination_number":"+4922155400300", 
    "tenios_number":"+4922155400300",
    "callstate_info_url":"https://myserver.com/callstate"
}

 

API-Response:

HTTP Status Code: 200 (OK)

{
    "id" : 10
}

 

Examples of invalid requests:

 

BAD_CREDENTIALS
This error is returned if a wrong or invalid access_key was provided.

Request:

{
    "access_key" : "XXXXX-XXXX-XXXXXX",
    "callback_config_id" : "39d3f096-ad39-4fb1-a666-8353b27e2a8b",
    "callback_number" : "+491234567890",
    "delay" : 30
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
    "error_code": "BAD_CREDENTIALS",
    "error_message": "Bad credentials",
    "fields": []
}
INVALID_JSON
This error is returned if the passed JSON object contains unknown parameters or is invalid in general.

Request:

{
        "access_key" : "XXXXX-XXXX-XXXXXX",
        "destination_number":"+4922155400300",
        "tenios_number":"+49221554003",
        "caller_id":"+4922155400399999",
        "unknown_parameter":"unknown"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
        "error_code": "INVALID_JSON",
        "error_message": "An invalid JSON object was provided in the request body.",
        "fields": [
            "unknown_parameter"
        ]
}
MAKE_CALL_INVALID_NUMBER
This error is returned if the provided tenios_number in invalid not assigned to the TENIOS account.

Request:

{
    "access_key" : "XXXXX-XXXX-XXXXXX",
    "destination_number":"+4922155400300",
    "tenios_number":"+4922155400300",
    "caller_id":"+4922155400300"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
    "error_code": "MAKE_CALL_INVALID_NUMBER",
    "error_message": "Invalid 'tenios_number'. The provided phone number for the 'tenios_number' is not valid. You can use only geographical and freephone numbers which are assigned to your account",
    "fields": [
        "tenios_number"
    ]
}
MAKE_CALL_INVALID_CALLSTATE_INFO_URL
This error is returned if the provided callstate_info_url  is invalid or not a HTTPS URL.

Request:

{
    "access_key" : "XXXXX-XXXX-XXXXXX",
    "destination_number":"+4922155400300",
    "tenios_number":"+49221554003",
    "callstate_info_url":"http://test.com"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
    "error_code": "MAKE_CALL_INVALID_CALLSTATE_INFO_URL",
    "error_message": "Provided callstate_info_url is invalid https url.",
    "fields": [
        "callstate_info_url"
    ]
}

TOP