curl --request POST \
--url https://api.pyai.com/v1/telephony/calls/{id}/transfers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"to": "<string>",
"hold_audio_pcm16": "<string>",
"user_id": "<string>"
}
'import requests
url = "https://api.pyai.com/v1/telephony/calls/{id}/transfers"
payload = {
"to": "<string>",
"hold_audio_pcm16": "<string>",
"user_id": "<string>"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({to: '<string>', hold_audio_pcm16: '<string>', user_id: '<string>'})
};
fetch('https://api.pyai.com/v1/telephony/calls/{id}/transfers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pyai.com/v1/telephony/calls/{id}/transfers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'to' => '<string>',
'hold_audio_pcm16' => '<string>',
'user_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pyai.com/v1/telephony/calls/{id}/transfers"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/telephony/calls/{id}/transfers")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/telephony/calls/{id}/transfers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"version": 123,
"project_id": "<string>",
"direction": "inbound",
"from": "<string>",
"destination_number_id": "<string>",
"admission_mode": "client",
"admission_status": "pending",
"admission_expires_at": 123,
"max_duration_seconds": 123,
"client_reference": "<string>",
"agent_release_id": "<string>",
"stop_requested": true,
"object": "telephony.call",
"id": "tcall_...",
"from_number_id": "<string>",
"to": "+14155550123",
"dialing_mode": "parallel",
"destinations": [
"<string>"
],
"connected_to": "<string>",
"lines": [
{
"id": "<string>",
"to": "<string>",
"status": "pending",
"duration_seconds": 1
}
],
"agent_id": "<string>",
"call_type": "human",
"user_id": "<string>",
"forwarding": {
"to": "<string>",
"status": "waiting",
"menu": {
"kind": "keypad",
"status": "pending",
"choice_id": "<string>"
}
},
"transfer_enabled": true,
"held": true,
"hold_pending": true,
"transfers": [
{
"id": "<string>",
"mode": "warm",
"to": "<string>",
"status": "holding"
}
],
"use_case": "transactional",
"routing_profile": "quality_first",
"status": "queued",
"attempt_count": 1,
"max_attempts": 2,
"failure_reason": "network_unavailable",
"created_at": 123,
"updated_at": 123,
"answered_at": 123,
"ended_at": 123,
"artifacts": {
"status": "pending",
"omni_call_id": "<string>",
"recording": {
"status": "<string>",
"reason": "<string>",
"resource": "<string>"
},
"transcript": {
"status": "<string>",
"reason": "<string>",
"text": "<string>",
"resource": "<string>"
},
"ai_usage": {
"status": "pending",
"meter": "agents.minutes",
"units": 123,
"billable_units": 123
},
"usage": {
"status": "pending",
"meter": "telephony.minutes",
"units": 123,
"billable": true
}
}
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}Start a human call transfer
For an admitted transfer-enabled human call. Warm mode holds the caller before dialing a private consultation; complete only after the target joins. Cold mode holds the caller and removes the initiating browser before dialing. Failed cold transfers end the remaining caller. Each target needs consent and its own atomic capacity reservation. Retry the same Idempotency-Key and unchanged body; an uncertain carrier acknowledgment never permits redial. On the owned switch, the original browser/caller stays connected while the target dials. Warm mode then parks the retained caller for private browser/target consultation; complete connects caller/target, cancel restores browser/caller. Cold mode connects caller/target automatically only after verified target adoption. Cancel a cold target only before handoff starts. Retained recording and the original absolute call deadline continue across switch media stages; older unprotected switch channels refuse warm transfer. Existing single and parallel calls cannot change transport. Requires telephony:manage and the original authenticated user ID for browser calls. For an eligible inbound forwarded call, send mode warm and the destination without user_id.
curl --request POST \
--url https://api.pyai.com/v1/telephony/calls/{id}/transfers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"to": "<string>",
"hold_audio_pcm16": "<string>",
"user_id": "<string>"
}
'import requests
url = "https://api.pyai.com/v1/telephony/calls/{id}/transfers"
payload = {
"to": "<string>",
"hold_audio_pcm16": "<string>",
"user_id": "<string>"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({to: '<string>', hold_audio_pcm16: '<string>', user_id: '<string>'})
};
fetch('https://api.pyai.com/v1/telephony/calls/{id}/transfers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pyai.com/v1/telephony/calls/{id}/transfers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'to' => '<string>',
'hold_audio_pcm16' => '<string>',
'user_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pyai.com/v1/telephony/calls/{id}/transfers"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/telephony/calls/{id}/transfers")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/telephony/calls/{id}/transfers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"to\": \"<string>\",\n \"hold_audio_pcm16\": \"<string>\",\n \"user_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"version": 123,
"project_id": "<string>",
"direction": "inbound",
"from": "<string>",
"destination_number_id": "<string>",
"admission_mode": "client",
"admission_status": "pending",
"admission_expires_at": 123,
"max_duration_seconds": 123,
"client_reference": "<string>",
"agent_release_id": "<string>",
"stop_requested": true,
"object": "telephony.call",
"id": "tcall_...",
"from_number_id": "<string>",
"to": "+14155550123",
"dialing_mode": "parallel",
"destinations": [
"<string>"
],
"connected_to": "<string>",
"lines": [
{
"id": "<string>",
"to": "<string>",
"status": "pending",
"duration_seconds": 1
}
],
"agent_id": "<string>",
"call_type": "human",
"user_id": "<string>",
"forwarding": {
"to": "<string>",
"status": "waiting",
"menu": {
"kind": "keypad",
"status": "pending",
"choice_id": "<string>"
}
},
"transfer_enabled": true,
"held": true,
"hold_pending": true,
"transfers": [
{
"id": "<string>",
"mode": "warm",
"to": "<string>",
"status": "holding"
}
],
"use_case": "transactional",
"routing_profile": "quality_first",
"status": "queued",
"attempt_count": 1,
"max_attempts": 2,
"failure_reason": "network_unavailable",
"created_at": 123,
"updated_at": 123,
"answered_at": 123,
"ended_at": 123,
"artifacts": {
"status": "pending",
"omni_call_id": "<string>",
"recording": {
"status": "<string>",
"reason": "<string>",
"resource": "<string>"
},
"transcript": {
"status": "<string>",
"reason": "<string>",
"text": "<string>",
"resource": "<string>"
},
"ai_usage": {
"status": "pending",
"meter": "agents.minutes",
"units": 123,
"billable_units": 123
},
"usage": {
"status": "pending",
"meter": "telephony.minutes",
"units": 123,
"billable": true
}
}
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}Authorizations
Body
Response
Durable transfer intent; status describes progress, not a promise of connection.