The VoiceRecord REST Interface is very similar to the Developer Garden REST Interface. Therefore, to invoke a REST method, the aquisition of a security token from the Security Token Server is required.
The only difference is that the authentication token for the Voice Record Lab API has to be obtained from a different path at the Security Token Server:
| Path for Developer Garden Services | https://sts.idm.telekom.com/rest-v1/tokens/odg |
| Path for Voice Record Lab API | https://sts.idm.telekom.com/rest-v1/tokens/voicerecording |
For further information on this procedure, please see the Appendix of the Developer Garden Documentation.
This ressource realizes the method createVoiceRecord
Table 3.13. REST resource information for REST Method: Initiate recording of a voice data record
| HTTP Method | POST |
| REST URL | https://esg.i3alab.net/es-odg/voicerecord-service/rest/<environment>/voicerecord |
Table 3.14. REST resource path for REST Method: Initiate recording of a voice data record
| Path element | Meaning |
|---|---|
/esg.i3alab.net/es-odg/voicerecord-service/rest | URL of the REST interface |
| The environment in which the service should be used. Possible values are:
|
/voicerecord | |
Table 3.15. Request Parameters for REST Method: Initiate recording of a voice data record
| Name | Description |
|---|---|
| The underlying voice application calls this phone number and prompts the callee for the voice message to be stored. |
| The call establishment will be started at the
given date and time. The If no
The format follows ISO8601 specification. |
| URL reference to a voice call data object that stores an individual welcome message prompt. If no welcome message prompt is specified, the default prompt is used. |
| URL reference to a voice call data object that stores an individual goodbye message prompt which will be played at the end of the recording. If no goodbye message prompt is specified, the default goodbye message promt is used. |
| URL reference to a voice call data object that stores an individual message prompt which will be played when the callee speaks not loud enough. If no message prompt is specified, the default message prompt is used. |
| An application specific maximum recording time for a voice call data object in seconds. This timeout can be used to override the system specific timeout of 30 minutes (1800 seconds), if it is too large. Maximum recording times larger than 30 minutes are forbidden. |
REST invocation (example)
Example 3.1. REST request for Method: Initiate recording of a voice data record
POST /es-odg/voicerecord-service/rest/production/voicerecord/ HTTP/1.1 Host: esg.i3alab.net Authorization: TAuth realm="https://odg.t-online.de",tauth_token="<token>" Accept: application/json Content-type: application/x-www-form-urlencoded Content-Length: 59 recordingPhoneNo=016097xxxxxx&startTime=2010-06-01T12:30:00
Example 3.2. REST response for Method: Initiate recording of a voice data record
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Date: Tue, 01 Jun 2010 12:30:01 GMT
Content-Type: application/json
{"mediaObjectRef": "moSJwSGsCH3MQNDY5gNmVYDHR7-xxxxxxxxx-1234567890000-1234567890000"}Table 3.16. Return values for REST Method: Initiate recording of a voice data record
| Field | Meaning |
|---|---|
| Unique references to voice call data object to be recorded. The reference is required in order to get either the status or the voice call data object itself. |
Table 3.17. Return codes for REST Method: Initiate recording of a voice data record
| REST HTTP code | Message (response body in case of error) |
|---|---|
| OK |
| No phone number was given. |
| The number format is invalid. |
| The number is not allowed. |
| Schedule time format is invalid. |
| Schedule time is invalid. |
| The schedule time exceeded: the number of days until the recording will start is higher than the limit. |
| Token is invalid. |
| Required permissions are missing. |
| The number is not allowed. |
| The environment is invalid. |
| Invalid welcome message URL. |
| Invalid goodbye message URL. |
| Invalid cannot hear you message URL. |
| The accept header is unknown. |
| An internal error occurred. |
In case of an error, the detail message is returned as response body:
Example 3.3. Example REST error response
HTTP/1.1 404 Not Found Transfer-Encoding: chunked Date: Tue, 01 Jun 2010 12:50:01 GMT Content-Length: 38 Content-Type: text/plain Vary: Accept-Encoding The media object reference is invalid.
