## Overview

The atomic assignment API changes the responsible party and team in one locked transaction. Use
`PUT /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignment` when an integration
distributes conversations, especially in batches. The response always reports the state actually persisted.

## Prerequisites

- An `api_access_token` with access to the conversation inbox.
- IDs from the same account. A human agent sent with a team must belong to that team.

## Step by step

1. Find the `conversation_id` exposed by the API.
2. Send `assignee_id`, `team_id`, or both to the atomic endpoint.
3. Use `assignee_type: "AgentBot"` when the ID belongs to an AI Robot; the default is `User`.
4. Read `assignee`, `assignee_type`, and `team` from the response instead of assuming the final state.

```json
{
  "assignee_id": 42,
  "assignee_type": "User",
  "team_id": 7
}
```

## Settings & options

- An omitted field keeps its current value; `null` clears that dimension. `team_id: 0` also clears the team.
- `assignee_id: null` removes either a human agent or an AI Robot.
- Unknown or cross-account IDs return `422`; they never silently unassign the conversation.
- Repeating the same state is idempotent and does not create another timeline activity.
- The legacy `POST .../assignments` remains supported. When it receives both dimensions, the assignee
  keeps historical precedence, the team is ignored, and the response includes an HTTP `Warning` header.
- The generic conversation PATCH does not update assignments and returns
  `assignment_parameters_not_supported` for those fields.

## Use cases

- Distribute thousands of leads across a team without exposing partial states.
- Replace a human agent with an AI Robot while preserving the team.
- Clear the team without changing the current responsible party.

## Tips, limits & best practices

- Prefer one atomic operation over two sequential assignment calls.
- Back off on transient failures; correct `422` input errors before retrying.
- Under bulk load, monitor HTTP latency and the `high`, `scheduled_jobs`, and `conversation_activity` queues.

## Troubleshooting

- **`assignee_not_in_team`**: add the agent to the team or send a valid combination.
- **`assignee_not_found` / `team_not_found`**: check the account and supplied ID.
- **`assignment_parameters_not_supported`**: replace the generic PATCH with the assignment PUT.

## See also

- [API Reference (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-en)
- [Assignment, status, priority and labels](/hc/ajuda/articles/conversations-atribuicao-status-prioridade-labels-en)