Voisnap Docs
Getting Started

Quickstart

Create your first Voisnap voice agent and make a test call in under 10 minutes.

Quickstart

This guide walks you from zero to a live, callable voice AI agent. You'll create an API key, configure an agent, provision a phone number, and make a test call — all via the Voisnap API.

Total time: ~10 minutes

Step 1: Sign up and open the Console

Go to console.voisnap.ai and create your account. After email verification, you land on the Dashboard.

For this quickstart you'll work with both the Console UI and the API. You can do everything below via API alone once you have your first key.

Step 2: Create an API key

Navigate to Console → Settings → API Keys and click New API Key, or use the API directly:

# You can get your first key from the Console UI.
# Subsequent keys can be created via the API once you have one.
POST https://api.voisnap.ai/api/v1/api-keys
Authorization: Bearer <existing_api_key>
Content-Type: application/json
 
{
  "name": "My first key",
  "scopes": [
    "agents:read",
    "agents:write",
    "conversations:read",
    "telephony:read",
    "telephony:write"
  ]
}
import voisnap
 
client = voisnap.VoisnapClient(api_key="vsnp_...")
 
key = client.api_keys.create(
    name="My first key",
    scopes=["agents:read", "agents:write", "conversations:read",
            "telephony:read", "telephony:write"]
)
print(key.key)  # vsnp_abc123... — store this, it won't be shown again
import { VoisnapClient } from '@voisnap/sdk';
 
const client = new VoisnapClient({ apiKey: 'vsnp_...' });
 
const key = await client.apiKeys.create({
  name: 'My first key',
  scopes: ['agents:read', 'agents:write', 'conversations:read',
           'telephony:read', 'telephony:write'],
});
console.log(key.key); // store this immediately

Response:

{
  "id": "key_01HXK8ZABCDEF",
  "name": "My first key",
  "key": "vsnp_live_k8za1b2c3d4e5f6g7h8i9j0",
  "scopes": ["agents:read", "agents:write", "conversations:read", "telephony:read", "telephony:write"],
  "createdAt": "2025-06-15T10:00:00Z",
  "lastUsedAt": null,
  "expiresAt": null
}

:::warning The full API key is only returned once at creation. Store it securely (e.g., in a secrets manager or .env file). If you lose it, revoke and regenerate. :::

Step 3: Create your first agent

An agent defines the AI persona, voice, behaviour, and channel configuration. Here's a minimal but complete agent:

curl -X POST https://api.voisnap.ai/api/v1/agents \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria – Support Agent",
    "description": "Front-line customer support agent for Acme Corp",
    "persona": {
      "name": "Aria",
      "personality": "friendly, concise, professional"
    },
    "voice": {
      "provider": "elevenlabs",
      "voiceId": "EXAVITQu4vr4xnSDxMaL",
      "stability": 0.5,
      "similarityBoost": 0.75,
      "style": 0.0,
      "useSpeakerBoost": true
    },
    "llm": {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.7,
      "maxTokens": 300
    },
    "transcription": {
      "provider": "deepgram",
      "model": "nova-2",
      "language": "en-US"
    },
    "systemPromptTemplate": "You are Aria, a friendly customer support agent for Acme Corp. Your goal is to resolve customer issues efficiently and empathetically.\n\nGuidelines:\n- Keep responses under 2 sentences unless more detail is needed\n- Always confirm the customer'\''s issue before offering a solution\n- If you cannot resolve an issue, offer to transfer to a human agent\n- Do not make up information; say you'\''ll look into it if unsure",
    "firstMessage": "Hello! Thanks for calling Acme support. I'\''m Aria — how can I help you today?",
    "firstMessageMode": "assistant_speaks_first",
    "endCallPhrases": ["goodbye", "have a good day", "thank you, bye"],
    "maxDurationSeconds": 600,
    "maxIdleTimeSeconds": 15,
    "silenceDetection": {
      "enabled": true,
      "timeoutSeconds": 8,
      "message": "Are you still there?"
    },
    "recording": {
      "enabled": true,
      "format": "mp3",
      "storageRetentionDays": 90
    }
  }'
agent = client.agents.create(
    name="Aria – Support Agent",
    description="Front-line customer support agent for Acme Corp",
    persona={"name": "Aria", "personality": "friendly, concise, professional"},
    voice={
        "provider": "elevenlabs",
        "voice_id": "EXAVITQu4vr4xnSDxMaL",
        "stability": 0.5,
        "similarity_boost": 0.75,
    },
    llm={"provider": "openai", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 300},
    transcription={"provider": "deepgram", "model": "nova-2", "language": "en-US"},
    system_prompt_template=(
        "You are Aria, a friendly customer support agent for Acme Corp. "
        "Keep responses under 2 sentences unless more detail is needed..."
    ),
    first_message="Hello! Thanks for calling Acme support. I'm Aria — how can I help you today?",
    first_message_mode="assistant_speaks_first",
    end_call_phrases=["goodbye", "have a good day", "thank you, bye"],
    max_duration_seconds=600,
    max_idle_time_seconds=15,
    recording={"enabled": True, "format": "mp3", "storage_retention_days": 90},
)
print(f"Agent created: {agent.id}")
const agent = await client.agents.create({
  name: 'Aria – Support Agent',
  description: 'Front-line customer support agent for Acme Corp',
  persona: { name: 'Aria', personality: 'friendly, concise, professional' },
  voice: {
    provider: 'elevenlabs',
    voiceId: 'EXAVITQu4vr4xnSDxMaL',
    stability: 0.5,
    similarityBoost: 0.75,
  },
  llm: { provider: 'openai', model: 'gpt-4o', temperature: 0.7, maxTokens: 300 },
  transcription: { provider: 'deepgram', model: 'nova-2', language: 'en-US' },
  systemPromptTemplate: 'You are Aria, a friendly customer support agent...',
  firstMessage: "Hello! Thanks for calling Acme support. I'm Aria — how can I help you today?",
  firstMessageMode: 'assistant_speaks_first',
  endCallPhrases: ['goodbye', 'have a good day', 'thank you, bye'],
  maxDurationSeconds: 600,
  maxIdleTimeSeconds: 15,
  recording: { enabled: true, format: 'mp3', storageRetentionDays: 90 },
});
console.log('Agent created:', agent.id);

Response:

{
  "id": "agt_01HXK8Z3MNPQRS",
  "name": "Aria – Support Agent",
  "status": "inactive",
  "version": 1,
  "createdAt": "2025-06-15T10:05:00Z",
  "updatedAt": "2025-06-15T10:05:00Z"
}

Step 4: Assign a phone number

Search for an available number, provision it, then assign it to your agent.

# Search available numbers
curl "https://api.voisnap.ai/api/v1/telephony/numbers/search?country=US&areaCode=415&capabilities=voice" \
  -H "Authorization: Bearer vsnp_live_..."
 
# Provision (purchase) a number
curl -X POST https://api.voisnap.ai/api/v1/telephony/numbers \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+14155550123", "provider": "twilio"}'
 
# Assign the number to your agent
curl -X POST "https://api.voisnap.ai/api/v1/telephony/numbers/num_01HXABC/assign/agt_01HXK8Z3MNPQRS" \
  -H "Authorization: Bearer vsnp_live_..."
# Search
numbers = client.telephony.numbers.search(country="US", area_code="415", capabilities=["voice"])
number = numbers[0]
 
# Provision
provisioned = client.telephony.numbers.provision(
    phone_number=number.phone_number,
    provider="twilio"
)
 
# Assign to agent
client.telephony.numbers.assign(number_id=provisioned.id, agent_id=agent.id)
print(f"Number {provisioned.phone_number} assigned to agent {agent.id}")
const numbers = await client.telephony.numbers.search({
  country: 'US', areaCode: '415', capabilities: ['voice'],
});
 
const provisioned = await client.telephony.numbers.provision({
  phoneNumber: numbers[0].phoneNumber,
  provider: 'twilio',
});
 
await client.telephony.numbers.assign(provisioned.id, agent.id);
console.log(`${provisioned.phoneNumber} assigned to agent ${agent.id}`);

Step 5: Activate your agent and make a test call

Before an agent can receive calls, it must be activated:

curl -X POST "https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/activate" \
  -H "Authorization: Bearer vsnp_live_..."

Now call the provisioned phone number. The agent will answer, speak the first message, and respond to your conversation.

:::tip You can also trigger a test outbound call from the Console under Agents → [Agent Name] → Test Call, which places a call from the agent to any phone number you enter. :::

Step 6: Retrieve the conversation transcript

After the call ends, retrieve the full transcript with word-level timing:

curl "https://api.voisnap.ai/api/v1/conversations/conv_01HXDEF456/transcript" \
  -H "Authorization: Bearer vsnp_live_..."
transcript = client.conversations.transcript(conversation_id="conv_01HXDEF456")
for turn in transcript.turns:
    print(f"[{turn.speaker}] {turn.text}")
    # e.g.: [agent] Hello! Thanks for calling Acme support. I'm Aria...
    # e.g.: [user] Hi, I have a billing question
const transcript = await client.conversations.transcript('conv_01HXDEF456');
for (const turn of transcript.turns) {
  console.log(`[${turn.speaker}] ${turn.text}`);
}

Response:

{
  "conversationId": "conv_01HXDEF456",
  "agentId": "agt_01HXK8Z3MNPQRS",
  "duration": 87,
  "turns": [
    {
      "id": "turn_01",
      "speaker": "agent",
      "text": "Hello! Thanks for calling Acme support. I'm Aria — how can I help you today?",
      "startTime": 0.0,
      "endTime": 4.2,
      "words": [
        { "word": "Hello!", "startTime": 0.0, "endTime": 0.4, "confidence": 0.99 },
        { "word": "Thanks", "startTime": 0.5, "endTime": 0.8, "confidence": 0.98 }
      ]
    },
    {
      "id": "turn_02",
      "speaker": "user",
      "text": "Hi, I have a billing question about my last invoice.",
      "startTime": 4.8,
      "endTime": 7.3,
      "words": []
    }
  ]
}

Next steps

Previous

Introduction

Next

Authentication

On this page