PATCH /conversations/voice/{conversationId} transfer target queue rejection

NICE CXone API & Integrations
1
  • Need some troubleshooting help with a 400 Bad Request when attempting to transfer an active voice conversation to a specific queue via the Genesys Cloud Conversations API.
  • Using the PATCH /api/v2/conversations/voice/{conversationId} endpoint.
  • Request body:
{
 "transfers": [
 {
 "target": {
 "id": "8a31a067-1234-5678-90ab-cdef12345678",
 "type": "queue"
 },
 "transferType": "blind"
 }
 ]
}
  • Response:
{
 "errors": [
 {
 "code": "invalid_request",
 "message": "Transfer target is invalid or not reachable"
 }
 ]
}
  • Verified the queue ID exists and is active.
  • The agent initiating the transfer has conversation:write and routing:write permissions.
  • The source conversation state is connected.
  • Standard conference transfer works fine, but queue transfer fails.
  • Is there a specific capability required on the destination queue for programmatic blind transfers? Or a missing field in the payload?
2

It depends, but generally… the queue ID must match an active, enabled queue in your specific organization to avoid this 400 rejection. Check the validation logic here: https://support.example.com/articles/queue-transfer-validation.

3

The easiest fix here is this is to verify the queue ID exists in your Org before patching, as I hit this 400 during my Terraform migration when the ID was stale.

curl -X GET https://api.mypurecloud.com/api/v2/queues/{id}

Check the response code to ensure the target is valid before attempting the transfer.

4

Check your payload structure against the strict JSON schema. The suggestion above regarding ID validation is correct, but it does not address the syntactic error causing the 400 rejection.

Need some help troubleshooting a 400 Bad Request when attempting to transfer an active voice conversation to a specific queue via the Genesys Cloud Conversations API.

You are missing the toExternal flag or incorrect usage of the transfers array object. In the current API version, the transfers array requires a specific object structure where target is nested correctly, but often developers omit the wrapUpCode or fail to specify the transfer direction properly for blind transfers. More critically, ensure your Authorization header includes the conversation:write scope. If you are using the PureCloudPlatformClientV2 SDK, do not construct raw JSON. Use the typed builder to avoid schema mismatches.

  1. Validate Scope: Ensure your OAuth token has conversation:write.
  2. Use SDK: Construct the ConversationTransfer object.
  3. Execute: Call putConversationVoice.

Here is the correct Java SDK implementation:

import com.mypurecloud.api.v2.model.ConversationTransfer;
import com.mypurecloud.api.v2.model.ConversationTransferTarget;

// Construct the target
ConversationTransferTarget target = new ConversationTransferTarget();
target.setId("8a31a067-1234-5678-90ab-cdef12345678");
target.setType("queue");

// Construct the transfer
ConversationTransfer transfer = new ConversationTransfer();
transfer.setTarget(target);
transfer.setTransferType("blind");

// Wrap in the conversation update object
ConversationVoiceUpdate body = new ConversationVoiceUpdate();
body.setTransfers(Arrays.asList(transfer));

// Execute via SDK client
platformClient.ConversationsApi.putConversationVoice(conversationId, body);

This approach enforces type safety and ensures the JSON structure matches the Genesys Cloud API specification exactly. Raw curl requests often fail due to subtle whitespace or missing fields in the transfers array.