Save Ultravox Integration

Validates an Ultravox API key (unless validation is skipped) and securely stores it in encrypted form for the authenticated agency. Returns a webhook URL for the agency after successful storage.

Endpoint

Property	Value
Function Name	save-ultravox-integration
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Body

Field	Type	Required	Description
api_key	string	Yes	The Ultravox API key to store
skip_validation	boolean	No	If true, skips the Ultravox API validation step. Defaults to false.

Response

Success (200)

{
  "success": true,
  "webhook_url": "https://<supabase-url>/functions/v1/webhook-ingest/<agency_id>/<webhook_secret>"
}

Error Responses

Status	Condition
400	API key is missing from the request body
400	API key is invalid (validation failed); includes hint to use skip_validation: true
401	Missing or invalid authorization header
403	User is not an agency user or is not an agency_owner
405	HTTP method is not POST
500	Failed to encrypt or store the API key

Behavior

• Authenticates the user via Supabase JWT and verifies they have the agency_owner role
• Extracts api_key and optional skip_validation from the request body
• Unless skip_validation is true, validates the key against GET https://api.ultravox.ai/api/calls?limit=1 using the X-API-Key header
• If validation fails, returns an error with a hint about using skip_validation: true (useful for accounts with no credits)
• Encrypts the API key using the encrypt_api_key RPC function
• Updates the agencies table with:
  • ultravox_api_key_encrypted: The encrypted key
  • ultravox_api_key_added_at: Current timestamp
  • ultravox_api_key_validated_at: Current timestamp (or null if validation was skipped)
• Retrieves the agency's webhook_secret and builds the webhook URL
• Returns the webhook URL for configuring external services

Database Tables Read/Written

Table	Operation	Purpose
users	Read	Verify user role and agency membership
agencies	Read	Retrieve webhook secret
agencies	Write	Store encrypted API key and timestamps

RPC Functions Called

Function	Purpose
encrypt_api_key	Encrypt the API key for secure storage

External APIs Called

API	Method	Endpoint	Purpose
Ultravox	GET	/api/calls?limit=1	Validate the API key (unless skip_validation is set)

Related Functions

• Validate Ultravox Key -- Validate a key without storing it
• Store Telnyx Credentials -- Store Telnyx API keys for the agency
• Provision Telephony -- Full telephony provisioning (requires both Ultravox and Telnyx keys)