Txt2Voice
Interface Description
HTTP GET v1.0

Document name:HTTP GET v1.0
Document number:EGN15001SCH
Revision:1.3
Author:Gunnar Nilsson
Date:2015-09-03
Information class:Open Information
Reviewer:Martin Kristell
Review date:2015-09-03
Name:SPIRIUS AB
VAT/REG number:556788-4183
Postal address:Box 67
371 21 KARLSKRONA
Telephone number:+46 (455) 65 55 00
Fax number:+46 (455) 65 55 19
Home page:www.spirius.com

© Copyright SPIRIUS AB 2018

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. SPIRIUS AB shall have no liability for any error or damages of any kind resulting from use of this document.

1. INTRODUCTION

1.1 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 HTTP1 protocol is assumed.

2. HTTP GET INTERFACE

2.1 Voice Phone Terminated Messages

2.1.1 Usage

To send a message using the interface, the client creates and sends a HTTP GET request containing both login credentials and information regarding 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.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.

2.1.2 Parameters

The table below lists available parameters for Text To Speech (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 encoded2

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword
ToYesRecipient of the message, specified as MSISDN number in International format with preceding ‘+’ character.To=+46701234567
FromNoSender 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 require 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
MsgYesThe actual message.Msg=Hello+world
LangNoSet 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.Lang=SE

2.1.3 Response Codes

This is not an exhaustive list of response codes, but show some of the most frequent errors returned from Txt2Voice.

CodeResponseDescription
200 OKrequest=false&TransactionId=uuidRequest was received but could not be delivered as Voice call. No DLR will be sent.
202 Acceptedrequest=true&TransactionId=uuidMessage has been accepted for delivery as Voice call. DLR will be sent.
401 UnauthorizedWrong user or password.Wrong username or password.
401 UnauthorizedUser account disabled.User account disabled.
404 Not FoundMissing parameters: ToThe request was missing a mandatory parameter.
400 Bad RequestMalformed XML in Msg parameter.The request contained malformed XML tags for voice control.
400 Bad RequestUser present more than once in query string.The request string contained more than one copy of the parameter named User.
400 Bad RequestIllegal character } in URL, remove character and try again.Message contain an unsupported character
400 Bad RequestMissing mandatory parameter Msg.No message given (or message starts with the illegal character # which will result in message being cut off).
500 Internal Server ErrorThe server encountered an unexpected condition which prevented it from fulfilling the request.Unknown error.
503 Service UnavailableThe 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.

2.1.4 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 (World Wide Web Consortium) standards:

Speech Synthesis Markup Language (SSML) Version 1.0      http://www.w3.org/TR/speech-synthesis/

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.

NameDescription
prosody rateControl the playback speed, i.e. to speed up or slow down the reading speed.
break timePause playback, a command that allow you to add pauses between words being read.

Examples of speed control:

Msg=The price of XYZ is <prosody rate='-50%'>$45</prosody>

The price in dollars is spoken more slowly than the rest of the sentence.

Examples of a pauses in playback:

Msg=The winner is <break time='5000ms'/>SPIRIUS.

There is a 5 seconds long pause before the last word is spoken.

2.1.5 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.

2.1.6 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.

2.1.7 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.

ResultStatusCodeDescription
11The message has been successfully delivered.
21The message could not be delivered.
25Internal 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:

Result=1&StatusCode1&Sequence=end&TransactionId=fa7a2ada-d3d4-4c93-a125-fec9ecd84f92&ProgressTime=87&Digits=22255

Fail example:

Result=2&StatusCode=1&Sequence=end&TransactionId=fa7a2ada-d3d4-4c93-a125-fec9ecd84f92&ProgressTime=5.

3. APPENDIX

3.1 Document History

RevisionDateSignatureComments
0.1 BETA2015-06-03GNFirst BETA revision 0.1
1.02015-07-09GNFirst revision 1.0
1.12015-07-10JRAdding 2.1.3 Controlling reading.
1.22015-07-14JRSmaller corrections done.
1.32015-08-31MKReviewed and updated. New URL.

3.2 Two-Letter Country Codes

CodeLanguage
AR
Arabic
AU
Australian
BR
Portuguese (Brazilian)
CA
Canadian French
CN
Mandarin Chinese
CZ
Czech
DE
German
DK
Danish
EN
English
ES
Spanish
FI
Finnish
FR
French
GB
Welsh
GR
Greek
IN
Hindi
IS
Icelandic
IT
Italian
JP
Japanese
KR
Korean
NL
Dutch
NONorwegian
PL
Polish
PTPortuguese
RO
Romanian
RU
Russian
SESwedish
SKSlovakian 
TR
Turkish
US
American English
VN
Vietnamese

3.3 URL Encoding

UTF-8 is used.