Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.slng.ai/llms.txt

Use this file to discover all available pages before exploring further.

Voice Agents are server-managed configurations that pair an LLM with SLNG’s STT and TTS models. You create an agent once, then dispatch it to phone calls or web sessions. Agents support template tools, built-in utilities like current date/time lookup, webhooks, human transfer, and dynamic prompts via template variables.
The Voice Agents API is served from https://api.agents.slng.ai under /v1/agents.
If you prefer a UI (or you’re setting up telephony), start in the Dashboard:
If you already have an agent configured the way you want, you can duplicate it from the API or from Agent Infra. Duplication preserves the stored agent configuration, but it requires a new slng_api_key and does not copy the inbound connection.

​
Quick Start (API)

1

Create an agent

curl -X POST https://api.agents.slng.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Healthcare Outreach Agent",
    "system_prompt": "You are Sarah, a patient outreach coordinator for {{practice_name}}. You are calling {{patient_name}} to help schedule their next visit. Keep responses to 1–2 sentences, ask one question at a time, and never provide medical advice.",
    "greeting": "Hi, is this {{patient_name}}? This is Sarah calling from {{practice_name}}. I'm reaching out because it looks like you're due for a visit, and I wanted to help get that scheduled for you if now's a good time?",
    "language": "en",
    "region": "eu-central",
    "models": {
      "stt": "slng/deepgram/nova:3-en",
      "llm": "groq/moonshotai/kimi-k2-instruct-0905",
      "tts": "slng/deepgram/aura:2-en",
      "tts_voice": "aura-2-thalia-en",
      "llm_kwargs": {}
    },
    "enable_interruptions": true,
    "tools": [
      {
        "type": "template",
        "id": "dc4d6391-dc51-44e3-a816-bf65948290a2",
        "template": "hangup",
        "execution_policy": {
          "pre_action_message": {
            "enabled": true,
            "text": "Thank you for your time. Have a great day."
          }
        }
      }
    ],
    "slng_api_key": "YOUR_SLNG_API_KEY",
    "template_defaults": {
      "patient_name": "Maria",
      "practice_name": "Greenfield Family Medicine"
    }
  }'
slng_api_key is the API key your agent uses for SLNG model requests. You can reuse the same key you use for this API, or use a dedicated key.
region is required. It determines where the agent runs and which telephony and browser-session path it uses.
2

Create a web session (no telephony)

Use web sessions to test an agent without setting up telephony:
curl -X POST https://api.agents.slng.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000/web-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_name": "Test user",
    "arguments": {
      "patient_name": "Maria",
      "practice_name": "Greenfield Family Medicine"
    }
  }'
3

Dispatch an outbound call (requires telephony)

Outbound calls require the agent to be configured with an outbound connection (sip_outbound_trunk_id). Configure this in the Dashboard Telephony page and attach it to your agent.
Outbound telephony country pinning follows the agent’s selected region. Today the mapping is eu-central -> DE, us-east -> US, and ap-south -> IN.
curl -X POST https://api.agents.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": {
      "patient_name": "Maria",
      "practice_name": "Greenfield Family Medicine"
    }
  }'

​
Agent configuration

​
Required fields

FieldTypeDescription
namestringUnique agent name (max 255 chars)
system_promptstringSystem prompt with Handlebars template support
greetingstringDefault greeting
languagestringLanguage code (e.g., “en”, “es”, “fr”)
regionstringDeployment region (us-east, eu-central, ap-south)
modelsobjectModel configuration (see below)
slng_api_keystringSLNG API key for the agent runtime

​
Common optional fields

FieldTypeDefaultDescription
inbound_greetingstringnullGreeting override for inbound calls
outbound_greetingstringnullGreeting override for outbound calls
sip_inbound_trunk_idstringnullInbound connection ID (for inbound calls)
sip_outbound_trunk_idstringnullOutbound connection ID (for outbound calls)
enable_interruptionsbooleantrueAllow user to interrupt agent speech
idle_nudgesobjectlanguage defaultsSilence recovery prompts and final hangup behavior
toolsarray[]Tools available to the agent
template_defaultsobject{}Default values for template variables

​
Models configuration

The models object configures the STT, LLM, and TTS models used by the agent runtime: 
{
  "models": {
    "stt": "slng/deepgram/nova:3-en",
    "llm": "groq/moonshotai/kimi-k2-instruct-0905",
    "tts": "slng/deepgram/aura:2-en",
    "tts_voice": "aura-2-thalia-en",
    "stt_kwargs": {},
    "llm_kwargs": {},
    "tts_kwargs": {}
  }
}
Advanced optional controls are also supported: 
{
  "models": {
    "stt": "slng/deepgram/nova:3-en",
    "llm": "groq/moonshotai/kimi-k2-instruct-0905",
    "tts": "slng/deepgram/aura:2-en",
    "tts_voice": "aura-2-thalia-en",
    "fallbacks": {
      "stt": ["slng/deepgram/nova:3-multi"],
      "llm": ["groq/moonshotai/kimi-k2-instruct-0905"],
      "tts": [
        { "model": "slng/deepgram/aura:2-en", "voice": "aura-2-asteria-en" }
      ]
    },
    "stt_final_timeout_s": 4.0,
    "llm_first_token_timeout_s": 6.0,
    "tts_first_audio_timeout_s": 4.0,
    "failure_audio_enabled": true
  }
}

​
Idle nudges

Use idle_nudges to recover from long silences. The agent can send two follow-up prompts, then speak a final message and hang up. 
{
  "idle_nudges": {
    "enabled": true,
    "first_nudge_delay_seconds": 15,
    "second_nudge_delay_seconds": 30,
    "hangup_delay_seconds": 15,
    "first_nudge_text": "Are you still there?",
    "second_nudge_text": "I can stay on the line if you need a moment.",
    "final_hangup_text": "I’m going to disconnect for now. Feel free to call back anytime."
  }
}
If you omit this field, the API can still return language-specific defaults for the agent.

​
Template variables

Use Handlebars syntax ({{variable}}) in your system prompt and greeting(s) to create dynamic agents:
If you are configuring agents in the Dashboard, the same concepts appear in Agent Infra. That page now calls out both prompt/greeting template variables and tool personalization directly from the create-agent flow.
{
  "system_prompt": "You are calling {{patient_name}} from {{practice_name}} to help schedule a checkup.",
  "template_defaults": {
    "practice_name": "Greenfield Family Medicine"
  }
}
When dispatching a call, provide values for template variables: 
{
  "phone_number": "+14155551234",
  "arguments": {
    "patient_name": "Maria",
    "practice_name": "Greenfield Family Medicine"
  }
}

​
Tool personalization

Tool personalization uses the same {{variable}} syntax, but only on runtime-safe tool fields. Tool fields are validated when the tool runs rather than when the call starts. If you are looking for the UI entry point first, see Agent Infra. The create-agent page surfaces this via the Personalizable indicator in supported tool fields.
  • Prompt / greeting variables are start-critical. Missing values can block the session.
  • Tool-only variables are runtime-only. Missing or invalid values fail the tool, not the call.
Supported surfaces in v1:
Tool surfaceSupports personalizationNotes
Contextual webhook urlYesOnly in path segments and query parameter values. Scheme, host, port, credentials, fragments, and query parameter names must stay literal.
System webhook urlYesOnly in path segments and query parameter values. Scheme, host, port, credentials, fragments, and query parameter names must stay literal.
System webhook argument valuesYesScalar values only in v1 (string, integer, number, boolean)
System webhook descriptionNoMust stay static
System webhook llm_result_instructionsNoMust stay static
System webhook pre-action message textNoMust stay static
Human transfer phone_numberYesMust resolve to E.164
Built-in timezoneYesMust resolve to an IANA timezone
Auth secretsNoSecrets remain literal-only
Examples: 
{
  "tools": [
    {
      "type": "webhook",
      "id": "2e4e8759-8467-4a53-9c96-0e08112ea13d",
      "name": "lookup_catalog_item",
      "description": "Load item details before continuing.",
      "url": "https://api.example.com/catalog/{{item_id}}/webhook?case={{case_id}}",
      "parameters": {
        "type": "object",
        "properties": {}
      },
      "source": "system",
      "system": {
        "triggers": [{ "event": "call_end" }],
        "arguments": [
          {
            "name": "retry_count",
            "type": "integer",
            "source": {
              "type": "template",
              "template": "{{max_retries}}"
            }
          },
          {
            "name": "vip",
            "type": "boolean",
            "source": {
              "type": "template",
              "template": "{{is_vip}}"
            }
          }
        ]
      },
      "execution_policy": {
        "pre_action_message": {
          "enabled": true,
          "text": "One moment while I load item details."
        }
      }
    },
    {
      "type": "human_transfer",
      "id": "af5265b7-4a93-4bf5-a56a-7ccb0f3c0145",
      "name": "transfer_to_support",
      "phone_number": "+34{{local_number}}"
    },
    {
      "type": "built_in",
      "id": "0d2fdfe8-0375-4283-bfe0-e6013ed1df59",
      "built_in": "current_datetime",
      "timezone": "Europe/{{timezone_city}}"
    }
  ]
}
Validation rules:
  • URLs must resolve to a full http:// or https:// URL while preserving the configured origin.
  • URL placeholders are allowed only in path segments and query parameter values.
  • URL placeholders are rejected in scheme, host, port, user info, fragments, and query parameter names.
  • phone_number must resolve to E.164, for example +34600111222.
  • timezone must resolve to an IANA timezone, for example Europe/Madrid.
  • Templated system argument values are scalar-only in v1. Arrays must remain literal constants.
  • description, llm_result_instructions, and pre-action message text are static configuration and do not support runtime personalization.
Runtime arguments are also bounded:
  • Maximum 32 keys
  • Maximum key length 64 characters
  • Maximum value length 1024 characters
  • Maximum combined value length 8192 characters
  • Template substitution only. Expressions and formulas are not supported.

​
Tools

Tool id is required for all tools and must be unique within an agent. Tool IDs should be stable (don’t regenerate them on every update).

​
Template tools

{
  "tools": [
    {
      "type": "template",
      "id": "dc4d6391-dc51-44e3-a816-bf65948290a2",
      "template": "hangup",
      "execution_policy": {
        "pre_action_message": {
          "enabled": true,
          "text": "Thank you for your time. Have a great day."
        }
      }
    },
    {
      "type": "template",
      "id": "95f6f6b2-0a1c-4ff2-8c91-451e36df3c73",
      "template": "voicemail_detection"
    }
  ]
}

​
Built-in date/time tool

{
  "tools": [
    {
      "type": "built_in",
      "id": "f0d84ac5-7988-460c-995d-2ad9621c09bb",
      "built_in": "current_datetime",
      "timezone": "Europe/Madrid",
      "prompt": "Use this whenever you need the current local date, time, or day of week for the caller."
    }
  ]
}
This exposes a get_current_datetime tool to the model. The result includes timezone, local_datetime, local_date, local_time, day_of_week, utc_offset, and is_dst. Like webhook tools, built-in tools can also be configured with "source": "system" plus system.triggers to inject the current date/time automatically on events such as call_start.

​
Webhook tools (LLM-invoked)

{
  "tools": [
    {
      "type": "webhook",
      "id": "8d7f2a3f-35d6-4ff9-97e6-1ab6a2d6867a",
      "name": "check_order_status",
      "description": "Check the status of a customer order by order ID",
      "url": "https://api.yourcompany.com/orders/status",
      "parameters": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      },
      "auth": { "type": "bearer", "token": "your-api-token" },
      "timeout_seconds": 10,
      "wait_for_response": true,
      "show_results_to_llm": true,
      "llm_result_instructions": "Summarize the tool result briefly and ask the caller for the next required detail."
    }
  ]
}
Webhook auth secrets are write-only. Agent responses will include auth_type but never return tokens/secrets.
Use show_results_to_llm to control whether successful webhook payloads are exposed back to the model. Set it to false when the webhook is side-effect only. Use llm_result_instructions to tell the model how to interpret and respond to successful results when they are visible. This field is static configuration and does not support runtime personalization.

​
HTTP method and payload format

Two optional fields control how SLNG calls your webhook:
  • http_method: POST (default), PUT, PATCH, or DELETE.
  • webhook_format: envelope (default) or raw. envelope wraps your tool arguments in an SLNG metadata envelope (call ID, timestamps, tool context). raw sends just the tool arguments, which is useful when the receiving service expects a specific schema and cannot parse the envelope.
{
  "type": "webhook",
  "name": "update_crm_record",
  "url": "https://api.yourcompany.com/crm/contacts/{{contact_id}}",
  "http_method": "PATCH",
  "webhook_format": "raw",
  "parameters": {
    "type": "object",
    "properties": { "status": { "type": "string" } }
  }
}

​
System webhook tools (automatic triggers)

{
  "tools": [
    {
      "type": "webhook",
      "id": "7bb0a71a-9153-4b4d-93b7-5d4d74efef24",
      "name": "send_call_summary",
      "description": "Send a JSON summary when the call ends",
      "url": "https://api.yourcompany.com/calls/summary",
      "parameters": { "type": "object", "properties": {}, "required": [] },
      "source": "system",
      "system": {
        "triggers": [{ "event": "call_end" }],
        "arguments": [
          {
            "name": "call_id",
            "type": "string",
            "source": { "type": "call_id" }
          },
          {
            "name": "transcript",
            "type": "transcript_messages",
            "source": { "type": "transcript_messages", "max_messages": 200 }
          }
        ]
      }
    }
  ]
}

​
Human transfer tool

Transfer the caller to a human (requires sip_outbound_trunk_id on the agent): 
{
  "tools": [
    {
      "type": "human_transfer",
      "id": "a9040e05-15a8-4fc9-86bd-a4903a6a907e",
      "name": "transfer_to_support",
      "description": "Transfer to a human support agent",
      "phone_number": "+14155551234",
      "execution_policy": {
        "pre_action_message": {
          "enabled": true,
          "text": "Let me connect you to a member of our team."
        }
      }
    }
  ]
}

​
Example agent patterns

These are common production-style combinations:
  • Scheduling assistant: current_datetime + hangup + idle_nudges. Useful when the agent needs accurate local time before offering appointment slots.
  • Support router: contextual webhook lookup + human_transfer. Good for triage flows where the agent resolves routine cases but escalates exceptions.
  • Collections follow-up: voicemail_detection + system webhook on call_end. Useful when every completed call needs a CRM or collections-platform summary.
  • Restaurant host: current_datetime + availability webhook. Good for reservation, booking, and inventory-style lookups that depend on real-time availability.
  • After-hours clinic router: system-injected current_datetime on call_start + human_transfer + hangup. Useful when business-hour logic should be available to the model before the first user turn.
The API reference now includes multiple Create agent request examples showing these patterns with concrete payloads.

​
Calls and sessions

  • POST /v1/agents/{agent_id}/calls dispatches an outbound call (requires telephony)
  • POST /v1/agents/{agent_id}/web-sessions creates a web (non-telephony) session
  • POST /v1/agents/{agent_id}/duplicate creates a server-side copy with a new name and slng_api_key
  • GET /v1/agents/{agent_id}/calls lists calls (paginated)
  • GET /v1/agents/{agent_id}/calls/{call_id} fetches a call record
Call records may include additional runtime diagnostics when available. These fields are treated as opaque objects and their structure may change. For a user-friendly transcript view, use the Dashboard calls page.

​
Tool execution tracking

Record webhook, template, human-transfer, and built-in tool activity against a call by posting to the tool executions endpoint. Each record carries the outcome, duration, and HTTP status. Submitted executions also surface on the call detail response for after-the-fact debugging or analytics.

​
API reference

See the Voice Agents API tab for a complete OpenAPI reference.

​
Next steps

Agent Infra

Build and test agents with a visual UI.

Agent configuration

System prompts, tools, and template variables.

Call Examples

Dispatch outbound calls and batch campaigns.