PATCH /api/v2/conversations/voice/{id} transfer fails with 400 when trying to set target queue

We’re trying to automate call transfers based on specific interaction attributes captured in our Data Actions. The goal is to take an active voice conversation and move it to a different queue programmatically via the Conversations API.

I’ve been injecting the traceparent header from our OTel SDK into the request to keep the distributed trace intact, but the transfer itself is failing. The endpoint seems to accept the call ID, but it rejects the transfer payload.

Here’s the request details:

Endpoint:
PATCH /api/v2/conversations/voice/{conversationId}

Headers:

Authorization: Bearer {token}
Content-Type: application/json
traceparent: 00-{traceId}-{spanId}-01

Payload:

{
 "target": {
 "id": "550e8400-e29b-41d4-a716-446655440000",
 "type": "queue"
 }
}

The response is a 400 Bad Request. The error message is generic:

{
 "message": "Invalid input",
 "errors": [
 {
 "message": "The requested action is not valid for the current conversation state."
 }
 ]
}

I’ve verified the queue ID is correct and the conversation is in an active state with a participant on the line. I can do this manually in the GUI, so permissions shouldn’t be the issue. Is there a specific participant ID or token required in the payload that the docs are missing? Or am I hitting a limitation with programmatic transfers on voice channels?

The docs say you need to include the target object in the PATCH body, not just the queue ID. Try this payload structure.

{
 "target": {
 "type": "queue",
 "id": "your-queue-id-here"
 }
}

Also check if the user context has the right permissions.