Hand back a transferred call

curl --request POST \
  --url http://localhost:8080/phone/calls/hand-back \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "summary": "<string>"
}
'

import requests

url = "http://localhost:8080/phone/calls/hand-back"

payload = {
    "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "summary": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', summary: '<string>'})
};

fetch('http://localhost:8080/phone/calls/hand-back', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/phone/calls/hand-back",
  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([
    'session_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'summary' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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 := "http://localhost:8080/phone/calls/hand-back"

	payload := strings.NewReader("{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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("http://localhost:8080/phone/calls/hand-back")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/phone/calls/hand-back")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "handed_back"
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

POST

phone

calls

hand-back

Hand back a transferred call

curl --request POST \
  --url http://localhost:8080/phone/calls/hand-back \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "summary": "<string>"
}
'

import requests

url = "http://localhost:8080/phone/calls/hand-back"

payload = {
    "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "summary": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', summary: '<string>'})
};

fetch('http://localhost:8080/phone/calls/hand-back', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/phone/calls/hand-back",
  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([
    'session_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'summary' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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 := "http://localhost:8080/phone/calls/hand-back"

	payload := strings.NewReader("{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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("http://localhost:8080/phone/calls/hand-back")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/phone/calls/hand-back")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"summary\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "handed_back"
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

When a Classical IVR transfers a caller to a SIP destination, the caller stays on the OpenCX call while your SIP endpoint talks to them. Call this endpoint, instead of hanging up, when the caller should continue with the organization. OpenCX hangs up your SIP leg, then the IVR continues with the steps after the transfer, usually a transfer to a team. The caller keeps the same call, recording and session throughout. Send the session ID you received in the X-OPENCX-SESSION-ID SIP header of the transfer. The destination must list X-OPENCX-SESSION-ID among its allowed headers if it uses an allowlist.

Create the API key with the Hand back transferred calls (phone-calls:write) scope. That scope cannot read or change any other phone configuration. A phone:write key can also hand calls back.
Pass an optional summary of the conversation so far. It replaces the session’s summary before the teammate is connected, so they see it when the call rings. It is saved only when the hand-back is accepted.
Repeating a successful hand-back returns the same response and changes nothing; a summary sent with the repeat is ignored.
A 409 means the session has no transferred call waiting: your leg has not answered yet, your leg or the caller already hung up, or the session has no SIP transfer. Hanging up without calling this endpoint returns the caller to the IVR, which continues with the completed outcome.
A 404 means the session does not exist in the organization that owns the API key.

Do not hang up your leg first: OpenCX hangs it up for you once the hand-back is accepted. If your leg hangs up before the hand-back arrives, the hand-back is still accepted for a few seconds.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

session_id

string<uuid>

required

The session of the call to hand back, as received in the X-OPENCX-SESSION-ID SIP header

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

summary

string

Your summary of the conversation so far. Saved as the session's summary before a teammate is connected.

Required string length: 1 - 10000

Response

Default Response

session_id

string<uuid>

required

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

status

string

required

Allowed value: "handed_back"

Overview

Blocklist

Autopilot

Organization

Contacts

Companies

Sessions

Connect

AI Phone Agents

Classical IVR

AI Email

AI WhatsApp

AI Actions

Sequences

Outbound Blocklist

Media

AI Training

Help Center

Resource Usage

Customer Insights

Teams

CSAT

Redaction

Crawl

Tags

Custom Statuses

Inbox Views

Office Hours

Handoff Analytics

SLA Analytics

Secrets

Audit Logs

Workflows (Beta)

Salesforce MIAW

Webhooks

Hand back a transferred call

Authorizations

Body

Response