Fragen? 0800 55400300
View Categories

Makecall API

5 min read

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": "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"
   },
   "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"
   ]
}

 

{ "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