API de asignación atómica de conversaciones

Visión general

La API de asignación atómica modifica el responsable y el equipo en una única transacción bloqueada. Usa PUT /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignment cuando una integración distribuya conversaciones, especialmente en lotes. La respuesta siempre muestra el estado persistido.

Requisitos previos

Un api_access_token con acceso a la bandeja de la conversación.
IDs de la misma cuenta. Un agente humano enviado con un equipo debe pertenecer a él.

Paso a paso

Localiza el conversation_id expuesto por la API.
Envía assignee_id, team_id o ambos al endpoint atómico.
Usa assignee_type: "AgentBot" cuando el ID sea de un Robot de IA; el valor predeterminado es User.
Lee assignee, assignee_type y team de la respuesta en vez de asumir el estado final.

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

Configuración y opciones

Un campo omitido conserva el valor actual; null limpia esa dimensión. team_id: 0 también elimina el equipo.
assignee_id: null elimina al agente o Robot de IA.
Los IDs desconocidos o de otra cuenta devuelven 422; nunca desasignan silenciosamente.
Repetir el mismo estado es idempotente y no crea otra actividad en la cronología.
El POST .../assignments legado sigue disponible. Si recibe ambas dimensiones, conserva la precedencia histórica del responsable, ignora el equipo y devuelve un header HTTP Warning.
El PATCH genérico de la conversación no modifica asignaciones y devuelve assignment_parameters_not_supported cuando recibe esos campos.

Casos de uso

Distribuir miles de leads entre un equipo sin exponer estados parciales.
Sustituir un agente por un Robot de IA manteniendo el equipo.
Eliminar el equipo sin cambiar el responsable actual.

Consejos, límites y buenas prácticas

Prefiere una operación atómica a dos llamadas secuenciales de asignación.
Aplica backoff ante fallos transitorios; corrige los errores 422 antes de repetir.
Con carga masiva, supervisa la latencia HTTP y las colas high, scheduled_jobs y conversation_activity.

Solución de problemas

assignee_not_in_team: añade el agente al equipo o envía una combinación válida.
assignee_not_found / team_not_found: comprueba la cuenta y el ID indicado.
assignment_parameters_not_supported: sustituye el PATCH genérico por el PUT de asignación.