Transferir Conversa
POST/external/v1/conversations/:id/transferAtribui 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ê envia | O que acontece |
|---|---|
só user_id | O usuário vira o responsável. O setor da conversa não muda. |
só sector_id | A conversa vai para o setor e o rodízio do setor escolhe o responsável. A resposta diz quem foi escolhido. |
sector_id + user_id | A 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string (UUID) | Sim | Identificador único da conversa |
Corpo da Requisição
Pelo menos um dos dois campos é obrigatório.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
sector_id | string (UUID) | Não* | Setor de destino (veja Listar Setores). Precisa estar ativo. |
user_id | string (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
# 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"
}'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}`);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:
{ "user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" }Mover para um setor e atribuir um usuário específico (sem rodízio):
{
"sector_id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}Resposta
Só setor — o rodízio escolheu o responsável:
{
"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:
{
"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
| Campo | Tipo | Descrição |
|---|---|---|
conversation_id | string | A conversa que foi transferida |
sector | object | null | Setor em que a conversa está depois da chamada (id, name). null só quando a conversa nunca teve setor e você enviou só user_id |
assignee | object | null | Usuário agora responsável (id, name, email). null quando a fila do rodízio estava vazia |
assigned_via | string | null | Como 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_empty | boolean | true quando o rodízio foi usado e o setor não tinha ninguém para receber |
previous.sector_id | string | null | Setor da conversa antes da chamada |
previous.assigned_user_id | string | null | Responsá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
| Status | Código | Descrição |
|---|---|---|
| 400 | VALIDATION_ERROR | Nem sector_id nem user_id foram enviados, ou um id não é UUID |
| 400 | SECTOR_INACTIVE | O setor de destino está inativo e não pode receber conversas |
| 403 | INSUFFICIENT_PERMISSIONS | A API key não tem a permissão conversations:write |
| 403 | ASSIGNEE_NOT_IN_SECTOR | O user_id não é do setor de destino |
| 404 | NOT_FOUND | Conversa, 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.