> ## Documentation Index > Fetch the complete documentation index at: https://docs.mrassistant.ai/llms.txt > Use this file to discover all available pages before exploring further. # Register Phone Number > Register a phone number for an agent. Two modes of operation: 1. **LiveKit Phone Numbers** (provider='livekit'): - For numbers already purchased through LiveKit Cloud dashboard - No SIP trunk configuration needed - Simplified setup - just provide the phone number - LiveKit automatically manages the infrastructure 2. **External SIP Providers** (twilio, vonage, telnyx, etc.): - You must already own the phone number - Creates SIP dispatch rule in LiveKit - Returns SIP URI to configure in provider's dashboard - Supports both inbound and outbound calling ## OpenAPI ````yaml https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/phone-numbers openapi: 3.1.0 info: title: Backend - Multilingual Voice Agent System description: FastAPI backend for multilingual voice agents with tool use version: 1.0.0 servers: [] security: [] paths: /agents/{agent_id}/phone-numbers: post: tags: - agent-phone-numbers summary: Register Phone Number description: |- Register a phone number for an agent. Two modes of operation: 1. **LiveKit Phone Numbers** (provider='livekit'): - For numbers already purchased through LiveKit Cloud dashboard - No SIP trunk configuration needed - Simplified setup - just provide the phone number - LiveKit automatically manages the infrastructure 2. **External SIP Providers** (twilio, vonage, telnyx, etc.): - You must already own the phone number - Creates SIP dispatch rule in LiveKit - Returns SIP URI to configure in provider's dashboard - Supports both inbound and outbound calling operationId: register_phone_number_agents__agent_id__phone_numbers_post parameters: - name: agent_id in: path required: true schema: type: string format: uuid title: Agent Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterPhoneNumberRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: RegisterPhoneNumberRequest: properties: phone_number: type: string title: Phone Number description: E.164 format phone number (e.g., +15551234567) provider: type: string title: Provider description: 'SIP provider: livekit, twilio, vonage, telnyx, bandwidth, or custom' trunk_numbers: anyOf: - items: type: string type: array - type: 'null' title: Trunk Numbers description: Phone numbers on this trunk (defaults to [phone_number]) allowed_addresses: anyOf: - items: type: string type: array - type: 'null' title: Allowed Addresses description: Allowed IP addresses (empty = allow all) allowed_numbers: anyOf: - items: type: string type: array - type: 'null' title: Allowed Numbers description: Allowed caller numbers (empty = allow all) auth_username: anyOf: - type: string - type: 'null' title: Auth Username description: SIP authentication username (REQUIRED for Vonage outbound) auth_password: anyOf: - type: string - type: 'null' title: Auth Password description: SIP authentication password (REQUIRED for Vonage outbound) enable_outbound: type: boolean title: Enable Outbound description: >- Enable outbound calling (frontend may also send as 'outbound_enabled') default: false outbound_address: anyOf: - type: string - type: 'null' title: Outbound Address description: >- Provider's SIP termination URI for outbound calls. REQUIRED for outbound calling. Get this from your provider's dashboard. Examples: - Vonage: sip-us.vonage.com - Twilio: pstn.twilio.com - Telnyx: sip.telnyx.com outbound_numbers: anyOf: - items: type: string type: array - type: 'null' title: Outbound Numbers description: Phone numbers for outbound caller ID outbound_transport: type: string pattern: ^(AUTO|UDP|TCP|TLS)$ title: Outbound Transport description: 'SIP transport protocol: AUTO, UDP, TCP, or TLS' default: AUTO destination_country: anyOf: - type: string maxLength: 2 minLength: 2 - type: 'null' title: Destination Country description: >- Two-letter country code (e.g., 'US', 'IN'). Required for India compliance. media_encryption: type: string pattern: ^(DISABLE|ALLOW|REQUIRE)$ title: Media Encryption description: 'Media encryption: DISABLE, ALLOW, or REQUIRE (ALLOW recommended)' default: ALLOW krisp_enabled: type: boolean title: Krisp Enabled description: Enable Krisp noise cancellation for better call quality default: true ringing_timeout_seconds: type: integer maximum: 300 minimum: 1 title: Ringing Timeout Seconds description: Maximum time for call to ring (1-300 seconds) default: 30 max_call_duration_seconds: type: integer maximum: 86400 minimum: 60 title: Max Call Duration Seconds description: Maximum call duration (60-86400 seconds) default: 3600 hide_phone_number: type: boolean title: Hide Phone Number description: Hide caller phone number from participant attributes for privacy default: false custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: Custom SIP X-* headers to include in requests headers_to_attributes: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers To Attributes description: Map SIP headers to participant attributes dtmf_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Dtmf Config description: DTMF and IVR configuration example: auto_navigate_ivr: true dtmf_sequence: '*123#ww456' dtmf_timeout: 30 ivr_detection: true transfer_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Transfer Config description: Call transfer configuration example: allowed_destinations: - tel:+15105550100 cold_transfer_enabled: true requires_confirmation: true supervisor_phone: tel:+15105550100 warm_transfer_enabled: false agent_features: anyOf: - additionalProperties: true type: object - type: 'null' title: Agent Features description: Agent-specific telephony features example: call_screening: false recording_enabled: true sentiment_analysis: true transcription_enabled: true metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: Additional metadata provider_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Provider Config description: Provider-specific configuration (stored in database as JSON) type: object required: - phone_number - provider title: RegisterPhoneNumberRequest description: >- Request to register a phone number for an agent. Provide phone number and trunk details - LiveKit handles the SIP infrastructure. For LiveKit phone numbers (provider='livekit'): - Purchase your number through LiveKit Cloud dashboard first - No trunk configuration needed - LiveKit manages the infrastructure - Just provide the phone number and it will be configured automatically For external providers (twilio, vonage, etc.): - You must own the number already - SIP trunk configuration is required - You'll receive a SIP URI to configure in provider's dashboard **IMPORTANT FOR VONAGE USERS:** Vonage Elastic SIP Trunking requires your trunk domain in the outbound_address. Format: {your-trunk-domain}.sip-{region}.vonage.com Example: mrassistant-developer.sip-us.vonage.com Find this in Vonage Dashboard → SIP Trunks → Your Trunk → Outbound Calling section. PhoneNumberResponse: properties: agent_id: type: string title: Agent Id phone_number: type: string title: Phone Number provider: type: string title: Provider sip_uri: type: string title: Sip Uri dispatch_rule_id: type: string title: Dispatch Rule Id outbound_enabled: type: boolean title: Outbound Enabled outbound_trunk_id: anyOf: - type: string - type: 'null' title: Outbound Trunk Id description: LiveKit outbound trunk ID if outbound is enabled outbound_address: anyOf: - type: string - type: 'null' title: Outbound Address description: SIP address used for outbound calls (e.g., sip.telnyx.com) status: type: string title: Status created_at: type: string title: Created At instructions: additionalProperties: true type: object title: Instructions provider_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Provider Config room_pattern: anyOf: - type: string - type: 'null' title: Room Pattern description: LiveKit room naming pattern for this agent's calls livekit_sip_domain: anyOf: - type: string - type: 'null' title: Livekit Sip Domain description: LiveKit SIP domain for this deployment inbound_addresses: anyOf: - items: type: string type: array - type: 'null' title: Inbound Addresses description: LiveKit inbound SIP server addresses supported_providers: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Supported Providers description: List of supported SIP providers with default addresses type: object required: - agent_id - phone_number - provider - sip_uri - dispatch_rule_id - outbound_enabled - status - created_at - instructions title: PhoneNumberResponse description: Response for phone number registration. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````