Assign Agent

Updates only the local agent_mappings fields for organizational assignment of agents to clients and campaigns. This function does not communicate with the Ultravox API -- it is purely a local database operation. Supports both single assignments and batch assignments via an array.

Endpoint

Property	Value
Function Name	agents-assign
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner or agency_admin

Request

Headers

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

Body (Single Assignment)

Field	Type	Required	Description
agent_id	string	Yes	The Ultravox agent ID to assign.
client_id	string | null	No	Client UUID to assign. Set to null to clear.
campaign_id	string | null	No	Campaign UUID to assign. Set to null to clear.
default_direction	"inbound" | "outbound" | null	No	Default call direction. Set to null to clear.

Body (Batch Assignment)

{
  "assignments": [
    {
      "agent_id": "uv-agent-abc123",
      "client_id": "uuid-of-client",
      "campaign_id": "uuid-of-campaign",
      "default_direction": "outbound"
    },
    {
      "agent_id": "uv-agent-def456",
      "client_id": null,
      "campaign_id": null
    }
  ]
}

If the body contains an assignments array, each element is processed individually. If no assignments array is present, the body itself is treated as a single assignment.

Response

Success (200)

{
  "success": true,
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "results": [
    {
      "agent_id": "uv-agent-abc123",
      "success": true,
      "mapping_id": "uuid-of-mapping"
    },
    {
      "agent_id": "uv-agent-def456",
      "success": true,
      "mapping_id": "uuid-of-mapping-2"
    }
  ]
}

The top-level success field is true only when all assignments succeed (i.e., failed is 0).

Partial Failure (200)

When some assignments fail, the response still returns 200 but success is false:

{
  "success": false,
  "summary": {
    "total": 2,
    "successful": 1,
    "failed": 1
  },
  "results": [
    {
      "agent_id": "uv-agent-abc123",
      "success": true,
      "mapping_id": "uuid-of-mapping"
    },
    {
      "agent_id": "uv-agent-def456",
      "success": false,
      "error": "Invalid client_id"
    }
  ]
}

Error Responses

Status	Condition
400	No assignments provided (empty array)
401	Missing or invalid authorization header
403	User is not associated with an agency
403	User role is not agency_owner or agency_admin
405	HTTP method is not POST
500	Unexpected server error

Individual assignment errors are reported in the results array rather than as HTTP errors. Per-assignment validation errors include:

Error Message	Condition
agent_id is required	Assignment is missing the agent_id field
Invalid client_id	client_id does not belong to the agency
Invalid campaign_id	campaign_id does not belong to the agency
Campaign does not belong to the specified client	campaign_id is provided with a client_id but the campaign belongs to a different client

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency with the agency_owner or agency_admin role.
• Parses the request body. If body.assignments is an array, uses it; otherwise wraps the body itself as a single-element array.
• Pre-fetches all clients and campaigns for the agency to build validation lookup structures (a Set of client IDs and a Map of campaign IDs to their client IDs).
• Iterates through each assignment and validates:
  • agent_id is present.
  • client_id belongs to the agency (if provided and non-null).
  • campaign_id belongs to the agency (if provided and non-null).
  • If both client_id and campaign_id are provided, the campaign belongs to the specified client.
• For each valid assignment, checks if a local agent_mappings record already exists:
  • If mapping exists: Updates the existing record with the provided fields and a new updated_at timestamp. Only fields explicitly present in the assignment (including null for clearing) are updated.
  • If no mapping exists: Creates a new agent_mappings record with managed_by_virsyn set to false (since the agent was not created through Virsyn).
• Collects results for all assignments and returns a summary with success/failure counts.

Database Tables

Table	Operation	Description
users	Read	Fetches user profile to determine agency_id and role
clients	Read	Fetches all agency clients for validation
campaigns	Read	Fetches all agency campaigns for validation (including client_id for cross-reference)
agent_mappings	Read	Checks for existing mapping per agent
agent_mappings	Update	Updates existing mapping with assignment data
agent_mappings	Insert	Creates new mapping for agents without one

External APIs

None. This function operates entirely on the local database.

Related Functions

• List Agents -- List all agents (returns available clients and campaigns for dropdowns)
• Update Agent -- Update agent configuration (also supports client/campaign assignment alongside Ultravox config changes)
• Sync Agents -- Import agents from Ultravox and create local mappings