Atendentes e times

Do lado de dentro do atendimento há duas entidades: o atendente, que é uma pessoa da equipe do seu cliente, e o time, que agrupa atendentes. As duas existem na API para uma única finalidade prática — dizer quem cuida de uma conversa.

Atendente não é contato

É a confusão mais cara de cometer aqui, porque as duas entidades descrevem pessoas. O contato é quem está do outro lado — o cliente final, que chega por um canal. O atendente é quem está do lado de dentro: tem login no painel, aparece na fila e recebe conversas.

Elas nunca se misturam: um atendente não pode ser destinatário de mensagem, e um contato não pode receber uma conversa atribuída. Os prefixos deixam isso visível — usr_… e cnt_… — e mandar um no lugar do outro é 404, não silêncio.

Atendentes

A API pública lê atendentes; ela não os cria. Quem convida, remove e muda papel é o painel, e há um motivo: criar atendente é criar acesso à conta do seu cliente, e isso passa por convite, aceite e verificação de e-mail — um fluxo que não cabe numa chamada de API e cuja ausência de fricção seria uma falha de segurança, não uma conveniência.

curl "https://api.amivu.com.br/v1/users?limit=20" \
  -H "Authorization: Bearer $AMIVU_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "usr_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
      "name": "Ana Souza",
      "email": "ana@empresa.com.br",
      "role": "agent",
      "created_at": "2026-08-26T20:10:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

Times

Um time agrupa atendentes por assunto — Suporte, Financeiro, Vendas. Atribuir uma conversa a um time, em vez de a uma pessoa, é o que evita o buraco mais comum de uma operação: conversa parada porque quem a recebeu entrou de férias.

curl https://api.amivu.com.br/v1/teams \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Suporte" }'

GET /v1/teams/{team_id}/users devolve quem está no time. É a chamada que responde “para quem isso pode ir?” antes de você atribuir.

Atribuir uma conversa

A atribuição não é um campo: é uma ação, com rota própria. Ela aceita user_id ou team_id — exatamente um dos dois.

curl -X POST https://api.amivu.com.br/v1/conversations/conv_01K7.../assign \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "team_id": "team_01K7ZFA5X8Q2M4N6P8R0T2V4W6" }'

A conversa passa a pending, e o evento conversation.assigned sai para quem o assinar. Para soltar, POST .../unassign.

O que a API não faz

• Não cria nem remove atendente. Convite e desligamento são do painel, pelo motivo acima.
• Não muda papel nem permissão. Quem pode o quê é decisão administrativa, e uma chave de integração não deveria conseguir se promover.
• Não gerencia quem está em qual time. A API lê a composição; alterar é no painel.
• Não expõe disponibilidade nem carga. Distribuição automática é regra de produto, e vive nas automações — não numa chamada de fora.

Veja também Conversas e Eventos.