Dokumentation

Makecall API

Mit der Makecall API können Sie Anrufe in das öffentliche Telefonnetz initiieren.

Anruf in das öffentliche Telefonnetz

Mit dieser Methode wird ein Anruf in das öffentliche Telefonnetz initiiert. Es werden zwei Telefonnummern angegeben. Zuerst wird die destination_number angewählt. Sobald dieser Anruf verbunden wird, erfolgt die Anwahl der tenios_number und der für diese Rufnummer hinterlegte Routingplan wird ausgeführt. Wenn Sie eine callstate_info_url angegeben haben, wird bei jedem Wechsel des Anrufstatus eine HTTPS POST Anfrage mit Informationen zum Anrufstatus an diese URL getätigt. Wenn Sie hinter der tenios_number einen Routingplan mit einem Call Control Block verwenden, sehen Sie in der Variablen callback_id die id die beim Aufruf von makecall/init zurückgegeben wird. Zudem finden Sie in der Variablen callback_bleg_uuid die uuid des Anrufs an die tenios_number.

Beispiel:

{
   "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
}
Die Makecall-Funktion bietet Ihnen optional die Möglichkeit Call Control Funktionen zu integrieren. Details zu den Call Control Funktionen finden Sie hier.
POSThttps://api.tenios.com/makecall/init

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
destination_number StringDie Zielnummer, die angerufen werden soll.
tenios_number StringDie TENIOS Servicenummer mit der der Anruf nach dem Verbindungsaufbau zur destination_number verbunden wird.
caller_id String OptionalDie Anruferkennung, die signalisiert werden soll. Es können alle im Kundenkonto zugewiesenen Rufnummern (plus max. 5-stellige Nebenstelle) verwendet werden.
callstate_info_url String OptionalEine URL (HTTPS), die bei jedem Wechsel eines Anrufstatus mit den entsprechenden Informationen aufgerufen wird.
destination_origination_timeout Integer OptionalDie Sekundenzahl bis zur Zeitüberschreitung (z.B. Klingelzeit) beim Ziel. Diese kann auf 5 bis 120 Sekunden eingestellt werden.

Beispiel 2: (inkl. 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
}

 

Antwortparameter:

idDie Id der makecall Anfrage. Diese Id wird auch in den Anrufstatusinformationen mitgegeben, wenn eine callstate_info_url angegeben wurde.

Parameter die im JSON der Anfragen an die callstate_info_url mitgegeben werden:

callback_idDie Id der makecall Anfrage die diesen Anruf generiert hat.
call_uuidDie uuid des Anrufs.
callback_a_numberDie A-Nummer des „Anrufbeins“.
callback_b_numberDie B-Nummer des „Anrufbeins“.
call_legDas „Anrufbein“ zu dem diese Anfrage gehört. Kann den Wert A_LEG oder B_LEG haben.
destination_numberDie Zielnummer der makecall Anfrage.
calleridDie Anruferkennung für diese „Anrufbein“
dialstatusDer aktuelle Status des Anrufs. Mögliche Werte:

  • ANSWER – Das „Anrufbein“ wurde angenommen / verbunden
  • BRIDGE – Das „Anrufbein“ wurde mit dem.
  • HANGUP_COMPLETE – Das „Anrufbein wurde aufgelegt“.

Beispiel für eine erfolgreiche Anfrage:

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
}

 

{
"id": 10
}

 

Beispiele für fehlerhafte Anfragen:

BAD_CREDENTIALS
Dieser Fehler wird zurückgegeben, wenn ein falscher oder ungültiger access_key angegeben wurde.

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
Dieser Fehler wird zurückgegeben, wenn das übergebene JSON unbekannte Parameter enthält oder generell ungültig ist.

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
Dieser Fehler wird zurückgegeben, wenn die angegebene tenios_number ungültig oder dem verwendeten TENIOS-Konto nicht zugewiesen ist.

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
Dieser Fehler wird zurückgegeben, wenn die angegebene callstate_info_url ungültig oder keine HTTPS URL ist.

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"
   ]
}
Die Makecall-Funktion bietet Ihnen optional die Möglichkeit Call Control Funktionen zu integrieren. Details zu den Call Control Funktionen finden Sie hier.

Wenn Sie hinter der tenios_number einen Routingplan mit einem Call Control Block verwenden, sehen Sie in der Variablen callback_id die id, die beim Aufruf von makecall/init zurückgegeben wird. Zudem finden Sie in der Variablen callback_bleg_uuid die uuid des Anrufs an die tenios_number.

Beispiel:

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

 

Dieser Artikel könnte Sie auch interessieren …