Skip to content
Docs
Open Soosh
View as Markdown
ReferenceWorkspace

Teams

Manage teams for chat routing and agent assignment

DevelopersUpdated

Overview

Section titled “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

Section titled “List Teams”

Get all teams accessible to the current user.

GET/api/teams

Response

Section titled “Response”
{
  "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"
      }
    ]
  }
}

Get Team

Section titled “Get Team”

Get details of a specific team.

GET/api/teams/{id}

Response

Section titled “Response”
{
  "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

Section titled “Create Team”

Create a new team. Requires admin role.

POST/api/teams

Request Body

Section titled “Request Body”
{
  "name": "Support Team",
  "description": "Handles customer support inquiries",
  "assignment_strategy": "load_balanced",
  "is_active": true
}

Assignment Strategies

Section titled “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

Section titled “Response”
{
  "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

Section titled “Update Team”

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

PUT/api/teams/{id}

Request Body

Section titled “Request Body”
{
  "name": "Support Team",
  "description": "Updated description",
  "assignment_strategy": "manual",
  "is_active": true
}

Delete Team

Section titled “Delete Team”

Delete a team. Requires admin role.

DELETE/api/teams/{id}

List Team Members

Section titled “List Team Members”

Get all members of a team.

GET/api/teams/{id}/members

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "members": [
      {
        "id": "uuid",
        "user_id": "uuid",
        "full_name": "John Doe",
        "email": "[email protected]",
        "role": "agent",
        "is_available": true,
        "last_assigned_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Member Roles

Section titled “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

Section titled “Add Team Member”

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

POST/api/teams/{id}/members

Request Body

Section titled “Request Body”
{
  "user_id": "uuid",
  "role": "agent"
}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "member": {
      "id": "uuid",
      "user_id": "uuid",
      "full_name": "Jane Smith",
      "email": "[email protected]",
      "role": "agent",
      "is_available": true
    }
  }
}

Remove Team Member

Section titled “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

Section titled “Team-Based Transfers”

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

POST/api/chatbot/transfers

Request Body

Section titled “Request Body”
{
  "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

Section titled “Queue Counts”

The list transfers endpoint returns queue counts per team:

GET/api/chatbot/transfers?status=active

Response

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