Transfer Conversation
POST/external/v1/conversations/:id/transferAssigns a conversation to a user, moves it to a sector, or both. It is the same action as the transfer selector of the inbox: sector and assignee are written together, a transferred event is added to the conversation timeline, the new assignee is notified and the inbox updates in real time.
The request body decides what happens:
| You send | What happens |
|---|---|
user_id only | The user becomes the assignee. The sector of the conversation does not change. |
sector_id only | The conversation moves to the sector and the sector's round-robin picks the assignee. The response tells you who was picked. |
sector_id + user_id | The conversation moves to the sector and that user becomes the assignee. The round-robin is not consulted and its queue does not advance. |
Authentication
Requires conversations:write permission. This scope can only be granted by an account administrator.
The action is recorded in the timeline under the user who created the API key.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID) | Yes | The unique identifier of the conversation |
Request Body
At least one of the two fields is required.
| Field | Type | Required | Description |
|---|---|---|---|
sector_id | string (UUID) | No* | Target sector (see List Sectors). Must be active. |
user_id | string (UUID) | No* | User who becomes the assignee (see List Users). Must be active and a member of the target sector. |
* Send sector_id, user_id or both.
Rules
Who can be assigned
user_id must be someone the sector is configured to serve with, exactly as set in Settings › Sectors:
- users that belong to the sector and are in its distribution queue, or
- supervisors of the sector.
The user is checked against the target sector: the sector_id you sent or, when you send only user_id, the sector the conversation is already in. Anyone else is refused with 403 ASSIGNEE_NOT_IN_SECTOR — including account administrators that are not members of that sector.
When you send only user_id and the conversation has no sector yet, the user is assigned and the conversation stays without a sector.
Round-robin (sector_id only)
The assignee is picked by the same queue that distributes the AI employee hand-offs to that sector:
- the queue is made of the active users of the sector, minus the ones removed from distribution;
- it continues from the last person who received a conversation in that sector, and this call advances it;
- if the sector has "do not distribute to offline users" enabled, offline users are skipped. Away users still receive. If nobody is connected, the filter is dropped and the queue runs normally.
If the queue is empty (the sector has nobody in distribution), the transfer still happens: the conversation moves to the sector with no assignee, and the response comes with assignee: null and queue_empty: true. It lands in the sector inbox, where the first person to take it becomes the assignee.
What does not change
- The conversation status and the AI employee are not touched. If an AI employee is handling the conversation it keeps answering.
- The owner of the linked opportunity is not changed.
Request
# Move to a sector and let its round-robin pick the assignee
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 ? 'No one in the queue' : `Assigned to ${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())Other request bodies
Assign a user, keeping the sector:
{ "user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" }Move to a sector and assign a specific user (no round-robin):
{
"sector_id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"user_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}Response
Sector only — the round-robin picked the assignee:
{
"success": true,
"data": {
"conversation_id": "6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60",
"sector": {
"id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"name": "Support"
},
"assignee": {
"id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"name": "Maria Silva",
"email": "maria@company.com"
},
"assigned_via": "round_robin",
"queue_empty": false,
"previous": {
"sector_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"assigned_user_id": null
}
}
}Sector only — nobody in the queue:
{
"success": true,
"data": {
"conversation_id": "6f1d2c3b-4a5e-4f60-8a71-9b2c3d4e5f60",
"sector": {
"id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"name": "Support"
},
"assignee": null,
"assigned_via": null,
"queue_empty": true,
"previous": {
"sector_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"assigned_user_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
}
}
}Response Fields
| Field | Type | Description |
|---|---|---|
conversation_id | string | The conversation that was transferred |
sector | object | null | Sector the conversation is in after the call (id, name). null only when the conversation never had a sector and you sent only user_id |
assignee | object | null | User now responsible (id, name, email). null when the round-robin queue was empty |
assigned_via | string | null | How the assignee was chosen: manual (you sent user_id) or round_robin (the sector queue picked). null when there is no assignee |
queue_empty | boolean | true when the round-robin was used and the sector had nobody to receive |
previous.sector_id | string | null | Sector of the conversation before the call |
previous.assigned_user_id | string | null | Assignee of the conversation before the call |
Idempotency
With sector_id only, every successful call advances the sector queue. If a request times out and you retry it blindly, the second call picks the next person. Send an Idempotency-Key header and reuse it on the retry: the original response is replayed and the queue is not advanced again.
Errors
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Neither sector_id nor user_id was sent, or an id is not a UUID |
| 400 | SECTOR_INACTIVE | The target sector is inactive and cannot receive conversations |
| 403 | INSUFFICIENT_PERMISSIONS | The API key lacks the conversations:write permission |
| 403 | ASSIGNEE_NOT_IN_SECTOR | user_id is not a member of the target sector |
| 404 | NOT_FOUND | Conversation, sector or user not found in this account (an inactive user is also reported as not found) |
When a request is refused nothing is written: the conversation keeps its sector and assignee, and the round-robin queue does not advance.
MCP
The same action is available to MCP clients as the conversations_transfer tool, with dry_run support: a dry run shows who the round-robin would pick without advancing the queue.