Skip to content

Transfer Conversation ​

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

Assigns 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 sendWhat happens
user_id onlyThe user becomes the assignee. The sector of the conversation does not change.
sector_id onlyThe conversation moves to the sector and the sector's round-robin picks the assignee. The response tells you who was picked.
sector_id + user_idThe 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 ​

ParameterTypeRequiredDescription
idstring (UUID)YesThe unique identifier of the conversation

Request Body ​

At least one of the two fields is required.

FieldTypeRequiredDescription
sector_idstring (UUID)No*Target sector (see List Sectors). Must be active.
user_idstring (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 ​

bash
# 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"
  }'
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 ? 'No one in the queue' : `Assigned to ${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())

Other request bodies ​

Assign a user, keeping the sector:

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

Move to a sector and assign a specific user (no round-robin):

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

Response ​

Sector only — the round-robin picked the assignee:

json
{
  "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:

json
{
  "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 ​

FieldTypeDescription
conversation_idstringThe conversation that was transferred
sectorobject | nullSector the conversation is in after the call (id, name). null only when the conversation never had a sector and you sent only user_id
assigneeobject | nullUser now responsible (id, name, email). null when the round-robin queue was empty
assigned_viastring | nullHow the assignee was chosen: manual (you sent user_id) or round_robin (the sector queue picked). null when there is no assignee
queue_emptybooleantrue when the round-robin was used and the sector had nobody to receive
previous.sector_idstring | nullSector of the conversation before the call
previous.assigned_user_idstring | nullAssignee 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 ​

StatusCodeDescription
400VALIDATION_ERRORNeither sector_id nor user_id was sent, or an id is not a UUID
400SECTOR_INACTIVEThe target sector is inactive and cannot receive conversations
403INSUFFICIENT_PERMISSIONSThe API key lacks the conversations:write permission
403ASSIGNEE_NOT_IN_SECTORuser_id is not a member of the target sector
404NOT_FOUNDConversation, 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.

GetRaze - AI-Powered Lead Generation