Get Ultravox Agents

Fetches the complete list of agents from the Ultravox API (with pagination), retrieves each agent's full configuration details (including callTemplate), and merges the results with existing local agent mappings. Also returns the agency's available clients and campaigns for mapping dropdown population. This endpoint powers the "Sync Ultravox Agents" dialog.

Endpoint

Property	Value
Function Name	get-ultravox-agents
HTTP Method	GET
Authentication	Supabase JWT (Bearer token in Authorization header)
Required Role	Any authenticated agency user

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer <supabase_jwt>

Query Parameters

None.

Response

Success (200)

{
  "agents": [
    {
      "ultravox_agent_id": "agent-uuid-123",
      "name": "Sales Bot Alpha",
      "created": "2025-01-10T08:00:00Z",
      "system_prompt": "You are a helpful sales assistant...",
      "voice": "lily",
      "temperature": 0.4,
      "language_hint": "en",
      "recording_enabled": true,
      "mapping": {
        "id": "mapping-uuid",
        "client_id": "client-uuid",
        "client_name": "Acme Corp",
        "campaign_id": "campaign-uuid",
        "campaign_name": "Q1 Outreach",
        "campaign_type": "sdr"
      }
    },
    {
      "ultravox_agent_id": "agent-uuid-456",
      "name": "Support Bot Beta",
      "created": "2025-02-01T12:00:00Z",
      "system_prompt": null,
      "voice": null,
      "temperature": 0.4,
      "language_hint": "en",
      "recording_enabled": true,
      "mapping": null
    }
  ],
  "clients": [
    { "id": "client-uuid", "name": "Acme Corp" }
  ],
  "campaigns": [
    { "id": "campaign-uuid", "name": "Q1 Outreach", "type": "sdr", "client_id": "client-uuid" }
  ],
  "total": 2
}

The mapping field is null for agents that have not yet been mapped to a local client and campaign.

Error Responses

Status	Condition
400	Ultravox API key is not configured for the agency
401	Missing or invalid Authorization header / JWT token
403	Authenticated user is not associated with an agency
500	Failed to retrieve agency credentials or unexpected server error
502	Ultravox API returned an error during agent list or detail fetch

Behavior

• Handles CORS preflight (OPTIONS) requests.
• Validates the JWT token via supabase.auth.getUser().
• Looks up the user's agency_id from the users table.
• Retrieves the agency's decrypted Ultravox API key via get_agency_credentials RPC.
• Fetches all agents from Ultravox by paginating through GET /api/agents?limit=100 until no next URL is returned.
• Fetches full details for each agent via GET /api/agents/{agentId} in parallel (Promise.all) to obtain the complete callTemplate configuration.
• Loads local data:
  • Existing agent_mappings for the agency (with joined clients and campaigns data).
  • Available clients for the agency, ordered by name.
  • Available campaigns for the agency, ordered by name.
• Merges Ultravox agent data with local mappings, extracting key fields from each agent's callTemplate:
  • system_prompt (from callTemplate.systemPrompt)
  • voice (from callTemplate.voice)
  • temperature (from callTemplate.temperature, default 0.4)
  • language_hint (from callTemplate.languageHint, default "en")
  • recording_enabled (from callTemplate.recordingEnabled, default true)

Database Tables / RPCs

Table / RPC	Operation	Description
users	Read	Fetches agency_id for the authenticated user
get_agency_credentials (RPC)	Read	Retrieves the decrypted Ultravox API key
agent_mappings	Read	Fetches existing Ultravox-to-client/campaign mappings (with joined clients and campaigns)
clients	Read	Lists available clients for the agency
campaigns	Read	Lists available campaigns for the agency

External APIs

API	Method	Endpoint	Description
Ultravox	GET	/api/agents?limit=100	Lists all agents with pagination
Ultravox	GET	/api/agents/{agentId}	Fetches full agent details including callTemplate

Related Functions

• save-agent-mapping -- Saves agent-to-client/campaign mappings created from the data returned by this function
• get-integration-status -- Reports whether the Ultravox API key is configured (prerequisite for this function)