Documentation

Voice Agents

Copy page

Build intelligent voice agents that can make outbound calls, handle conversations, and integrate with your systems through webhooks.

Overview

Voice Agents combine STT, LLM, and TTS models into a unified conversational AI that can:

• Make outbound phone calls with a defined personality and behavior
• Handle real-time conversations with low latency
• Use tools to interact with your backend systems
• Support dynamic prompts with template variables

Quick Start

1. Create an Agent

Code
 
curl -X POST https://api.slng.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "system_prompt": "You are a helpful customer support agent for {{company_name}}. Be polite, professional, and concise. Help customers with their questions about {{topic}}.",
    "greeting": "Hello! Thank you for taking my call. How can I help you today?",
    "language": "en",
    "models": {
      "stt": "deepgram/nova:2",
      "llm": "openai/gpt-4o",
      "tts": "deepgram/aura:2",
      "tts_voice": "aura-2-andromeda-en",
      "llm_kwargs": {
        "temperature": 0.7
      }
    },
    "slng_api_key": "YOUR_SLNG_API_KEY",
    "livekit_deployment": "production",
    "template_defaults": {
      "company_name": "Acme Corp",
      "topic": "orders and returns"
    }
  }'

Response:

Code
 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organisation_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Customer Support Agent",
  "system_prompt": "You are a helpful customer support agent for {{company_name}}...",
  "greeting": "Hello! Thank you for taking my call...",
  "language": "en",
  "models": {
    "stt": "deepgram/nova:2",
    "llm": "openai/gpt-4o",
    "tts": "deepgram/aura:2",
    "tts_voice": "aura-2-andromeda-en",
    "llm_kwargs": { "temperature": 0.7 }
  },
  "enable_interruptions": true,
  "tools": [],
  "livekit_deployment": "production",
  "template_variables": {
    "company_name": { "required": false, "default": "Acme Corp" },
    "topic": { "required": false, "default": "orders and returns" }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

2. Dispatch an Outbound Call

Code
 
curl -X POST https://api.slng.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "arguments": {
      "company_name": "TechCorp",
      "topic": "software subscriptions"
    }
  }'

Response:

Code
 
{
  "call_id": "660e8400-e29b-41d4-a716-446655440001",
  "message": "Call dispatched successfully"
}

Agent Configuration

Required Fields

Field	Type	Description
name	string	Unique agent name (max 255 chars)
system_prompt	string	System prompt with Handlebars template support
greeting	string	Initial message spoken when call connects
language	string	Language code (e.g., "en", "es", "fr")
models	object	Model configuration (see below)
slng_api_key	string	SLNG API key for the agent to use
livekit_deployment	string	LiveKit deployment name

Models Configuration

The models object configures which AI models power your agent:

Code
 
{
  "models": {
    "stt": "deepgram/nova:2",
    "llm": "openai/gpt-4o",
    "tts": "deepgram/aura:2",
    "tts_voice": "aura-2-andromeda-en",
    "stt_kwargs": {},
    "llm_kwargs": { "temperature": 0.7 },
    "tts_kwargs": {}
  }
}

Field	Type	Description
stt	string	Speech-to-text model (format: provider/model)
llm	string	Language model (format: provider/model)
tts	string	Text-to-speech model (format: provider/model:variant)
tts_voice	string	Voice identifier for TTS
stt_kwargs	object	Additional STT parameters
llm_kwargs	object	Additional LLM parameters (e.g., temperature)
tts_kwargs	object	Additional TTS parameters

Recommended Model Combinations

Low Latency (Real-time conversations):

Code
 
{
  "stt": "deepgram/nova:2",
  "llm": "openai/gpt-4o-mini",
  "tts": "deepgram/aura:2",
  "tts_voice": "aura-2-andromeda-en"
}

High Quality (Complex conversations):

Code
 
{
  "stt": "deepgram/nova:2",
  "llm": "openai/gpt-4o",
  "tts": "elevenlabs/eleven-flash:2.5",
  "tts_voice": "rachel"
}

Optional Fields

Field	Type	Default	Description
enable_interruptions	boolean	true	Allow user to interrupt agent speech
tools	array	[]	Tools available to the agent
template_defaults	object	{}	Default values for template variables

Template Variables

Use Handlebars syntax ({{variable}}) in your system prompt to create dynamic agents:

Code
 
{
  "system_prompt": "You are calling {{customer_name}} about their order #{{order_id}}. The order status is: {{order_status}}.",
  "template_defaults": {
    "order_status": "processing"
  }
}

When dispatching a call, provide values for template variables:

Code
 
{
  "phone_number": "+14155551234",
  "arguments": {
    "customer_name": "John Smith",
    "order_id": "ORD-12345",
    "order_status": "shipped"
  }
}

Variables with defaults in template_defaults are optional when dispatching. Variables without defaults are required.

Tools

Agents can use tools to interact with external systems during conversations.

Template Tools

Built-in tools for common actions:

Hangup Tool

Allows the agent to end the call gracefully:

Code
 
{
  "tools": [
    {
      "type": "template",
      "template": "hangup",
      "prompt": "Use this tool when the conversation is complete and the customer has no more questions."
    }
  ]
}

Voicemail Detection Tool

Detects if the call reached voicemail:

Code
 
{
  "tools": [
    {
      "type": "template",
      "template": "voicemail_detection"
    }
  ]
}

Webhook Tools

Custom tools that call your backend APIs:

Code
 
{
  "tools": [
    {
      "type": "webhook",
      "name": "check_order_status",
      "description": "Check the current status of a customer order by order ID",
      "url": "https://api.yourcompany.com/orders/status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The order ID to check"
          }
        },
        "required": ["order_id"]
      },
      "auth": {
        "type": "bearer",
        "token": "your-api-token"
      },
      "timeout_seconds": 10,
      "wait_for_response": true
    }
  ]
}

Webhook Tool Fields

Field	Type	Required	Description
type	string	Yes	Must be "webhook"
name	string	Yes	Tool name (lowercase, underscores, max 64 chars)
description	string	Yes	Description for the LLM (max 500 chars)
url	string	Yes	Webhook endpoint URL
parameters	object	Yes	JSON Schema for tool parameters
auth	object	No	Authentication config
timeout_seconds	number	No	Timeout (1-60, default: 10)
wait_for_response	boolean	No	Wait for response (default: true)

Authentication Options

Bearer Token:

Code
 
{
  "auth": {
    "type": "bearer",
    "token": "your-secret-token"
  }
}

HMAC Signature:

Code
 
{
  "auth": {
    "type": "hmac",
    "secret": "your-hmac-secret"
  }
}

API Reference

Create Agent

Code
 
POST /v1/agents

Creates a new voice agent.

List Agents

Code
 
GET /v1/agents

Returns all agents for your organization.

Get Agent

Code
 
GET /v1/agents/{agent_id}

Returns a single agent by ID.

Update Agent (Partial)

Code
 
PATCH /v1/agents/{agent_id}

Updates specific fields of an agent. Only include fields you want to change.

Code
 
curl -X PATCH https://api.slng.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Hi there! This is an updated greeting."
  }'

Replace Agent (Full)

Code
 
PUT /v1/agents/{agent_id}

Fully replaces an agent. All required fields must be provided.

Delete Agent

Code
 
DELETE /v1/agents/{agent_id}

Soft-deletes an agent (can be restored by support).

Dispatch Call

Code
 
POST /v1/agents/{agent_id}/calls

Initiates an outbound call using the specified agent.

Request Body:

Field	Type	Required	Description
phone_number	string	Yes	E.164 format (e.g., +14155551234)
arguments	object	No	Values for template variables

Best Practices

System Prompt Design

1. Be specific about the agent's role and limitations

   Code
    
   You are a scheduling assistant for Dr. Smith's dental office.
   You can ONLY help with appointment scheduling and rescheduling.
   Do not provide medical advice.

2. Include conversation flow guidance

   Code
    
   Start by confirming the customer's name, then ask about their
   preferred date and time. Always confirm the appointment details
   before ending the call.

3. Handle edge cases

   Code
    
   If the customer asks about something outside your scope,
   politely explain your limitations and offer to transfer
   to a human agent.

Error Handling

• Check the response status code for errors
• 400: Validation error (check your request body)
• 403: API key issue or organization not found
• 404: Agent not found
• 409: Agent name already exists

Security

• Store webhook auth tokens securely
• Use HTTPS for all webhook URLs
• Rotate API keys regularly
• Use template variables for sensitive data instead of hardcoding

Complete Example

Here's a complete example of a customer outreach agent with tools:

Code
 
// Create the agent
const response = await fetch("https://api.slng.ai/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Outreach Agent",
    system_prompt: `You are calling {{customer_name}} from {{company_name}}.
Your goal is to follow up on their recent {{service_type}} service.

Guidelines:
- Be friendly and professional
- Ask about their satisfaction with the service
- If they have concerns, log them using the log_feedback tool
- If they're satisfied, thank them and offer to schedule a follow-up
- Keep the call under 3 minutes

If you detect voicemail, leave a brief message and hang up.`,
    greeting:
      "Hi, this is Sarah from {{company_name}}. Am I speaking with {{customer_name}}?",
    language: "en",
    models: {
      stt: "deepgram/nova:2",
      llm: "openai/gpt-4o",
      tts: "elevenlabs/eleven:flash-v2.5",
      tts_voice: "rachel",
      llm_kwargs: { temperature: 0.8 },
    },
    enable_interruptions: true,
    tools: [
      {
        type: "template",
        template: "hangup",
      },
      {
        type: "template",
        template: "voicemail_detection",
      },
      {
        type: "webhook",
        name: "log_feedback",
        description: "Log customer feedback about the service",
        url: "https://api.yourcompany.com/feedback",
        parameters: {
          type: "object",
          properties: {
            sentiment: {
              type: "string",
              enum: ["positive", "neutral", "negative"],
            },
            notes: {
              type: "string",
              description: "Summary of customer feedback",
            },
          },
          required: ["sentiment", "notes"],
        },
        auth: { type: "bearer", token: "your-api-token" },
        timeout_seconds: 5,
      },
    ],
    slng_api_key: "your-slng-api-key",
    livekit_deployment: "production",
    template_defaults: {
      company_name: "Acme Services",
      service_type: "maintenance",
    },
  }),
});

const agent = await response.json();
console.log("Agent created:", agent.id);

// Dispatch a call
const callResponse = await fetch(
  `https://api.slng.ai/v1/agents/${agent.id}/calls`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155551234",
      arguments: {
        customer_name: "John Smith",
        service_type: "HVAC repair",
      },
    }),
  },
);

const call = await callResponse.json();
console.log("Call dispatched:", call.call_id);

Next Steps

• View API Reference - Complete OpenAPI specification
• Agent CRUD Examples - More code examples
• Call Dispatch Examples - Outbound call patterns