UneeQ Digital Human Integration

Overview

UneeQ 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

Configure UneeQ

In your UneeQ experience settings, set the custom voice endpoint URL and provide your Hamsa API key.

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.

Hamsa synthesises speech

Hamsa validates the API key, generates the audio using the requested voice, and streams back raw PCM audio.

UneeQ plays the audio

UneeQ receives the binary stream and drives the digital human’s lip sync and speech in real time.

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.

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

Request Body

{
  "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

These audio specs match UneeQ’s custom voice requirements exactly. No conversion is needed on your end.

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 on the dashboard. Some examples:

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

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.

Setting Up in UneeQ

Open your UneeQ experience

Go to the UneeQ Creator and open the experience you want to configure.

Navigate to Voice settings

Go to Settings → Voice → Custom Voice.

Set the endpoint URL

Enter:

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

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.

Set the voice preset

Enter the Hamsa speaker name (e.g. Amjad) in the Preset / Voice field.

Save and test

Save the configuration and use UneeQ’s built-in voice preview to confirm the integration is working.

Example Request

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

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

Getting Started

SDKs

APIs Guides

Agent Guides

UneeQ Digital Human Integration

Overview

How It Works

Endpoint

Authentication

Request Body

Response

Error Responses

Available Voices (Presets)

Setting Up in UneeQ

Example Request

Support

Contact Support

UneeQ Custom Voice Docs

​Overview

​How It Works

​Endpoint

​Authentication

​Request Body

​Response

​Error Responses

​Available Voices (Presets)

​Setting Up in UneeQ

​Example Request

​Support

Contact Support

UneeQ Custom Voice Docs

Overview

How It Works

Endpoint

Authentication

Request Body

Response

Error Responses

Available Voices (Presets)

Setting Up in UneeQ

Example Request

Support