Integration Guides - Call2Me Voice AI Platform

Quickstart

Create your first voice agent and make a test call in 5 minutes

1Install the SDK

Install the Call2Me Python SDK using pip:

pip install call2me

2Set Your API Key

Get your API key from the Dashboard and set it as an environment variable:

export CALL2ME_API_KEY="your-api-key-here"

3Create Your First Agent

Create a voice agent with a system prompt that defines its personality:

from call2me import Call2Me

client = Call2Me()

# Create a customer support agent
agent = client.agents.create(
    agent_name="Support Assistant",
    voice_id="openai-nova",
    language="tr",
    response_engine={
        "type": "call2me-llm",
        "system_prompt": """Sen yardimci bir musteri destek asistanisin.
Kibar ve profesyonel ol. Sorulari acik ve anlasilir sekilde cevapla.""",
        "model": "gpt-4o"
    }
)

print(f"Agent created: {agent.agent_id}")

4Make a Test Call

Initiate an outbound call with your new agent:

# Make a call
call = client.calls.create(
    agent_id=agent.agent_id,
    to_number="+905551234567",
    from_number="+908501234567"  # Your Call2Me number
)

print(f"Call started: {call.call_id}")
print(f"Status: {call.status}")

Tip

Test your agent locally first using WebSocket before making real phone calls. See the WebSocket documentation for details.

Authentication

Learn how to authenticate API requests and manage your API keys

API Key Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Using with cURL

curl -X GET https://api.call2me.app/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Using with Python SDK

The SDK automatically reads from the CALL2ME_API_KEY environment variable:

from call2me import Call2Me

# Option 1: Environment variable (recommended)
client = Call2Me()  # Reads CALL2ME_API_KEY

# Option 2: Pass directly
client = Call2Me(api_key="your-api-key")

Managing API Keys

Create and manage keys in the Dashboard
Each key has specific permissions (read, write, admin)
Rotate keys regularly for security
Never commit API keys to version control

Security Warning

Keep your API keys secure. Never expose them in client-side code or public repositories.

Creating Agents

Configure voice, personality, and behavior for your AI agents

Agent Configuration

An agent consists of several key components:

Voice - The TTS voice used to speak
Language - Primary language for the agent
Response Engine - LLM configuration and system prompt
Knowledge Base - Optional RAG documents for context

Basic Agent Creation

agent = client.agents.create(
    agent_name="Sales Assistant",
    voice_id="elevenlabs-rachel",
    language="en",
    response_engine={
        "type": "call2me-llm",
        "system_prompt": "You are a helpful sales assistant...",
        "model": "gpt-4o",
        "temperature": 0.7
    }
)

Agent with Knowledge Base

Link a knowledge base for context-aware responses:

agent = client.agents.create(
    agent_name="Product Expert",
    voice_id="openai-alloy",
    language="tr",
    response_engine={
        "type": "call2me-llm",
        "system_prompt": "Sen bir urun uzmanisin..."
    },
    knowledge_base_ids=["kb_abc123", "kb_def456"]
)

Custom LLM Agent

Connect your own LLM server via WebSocket:

agent = client.agents.create(
    agent_name="Custom Bot",
    voice_id="openai-nova",
    response_engine={
        "type": "custom-llm",
        "websocket_url": "wss://your-server.com/llm"
    }
)

Update Agent

# Update system prompt
updated = client.agents.update(
    agent_id="agent_123",
    response_engine={
        "system_prompt": "Updated prompt..."
    }
)

Voice Selection

Choose from multiple TTS providers and voices for your agents

Available Providers

OpenAI TTS

alloy, echo, fable, onyx, nova, shimmer

ElevenLabs

High-quality, natural voices with cloning

Cartesia

Ultra-low latency, real-time streaming

MiniMax

Multilingual support, expressive voices

List Available Voices

# List all voices
voices = client.voices.list()

for voice in voices:
    print(f"{voice.voice_id}: {voice.name} ({voice.provider})")

Voice ID Format

Voice IDs follow the format: provider-voicename

# OpenAI voices
"openai-nova"
"openai-alloy"
"openai-shimmer"

# ElevenLabs voices
"elevenlabs-rachel"
"elevenlabs-adam"

# Cartesia voices
"cartesia-british-lady"

# MiniMax voices
"minimax-male-qn-jingying"

Get Voice Details

voice = client.voices.get("openai-nova")

print(f"Name: {voice.name}")
print(f"Provider: {voice.provider}")
print(f"Languages: {voice.supported_languages}")

Tip

For Turkish conversations, openai-nova and minimax voices work well. For English, try elevenlabs-rachel for the most natural sound.

System Prompts

Write effective prompts that define your agent's personality and behavior

Prompt Structure

A good system prompt includes:

Role Definition - Who is the agent?
Personality Traits - How should it communicate?
Task Instructions - What should it do?
Constraints - What should it avoid?
Response Format - How should responses be structured?

Example: Customer Support Agent

system_prompt = """Sen Acme Teknoloji'nin musteri destek asistanisin.

KISILIK:
- Kibar, profesyonel ve yardimci ol
- Sabirl ol, musterinin sorusunu tam anlayana kadar sor
- Kisa ve oz cevaplar ver, telefon gorusmesi icin uygun

GOREVLER:
- Teknik destek sorularina yardim et
- Siparis durumu sorgularina cevap ver
- Gerekirse insana bagla

KISITLAMALAR:
- Iade veya fiyat pazarligi yapma, bu konularda insana bagla
- Kisisel bilgi isteme (sifre, kredi karti)
- Rakip firmalar hakkinda yorum yapma

ORNEK CEVAPLAR:
- "Tabii ki size yardimci olayim. Hangi urunumuzle ilgili sorun yasiyorsunuz?"
- "Siparis numaranizi alabilir miyim lutfen?"
"""

Example: Sales Agent

system_prompt = """Sen Acme'nin satis temsilcisisin.

AMAC: Potansiyel musterilere urunlerimizi tanit ve demo planla.

YAKLASIM:
- Ilk olarak musterinin ihtiyaclarini anla
- Urunun bu ihtiyaclara nasil cozum sunacagini acikla
- Demo icin randevu ayarla

URUNLER:
- Basic Plan: Aylik 99 TL, 1000 dakika
- Pro Plan: Aylik 299 TL, sinirsiz dakika
- Enterprise: Ozel fiyatlandirma

SATIS TEKNIKLERI:
- Acik uclu sorular sor
- Musterinin isini anla
- Deger onerisi sun
"""

Tips for Voice Agents

Keep responses concise - phone conversations need brevity
Avoid markdown or formatting - it's voice only
Include example phrases for consistency
Define escalation paths clearly
Test with various scenarios before production

RAG Setup

Add documents and URLs for context-aware agent responses

Create a Knowledge Base

# Create a new knowledge base
kb = client.knowledge_bases.create(
    name="Product Documentation",
    description="All product manuals and FAQs"
)

print(f"Knowledge Base ID: {kb.id}")

Add Text Documents

# Add a document with text content
doc = client.knowledge_bases.add_document(
    knowledge_base_id=kb.id,
    content="""
    Urun Iade Politikasi

    30 gun icerisinde fatura ile birlikte iade yapilabilir.
    Urun acilmamis ve hasarsiz olmalidir.
    Iade sureci 5-7 is gununde tamamlanir.
    """,
    metadata={
        "title": "Iade Politikasi",
        "category": "policies"
    }
)

Add URL Content

# Scrape and add content from URL
doc = client.knowledge_bases.add_url(
    knowledge_base_id=kb.id,
    url="https://docs.example.com/faq"
)

Link to Agent

# Create agent with knowledge base
agent = client.agents.create(
    agent_name="Support Bot",
    voice_id="openai-nova",
    knowledge_base_ids=[kb.id],
    response_engine={
        "type": "call2me-llm",
        "system_prompt": "Sen bir destek asistanisin. Knowledge base'deki bilgileri kullan."
    }
)

Tip

Documents are automatically chunked and embedded. Keep individual documents focused on a single topic for best retrieval results.

Semantic Search

Query your knowledge base with natural language

Basic Search

# Search the knowledge base
results = client.knowledge_bases.search(
    knowledge_base_id="kb_abc123",
    query="iade sureci nasil?",
    limit=5
)

for result in results:
    print(f"Score: {result.score}")
    print(f"Content: {result.content[:200]}...")
    print("---")

Search with Filters

# Filter by metadata
results = client.knowledge_bases.search(
    knowledge_base_id="kb_abc123",
    query="fiyat bilgisi",
    filter={"category": "pricing"},
    limit=3
)

Direct API Call

curl -X POST https://api.call2me.app/v1/knowledge-base/kb_abc123/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "iade politikasi",
    "limit": 5
  }'

Response Format

{
  "results": [
    {
      "id": "doc_xyz789",
      "content": "30 gun icerisinde iade yapilabilir...",
      "score": 0.92,
      "metadata": {
        "title": "Iade Politikasi"
      }
    }
  ]
}

Making Calls

Initiate outbound calls programmatically with your AI agents

Create a Call

call = client.calls.create(
    agent_id="agent_abc123",
    to_number="+905551234567",
    from_number="+908501234567",
    metadata={
        "customer_id": "cust_xyz",
        "campaign": "welcome_call"
    }
)

print(f"Call ID: {call.call_id}")
print(f"Status: {call.status}")

Check Call Status

# Get call details
call = client.calls.get("call_123")

print(f"Status: {call.status}")  # queued, ringing, in_progress, completed, failed
print(f"Duration: {call.duration}s")
print(f"Started: {call.start_time}")

End a Call

# End an active call
client.calls.end("call_123")

List Recent Calls

# List calls with pagination
calls = client.calls.list(
    limit=20,
    status="completed"
)

for call in calls:
    print(f"{call.call_id}: {call.to_number} - {call.duration}s")

Call Statuses

queued - Call is waiting to be placed
ringing - Call is ringing on recipient's phone
in_progress - Call is active
completed - Call ended normally
failed - Call failed (busy, no answer, etc.)

Webhooks

Receive real-time notifications for call events

Available Events

call_started - Call has been answered
call_ended - Call has ended
call_analyzed - Call analysis is ready (transcript, summary)

Configure Webhook URL

Set your webhook URL in the Dashboard or via API:

client.webhooks.create(
    url="https://your-server.com/webhooks/call2me",
    events=["call_started", "call_ended", "call_analyzed"]
)

Webhook Payload

{
  "event": "call_ended",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "agent_id": "agent_xyz",
    "to_number": "+905551234567",
    "from_number": "+908501234567",
    "duration": 125,
    "status": "completed",
    "metadata": {
      "customer_id": "cust_xyz"
    }
  }
}

Verify Webhook Signature

All webhooks include a signature header for verification:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler
@app.post("/webhooks/call2me")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("x-call2me-signature")

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(401, "Invalid signature")

    data = json.loads(payload)
    # Process the webhook...

Tip

Webhook endpoints should respond with 2xx status within 5 seconds. For longer processing, acknowledge immediately and process asynchronously.