Call

public class Call

A Call represents an audio or video communication session between two endpoints: WebRTC Clients, SIP clients, or phone numbers. The Call object manages the entire lifecycle of a call, from initiation to termination, handling both outbound and inbound calls.

A Call object is created in two scenarios:

  1. When you initiate a new outbound call using TxClient’s newCall method
  2. When you receive an inbound call through the TxClientDelegate’s onIncomingCall callback

Key Features

  • Audio and video call support
  • Call state management (NEW, CONNECTING, RINGING, ACTIVE, HELD, DONE)
  • Mute/unmute functionality
  • DTMF tone sending
  • Custom headers support for both INVITE and ANSWER messages
  • Call statistics reporting when debug mode is enabled

Examples

Creating an Outbound Call:

   // Initialize the client
   self.telnyxClient = TxClient()
   self.telnyxClient?.delegate = self

   // Connect the client (see TxClient documentation for connection options)
   self.telnyxClient?.connect(....)

   // Create and initiate a call
   self.currentCall = try self.telnyxClient?.newCall(
       callerName: "John Doe",           // The name to display for the caller
       callerNumber: "155531234567",     // The caller's phone number
       destinationNumber: "18004377950", // The target phone number or SIP URI
       callId: UUID.init(),              // Unique identifier for the call
       clientState: nil,                 // Optional client state information
       customHeaders: [:]                // Optional custom SIP headers
   )

Handling an Incoming Call:

class CallHandler: TxClientDelegate {
    var activeCall: Call?

    func initTelnyxClient() {
        let client = TxClient()
        client.delegate = self
        client.connect(....)
    }

    func onIncomingCall(call: Call) {
        // Store the call reference
        self.activeCall = call

        // Option 1: Auto-answer the call
        call.answer()

        // Option 2: Answer with custom headers
        call.answer(customHeaders: ["X-Custom-Header": "Value"])

        // Option 3: Reject the call
        // call.hangup()
    }
}

  • Custom headers received from the WebRTC INVITE message. These headers are passed during call initiation and can contain application-specific information. Format should be [“X-Header-Name”: “Value”] where header names must start with “X-”.

    Declaration

    Swift

    public internal(set) var inviteCustomHeaders: [String : String]? { get }

  • Custom headers received from the WebRTC ANSWER message. These headers are passed during call acceptance and can contain application-specific information. Format should be [“X-Header-Name”: “Value”] where header names must start with “X-”.

    Declaration

    Swift

    public internal(set) var answerCustomHeaders: [String : String]? { get }

  • The unique session identifier for the current WebRTC connection. This ID is established during client connection and remains constant for the session duration.

    Declaration

    Swift

    public internal(set) var sessionId: String? { get }

  • The unique Telnyx session identifier for this call. This ID can be used to track the call in Telnyx’s systems and logs.

    Declaration

    Swift

    public internal(set) var telnyxSessionId: UUID? { get }

  • The unique Telnyx leg identifier for this call. A call can have multiple legs (e.g., in call transfers). This ID identifies this specific leg.

    Declaration

    Swift

    public internal(set) var telnyxLegId: UUID? { get }

  • Enables WebRTC statistics reporting for debugging purposes. When true, the SDK will collect and send WebRTC statistics to Telnyx servers. This is useful for troubleshooting call quality issues.

    Declaration

    Swift

    public internal(set) var debug: Bool { get }

  • Controls whether the SDK should force TURN relay for peer connections. When enabled, the SDK will only use TURN relay candidates for ICE gathering, which prevents the “local network access” permission popup from appearing.

    Declaration

    Swift

    public internal(set) var forceRelayCandidate: Bool { get }

Properties

  • Contains essential information about the current call including:

    • callId: Unique identifier for this call
    • callerName: Display name of the caller
    • callerNumber: Phone number or SIP URI of the caller See TxCallInfo for complete details.

    Declaration

    Swift

    public var callInfo: TxCallInfo?

  • The current state of the call. Possible values:

    • NEW: Call object created but not yet initiated
    • CONNECTING: Outbound call is being established
    • RINGING: Incoming call waiting to be answered
    • ACTIVE: Call is connected and media is flowing
    • HELD: Call is temporarily suspended
    • DONE: Call has ended

    The state changes are notified through the CallProtocol delegate.

    Declaration

    Swift

    public var callState: CallState

  • Indicates whether the local audio is currently muted.

    Use muteAudio() and unmuteAudio() to change the mute state.

    Declaration

    Swift

    public var isMuted: Bool { get }

    Return Value

    false if the call is not muted (audio track enabled)

Call handling

  • Hangup or reject an incoming call.

    Example:

    call.hangup()

    Declaration

    Swift

    public func hangup()

  • Starts the process to answer the incoming call.

    Example:

    call.answer()

    Declaration

    Swift

    public func answer(customHeaders: [String : String] = [:])

DTMF

  • Sends a DTMF (Dual-Tone Multi-Frequency) signal during an active call. DTMF signals are used to send digits and symbols over a phone line, typically for interacting with automated systems, voicemail, or IVR menus.

    Examples:

    // Navigate an IVR menu
currentCall?.dtmf("1")    // Select option 1
currentCall?.dtmf("0")    // Select option 0

// Special characters
currentCall?.dtmf("*")    // Send asterisk
currentCall?.dtmf("#")    // Send pound/hash

    Note: The call must be in ACTIVE state for DTMF signals to be sent successfully. Each DTMF tone should be sent individually with appropriate timing between tones when sending multiple digits.

    Declaration

    Swift

    public func dtmf(dtmf: String)

    Parameters

    dtmf

    A string containing a single DTMF character. Valid characters are:

    • Digits: 0-9
    • Special characters: * (asterisk), # (pound)
    • Letters: A-D (less commonly used)

Audio handling

  • Turns off audio output, i.e. makes it so other call participants cannot hear your audio.

    Example:

    call.muteAudio()

    Declaration

    Swift

    public func muteAudio()

  • Turns on audio output, i.e. makes it so other call participants can hear your audio.

    Example:

    call.unmuteAudio()

    Declaration

    Swift

    public func unmuteAudio()

Hold / Unhold handling

  • Holds the call.

    Example:

    call.hold()

    Declaration

    Swift

    public func hold()

  • Removes hold from the call.

    Example:

    call.unhold()

    Declaration

    Swift

    public func unhold()

  • Toggles between active and held state of the call.

    Example:

    call.toggleHold()

    Declaration

    Swift

    public func toggleHold()