TTS API

Version: vbeta

Specification Release Notes Other versions

The TTS API enables you to send voice messages to your customers using variety of text to speech engines.

The service is currently on closed beta. If you are interested in using it, don't hesitate to contact us at support@tyntec.com.

Base URLs

https://api.tyntec.com/

Text to speech

tyntec’s TTS service is governed by two operations that allow you:

to send an TTS and
to query the status of a previously sent TTS

Important

tyntec stores status details for up to 3 months after the final delivery state is known.

Initiate a Text to speech call

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/tts/v1/calls \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/tts/v1/calls HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "from": "49123456789",
  "to": "1987654321",
  "message": "This is an example - the data is garbage.",
  "language": "ar_eg",
  "initialDelay": 0,
  "eventsUrl": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/tts/v1/calls',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/tts/v1/calls',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/tts/v1/calls', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/tts/v1/calls', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/tts/v1/calls");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/tts/v1/calls", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /tts/v1/calls

Sends an TTS via the POST HTTP method with parameters defined in the request body.

Body parameter

{
  "from": "49123456789",
  "to": "1987654321",
  "message": "This is an example - the data is garbage.",
  "language": "ar_eg",
  "initialDelay": 0,
  "eventsUrl": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	TextToSpeechRequest	true	TTS message you would like to send

Example responses

200 Response

{
  "callId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
  "status": "starting",
  "from": "49123456789",
  "to": "1987654321"
}

Responses

Status	Meaning	Description	Schema
200	OK	The callId of your request	TextToSpeechResponse
400	Bad Request	Invalid request	Problem
401	Unauthorized	Unauthorized	Problem
403	Forbidden	Forbidden	Problem
500	Internal Server Error	Something went wrong. :-(	Problem

Text to speech status events

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/tts/v1/calls/{callId}/events \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/tts/v1/calls/{callId}/events HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/tts/v1/calls/{callId}/events',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/tts/v1/calls/{callId}/events',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/tts/v1/calls/{callId}/events', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/tts/v1/calls/{callId}/events', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/tts/v1/calls/{callId}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/tts/v1/calls/{callId}/events", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /tts/v1/calls/{callId}/events

Returns the events recorded for this call ID.

Important

The TTS Message Status is available for 3 months after a final delivery state is reached.

Parameters

Name	In	Type	Required	Description
callId	path	string	true	The unique identifier provided for each request. (UUID format)

Example responses

200 Response

[
  {
    "callId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
    "direction": "outbound",
    "from": "49123456789",
    "to": "1987654321",
    "startTime": "2018-06-01T00:00:00+0200",
    "answerTime": "2018-06-01T00:00:00+0200",
    "endTime": "2018-06-01T00:00:00+0200",
    "duration": "10",
    "country": "DE",
    "rate": "0.0728",
    "price": "0.0001",
    "currency": "EUR",
    "network": "Germany-ACME mobile",
    "status": "started"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	Inline
401	Unauthorized	Unauthorized	Problem
403	Forbidden	Forbidden	Problem
404	Not Found	Not Found	Problem
500	Internal Server Error	Something went wrong. :-(	Problem

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[TextToSpeechEvent]	false	none	[This is the event object containing informations regarding the call.]
» callId	string(uuid)	false	none	Company's postal address
» direction	string	false	none	The direction of the call
» from	string	false	none	Phone number of the calling party in the international format E.164
» to	string	false	none	Phone number of the callee party in the international format E.164
» startTime	string(date-time)	false	none	The timestamp when the call started.
» answerTime	string(date-time)	false	none	The timestamp when the call was answered.
» endTime	string(date-time)	false	none	The timestamp when the call completed.
» duration	string	false	none	The duration in seconds of the call.
» country	string	false	none	The alpha 2 code of the destionation country.
» rate	string	false	none	The rate charge per minute for this country.
» price	string	false	none	The price charged for this call.
» currency	string	false	none	The currency used for this charge.
» network	string	false	none	The name of the network for the destination call.
» status	string	false	none	The status reported for this event.

Enumerated values

Property	Value
direction	outbound
direction	inbound
status	started
status	early
status	hangup
status	ringing
status	completed

Schemas

TextToSpeechRequest

{
  "from": "49123456789",
  "to": "1987654321",
  "message": "This is an example - the data is garbage.",
  "language": "ar_eg",
  "initialDelay": 0,
  "eventsUrl": "string"
}

Contract Array Response schema

Properties

Name	Type	Required	Restrictions	Description
from	string	true	none	Phone number of the calling party in the international format E.164
to	string	true	none	Phone number of the callee party in the international format E.164
message	string	true	none	The message you want to send via TTS call
language	string	true	none	language
initialDelay	integer(int32)	false	none	The initial pause before the TTS is announced through the call.
eventsUrl	string	false	none	Your URL for delivering the events for this call; leave empty for no events push.

Enumerated values

Property	Value
language	ar_eg
language	ar_sa
language	bg_bg
language	ca_es
language	zh_cn
language	zh_hk
language	zh_tw
language	hr_hr
language	cs_cz
language	da_dk
language	nl_be
language	nl_nl
language	en_au
language	en_ca
language	en_gb
language	en_in
language	en_ie
language	en_us
language	fi_fi
language	fr_ca
language	fr_fr
language	fr_ch
language	de_at
language	de_de
language	de_ch
language	el_gr
language	he_il
language	hi_in
language	hu_hu
language	id_id
language	it_it
language	ja_jp
language	ko_kr
language	ms_my
language	nb_no
language	pl_pl
language	pt_pt
language	ro_ro
language	ru_ru
language	sk_sk
language	sl_si
language	es_mx
language	es_es
language	sv_se
language	ta_in
language	th_th
language	tr_tr
language	vi_vn

TextToSpeechResponse

{
  "callId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
  "status": "starting",
  "from": "49123456789",
  "to": "1987654321"
}

Contract Entity schema

Properties

Name	Type	Required	Restrictions	Description
callId	string(uuid)	false	none	Company's postal address
status	string	false	none	Status of the call
from	string	false	none	Phone number of the calling party in the international format E.164
to	string	false	none	Phone number of the callee party in the international format E.164

Enumerated values

Property	Value
status	starting

TextToSpeechEvent

{
  "callId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
  "direction": "outbound",
  "from": "49123456789",
  "to": "1987654321",
  "startTime": "2018-06-01T00:00:00+0200",
  "answerTime": "2018-06-01T00:00:00+0200",
  "endTime": "2018-06-01T00:00:00+0200",
  "duration": "10",
  "country": "DE",
  "rate": "0.0728",
  "price": "0.0001",
  "currency": "EUR",
  "network": "Germany-ACME mobile",
  "status": "started"
}

This is the event object containing informations regarding the call.

Properties

Name	Type	Required	Restrictions	Description
callId	string(uuid)	false	none	Company's postal address
direction	string	false	none	The direction of the call
from	string	false	none	Phone number of the calling party in the international format E.164
to	string	false	none	Phone number of the callee party in the international format E.164
startTime	string(date-time)	false	none	The timestamp when the call started.
answerTime	string(date-time)	false	none	The timestamp when the call was answered.
endTime	string(date-time)	false	none	The timestamp when the call completed.
duration	string	false	none	The duration in seconds of the call.
country	string	false	none	The alpha 2 code of the destionation country.
rate	string	false	none	The rate charge per minute for this country.
price	string	false	none	The price charged for this call.
currency	string	false	none	The currency used for this charge.
network	string	false	none	The name of the network for the destination call.
status	string	false	none	The status reported for this event.

Enumerated values

Property	Value
direction	outbound
direction	inbound
status	started
status	early
status	hangup
status	ringing
status	completed

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "The given data were not parsable.",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows RFC-7807.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The URI reference [RFC3986] that identifies the problem type
title	string	true	none	Short, human-readable summary of the problem type
status	string	true	none	The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem
detail	string	true	none	Human-readable explanation specific to this problem occurrence