## Visão geral

A API de atribuição atômica altera responsável e equipe em uma única transação bloqueada. Use
`PUT /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignment` quando uma integração
distribuir conversas, especialmente em lotes. A resposta sempre mostra o estado realmente persistido.

## Pré-requisitos

- Um `api_access_token` com acesso à inbox da conversa.
- IDs pertencentes à mesma conta. Um atendente enviado com uma equipe precisa ser membro dela.

## Passo a passo

1. Localize o `conversation_id` exibido pela API.
2. Envie `assignee_id`, `team_id` ou ambos ao endpoint atômico.
3. Use `assignee_type: "AgentBot"` quando o ID for de um Robô de IA; o padrão é `User`.
4. Leia `assignee`, `assignee_type` e `team` da resposta em vez de presumir o estado final.

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

## Configurações & opções

- Campo omitido mantém o valor atual; `null` limpa a dimensão. `team_id: 0` também limpa a equipe.
- `assignee_id: null` remove atendente ou Robô de IA.
- IDs desconhecidos ou de outra conta retornam `422`, nunca desatribuem silenciosamente.
- Repetir o mesmo estado é idempotente e não cria outra atividade na timeline.
- O `POST .../assignments` legado continua aceito. Se receber responsável e equipe juntos, mantém a
  precedência histórica do responsável, ignora a equipe e devolve o header HTTP `Warning`.
- O PATCH genérico da conversa não altera atribuições e devolve
  `assignment_parameters_not_supported` quando recebe esses campos.

## Casos de uso

- Distribuir milhares de leads entre uma equipe sem expor estados parciais.
- Trocar um atendente por um Robô de IA mantendo a equipe.
- Remover a equipe sem alterar o responsável atual.

## Dicas, limites e boas práticas

- Prefira uma operação atômica a duas chamadas sequenciais de atribuição.
- Aplique backoff em falhas transitórias; corrija erros `422` antes de repetir.
- Em cargas grandes, monitore latência HTTP e as filas `high`, `scheduled_jobs` e `conversation_activity`.

## Solução de problemas

- **`assignee_not_in_team`**: adicione o atendente à equipe ou envie uma combinação válida.
- **`assignee_not_found` / `team_not_found`**: confirme a conta e o ID informado.
- **`assignment_parameters_not_supported`**: troque o PATCH genérico pelo PUT de atribuição.

## Veja também

- [Referência da API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)
- [Atribuição, status, prioridade e labels](/hc/ajuda/articles/conversations-atribuicao-status-prioridade-labels-pt-br)