Warm transfer with Zoom Phone

Zoom Phone supports warm transfers. During a warm transfer, the original agent stays on the line to introduce the caller and issue to the next agent. This guide explains how to retrieve warm transfer details using Zoom Phone APIs.

Changes

Consolidated report

Previously, warm transfers used a separate call_history_uuid. Now one call_history_uuid and one consolidated report cover the entire call, including the pre-transfer, warm transfer, and post-transfer segments.

Warm transfers no longer generate separate events or reports. The incoming and outgoing transfer event names are now:

• warm_transfer_outgoing
• warm_transfer_incoming

Additionally, we now list the following payload fields in the consolidated call record within the call_elements object:

• operator_name - name of user who performed the transfer
• operator_ext_number - extension number of user who performed transfer
• segment - sequential integer to indicate the orders of events that starts from 0. Each phase has the same segment ID

How to access warm transfer records

If your integration retrieves warm transfer records from the Call History endpoint by matching the call_id to the transfer_call_id, update it as follows:

• Call the List API (/phone/call_history) and observe that it returns a single consolidated record instead of multiple records.

  {
      "total_records": 1,
      "call_history": [
          {
              "call_history_uuid": "20260519-abcd1234-5678-90ef-ghij-klmnopqrstuv",
              "direction": "inbound",
              "call_id": "1234567890123456789",
              "caller_did_number": "+15551234567",
              "callee_name": "Support Queue"
          }
      ]
  }
  

• Capture the call UUID and pass it as a query parameter in a subsequent request to the Details API endpoint (/phone/call_history/{callHistoryUuid}).

  {
      "call_history_uuid": "20240101-abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "call_elements": [
          {
              "segment": 1,
              "event": "incoming",
              "callee_name": "Support Queue",
              "result": "forwarded"
          },
          {
              "segment": 1,
              "event": "warm_transfer_incoming",
              "callee_name": "John Smith"
          },
          {
              "segment": 2,
              "event": "warm_transfer_incoming",
              "call_id": "1234567890abcdef123",
              "caller_name": "John Smith"
          }
          // ...
      ]
  }
  

Key Characteristics

• All phases are consolidated into one call_history_uuid.
• To retrieve call details, pass the UUID as a query parameter to the Call History endpoint.
• Post-transfer call_id exists only within call_elements.

Affected data access patterns

The following table outlines the updates required for common processes.