Telnyx Plugins

Name: Telnyx Plugins
Rating: 3.5 (1 reviews)
Author: darland6

By darland6 👁 67 views ▲ 0 votes

Free OpenClaw plugins for Telnyx voice (Groq TTS/STT) and SMS

GitHub

Install

openclaw plugins install ./openclaw-telnyx-plugins/groq-telnyx-voice

Configuration Example

{
  "plugins": {
    "entries": {
      "groq-telnyx-voice": {
        "enabled": true,
        "config": {
          "groqApiKey": "your-groq-api-key",
          "telnyxApiKey": "your-telnyx-api-key",
          "ttsVoice": "tara",
          "ttsModel": "canopylabs/orpheus-v1-english",
          "sttModel": "whisper-large-v3-turbo",
          "vadSilenceMs": 1200,
          "vadMinSpeechMs": 300,
          "fallbackToNative": true,
          "streamPort": 3335,
          "streamPath": "/voice/stream"
        }
      }
    }
  }
}

README

# OpenClaw Telnyx Plugins

Free, open-source plugins that add **Telnyx voice and SMS** capabilities to [OpenClaw](https://github.com/openclaw).

## Plugins

### groq-telnyx-voice

Replaces Telnyx native TTS/STT with **Groq Orpheus TTS** and **Groq Whisper STT** on voice calls. Uses Telnyx media streaming (WebSocket) for bidirectional audio.

**Features:**
- Groq Orpheus TTS with 8 expressive voices (tara, leah, jess, leo, dan, mia, zac, zoe)
- Supports vocal directions: `[cheerful]`, `[sad]`, `[whisper]`, `[laugh]`
- Groq Whisper STT ($0.04/hr) with energy-based Voice Activity Detection
- Barge-in support (interrupts TTS when caller speaks)
- Auto-detects Tailscale hostname for public WebSocket URL
- Falls back gracefully when Groq is unreachable

**Audio Pipeline:**
```
TTS: Text → Groq Orpheus (WAV 24kHz) → Resample 8kHz → PCM→mu-law → Chunk 160B/20ms → WebSocket → Phone
STT: Phone → mu-law 8kHz → VAD → mu-law→WAV → Groq Whisper → Transcript
```

### telnyx-sms

Send and receive **SMS/MMS** messages via Telnyx Messaging API v2.

**Features:**
- Send SMS and MMS (with media URLs)
- Inbound SMS webhook server for receiving messages
- Message delivery status tracking
- Automatic US phone number formatting (+1 prefix)
- Inbox queue with peek/drain pattern

## Requirements

- [OpenClaw](https://github.com/openclaw) instance
- [Telnyx](https://telnyx.com) account with a phone number and Call Control connection
- [Groq](https://groq.com) API key (for groq-telnyx-voice only)
- [Tailscale](https://tailscale.com) with Funnel enabled (for groq-telnyx-voice, so Telnyx can reach your WebSocket)

## Installation

### From source (recommended)

```bash
# Clone this repo
git clone https://github.com/darland6/openclaw-telnyx-plugins.git

# Install the voice plugin
openclaw plugins install ./openclaw-telnyx-plugins/groq-telnyx-voice --link

# Install the SMS plugin
openclaw plugins install ./openclaw-telnyx-plugins/telnyx-sms --link
```

### From npm (when published)

```bash
openclaw plugins install @openclaw-community/groq-telnyx-voice
openclaw plugins install @openclaw-community/telnyx-sms
```

## Configuration

Add to your `~/.openclaw/openclaw.json`:

### groq-telnyx-voice

```json
{
  "plugins": {
    "entries": {
      "groq-telnyx-voice": {
        "enabled": true,
        "config": {
          "groqApiKey": "your-groq-api-key",
          "telnyxApiKey": "your-telnyx-api-key",
          "ttsVoice": "tara",
          "ttsModel": "canopylabs/orpheus-v1-english",
          "sttModel": "whisper-large-v3-turbo",
          "vadSilenceMs": 1200,
          "vadMinSpeechMs": 300,
          "fallbackToNative": true,
          "streamPort": 3335,
          "streamPath": "/voice/stream"
        }
      }
    }
  }
}
```

You can also use environment variables instead of config keys:
- `GROQ_API_KEY` — Groq API key
- `TELNYX_API_KEY` — Telnyx API key

### telnyx-sms

```json
{
  "plugins": {
    "entries": {
      "telnyx-sms": {
        "enabled": true,
        "config": {
          "telnyxApiKey": "your-telnyx-api-key",
          "fromNumber": "+15551234567",
          "webhookPort": 3336,
          "webhookPath": "/sms/webhook",
          "enableWebhook": true
        }
      }
    }
  }
}
```

## Usage

### Voice (groq-telnyx-voice)

```
# First, start a voice call using the stock voice_call tool
voice_call({ action: "call", to: "+15551234567" })

# Then activate Groq audio on the call
groq_voice_call({ action: "activate", providerCallId: "<call_control_id>" })

# Speak to the caller
groq_voice_call({ action: "speak", text: "Hello! [cheerful] How can I help you today?" })

# Listen for a response
groq_voice_call({ action: "listen", timeoutMs: 15000 })

# Or speak and listen in one step
groq_voice_call({ action: "converse", text: "What's your name?" })

# When done
groq_voice_call({ action: "deactivate" })
```

### SMS (telnyx-sms)

```
# Send an SMS
telnyx_sms({ action: "send", to: "+15551234567", text: "Hello from OpenClaw!" })

# Send an MMS with media
telnyx_sms({ action: "send", to: "+15551234567", text: "Check this out", mediaUrls: ["https://example.com/image.jpg"] })

# Check delivery status
telnyx_sms({ action: "status", messageId: "<message_id>" })

# Read received messages
telnyx_sms({ action: "inbox" })

# Preview inbox without clearing
telnyx_sms({ action: "peek" })
```

## Tailscale Funnel Setup (for voice)

The groq-telnyx-voice plugin requires a public WebSocket URL so Telnyx can stream audio to your machine. [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) is the easiest way to expose it:

```bash
# Install Tailscale
# https://tailscale.com/download

# Enable Funnel for the voice stream port
tailscale funnel 3335

# The plugin auto-detects your Tailscale hostname
# Or set publicStreamUrl manually in config
```

## Architecture

```
┌─────────────────────────────────────────────┐
│  OpenClaw Gateway                            │
│  ├── voice-call plugin (stock)               │
│  │   └── Telnyx Call Control v2              │
│  ├── groq-telnyx-voice plugin (this repo)    │
│  │   ├── Groq Orpheus TTS                    │
│  │   ├── Groq Whisper STT                    │
│  │   ├── Energy-based VAD                    │
│  │   └── Telnyx WebSocket media stream       │
│  └── telnyx-sms plugin (this repo)           │
│      └── Telnyx Messaging API v2             │
└─────────────────────────────────────────────┘
         │                    │
    Tailscale Funnel     Direct HTTPS
         │                    │
    ┌────▼────┐         ┌────▼────┐
    │ Telnyx  │         │  Groq   │
    │ (PSTN)  │         │  Cloud  │
    └─────────┘         └─────────┘
```

## Port Map (defaults)

| Port | Service |
|------|---------|
| 3334 | Voice webhook (stock voice-call plugin) |
| 3335 | Groq voice WebSocket media stream |
| 3336 | SMS inbound webhook |

## License

MIT

voice