🎙️ ElevenClaw

AI-powered voice assistant combining ElevenLabs Conversational AI with Twilio telephony. Built for hackathons, production-ready for scale.

---

🚀 What It Does

Build two-way voice agents for any scenario:

• 🎂 Birthday bots - Automated birthday wishes with personality
• 💼 Sales assistants - Qualify leads and book demos
• 🎧 Customer support - Handle common issues 24/7
• 📅 Appointment booking - Schedule without human intervention
• 📊 Surveys & feedback - Collect insights via voice

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ElevenLabs ConvAI                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐   │
│  │   ASR   │→│   LLM   │→│   TTS   │→│ Turn-Taking  │   │
│  │ (Speech │  │(Reason) │  │ (Voice) │  │   Model      │   │
│  │ to Text)│  │         │  │         │  │              │   │
│  └─────────┘  └─────────┘  └─────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↕ WebSocket/WebRTC
┌─────────────────────────────────────────────────────────────┐
│                    Twilio Telephony                         │
│         Phone calls, PSTN connectivity, call routing        │
└─────────────────────────────────────────────────────────────┘

---

⚡ Quick Start

Prerequisites

# Environment variables
export ELEVENLABS_API_KEY="sk_..."
export TWILIO_ACCOUNT_SID="AC..."
export TWILIO_AUTH_TOKEN="..."
export TWILIO_PHONE_NUMBER="+1234567890"

Create Your First Agent

# Create a birthday bot agent
curl -X POST "https://api.elevenlabs.io/v1/convai/agents" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Birthday Bot",
    "conversation_config": {
      "agent": {
        "prompt": {
          "prompt": "You are calling to wish someone a happy birthday. Be warm, enthusiastic, and genuine. Ask about their plans. Keep it under 3 minutes.",
          "llm": "gpt-4o",
          "temperature": 0.7
        },
        "first_message": "Happy birthday! I wanted to call and celebrate with you!",
        "language": "en"
      },
      "tts": {
        "model_id": "eleven_turbo_v2_5",
        "voice_id": "IKne3meq5aSn9XLyUdCD"
      }
    }
  }'

Make an Outbound Call

# Get signed URL from ElevenLabs
SIGNED_URL=$(curl -s -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'$ELEVENLABS_AGENT_ID'",
    "agent_phone_number": "'$TWILIO_PHONE_NUMBER'",
    "to_number": "+15551234567"
  }' | jq -r '.signed_url')

# Initiate call via Twilio
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  --data-urlencode "To=+15551234567" \
  --data-urlencode "From=$TWILIO_PHONE_NUMBER" \
  --data-urlencode "Url=$SIGNED_URL"

---

📦 Features

Feature	Description
🔄 Agent Versioning	Git-like version control with branching
🧪 A/B Testing	Traffic splitting between agent versions
📚 Knowledge Base	RAG-powered document access
🛠️ Custom Tools	Webhooks & client-side tool calling
🌍 Multi-language	30+ languages with auto-detection
📊 Post-call Analytics	Webhooks with conversation data

---

📚 Documentation

See SKILL.md for complete API reference including:

• Agent CRUD operations
• Conversation management
• Testing framework
• Knowledge base (RAG)
• Tools configuration
• Dynamic variables
• Voice settings & cloning
• Scenario templates

---

🛠️ Tech Stack

• ElevenLabs ConvAI - Speech recognition, LLM reasoning, text-to-speech
• Twilio - Telephony infrastructure
• OpenAI GPT-4o - Conversation intelligence

---

📝 License

MIT License - Hackathon ready!

---

Built with ❤️ for hackathons using ElevenLabs + Twilio