API de atribuição atômica de conversas

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

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

{
  "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.