Skip to main content

Getting Started

This guide walks through the initial setup of Virsyn Voice AI for a new agency.

Prerequisites​

  • A Virsyn account with an agency created
  • An Ultravox API key
  • A Telnyx account with API v2 key, public key, and account SID

Step 1: Save Ultravox API Key​

Store your Ultravox API key to enable agent management and call processing.

POST /functions/v1/save-ultravox-integration
Authorization: Bearer <jwt>

{
  "api_key": "your-ultravox-api-key"
}

The key is validated against the Ultravox API before being encrypted and stored. See Save Ultravox Integration.

Step 2: Save Telnyx Credentials​

Store your Telnyx credentials to enable telephony features.

POST /functions/v1/store-telnyx-credentials
Authorization: Bearer <jwt>

{
  "api_key": "your-telnyx-api-key",
  "api_key_public": "your-telnyx-public-key",
  "account_sid": "your-telnyx-account-sid"
}

All three values are encrypted before storage. See Store Telnyx Credentials.

Step 3: Provision Telephony​

Run the provisioning workflow to create the Telnyx-Ultravox bridge.

POST /functions/v1/provision-telephony
Authorization: Bearer <jwt>

This creates:

  1. A Telnyx Call Control Application with webhook URLs pointing to your agency's webhook endpoint
  2. A Telnyx Outbound Voice Profile linked to the application
  3. Imports Telnyx SIP credentials into Ultravox

See Provision Telephony.

Step 4: Create Your First Agent​

Create an AI voice agent with a system prompt and voice.

POST /functions/v1/agents-create
Authorization: Bearer <jwt>

{
  "name": "Reception Agent",
  "system_prompt": "You are a helpful receptionist...",
  "voice": "terrence",
  "language_hint": "en",
  "first_speaker_text": "Hello, how can I help you today?",
  "recording_enabled": true
}

See Create Agent.

Step 5: Purchase a Phone Number​

Search for and purchase a phone number.

# Search for available numbers
GET /functions/v1/phone-numbers-search?country_code=US&area_code=312
Authorization: Bearer <jwt>

# Purchase a number from the results
POST /functions/v1/phone-numbers-purchase
Authorization: Bearer <jwt>

{
  "phone_number": "+13125551234"
}

See Search Phone Numbers and Purchase Phone Numbers.

Step 6: Assign the Number to Your Agent​

Link the phone number to your agent so inbound calls are routed to it.

POST /functions/v1/phone-numbers-assign
Authorization: Bearer <jwt>

{
  "phone_number_id": "<phone-number-uuid>",
  "agent_id": "<agent-mapping-uuid>"
}

See Assign Phone Numbers.

Next Steps​