Elevenlabs Agents

ElevenLabs Agent Builder

Build a production-ready conversational AI voice agent. Produces a configured agent with tools, knowledge base, and SDK integration.

Packages

npm install @elevenlabs/react           # React SDK
npm install @elevenlabs/client          # JavaScript SDK (browser + server)
npm install @elevenlabs/react-native    # React Native SDK
npm install @elevenlabs/elevenlabs-js   # Full API (server only)
npm install -g @elevenlabs/agents-cli   # CLI ("Agents as Code")

DEPRECATED: @11labs/react, @11labs/client -- uninstall if present.

Server-only warning: @elevenlabs/elevenlabs-js uses Node.js child_process and won't work in browsers. Use @elevenlabs/client for browser environments, or create a proxy server.

Workflow

Step 1: Create Agent via Dashboard or CLI

Dashboard: https://elevenlabs.io/app/conversational-ai -> Create Agent

CLI (Agents as Code):

elevenlabs agents init
elevenlabs agents add "Support Bot" --template customer-service
# Edit agent_configs/support-bot.json
elevenlabs agents push --env dev

Templates: default, minimal, voice-only, text-only, customer-service, assistant.

Configure:

• Voice -- Choose from 5000+ voices or clone
• LLM -- GPT, Claude, Gemini, or custom
• System prompt -- Use the 6-component framework below
• First message -- What the agent says when conversation starts

Step 2: Write the System Prompt

Use the 6-component framework for effective agent prompts:

1. Personality -- who the agent is:

You are [NAME], a [ROLE] at [COMPANY].
You have [EXPERIENCE]. Your traits: [LIST TRAITS].

2. Environment -- communication context:

You're communicating via [phone/chat/video].
Consider [environmental factors]. Adapt to [context].

3. Tone -- speech patterns and formality:

Tone: Professional yet warm. Use contractions for natural speech.
Avoid jargon. Keep responses to 2-3 sentences. Ask one question at a time.

4. Goal -- objectives and success criteria:

Primary Goal: Resolve customer issues on the first call.
Success: Customer verbally confirms issue is resolved.

5. Guardrails -- boundaries and ethics:

Never: provide medical/legal/financial advice, share confidential info.
Always: verify identity before account access, document interactions.
Escalation: customer requests manager, issue beyond knowledge base.

6. Tools -- available functions and when to use them:

1. lookup_order(order_id) -- Use when customer mentions an order.
2. transfer_to_supervisor() -- Use when issue requires manager approval.
Always explain what you're doing before calling a tool.

Step 3: Add Tools

Client-side tools (run in browser):

const clientTools = {
  updateCart: {
    description: "Add or remove items from the shopping cart",
    parameters: z.object({
      action: z.enum(['add', 'remove']),
      item: z.string(),
      quantity: z.number().min(1)
    }),
    handler: async ({ action, item, quantity }) => {
      const cart = getCart();
      action === 'add' ? cart.add(item, quantity) : cart.remove(item, quantity);
      return { success: true, total: cart.total, items: cart.items.length };
    }
  },
  navigate: {
    description: "Navigate user to a different page",
    parameters: z.object({ url: z.string().url() }),
    handler: async ({ url }) => { window.location.href = url; return { success: true }; }
  }
};

Server-side tools (webhooks):

{
  "name": "get_weather",
  "description": "Fetch current weather for a city",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name" }
    },
    "required": ["city"]
  },
  "headers": {
    "Authorization": "Bearer {{secret__weather_api_key}}"
  }
}

Use {{secret__key_name}} for API keys in webhook headers -- never hardcode.

MCP Tools -- CRITICAL COMPATIBILITY NOTE:

ElevenLabs labels their MCP integration as "Streamable HTTP" but does NOT support the actual MCP 2025-03-26 Streamable HTTP spec (SSE responses). ElevenLabs expects:

• Plain JSON responses (application/json), NOT SSE (text/event-stream)
• Protocol version 2024-11-05, NOT 2025-03-26
• Simple JSON-RPC over HTTP with direct JSON responses

What does NOT work:

• Official MCP SDK's createMcpHandler (returns SSE)
• Cloudflare Agents SDK McpServer.serve() (returns SSE)
• Any server returning Content-Type: text/event-stream

Working MCP server pattern for ElevenLabs:

import { Hono } from 'hono';
import { cors } from 'hono/cors';

const tools = [{
  name: "my_tool",
  description: "Tool description",
  inputSchema: {
    type: "object",
    properties: { param1: { type: "string", description: "Description" } },
    required: ["param1"]
  }
}];

async function handleMCPRequest(request, env) {
  const { id, method, params } = request;
  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0', id,
        result: {
          protocolVersion: '2024-11-05',  // MUST be 2024-11-05
          serverInfo: { name: 'my-mcp', version: '1.0.0' },
          capabilities: { tools: {} }
        }
      };
    case 'tools/list':
      return { jsonrpc: '2.0', id, result: { tools } };
    case 'tools/call':
      const result = await handleTool(params.name, params.arguments, env);
      return { jsonrpc: '2.0', id, result };
    default:
      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Unknown: ${method}` } };
  }
}

const app = new Hono();
app.use('/*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
app.post('/mcp', async (c) => {
  const body = await c.req.json();
  return c.json(await handleMCPRequest(body, c.env));  // Plain JSON, NOT SSE
});
export default app;

Step 4: Add Knowledge Base (RAG)

Upload documents for the agent to reference:

• PDFs, text files, web URLs
• Configure via dashboard: Agent -> Knowledge Base -> Upload
• Or via API: POST /v1/convai/knowledge-base/upload (multipart/form-data)
• Agent automatically searches knowledge base during conversation

Step 5: Integrate SDK

React -- copy and customise assets/react-sdk-boilerplate.tsx:

import { useConversation } from '@elevenlabs/react';

const { startConversation, stopConversation, status } = useConversation({
  agentId: 'your-agent-id',
  signedUrl: '/api/elevenlabs/auth',
  clientTools,
  dynamicVariables: {
    user_name: 'John',
    account_type: 'premium',
  },
  onEvent: (event) => { /* transcript, agent_response, tool_call */ },
});

System prompt references dynamic variables as {{user_name}}.

React Native -- see assets/react-native-boilerplate.tsx Widget embed -- see assets/widget-embed-template.html Swift -- see assets/swift-sdk-boilerplate.swift

Step 6: Test

CLI testing:

# Run all tests for an agent
elevenlabs agents test "Support Agent"

# Add a test scenario
elevenlabs tests add "Refund Request" --template basic-llm

Test configuration:

{
  "name": "Refund Request Test",
  "scenario": "Customer requests refund for defective product",
  "user_input": "I want a refund for order #12345. The product arrived broken.",
  "success_criteria": [
    "Agent acknowledges the issue empathetically",
    "Agent asks for or uses provided order number",
    "Agent verifies order details",
    "Agent provides clear next steps or refund timeline"
  ],
  "evaluation_type": "llm"
}

Tool call testing:

{
  "name": "Order Lookup Test",
  "scenario": "Customer asks about order status",
  "user_input": "What's the status of order ORD-12345?",
  "expected_tool_call": {
    "tool_name": "lookup_order",
    "parameters": { "order_id": "ORD-12345" }
  }
}

API simulation:

const simulation = await client.agents.simulate({
  agent_id: 'agent_123',
  scenario: 'Customer requests refund',
  user_messages: [
    "I want a refund for order #12345",
    "It arrived broken",
    "Yes, process the refund"
  ],
  success_criteria: [
    "Agent shows empathy",
    "Agent verifies order",
    "Agent provides timeline"
  ]
});
console.log('Passed:', simulation.passed);

CI/CD integration:

name: Test Agent
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @elevenlabs/cli
      - run: elevenlabs tests push
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }}
      - run: elevenlabs agents test "Support Agent"
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }}

Step 7: Deploy

# Dry run first (always)
elevenlabs agents push --env prod --dry-run

# Deploy to production
elevenlabs agents push --env prod

Multi-environment workflow:

elevenlabs agents push --env dev       # Development
elevenlabs agents push --env staging   # Staging
elevenlabs agents test "Agent Name"    # Test in staging
elevenlabs agents push --env prod      # Production

---

Critical Patterns

Signed URLs (Security)

Never expose API keys in client code. Use a server endpoint:

app.get('/api/elevenlabs/auth', async (req, res) => {
  const response = await fetch(
    'https://api.elevenlabs.io/v1/convai/conversation/get-signed-url',
    {
      headers: { 'xi-api-key': process.env.ELEVENLABS_API_KEY },
      body: JSON.stringify({ agent_id: 'your-agent-id' }),
      method: 'POST'
    }
  );
  const { signed_url } = await response.json();
  res.json({ signed_url });
});

Agent Versioning (A/B Testing)

Dashboard: Agent -> Versions -> Create Branch. Compare metrics, promote winner.

Post-Call Webhook

{
  "type": "post_call_transcription",
  "data": {
    "conversation_id": "conv_xyz789",
    "transcript": "...",
    "duration_seconds": 120,
    "analysis": { "sentiment": "positive", "resolution": true }
  }
}

Verify with HMAC SHA-256:

const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(JSON.stringify(request.body)).digest('hex');
if (signature !== hmac) { /* reject */ }

---

Cost Optimisation

Model lineups and pricing rot fast — check the live list in the ElevenLabs dashboard (Agent → LLM dropdown) or docs before picking, and don't hardcode a model id you haven't verified this session. The durable picks: a current cheap-fast model for most agents (upgrade only where quality demands it), a long-context model when the knowledge base is large.

Key savings:

• LLM caching: up to 90% on repeated prompts (enable in config)
• Prompt length: 150 tokens > 500 tokens for same instructions
• RAG over context: use knowledge base instead of stuffing system prompt
• Duration limits: set max_duration_seconds to prevent runaway conversations
• Turn mode: "patient" mode = fewer LLM calls = lower cost

---

CLI Quick Reference

elevenlabs auth login                              # Authenticate
elevenlabs agents init                             # Init project
elevenlabs agents add "Name" --template default    # Add agent
elevenlabs agents push --env dev                   # Deploy to dev
elevenlabs agents push --env prod --dry-run        # Preview prod deploy
elevenlabs agents push --env prod                  # Deploy to prod
elevenlabs agents pull                             # Pull from platform
elevenlabs agents test "Name"                      # Run tests
elevenlabs agents list                             # List agents
elevenlabs agents status                           # Check sync status
elevenlabs agents widget "Name"                    # Generate widget
elevenlabs tools add-webhook "Name" --config-path tool.json  # Add tool
elevenlabs tests add "Name" --template basic-llm   # Add test

Environment: ELEVENLABS_API_KEY for CI/CD.

---

Optional References

For specialised use cases, see:

• references/api-reference.md -- full REST API for programmatic agent management
• references/compliance-guide.md -- GDPR, HIPAA, PCI DSS, data residency
• references/workflow-examples.md -- multi-agent routing, escalation, multi-language

---

Asset Files

• assets/react-sdk-boilerplate.tsx -- React integration template
• assets/react-native-boilerplate.tsx -- React Native template
• assets/swift-sdk-boilerplate.swift -- Swift/iOS template
• assets/javascript-sdk-boilerplate.js -- Vanilla JS template
• assets/widget-embed-template.html -- Embeddable widget
• assets/system-prompt-template.md -- System prompt guide
• assets/agent-config-schema.json -- Config schema reference
• assets/ci-cd-example.yml -- CI/CD pipeline template

System Prompt Template

Use this template to create structured, effective agent prompts.

---

Personality

You are [NAME], a [ROLE/PROFESSION] at [COMPANY].
You have [YEARS] years of experience [DOING WHAT].
Your key traits: [LIST 3-5 PERSONALITY TRAITS].

Example:

You are Sarah, a patient and knowledgeable technical support specialist at TechCorp.
You have 7 years of experience helping customers troubleshoot software issues.
Your key traits: patient, empathetic, detail-oriented, solution-focused, friendly.

---

Environment

You're communicating via [CHANNEL: phone/chat/video].
Context: [ENVIRONMENTAL FACTORS].
Communication style: [GUIDELINES].

Example:

You're speaking with customers over the phone.
Context: Background noise and poor connections are common.
Communication style: Speak clearly, use short sentences, pause occasionally for emphasis.

---

Tone

Formality: [PROFESSIONAL/CASUAL/FORMAL].
Language: [CONTRACTIONS/JARGON GUIDELINES].
Verbosity: [SENTENCE/RESPONSE LENGTH].
Emotional Expression: [HOW TO EXPRESS EMPATHY/ENTHUSIASM].

Example:

Formality: Professional yet warm and approachable.
Language: Use contractions for natural conversation. Avoid jargon unless customer uses it first.
Verbosity: 2-3 sentences per response. Ask one question at a time.
Emotional Expression: Show empathy with phrases like "I understand how frustrating that must be."

---

Goal

Primary Goal: [MAIN OBJECTIVE]

Secondary Goals:
- [SUPPORTING OBJECTIVE 1]
- [SUPPORTING OBJECTIVE 2]
- [SUPPORTING OBJECTIVE 3]

Success Criteria:
- [MEASURABLE OUTCOME 1]
- [MEASURABLE OUTCOME 2]

Example:

Primary Goal: Resolve customer technical issues on the first call.

Secondary Goals:
- Verify customer identity securely
- Document issue details accurately
- Provide proactive tips to prevent future issues

Success Criteria:
- Customer verbally confirms issue is resolved
- Issue documented in CRM
- Customer satisfaction ≥ 4/5

---

Guardrails

Never:
- [PROHIBITED ACTION 1]
- [PROHIBITED ACTION 2]
- [PROHIBITED ACTION 3]

Always:
- [REQUIRED ACTION 1]
- [REQUIRED ACTION 2]

Escalate When:
- [ESCALATION TRIGGER 1]
- [ESCALATION TRIGGER 2]

Example:

Never:
- Provide medical, legal, or financial advice
- Share confidential company information
- Make promises about refunds without verification
- Continue if customer becomes abusive

Always:
- Verify customer identity before accessing account details
- Document all interactions
- Offer alternative solutions if first approach fails

Escalate When:
- Customer requests manager
- Issue requires account credit/refund approval
- Technical issue beyond knowledge base
- Customer exhibits abusive behavior

---

Tools

Available Tools:

1. tool_name(param1, param2)
   Purpose: [WHAT IT DOES]
   Use When: [TRIGGER CONDITION]
   Example: [SAMPLE USAGE]

2. ...

Guidelines:
- Always explain to customer before calling tool
- Wait for tool response before continuing
- If tool fails, offer alternative

Example:

Available Tools:

1. lookup_order(order_id: string)
   Purpose: Fetch order details from database
   Use When: Customer mentions order number or asks about order status
   Example: "Let me look that up for you. [Call lookup_order('ORD-12345')]"

2. send_password_reset(email: string)
   Purpose: Trigger password reset email
   Use When: Customer can't access account and identity verified
   Example: "I'll send a password reset email. [Call send_password_reset('user@example.com')]"

3. transfer_to_supervisor()
   Purpose: Escalate to human agent
   Use When: Issue requires manager approval or customer explicitly requests
   Example: "Let me connect you with a supervisor. [Call transfer_to_supervisor()]"

Guidelines:
- Always explain what you're doing before calling tool
- Wait for tool response before continuing conversation
- If tool fails, acknowledge and offer alternative solution

---

Complete Prompt

Combine all sections into your final system prompt:

Personality:
You are [NAME], a [ROLE] at [COMPANY]. You have [EXPERIENCE]. Your traits: [TRAITS].

Environment:
You're communicating via [CHANNEL]. [CONTEXT]. [COMMUNICATION STYLE].

Tone:
[FORMALITY]. [LANGUAGE]. [VERBOSITY]. [EMOTIONAL EXPRESSION].

Goal:
Primary: [PRIMARY GOAL]
Secondary: [SECONDARY GOALS]
Success: [SUCCESS CRITERIA]

Guardrails:
Never: [PROHIBITIONS]
Always: [REQUIREMENTS]
Escalate: [TRIGGERS]

Tools:
[TOOL DESCRIPTIONS WITH EXAMPLES]

---

Testing Your Prompt

1. Create test scenarios covering common use cases 2. Run conversations and analyze transcripts 3. Check for:

• Tone consistency
• Goal achievement
• Guardrail adherence
• Tool usage accuracy

4. Iterate based on findings 5. Monitor analytics dashboard for real performance

ElevenLabs Agents API Reference

Base URL

https://api.elevenlabs.io/v1/convai

Authentication

All requests require an API key in the header:

curl -H "xi-api-key: YOUR_API_KEY" https://api.elevenlabs.io/v1/convai/agents

---

Agents

Create Agent

Endpoint: POST /agents/create

Request Body:

{
  "name": "Support Agent",
  "conversation_config": {
    "agent": {
      "prompt": {
        "prompt": "You are a helpful support agent.",
        "llm": "<verify current model id in dashboard>",
        "temperature": 0.7,
        "max_tokens": 500,
        "tool_ids": ["tool_123"],
        "knowledge_base": ["doc_456"]
      },
      "first_message": "Hello! How can I help?",
      "language": "en"
    },
    "tts": {
      "model_id": "eleven_turbo_v2_5",
      "voice_id": "voice_abc123",
      "stability": 0.5,
      "similarity_boost": 0.75,
      "speed": 1.0
    },
    "asr": {
      "quality": "high",
      "provider": "deepgram"
    },
    "turn": {
      "mode": "normal"
    }
  }
}

Response:

{
  "agent_id": "agent_abc123",
  "name": "Support Agent",
  "created_at": "2025-11-03T12:00:00Z"
}

Update Agent

Endpoint: PATCH /agents/:agent_id

Request Body: Same as Create Agent

Get Agent

Endpoint: GET /agents/:agent_id

Response:

{
  "agent_id": "agent_abc123",
  "name": "Support Agent",
  "conversation_config": { ... },
  "created_at": "2025-11-03T12:00:00Z",
  "updated_at": "2025-11-03T14:00:00Z"
}

List Agents

Endpoint: GET /agents

Response:

{
  "agents": [
    {
      "agent_id": "agent_abc123",
      "name": "Support Agent",
      "created_at": "2025-11-03T12:00:00Z"
    }
  ]
}

Delete Agent

Endpoint: DELETE /agents/:agent_id

Response:

{
  "success": true
}

---

Conversations

Create Conversation

Endpoint: POST /conversations/create

Request Body:

{
  "agent_id": "agent_abc123",
  "dynamic_variables": {
    "user_name": "John",
    "account_tier": "premium"
  },
  "overrides": {
    "agent": {
      "prompt": {
        "prompt": "Custom prompt override"
      }
    }
  }
}

Response:

{
  "conversation_id": "conv_xyz789",
  "signed_url": "wss://api.elevenlabs.io/v1/convai/...",
  "created_at": "2025-11-03T12:00:00Z"
}

Get Conversation

Endpoint: GET /conversations/:conversation_id

Response:

{
  "conversation_id": "conv_xyz789",
  "agent_id": "agent_abc123",
  "transcript": "...",
  "duration_seconds": 120,
  "status": "completed",
  "created_at": "2025-11-03T12:00:00Z",
  "ended_at": "2025-11-03T12:02:00Z"
}

---

Knowledge Base

Upload Document

Endpoint: POST /knowledge-base/upload

Request Body (multipart/form-data):

file: <binary>
name: "Support Documentation"

Response:

{
  "document_id": "doc_456",
  "name": "Support Documentation",
  "status": "processing"
}

Compute RAG Index

Endpoint: POST /knowledge-base/:document_id/rag-index

Request Body:

{
  "embedding_model": "e5_mistral_7b"
}

Response:

{
  "document_id": "doc_456",
  "status": "computing"
}

Get RAG Index Status

Endpoint: GET /knowledge-base/:document_id/rag-index

Response:

{
  "document_id": "doc_456",
  "status": "ready",
  "embedding_model": "e5_mistral_7b",
  "created_at": "2025-11-03T12:00:00Z"
}

---

Tools

Create Webhook Tool

Endpoint: POST /tools/webhook

Request Body:

{
  "name": "get_weather",
  "description": "Fetch current weather for a city",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["city"]
  },
  "headers": {
    "Authorization": "Bearer {{secret__weather_api_key}}"
  }
}

Response:

{
  "tool_id": "tool_123",
  "name": "get_weather",
  "created_at": "2025-11-03T12:00:00Z"
}

---

Testing

Simulate Conversation

Endpoint: POST /agents/:agent_id/simulate

Request Body:

{
  "scenario": "Customer requests refund",
  "user_messages": [
    "I want a refund for order #12345",
    "I ordered it last week"
  ],
  "success_criteria": [
    "Agent acknowledges request",
    "Agent provides timeline"
  ]
}

Response:

{
  "simulation_id": "sim_123",
  "passed": true,
  "transcript": "...",
  "evaluation": {
    "criteria_met": 2,
    "criteria_total": 2,
    "details": [
      {
        "criterion": "Agent acknowledges request",
        "passed": true
      },
      {
        "criterion": "Agent provides timeline",
        "passed": true
      }
    ]
  }
}

---

Error Codes

---

Rate Limits

• Standard Tier: 100 requests/minute
• Pro Tier: 500 requests/minute
• Enterprise Tier: Custom limits

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1730640000

---

Pagination

Query Parameters:

?page=1&per_page=50

Response Headers:

X-Total-Count: 250
X-Page: 1
X-Per-Page: 50

---

Webhook Events

Post-Call Webhook

Event Type: post_call_transcription

Payload:

{
  "type": "post_call_transcription",
  "data": {
    "conversation_id": "conv_xyz789",
    "agent_id": "agent_abc123",
    "transcript": "...",
    "duration_seconds": 120,
    "analysis": {
      "sentiment": "positive",
      "resolution": true,
      "extracted_data": {}
    }
  },
  "event_timestamp": "2025-11-03T12:02:00Z"
}

Verification (HMAC SHA-256):

import crypto from 'crypto';

const signature = request.headers['elevenlabs-signature'];
const payload = JSON.stringify(request.body);

const hmac = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (signature !== hmac) {
  // Invalid signature
}

---

SDK vs API

Recommendation: Use SDK for conversations, API for agent management.

Privacy & Compliance Guide

GDPR Compliance

Data Retention

Default: 2 years (730 days)

{
  "privacy": {
    "transcripts": {
      "retention_days": 730
    },
    "audio": {
      "retention_days": 730
    }
  }
}

Right to Be Forgotten

Enable data deletion requests:

await client.conversations.delete(conversation_id);

Data Residency

const { startConversation } = useConversation({
  serverLocation: 'eu-residency' // GDPR-compliant EU data centers
});

User Consent

Inform users before recording:

{
  "first_message": "This call will be recorded for quality and training purposes. Do you consent?"
}

---

HIPAA Compliance

Data Retention

Minimum: 6 years (2190 days)

{
  "privacy": {
    "transcripts": {
      "retention_days": 2190
    },
    "audio": {
      "retention_days": 2190
    }
  }
}

Encryption

• In Transit: TLS 1.3 (automatic)
• At Rest: AES-256 (automatic)

Business Associate Agreement (BAA)

Contact ElevenLabs for HIPAA BAA.

PHI Handling

Never:

• Store PHI in dynamic variables
• Log PHI in tool parameters
• Send PHI to third-party tools without BAA

Always:

• Use secure authentication
• Verify patient identity
• Document access logs

---

SOC 2 Compliance

Security Controls

✅ Encryption in transit and at rest (automatic) ✅ Access controls (API key management) ✅ Audit logs (conversation history) ✅ Incident response (automatic backups)

Best Practices

{
  "authentication": {
    "type": "signed_url", // Most secure
    "session_duration": 3600 // 1 hour max
  }
}

---

Regional Compliance

US Residency

serverLocation: 'us'

EU Residency (GDPR)

serverLocation: 'eu-residency'

India Residency

serverLocation: 'in-residency'

---

Zero Retention Mode

Maximum Privacy: Immediately delete all data after conversation ends.

{
  "privacy": {
    "zero_retention": true
  }
}

Limitations:

• No conversation history
• No analytics
• No post-call webhooks
• No MCP tool integrations

---

PCI DSS (Payment Card Industry)

Never:

❌ Store credit card numbers in conversation logs ❌ Send credit card data to LLM ❌ Log CVV or PIN numbers

Always:

✅ Use PCI-compliant payment processors (Stripe, PayPal) ✅ Tokenize payment data ✅ Use DTMF keypad for card entry (telephony)

Example: Secure Payment Collection

{
  "system_tools": [
    {
      "name": "dtmf_playpad",
      "description": "Display keypad for secure card entry"
    }
  ]
}

---

Compliance Checklist

GDPR

• [ ] Data retention ≤ 2 years (or justify longer)
• [ ] EU data residency enabled
• [ ] User consent obtained before recording
• [ ] Data deletion process implemented
• [ ] Privacy policy updated

HIPAA

• [ ] Data retention ≥ 6 years
• [ ] BAA signed with ElevenLabs
• [ ] Encryption enabled (automatic)
• [ ] Access logs maintained
• [ ] Staff trained on PHI handling

SOC 2

• [ ] API key security (never expose in client)
• [ ] Use signed URLs for authentication
• [ ] Monitor access logs
• [ ] Incident response plan documented

PCI DSS

• [ ] Never log card data
• [ ] Use tokenization for payments
• [ ] DTMF keypad for card entry
• [ ] PCI-compliant payment processor

---

Monitoring & Auditing

Access Logs

const logs = await client.conversations.list({
  agent_id: 'agent_123',
  from_date: '2025-01-01',
  to_date: '2025-12-31'
});

Compliance Reports

• Monthly conversation volume
• Data retention adherence
• Security incidents
• User consent rates

---

Incident Response

Data Breach Protocol

1. Identify affected conversations 2. Notify ElevenLabs immediately 3. Delete compromised data 4. Notify affected users (GDPR requirement) 5. Document incident 6. Review security controls

Contact

security@elevenlabs.io

Workflow Examples

Customer Support Routing

Scenario: Route calls to specialized agents based on customer needs.

{
  "workflow": {
    "nodes": [
      {
        "id": "initial_routing",
        "type": "subagent",
        "config": {
          "system_prompt": "Ask customer: Are you calling about billing, technical support, or sales?",
          "turn_eagerness": "patient"
        }
      },
      {
        "id": "billing_agent",
        "type": "subagent",
        "config": {
          "system_prompt": "You are a billing specialist. Help with invoices, payments, and account charges.",
          "voice_id": "billing_voice_id"
        }
      },
      {
        "id": "technical_agent",
        "type": "subagent",
        "config": {
          "system_prompt": "You are a technical support specialist. Troubleshoot product issues.",
          "voice_id": "tech_voice_id"
        }
      },
      {
        "id": "sales_agent",
        "type": "subagent",
        "config": {
          "system_prompt": "You are a sales representative. Help customers choose products.",
          "voice_id": "sales_voice_id"
        }
      }
    ],
    "edges": [
      { "from": "initial_routing", "to": "billing_agent", "condition": "user_mentions_billing" },
      { "from": "initial_routing", "to": "technical_agent", "condition": "user_mentions_technical" },
      { "from": "initial_routing", "to": "sales_agent", "condition": "user_mentions_sales" }
    ]
  }
}

Escalation Workflow

Scenario: Attempt self-service resolution, then escalate to human if needed.

{
  "workflow": {
    "nodes": [
      {
        "id": "self_service",
        "type": "subagent",
        "config": {
          "system_prompt": "Try to resolve issue using knowledge base and tools. If issue can't be resolved, offer human transfer.",
          "knowledge_base": ["faq_doc_id"],
          "tool_ids": ["lookup_order", "check_status"]
        }
      },
      {
        "id": "human_transfer",
        "type": "tool",
        "tool_name": "transfer_to_human"
      }
    ],
    "edges": [
      { "from": "self_service", "to": "human_transfer", "condition": "user_requests_human_or_issue_unresolved" }
    ]
  }
}

Multi-Language Support

Scenario: Detect language and route to appropriate voice/agent.

{
  "workflow": {
    "nodes": [
      {
        "id": "language_detection",
        "type": "subagent",
        "config": {
          "system_prompt": "Greet customer and detect language.",
          "language": "auto"
        }
      },
      {
        "id": "english_agent",
        "type": "subagent",
        "config": {
          "language": "en",
          "voice_id": "en_voice_id",
          "first_message": "Hello! How can I help you today?"
        }
      },
      {
        "id": "spanish_agent",
        "type": "subagent",
        "config": {
          "language": "es",
          "voice_id": "es_voice_id",
          "first_message": "¡Hola! ¿Cómo puedo ayudarte hoy?"
        }
      }
    ],
    "edges": [
      { "from": "language_detection", "to": "english_agent", "condition": "detected_language_en" },
      { "from": "language_detection", "to": "spanish_agent", "condition": "detected_language_es" }
    ]
  }
}

Best Practices

1. Keep workflows simple - Max 5-7 nodes for maintainability 2. Test all paths - Ensure every edge condition works 3. Add fallbacks - Always have a default path 4. Monitor transitions - Track which paths users take most 5. Avoid loops - Workflows can get stuck in infinite loops