Genesys TTS Connector Integration

Overview

The Genesys TTS Connector lets Genesys Cloud organizations plug a third-party text-to-speech engine into their call and bot flows. Hamsa exposes two endpoints that speak the connector’s protocol:

List Voices — the Voices Catalog API, which Genesys fetches once at activation to build the voice selection list.
Synthesize — a dedicated streaming endpoint that takes text plus a voice id and streams back raw PCM audio.

You only ever send Hamsa a voice id: language and dialect are resolved from the voice itself, so there is no language mapping to configure.

How It Works

Genesys fetches the voice catalog

At activation, the connector calls the Voices Catalog endpoint and caches the list. Each voice’s BCP-47 language tag places it under the matching flow language.

A flow needs speech

Genesys substitutes the utterance and the selected voice id into the configured request template and POSTs it to the Synthesize endpoint.

Hamsa synthesises speech

Hamsa validates the API key, resolves the voice (speaker, language, dialect), and streams raw 8kHz PCM audio back.

Genesys plays the audio

Call flows start playing as soon as the first bytes arrive; bot flows buffer the full payload before playback.

Synthesize Endpoint

POST https://api.tryhamsa.com/v1/realtime/connector/tts-stream

Authentication

Send your Hamsa API key in the Authorization header:

Authorization: Token <your-hamsa-api-key>

Keep your Hamsa API key secret. Anyone who has it can make TTS requests that will be billed against your account.

Request Body

{
  "text": "<text to speak>",
  "voiceId": "<voice id from the catalog>",
  "sampleRate": "8k"
}

Field	Type	Required	Description
`text`	string	Yes	Text to synthesise. Maximum 2000 characters
`voiceId`	string (UUID)	Yes	A voice `id` from the Voices Catalog. Determines speaker, language, and dialect
`sampleRate`	string	No	`8k` (default) or `16k`
`expressiveness`	number	No	0–2, default 1
`speed`	number	No	0.5–2, default 1

Response

On success the endpoint returns a chunked binary stream of raw PCM audio:

Parameter	Value
HTTP Status	`200 OK`
Sample Rate	8 kHz (default) or 16 kHz
Channels	Mono
Encoding	16-bit signed integers
Byte Order	Little-endian
Format	Raw PCM — no WAV headers or compression

This matches the connector’s audio/L16 requirement exactly — Genesys standardizes all provider audio to PCM at 8kHz. μ-law is not supported by the connector.

Error Responses

Status	Meaning
`400`	Validation error — check required fields and that `text` is under 2000 characters
`401`	Invalid or missing API key
`402`	Insufficient wallet balance
`404`	Voice not found or not available for this API key
`429`	Rate limit exceeded
`503`	TTS service temporarily unavailable

Setting Up in Genesys Cloud

Prerequisite: the Genesys TTS Connector installed from AppFoundry (requires a BYOT-A subscription — see Genesys’s install guide).

Open the integration

In Genesys Cloud go to Admin → Integrations, open your Genesys TTS Connector instance, and give it a recognizable name (e.g. Hamsa TTS).

Configure the URIs

On the Configuration tab set:

List Voices URI:      https://api.tryhamsa.com/v2/tts/voices/catalog
Synthesize Text URI:  https://api.tryhamsa.com/v1/realtime/connector/tts-stream
Request Method:       POST

To restrict the catalog to one dialect, bake the filter into the URI, e.g. .../catalog?language=ar-SA.

Leave the voice attributes at their defaults

Hamsa’s catalog matches the connector’s defaults (voices container; id, name, language attributes). Set the gender attribute to gender if you want gender shown in the voice list.

Set the synthesize body template

In the Advanced tab, configure:

{
  "synthesizeBody": {
    "text": "$text",
    "voiceId": "$voice",
    "sampleRate": "8k"
  }
}

$text and $voice are substituted by Genesys on every request. No language mapping is needed — the voice id carries it.

Set the credentials

On the Credentials tab choose the User Defined type and add one field:

Field name	Value
`Authorization`	`Token <your-hamsa-api-key>`

Activate and test

Set the integration to Active, then select the Hamsa engine and a voice in Architect and use TTS playback to verify.

Genesys caches the voice list at activation. If you add voices later (e.g. a new cloned voice), disable and re-enable the integration after at least 30 minutes so Genesys refreshes its cache.

Genesys allows TTS requests up to 3,000 characters, while Hamsa’s limit is 2,000 characters per request. Keep prompts under 2,000 characters to avoid validation errors.

Example Request

This is what Genesys sends to the Synthesize endpoint behind the scenes:

curl -X POST https://api.tryhamsa.com/v1/realtime/connector/tts-stream \
  -H "Authorization: Token your-hamsa-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحباً، كيف يمكنني مساعدتك اليوم؟",
    "voiceId": "6b52beba-b560-45d4-827b-49be73d50db7",
    "sampleRate": "8k"
  }' \
  --output audio.pcm

Getting Started

SDKs

APIs Guides

Agent Guides

Genesys TTS Connector Integration

Overview

How It Works

Synthesize Endpoint

Authentication

Request Body

Response

Error Responses

Setting Up in Genesys Cloud

Example Request

Support

Voices Catalog API

Contact Support

​Overview

​How It Works

​Synthesize Endpoint

​Authentication

​Request Body

​Response

​Error Responses

​Setting Up in Genesys Cloud

​Example Request

​Support

Voices Catalog API

Contact Support

Overview

How It Works

Synthesize Endpoint

Authentication

Request Body

Response

Error Responses

Setting Up in Genesys Cloud

Example Request

Support