# Teams

> Manage teams for chat routing and agent assignment

Source: https://docs.soosh.io/reference/api/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`

### Response

```json
{
  "status": "success",
  "data": {
    "teams": [
      {
        "id": "uuid",
        "name": "Sales Team",
        "description": "Handles sales inquiries",
        "assignment_strategy": "round_robin",
        "is_active": true,
        "member_count": 5,
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}
```

> **Note:** Admins see all teams. Managers and agents only see teams they are members of.

## Get Team

Get details of a specific team.

`GET /api/teams/{id}`

### Response

```json
{
  "status": "success",
  "data": {
    "team": {
      "id": "uuid",
      "name": "Sales Team",
      "description": "Handles sales inquiries",
      "assignment_strategy": "round_robin",
      "is_active": true,
      "member_count": 5,
      "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

```json
{
  "name": "Support Team",
  "description": "Handles customer support inquiries",
  "assignment_strategy": "load_balanced",
  "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

```json
{
  "status": "success",
  "data": {
    "team": {
      "id": "uuid",
      "name": "Support Team",
      "description": "Handles customer support inquiries",
      "assignment_strategy": "load_balanced",
      "is_active": true,
      "member_count": 0,
      "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

```json
{
  "name": "Support Team",
  "description": "Updated description",
  "assignment_strategy": "manual",
  "is_active": true
}
```

## Delete Team

Delete a team. Requires admin role.

`DELETE /api/teams/{id}`

> **Careful:** Deleting a team will remove all team memberships. Active transfers in the team queue will remain but will no longer be associated with the team.

## List Team Members

Get all members of a team.

`GET /api/teams/{id}/members`

### Response

```json
{
  "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

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

### Response

```json
{
  "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/{member_user_id}`

## Team-Based Transfers

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

`POST /api/chatbot/transfers`

### Request Body

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

When a transfer is created with a `team_id`:
1. The team's assignment strategy is applied
2. For `round_robin` or `load_balanced`, the transfer is auto-assigned to an available team member
3. 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

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

> **Tip:** Use teams to organize your support structure. For example, create separate teams for Sales, Support, and Billing, each with their own assignment strategy optimized for their workflow.