Create your first agent

This guide walks the fastest path to a working voice agent: create an agent with a prompt and a voice, configure its SIP registration, then make a test call and retrieve the transcript.

The examples use the Conversational AI base path https://api.simwood.com/convai/v1 and a Bearer API key. See Authentication for how keys and scopes work; the scopes used below are convai:read and convai:write.

You'll need an API key with convai:read and convai:write, and access to a SIP-capable PBX or SIP proxy that can route calls to the agent's registered address of record.

1. Choose a voice

Browse the voice catalogue to find a voice that fits your agent's persona. Listen to the preview URL before committing.

curl https://api.simwood.com/convai/v1/voices \
  -H "Authorization: Bearer sk_live_..."

Pick a voice from the response and note its id — you'll use it in the next step.

# Inspect a specific voice
curl https://api.simwood.com/convai/v1/voices/<voice-id> \
  -H "Authorization: Bearer sk_live_..."

2. Create the agent

Create an agent with a minimal configuration: a prompt, a voice, and sensible defaults for the other settings. You can refine the configuration later with PUT /agents/:id.

curl -X POST https://api.simwood.com/convai/v1/agents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first agent",
    "configuration": {
      "asr": {
        "keywords": []
      },
      "turn": {
        "timeout_seconds": 10,
        "silence_timeout_seconds": 3
      },
      "tts": {
        "voice_id": "<voice-id>",
        "settings": {
          "stability": 0.5,
          "similarity_boost": 0.75,
          "speed": 1.0
        }
      },
      "agent": {
        "first_message": "Hello, thanks for calling. How can I help you today?",
        "language": "en",
        "prompt": {
          "text": "You are a helpful assistant. Answer questions clearly and concisely. If you cannot help, say so politely and offer to transfer the caller.",
          "temperature": 0.5,
          "model": "gpt-4o"
        },
        "knowledge_base": [],
        "tools": []
      },
      "conversation": {
        "max_duration_seconds": 600
      }
    }
  }'

The response includes the agent's id — save it for the following steps.

3. Configure SIP registration

Register the agent to your PBX so it can receive calls. The PUT /agents/:id/sip-uac operation is an upsert — it creates or replaces the registration in one call.

curl -X PUT https://api.simwood.com/convai/v1/agents/<agent-id>/sip-uac \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sip_username": "agent-001",
    "sip_domain": "pbx.example.com",
    "sip_password": "your-sip-password"
  }'

The agent registers immediately. Confirm it is registered by checking your PBX's registration list — the agent's address of record will appear as agent-001@pbx.example.com (or whatever your sip_username@sip_domain resolves to).

If your registrar address differs from sip_domain, pass it explicitly as sip_registrar. See SIP UAC for the full set of fields.

4. Make a test call

Route a call to the agent's registered address from your PBX. The agent answers, says its first_message, and begins the conversation. End the call when you're done.

5. Retrieve the transcript

Once the call ends, the conversation record is available. List the agent's conversations to find it:

curl https://api.simwood.com/convai/v1/agents/<agent-id>/conversations \
  -H "Authorization: Bearer sk_live_..."

Retrieve the full transcript and analysis from the most recent conversation:

curl https://api.simwood.com/convai/v1/agents/<agent-id>/conversations/<conversation-id> \
  -H "Authorization: Bearer sk_live_..."

The transcript array contains each turn — who said what and when. If you defined analysis.data_collection on the agent, the extracted values appear in analysis.data_collection_results.

Next steps