Skip to content

Transferir Conversa ​

POST /external/v1/conversations/:id/transfer

Atribui uma conversa a um usuário, move para um setor, ou as duas coisas. É a mesma ação do seletor de transferência do inbox: setor e responsável são gravados juntos, um evento transferred entra na linha do tempo da conversa, o novo responsável é avisado e o inbox atualiza em tempo real.

O corpo da requisição decide o que acontece:

Você enviaO que acontece
só user_idO usuário vira o responsável. O setor da conversa não muda.
só sector_idA conversa vai para o setor e o rodízio do setor escolhe o responsável. A resposta diz quem foi escolhido.
sector_id + user_idA conversa vai para o setor e aquele usuário vira o responsável. O rodízio não é consultado e a fila não avança.

Autenticação ​

Requer permissão conversations:write. Esse escopo só pode ser concedido por um administrador da conta.

A ação fica registrada na linha do tempo em nome do usuário que criou a API key.

Parâmetros de Caminho ​

ParâmetroTipoObrigatórioDescrição
idstring (UUID)SimIdentificador único da conversa

Corpo da Requisição ​

Pelo menos um dos dois campos é obrigatório.

CampoTipoObrigatórioDescrição
sector_idstring (UUID)Não*Setor de destino (veja Listar Setores). Precisa estar ativo.
user_idstring (UUID)Não*Usuário que vira o responsável (veja Listar Usuários). Precisa estar ativo e ser do setor de destino.

* Envie sector_id, user_id ou os dois.

Regras ​

Quem pode receber ​

O user_id precisa ser alguém que o setor configurou para atender, exatamente como está em Configurações › Setores:

  • usuários que pertencem ao setor e estão na fila de distribuição dele, ou
  • supervisores do setor.

O usuário é conferido contra o setor de destino: o sector_id enviado ou, quando você envia só user_id, o setor em que a conversa já está. Qualquer outra pessoa é recusada com 403 ASSIGNEE_NOT_IN_SECTOR — inclusive administradores da conta que não são daquele setor.

Quando você envia só user_id e a conversa ainda não tem setor, o usuário é atribuído e a conversa continua sem setor.

Rodízio (só sector_id) ​

O responsável é escolhido pela mesma fila que distribui as transferências dos funcionários de IA para aquele setor:

  • a fila é formada pelos usuários ativos do setor, menos os que foram tirados da distribuição;
  • ela continua a partir da última pessoa que recebeu uma conversa naquele setor, e esta chamada faz a fila avançar;
  • se o setor está com "não distribuir para quem está offline" ligado, quem está offline é pulado. Quem está ausente continua recebendo. Se ninguém estiver conectado, o filtro é ignorado e a fila roda normalmente.

Se a fila estiver vazia (o setor não tem ninguém na distribuição), a transferência acontece mesmo assim: a conversa vai para o setor sem responsável, e a resposta vem com assignee: null e queue_empty: true. Ela cai na caixa do setor, e quem pegar primeiro assume.

O que não muda ​

  • O status da conversa e o funcionário de IA não são alterados. Se um funcionário de IA está atendendo a conversa, ele continua respondendo.
  • O dono da oportunidade ligada à conversa não é alterado.

Requisição ​

bash
# Move para um setor e deixa o rodízio escolher o responsável
curl --request POST \
  --url "https://app.getraze.com/external/v1/conversations/6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60/transfer" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Idempotency-Key: 7f1c2e9a-3b4d-4a6e-9c1f-2d3e4f5a6b7c" \
  --data '{
    "sector_id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d"
  }'
javascript
const axios = require('axios');

const conversationId = '6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60';

const response = await axios.post(
  `https://app.getraze.com/external/v1/conversations/${conversationId}/transfer`,
  { sector_id: '0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d' },
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': '7f1c2e9a-3b4d-4a6e-9c1f-2d3e4f5a6b7c'
    }
  }
);

const { assignee, queue_empty } = response.data.data;
console.log(queue_empty ? 'Ninguém na fila' : `Atribuída a ${assignee.name}`);
python
import requests

conversation_id = '6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60'

response = requests.post(
    f'https://app.getraze.com/external/v1/conversations/{conversation_id}/transfer',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Idempotency-Key': '7f1c2e9a-3b4d-4a6e-9c1f-2d3e4f5a6b7c'
    },
    json={'sector_id': '0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d'}
)

print(response.json())

Outros corpos ​

Atribuir um usuário, mantendo o setor:

json
{ "user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" }

Mover para um setor e atribuir um usuário específico (sem rodízio):

json
{
  "sector_id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
  "user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}

Resposta ​

Só setor — o rodízio escolheu o responsável:

json
{
  "success": true,
  "data": {
    "conversation_id": "6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60",
    "sector": {
      "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
      "name": "Suporte"
    },
    "assignee": {
      "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "name": "Maria Silva",
      "email": "maria@empresa.com"
    },
    "assigned_via": "round_robin",
    "queue_empty": false,
    "previous": {
      "sector_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "assigned_user_id": null
    }
  }
}

Só setor — ninguém na fila:

json
{
  "success": true,
  "data": {
    "conversation_id": "6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60",
    "sector": {
      "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
      "name": "Suporte"
    },
    "assignee": null,
    "assigned_via": null,
    "queue_empty": true,
    "previous": {
      "sector_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "assigned_user_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
    }
  }
}

Campos da Resposta ​

CampoTipoDescrição
conversation_idstringA conversa que foi transferida
sectorobject | nullSetor em que a conversa está depois da chamada (id, name). null só quando a conversa nunca teve setor e você enviou só user_id
assigneeobject | nullUsuário agora responsável (id, name, email). null quando a fila do rodízio estava vazia
assigned_viastring | nullComo o responsável foi escolhido: manual (você enviou user_id) ou round_robin (a fila do setor escolheu). null quando não há responsável
queue_emptybooleantrue quando o rodízio foi usado e o setor não tinha ninguém para receber
previous.sector_idstring | nullSetor da conversa antes da chamada
previous.assigned_user_idstring | nullResponsável pela conversa antes da chamada

Idempotência ​

Só com sector_id, cada chamada bem-sucedida faz a fila do setor avançar. Se uma requisição der timeout e você repetir às cegas, a segunda chamada escolhe a próxima pessoa. Envie o header Idempotency-Key e reutilize-o na repetição: a resposta original é devolvida e a fila não avança de novo.

Erros ​

StatusCódigoDescrição
400VALIDATION_ERRORNem sector_id nem user_id foram enviados, ou um id não é UUID
400SECTOR_INACTIVEO setor de destino está inativo e não pode receber conversas
403INSUFFICIENT_PERMISSIONSA API key não tem a permissão conversations:write
403ASSIGNEE_NOT_IN_SECTORO user_id não é do setor de destino
404NOT_FOUNDConversa, setor ou usuário não encontrado nesta conta (usuário inativo também volta como não encontrado)

Quando a requisição é recusada nada é gravado: a conversa mantém setor e responsável, e a fila do rodízio não avança.

MCP ​

A mesma ação está disponível para clientes MCP na tool conversations_transfer, com suporte a dry_run: a simulação mostra quem o rodízio escolheria sem fazer a fila avançar.

GetRaze - AI-Powered Lead Generation