Teams

Overview

The Teams API allows you to create and manage teams for organizing agents and routing chat transfers. Teams enable intelligent chat distribution based on assignment strategies.

List Teams

Get all teams accessible to the current user.

GET /api/teams

Query Parameters

Parameter	Type	Description
`search`	string	Filter by team name (case-insensitive)
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Items per page (default: 50)

Response

{
  "status": "success",
  "data": {
    "teams": [
      {
        "id": "uuid",
        "name": "Sales Team",
        "description": "Handles sales inquiries",
        "assignment_strategy": "round_robin",
        "per_agent_timeout_secs": 30,
        "is_active": true,
        "member_count": 5,
        "created_by_id": "uuid",
        "created_by_name": "Admin User",
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Get Team

Get details of a specific team.

GET /api/teams/{id}

Response

{
  "status": "success",
  "data": {
    "team": {
      "id": "uuid",
      "name": "Sales Team",
      "description": "Handles sales inquiries",
      "assignment_strategy": "round_robin",
      "per_agent_timeout_secs": 30,
      "is_active": true,
      "member_count": 5,
      "members": [
        {
          "id": "uuid",
          "user_id": "uuid",
          "full_name": "John Doe",
          "email": "john@example.com",
          "role": "agent",
          "is_available": true,
          "last_assigned_at": "2024-01-01T12:00:00Z"
        }
      ],
      "created_by_id": "uuid",
      "created_by_name": "Admin User",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  }
}

Create Team

Create a new team. Requires admin role.

POST /api/teams

Request Body

{
  "name": "Support Team",
  "description": "Handles customer support inquiries",
  "assignment_strategy": "load_balanced",
  "per_agent_timeout_secs": 30,
  "is_active": true
}

Assignment Strategies

Strategy	Description
`round_robin`	Distributes transfers evenly across available agents in order
`load_balanced`	Assigns to the agent with the fewest active transfers
`manual`	Transfers go to team queue for agents to manually pick

Response

{
  "status": "success",
  "data": {
    "team": {
      "id": "uuid",
      "name": "Support Team",
      "description": "Handles customer support inquiries",
      "assignment_strategy": "load_balanced",
      "per_agent_timeout_secs": 30,
      "is_active": true,
      "member_count": 0,
      "created_by_id": "uuid",
      "created_by_name": "Admin User",
      "created_at": "2024-01-01T12:00:00Z"
    }
  }
}

Update Team

Update team settings. Requires admin role or team manager role.

PUT /api/teams/{id}

Request Body

{
  "name": "Support Team",
  "description": "Updated description",
  "assignment_strategy": "manual",
  "per_agent_timeout_secs": 45,
  "is_active": true
}

Delete Team

Delete a team. Requires admin role.

DELETE /api/teams/{id}

List Team Members

Get all members of a team.

GET /api/teams/{id}/members

Response

{
  "status": "success",
  "data": {
    "members": [
      {
        "id": "uuid",
        "user_id": "uuid",
        "full_name": "John Doe",
        "email": "john@example.com",
        "role": "agent",
        "is_available": true,
        "last_assigned_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Member Roles

Role	Permissions
`manager`	Can manage team settings and members, view all team transfers
`agent`	Can pick and handle transfers from the team queue

Add Team Member

Add a user to a team. Requires admin role or team manager role.

POST /api/teams/{id}/members

Request Body

{
  "user_id": "uuid",
  "role": "agent"
}

Response

{
  "status": "success",
  "data": {
    "member": {
      "id": "uuid",
      "user_id": "uuid",
      "full_name": "Jane Smith",
      "email": "jane@example.com",
      "role": "agent",
      "is_available": true
    }
  }
}

Remove Team Member

Remove a user from a team. Requires admin role or team manager role.

DELETE /api/teams/{id}/members/{user_id}

Team-Based Transfers

When creating transfers via flows or the API, you can specify a team:

POST /api/chatbot/transfers

Request Body

{
  "contact_id": "uuid",
  "team_id": "uuid",
  "notes": "Customer needs help with order #12345"
}

When a transfer is created with a team_id:

The team’s assignment strategy is applied
For round_robin or load_balanced, the transfer is auto-assigned to an available team member
For manual, the transfer goes to the team queue

Queue Counts

The list transfers endpoint returns queue counts per team:

GET /api/chatbot/transfers?status=active

Response

{
  "status": "success",
  "data": {
    "transfers": [...],
    "general_queue_count": 3,
    "team_queue_counts": {
      "team-uuid-1": 5,
      "team-uuid-2": 2
    }
  }
}