Custom Voice (TTS)

Overview

Sulus supports custom TTS integration through a webhook-based pattern, allowing you to use any text-to-speech system with your assistant. Here's a comprehensive overview of the configuration options and voice settings.

To use a custom TTS provider, set provider to "custom-voice" in your assistant's voice configuration and point it to your TTS endpoint:

{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://your-tts-endpoint.com/api/synthesize",
      "secret": "your-webhook-secret",
      "timeoutSeconds": 45,
      "headers": {
        "Content-Type": "application/json",
        "X-API-Version": "v1"
      }
    }
  }
}

Custom Credentials (Recommended) — Reference a credential by ID for better security:

{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://your-tts-api.com/synthesize",
      "credentialId": "cred_tts_auth_123",
      "timeoutSeconds": 30
    }
  }
}

Legacy inline authentication — Pass headers and a secret directly in the config:

{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://your-tts-api.com/synthesize",
      "secret": "your-secret-token",
      "headers": {
        "X-API-Version": "v1",
        "X-Client-ID": "sulus-integration"
      }
    }
  }
}

Every time your assistant needs to speak, Sulus sends a POST request to your endpoint with this structure:

{
  "message": {
    "type": "voice-request",
    "text": "Hello, world! How can I help you today?",
    "sampleRate": 24000,
    "timestamp": 1677123456789,
    "call": { "id": "call-123", "orgId": "org-456" },
    "assistant": { "id": "assistant-789", "name": "Customer Service Bot" },
    "customer": { "number": "+1234567890" }
  }
}

Required request fields:

Your endpoint must return raw PCM audio with these exact specifications:

• Format: Raw PCM (no headers or containers)
• Channels: Mono only (1 channel)
• Bit Depth: 16-bit signed integer
• Byte Order: Little-endian
• Sample Rate: Must exactly match the sampleRate in the request
• HTTP Status: 200
• Content-Type: application/octet-stream

It's strongly recommended to configure a fallback voice in case your custom TTS endpoint experiences issues:

{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://your-tts-endpoint.com/api/synthesize",
      "secret": "your-webhook-secret"
    },
    "fallbackPlan": {
      "voices": [
        {
          "provider": "eleven-labs",
          "voiceId": "21m00Tcm4TlvDq8ikWAM"
        }
      ]
    }
  }
}

Without a fallback plan, your call will end with an error if the voice provider fails.

When a voice failure or synthesis request occurs, Sulus follows this sequence:

1. During a conversation, Sulus needs to convert text to speech
2. Sulus sends a POST request to your configured TTS endpoint
3. Your system generates audio and returns raw PCM data
4. Sulus streams the audio to the caller in real-time

In summary, custom TTS in Sulus is configured via the custom-voice provider with a server object pointing to your endpoint. Your server must accept Sulus's voice-request payload and return raw 16-bit mono PCM audio. Adding a fallbackPlan ensures call continuity if your endpoint is unavailable.