Save Agent Mapping

Creates or updates mappings that associate Ultravox agents with local clients and campaigns. Mappings are upserted on the composite key of (agency_id, ultravox_agent_id), so re-submitting a mapping for the same agent will update the existing record. Only users with the agency_owner or agency_admin role can modify mappings.

Endpoint

Property	Value
Function Name	save-agent-mapping
HTTP Method	POST
Authentication	Supabase JWT (Bearer token in Authorization header)
Required Role	agency_owner or agency_admin

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer <supabase_jwt>
Content-Type	Yes	application/json

Body

Field	Type	Required	Description
mappings	array	Yes	Array of mapping objects to upsert
mappings[].ultravox_agent_id	string	Yes	The Ultravox agent ID to map
mappings[].ultravox_agent_name	string	No	Display name of the Ultravox agent (stored for reference)
mappings[].client_id	string (UUID)	No	Local client ID to associate with the agent. Pass null to clear.
mappings[].campaign_id	string (UUID)	No	Local campaign ID to associate with the agent. Pass null to clear.

{
  "mappings": [
    {
      "ultravox_agent_id": "agent-uuid-123",
      "ultravox_agent_name": "Sales Bot Alpha",
      "client_id": "client-uuid",
      "campaign_id": "campaign-uuid"
    },
    {
      "ultravox_agent_id": "agent-uuid-456",
      "ultravox_agent_name": "Support Bot Beta",
      "client_id": null,
      "campaign_id": null
    }
  ]
}

Response

Success (200)

{
  "results": [
    {
      "ultravox_agent_id": "agent-uuid-123",
      "success": true,
      "id": "mapping-record-uuid"
    },
    {
      "ultravox_agent_id": "agent-uuid-456",
      "success": true,
      "id": "mapping-record-uuid-2"
    }
  ]
}

Partial Failure (200)

Individual mapping failures are reported inline without failing the entire request:

{
  "results": [
    {
      "ultravox_agent_id": "agent-uuid-123",
      "success": true,
      "id": "mapping-record-uuid"
    },
    {
      "ultravox_agent_id": null,
      "error": "Missing ultravox_agent_id"
    }
  ]
}

Error Responses

Status	Condition
400	mappings field is missing or is not an array
401	Missing or invalid Authorization header / JWT token
403	Authenticated user is not associated with an agency
403	User's role is not agency_owner or agency_admin
500	Unexpected server error

Behavior

• Handles CORS preflight (OPTIONS) requests.
• Validates the JWT token via supabase.auth.getUser().
• Looks up the user's agency_id and role from the users table.
• Checks that the user's role is agency_owner or agency_admin; returns 403 if not.
• Validates that the mappings request field is an array.
• Iterates through each mapping object:
  • Skips entries missing ultravox_agent_id (records an error in results).
  • Performs an upsert on the agent_mappings table with conflict resolution on (agency_id, ultravox_agent_id).
  • The agency_id is always set to the authenticated user's agency (cannot map agents for other agencies).
• Returns per-mapping results indicating success (with the record id) or failure (with an error message).

Database Tables

Table	Operation	Description
users	Read	Fetches agency_id and role for the authenticated user
agent_mappings	Write (Upsert)	Creates or updates agent-to-client/campaign mappings. Conflict key: (agency_id, ultravox_agent_id)

External APIs

None.

Related Functions

• get-ultravox-agents -- Fetches agent data and existing mappings that feed into this function's UI
• get-integration-status -- Reports whether the agency's integration is configured