> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Genesys TTS Connector Integration

> Use Hamsa TTS voices in Genesys Cloud call and bot flows via the Genesys TTS Connector

## Overview

The [Genesys TTS Connector](https://help.genesys.cloud/articles/activate-and-configure-the-genesys-tts-connector-integration/) 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:

1. **List Voices** — the [Voices Catalog API](/developers/apis/voices-catalog), which Genesys fetches once at activation to build the voice selection list.
2. **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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Hamsa synthesises speech">
    Hamsa validates the API key, resolves the voice (speaker, language, dialect), and streams raw 8kHz PCM audio back.
  </Step>

  <Step title="Genesys plays the audio">
    Call flows start playing as soon as the first bytes arrive; bot flows buffer the full payload before playback.
  </Step>
</Steps>

***

## 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>
```

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

### Request Body

```json theme={null}
{
  "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](/developers/apis/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 |

<Note>
  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.
</Note>

### 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](https://help.genesys.cloud/articles/install-the-genesys-tts-connector-integration/)).

<Steps>
  <Step title="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`).
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set the synthesize body template">
    In the **Advanced** tab, configure:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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>` |
  </Step>

  <Step title="Activate and test">
    Set the integration to **Active**, then select the Hamsa engine and a voice in Architect and use TTS playback to verify.
  </Step>
</Steps>

<Info>
  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.
</Info>

<Warning>
  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.
</Warning>

***

## Example Request

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

```bash theme={null}
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
```

***

## Support

<CardGroup cols={2}>
  <Card title="Voices Catalog API" icon="list" href="/developers/apis/voices-catalog">
    The List Voices endpoint reference
  </Card>

  <Card title="Contact Support" icon="headset" href="mailto:support@tryhamsa.com">
    Get help from our technical team
  </Card>
</CardGroup>