Interface Description
Introduction
Scope
This document describes the Txt2Voice HTTP GET Interface. It describes the basics of how to use the HTTP GET Interface ( from now on referred to as ‘Interface’) and provides a list of available parameters.
This document is intended for application developers and/or integrators. Basic knowledge of the HTTP protocol is assumed.
HTTP GET interface
Voice phone terminated messages
Usage
To send a message using the interface, the client creates and sends an HTTP GET request containing both login credentials and information regarding the sender, the actual message and its recipient(s). The URL is constructed using the server hostname and ports as shown below together with a query string made up of the parameters described in section 2.1.2:
https://get-spirispeech.spiricom.spirius.com:55550/sendtts
Upon reception of the GET-request Txt2Voice validates the credentials and parameters. If all checks are passed Txt2Voice
responds with a request=true and then proceeds to send the message to the given phone subscriber. Should there be
anything wrong with the request, it will be rejected with an HTTP error indicating the nature of the problem, please see
section of Response codes below.
If a delivery report URL is configured, a GET request will be sent from Txt2Voice to the client indicating if the message could be delivered. Delivery reports can be delivered via HTTP or HTTPS.
The client has to use TLS encryption to secure the connection when sending messages, although for the delivery reports the use of https encryption is not mandated.
There is no support for scheduling a message for later delivery. A message will be delivered as soon as possible.
Parameters
The table below lists available parameters for TTS messages. Parameters not marked as Mandatory can
be left out. Mandatory parameters must be present or the request will be rejected.
Parameter names are case sensitive.
Special characters like e.g. { } | \ ^ ~ [ ] ` # cannot be used. Please send only text that is easy to represent in
spoken language.
All parameters must be URI encoded.
| Name | Mandatory | Description | Example |
|---|---|---|---|
| User | Yes | Username of client. | User=myuser |
| Pass | Yes | Password of client. | Pass=mypassword |
| To | Yes | Recipient of the message, specified as MSISDN number in International format with preceding + character. |
To=+46701234567 |
| From | No | Sender of message specified as MSISDN number in International format with preceding + character. Can default to a pre-set number. Note that legislation in some countries requires that this number can be used to trace the sender of the call. The From number you set is not guaranteed to be displayed by all phone network operators. An omitted From number will result in undefined behaviour. |
From=+46701234567 |
| Msg | Yes | The actual message. | Msg=Hello+world |
| Lang | No | Set the language of the message. Default is EN for English. Available languages are AR, AU, BR, CA, CN, CZ, DE, DK, EN, ES, FI, FR, GB, GR, IN, IS, IT, JP, KR, NL, NO, PL, PT, RO, RU, SE, SK, TR, US and VN. See section 3.2 Two-Letter Country Codes. |
Response codes
This is not an exhaustive list of response codes, but show some of the most frequent errors returned from Txt2Voice.
| Code | Response | Description |
|---|---|---|
200 OK |
request=false&TransactionId=uuid | Request was received but could not be delivered as Voice call. No DLR will be sent. |
202 Accepted |
request=true&TransactionId=uuid | Message has been accepted for delivery as Voice call. DLR will be sent. |
401 Unauthorized |
Wrong user or password. | Wrong username or password. |
401 Unauthorized |
User account disabled. | User account disabled. |
404 Not Found |
Missing parameters: To. | The request was missing a mandatory parameter. |
400 Bad Request |
Malformed XML in Msg parameter. | The request contained malformed XML tags for voice control. |
400 Bad Request |
User present more than once in query string. | The request string contained more than one copy of the parameter named User. |
400 Bad Request |
Illegal character } in URL, remove character and try again. | Message contain an unsupported character. |
400 Bad Request |
Missing mandatory parameter Msg. | No message given (or message starts with the illegal character # which will result in the message being cut off). |
500 Internal Server Error |
The server encountered an unexpected condition which prevented it from fulfilling the request. | Unknown error. |
503 Service Unavailable |
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. | The TTS service is down or can’t be reached due to network problems. |
Voice control
It is possible to control playback speed and to add pauses directly in the text using a grammar that conforms to the W3C standards as defined in Speech Synthesis Markup Language (SSML) Version 1.0
The table shows the speech synthesis commands that have been implemented in Txt2Voice. Please note that single quotes must be used when assigning values to attributes in XML tags. If you use double quotes, we will do a dumb search and replace on your message to replace character “ with character ‘ before your request is processed. This operation will be avoided if the message string do not contain any double quotes.
| Name | Description |
|---|---|
| prosody rate | Control the playback speed, i.e. to speed up or slow down the reading speed. |
| break time | Pause playback, a command that allow you to add pauses between words being read. |
Examples of speed control:
1 | |
The price in dollars is spoken more slowly than the rest of the sentence.
Examples of a pauses in playback:
1 | |
There is a 5 seconds long pause before the last word is spoken.
Reattempts
If the Voice message cannot be delivered because there is no one to pick up the phone, it will be reattempted X times at Y interval.
Delivery Reports
If a delivery report URL has been configured, delivery reports are sent to the customer’s web server. Delivery reports is sent using http or https GET requests.
Push
Delivery reports will be sent out when a message has reached a final state. This is the only way to get DLRs from Txt2Voice.
Delivery reports will be sent as soon as they are available. The delivery report is sent using a http GET-request. Hostname, port etc. must be preset in the system. Using this information Txt2Voice connects and delivers the report, please see the example section below. The customer must be prepared to accept connections to the given hostname and port.
The DLR response will be delivered in the body of the GET request.
| Result | StatusCode | Description |
|---|---|---|
1 |
1 |
The message has been successfully delivered. |
2 |
1 |
The message could not be delivered. |
2 |
5 |
Internal error. |
Note that the Digits parameter, shown in the first example, will only be included if the receiver pressed any digits while listening on the message.
Success example:
1 | |
Fail example:
1 | |