ConversaLabs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Atomic conversation assignment API

Open in
View as Markdown Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Sep 1, 2026

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