Starting Conversations with AI Assistants

Overview

After a successful anonymousLogin, you can initiate a call to your AI Assistant using the newInvite method. The AI assistant will automatically answer the call, and standard call controls will work normally.

Method Usage

Call newInvite(
  String callerName,
  String callerNumber,
  String destinationNumber,
  String clientState, {
  Map<String, String> customHeaders = const {},
  List<AudioCodec>? preferredCodecs,
  bool debug = false,
})

Important Behavior

Destination Ignored: Because the session is locked to the AI Assistant, the destinationNumber parameter is ignored, but can still be useful for referencing logs.
Automatic Answer: The AI assistant automatically answers the call
Standard Controls: All normal call controls (mute, hold, end, etc.) work as expected
Custom Headers: You can pass custom SIP headers to provide context to the AI assistant. They will be mapped to dynamic variables in the portal. Hyphens in header names are converted to underscores in variable names, e.g. X-Session-Context header maps to {{session_context}} variable.

Basic Example

// After a successful anonymousLogin...

Call aiCall = _telnyxClient.newInvite(
  'Your Name',
  'Your Number', 
  '', // Destination is ignored, can be an empty string
  'Your custom state',
);

// The call will be automatically answered by the AI Assistant

Advanced Usage

With Custom Headers

Call aiCall = _telnyxClient.newInvite(
  'John Doe',
  '+1234567890',
  '', // Ignored
  'customer_support_session',
  customHeaders: {
    'X-Session-Context': 'billing_inquiry',
    'X-User-Tier': 'premium'
  }
);

Note: The above headers will map to dynamic variables {{session_context}} and {{user_tier}} in the AI assistant portal settings

With Preferred Audio Codecs

// Get supported codecs
List<AudioCodec> supportedCodecs = _telnyxClient.getSupportedAudioCodecs();

// Use preferred codecs (Opus for high quality)
Call aiCall = _telnyxClient.newInvite(
  'Jane Smith',
  '+1987654321',
  '',
  'technical_support',
  preferredCodecs: [
    AudioCodec(
      mimeType: 'audio/opus',
      clockRate: 48000,
      channels: 2,
      sdpFmtpLine: 'minptime=10;useinbandfec=1',
    ),
  ]
);

With Debug Mode

Call aiCall = _telnyxClient.newInvite(
  'Debug User',
  '+1555000123',
  '',
  'debug_session',
  debug: true // Enables call quality metrics
);

// Listen for call quality metrics
aiCall.onCallQualityChange = (metrics) {
  print('Call quality: ${metrics.quality}');
  print('MOS score: ${metrics.mos}');
};

Call State Management

The AI call follows the same state management as regular calls:

// Listen for call state changes
aiCall.callHandler.onCallStateChanged = (CallState state) {
  switch (state) {
    case CallState.connecting:
      print('Connecting to AI assistant...');
      break;
    case CallState.active:
      print('Connected to AI assistant');
      break;
    case CallState.done:
      print('AI conversation ended');
      break;
    // Handle other states...
  }
};

Call Control Examples

Mute/Unmute

// Mute the microphone
aiCall.onMuteUnmutePressed();

// Check mute status
bool isMuted = aiCall.muted;

Hold/Unhold

// Put the call on hold
aiCall.onHoldUnholdPressed();

// Check hold status  
bool isOnHold = aiCall.held;

Speaker Phone

// Enable speaker phone
aiCall.enableSpeakerPhone(true);

// Disable speaker phone
aiCall.enableSpeakerPhone(false);

End Call

// End the AI conversation
aiCall.endCall();

Error Handling

try {
  Call aiCall = _telnyxClient.newInvite(
    'User Name',
    'User Number',
    '',
    'session_state'
  );
  
  // Set up error handling
  aiCall.callHandler.onCallStateChanged = (CallState state) {
    if (state == CallState.done) {
      // Check for call termination reason
      if (state.terminationReason?.cause == 'FAILED') {
        print('Call failed: ${state.terminationReason?.sipReason}');
      }
    }
  };
  
} catch (e) {
  print('Failed to start AI conversation: $e');
}

Best Practices

State Management: Always set up call state listeners before initiating the call
Error Handling: Implement proper error handling for connection failures
Resource Cleanup: Ensure calls are properly ended to free resources
User Feedback: Provide clear UI feedback about connection status
Debugging: Use debug mode during development to monitor call quality

Next Steps

After starting a conversation:

Set up transcript updates to receive real-time conversation data
Send text messages during the active call
Use standard call controls as needed

​Starting Conversations with AI Assistants

​Overview

​Method Usage

​Important Behavior

​Basic Example

​Advanced Usage

​With Custom Headers

​With Preferred Audio Codecs

​With Debug Mode

​Call State Management

​Call Control Examples

​Mute/Unmute

​Hold/Unhold

​Speaker Phone

​End Call

​Error Handling

​Best Practices

​Next Steps