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:
- When you initiate a new outbound call using TxClient’s newCall method
- 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 }
-
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()
andunmuteAudio()
to change the mute state.Declaration
Swift
public var isMuted: Bool { get }
Return Value
false
if the call is not muted (audio track enabled)
-
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] = [:])
-
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)
-
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()
-
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
andheld
state of the call.Example:
call.toggleHold()
Declaration
Swift
public func toggleHold()