Attended Transfer Guide

Overview

An attended transfer allows a user to place an active call on hold, establish a new call to consult with another party, and then transfer the original caller to that new party. This guide walks through the complete process using the NS API.

Prerequisites

Correctly scoped API key and other credentials as needed
Understanding of call session management (see API reference endpoints under Calls (live/active) calls heading, referenced below)

Step-by-Step Process

Step 1: Initial Call Setup

Scenario: Inbound call from +1-555-555-5555 to +1-111-111-1111, routed to user 1000. User 1000 answers on their webphone.

Step 2: Retrieve Active Call Information

Use the Read Active Calls in Domain endpoint to get details about the current call.

Endpoint: GET /domains/{domain}/calls
Documentation: https://docs.ns-api.com/reference/get_domains-domain-calls

Key Response Fields to Note:

{
  "call-session-id": "1010101010101010101",
  "call-orig-call-id": "[email protected]",
  "call-term-call-id": "123451234512345-1a2d3f4g5h6j7k8l",
  "call-term-user": 1000,
  "call-term-domain": "TEST"
}

Important: Save the call-orig-call-id - you'll need it for the final transfer step.

Step 3: Place Original Call on Hold

Use the Hold Active Call endpoint to place the original call on hold.

Endpoint: PATCH /domains/{domain}/users/{user}/calls/{call_id}/hold
Documentation: https://docs.ns-api.com/reference/patch_domains-domain-users-user-calls-call-id-hold

Parameters:

call_id: Use the call-term-call-id from Step 2
domain: The 1000 user's domain
user: The user placing the call on hold, 1000

Step 4: Initiate "Consultation" Call

Create a new call from the transferring user to the target recipient. This is the call between the original recipient and the intended transfer target, allowing for a "consultation" to happen basically.

Endpoint: POST /domains/{domain}/users/{user}/calls
Documentation: https://docs.ns-api.com/reference/post_domains-domain-users-user-calls

Example: User 1000 calls user 1010 for consultation.

Step 5: Retrieve New Call Information

Use the Read Active Calls in Domain endpoint again to get details about the "consultation" call.

Key Response Fields:

{
  "call-session-id": "202020202020202020",
  "call-orig-user": 1000,
  "call-term-user": 1010,
  "call-orig-info": "active",
  "call-term-info": "active"
}

Important: Save the call-session-id again, you'll need it for the next transfer.

Step 6: Complete the Attended Transfer

Use the Transfer Call endpoint to finalize the attended transfer.

Endpoint: PATCH /domains/{domain}/users/{user}/calls/{call_id}/transfer
Documentation: https://docs.ns-api.com/reference/patch_domains-domain-users-user-calls-call-id-transfer

cURL Example:

curl --request PATCH \
  --url https://your-server.netsapiens.com/ns-api/v2/domains/test2/users/203/calls/[email protected]/transfer \
  --data '{
    "hostname": "your-server.netsapiens.com",
    "call-destination-session-id": "202020202020202020"
  }'

Parameters:

call_id (in URL): Use the call-orig-call-id from Step 2
hostname: The core server hostname
call-destination-session-id: The call-session-id from Step 5

Important Notes

API Documentation Correction

⚠️ Important: As of 44.2, the API documentation incorrectly states that call-term-user is required for the transfer endpoint. This has been corrected in future versions of the documentation, however please observe the following clarification for the existing documentation:

Do NOT include call-term-user in your transfer request - including it will prevent the attended transfer from completing successfully.

Call ID Reference Guide

For holding the call: Use call-term-call-id
For the final transfer: Use call-orig-call-id
For destination session: Use call-session-id from the consultation call

Error Handling / Best Practices

Verify all calls are in "active" state before proceeding
Ensure proper call session IDs are used for each step
Check that the consultation call is successfully established before attempting transfer

Summary

The attended transfer process involves:

Retrieving original call details
Placing original call on hold
Creating consultation call
Retrieving consultation call details
Executing the transfer with proper session IDs