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

# UneeQ Digital Human Integration

> Use Hamsa TTS voices to power UneeQ digital human avatars via the custom voice endpoint

## Overview

[UneeQ](https://www.uneeq.io) is a digital human platform that can use a custom voice service for text-to-speech synthesis. This guide explains how to connect UneeQ to Hamsa's real-time TTS engine so your digital human speaks with a Hamsa voice.

Hamsa exposes a dedicated endpoint that speaks the UneeQ custom voice protocol — UneeQ calls it directly, passing your Hamsa API key and the desired voice preset, and receives a raw PCM audio stream in response.

***

## How It Works

<Steps>
  <Step title="Configure UneeQ">
    In your UneeQ experience settings, set the custom voice endpoint URL and provide your Hamsa API key.
  </Step>

  <Step title="UneeQ sends a TTS request">
    When the digital human needs to speak, UneeQ sends a POST request to your endpoint with the text and the voice preset name.
  </Step>

  <Step title="Hamsa synthesises speech">
    Hamsa validates the API key, generates the audio using the requested voice, and streams back raw PCM audio.
  </Step>

  <Step title="UneeQ plays the audio">
    UneeQ receives the binary stream and drives the digital human's lip sync and speech in real time.
  </Step>
</Steps>

***

## Endpoint

```
POST https://api.tryhamsa.com/v1/realtime/uneeq/tts
```

### Authentication

Unlike other Hamsa endpoints, this one does **not** use an `Authorization` header. UneeQ sends the API key inside the JSON request body, so no extra headers are required on your side.

<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}
{
  "apiKey": "<your-hamsa-api-key>",
  "preset": "<hamsa-speaker-name>",
  "text": "<text to speak>"
}
```

| Field    | Type   | Required | Description                                                    |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| `apiKey` | string | Yes      | Your Hamsa API key                                             |
| `preset` | string | Yes      | Hamsa speaker name to use as the voice (e.g. `Amjad`, `Salma`) |
| `text`   | string | Yes      | Text to synthesise. Maximum 2000 characters                    |

### Response

On success the endpoint returns a **chunked binary stream** of raw PCM audio with the following properties:

| Parameter    | Value                                   |
| ------------ | --------------------------------------- |
| HTTP Status  | `200 OK`                                |
| Content-Type | `application/octet-stream`              |
| Sample Rate  | 16 kHz                                  |
| Channels     | Mono                                    |
| Encoding     | 16-bit signed integers                  |
| Byte Order   | Little-endian                           |
| Format       | Raw PCM — no WAV headers or compression |

<Note>
  These audio specs match UneeQ's custom voice requirements exactly. No conversion is needed on your end.
</Note>

### Error Responses

| Status | Meaning                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | Validation error — check that all required fields are present and `text` is under 2000 characters |
| `401`  | Invalid or missing API key                                                                        |
| `402`  | Insufficient wallet balance                                                                       |
| `429`  | Rate limit exceeded (100 requests/minute per API key)                                             |
| `503`  | TTS service temporarily unavailable                                                               |

***

## Available Voices (Presets)

Pass any Hamsa speaker name as the `preset` value. You can find the full list of available voices in the [Voice Library](https://media.tryhamsa.com/app/voices) on the dashboard. Some examples:

| Preset  | Description                  |
| ------- | ---------------------------- |
| `Amjad` | Male, Modern Standard Arabic |
| `Salma` | Female, Egyptian dialect     |
| `Lyali` | Female, Levantine dialect    |
| `Jasem` | Male, Gulf dialect           |

<Info>
  The `preset` value maps directly to Hamsa's speaker names. The language is Arabic (`ar`) by default. If you need a different dialect, contact support to discuss configuration options.
</Info>

***

## Setting Up in UneeQ

<Steps>
  <Step title="Open your UneeQ experience">
    Go to the UneeQ Creator and open the experience you want to configure.
  </Step>

  <Step title="Navigate to Voice settings">
    Go to **Settings → Voice → Custom Voice**.
  </Step>

  <Step title="Set the endpoint URL">
    Enter:

    ```
    https://api.tryhamsa.com/v1/realtime/uneeq/tts
    ```
  </Step>

  <Step title="Set the API key">
    Paste your Hamsa API key into the **API Key** field. UneeQ will include it as `apiKey` in every request body automatically.
  </Step>

  <Step title="Set the voice preset">
    Enter the Hamsa speaker name (e.g. `Amjad`) in the **Preset / Voice** field.
  </Step>

  <Step title="Save and test">
    Save the configuration and use UneeQ's built-in voice preview to confirm the integration is working.
  </Step>
</Steps>

***

## Example Request

This is what UneeQ sends to the endpoint behind the scenes:

```bash theme={null}
curl -X POST https://api.tryhamsa.com/v1/realtime/uneeq/tts \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-hamsa-api-key",
    "preset": "Amjad",
    "text": "مرحباً، كيف يمكنني مساعدتك اليوم؟"
  }' \
  --output audio.pcm
```

***

## Support

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

  <Card title="UneeQ Custom Voice Docs" icon="book" href="https://docs.uneeq.io/#/integrations/custom-voice">
    UneeQ's official custom voice integration guide
  </Card>
</CardGroup>