LiveKit SIP

The LiveKit SIP service acts as a bridge between WebRTC sessions and telephony networks using SIP Trunking. It allows you to bring SIP traffic into a LiveKit room, enabling features like dialing out (sending INVITEs), dialing in (accepting INVITEs), digest authentication, and DTMF (touch tone) support.

Inbound Call Workflow

To accept inbound calls, you must follow these steps:

1. Create an SIP Trunk using the CreateSIPTrunk API (via LiveKit server).
2. Create an SIP Dispatch Rule using the CreateSIPDispatchRule API (via LiveKit server).
3. When a call is received, the SIP service connects to the specified LiveKit room, and the SIP caller joins as a participant.

Service Architecture

The SIP service communicates with the LiveKit server via Redis, which is also used to store SIP session state. Note that the SIP service must expose a public IP address to allow remote SIP peers to connect.

The SIP service is configured using a YAML file. You can provide the configuration via the SIP_CONFIG_FILE environment variable (pointing to a file path) or the SIP_CONFIG_BODY environment variable (containing the raw YAML string).

Required Fields

• api_key: LiveKit server API key (or LIVEKIT_API_KEY env).
• api_secret: LiveKit server API secret (or LIVEKIT_API_SECRET env).
• ws_url: LiveKit server websocket URL (or LIVEKIT_WS_URL env).
• redis:
  • address: Redis address used by the LiveKit server.
  • username: Redis username.
  • password: Redis password.
  • db: Redis database index.

Optional Fields

• health_port: HTTP port for health checks.
• prometheus_port: Port for Prometheus metrics collection.
• log_level: debug, info, warn, or error (default: info).
• sip_port: Port for SIP traffic (default: 5060).
• rtp_port: Port range for RTP traffic (default: 10000-20000).

# required fields
api_key: livekit server api key. LIVEKIT_API_KEY env can be used instead
api_secret: livekit server api secret. LIVEKIT_API_SECRET env can be used instead
ws_url: livekit server websocket url. LIVEKIT_WS_URL env can be used instead
redis:
  address: must be the same redis address used by your livekit server
  username: redis username
  password: redis password
  db: redis db

# optional fields
health_port: if used, will open an http port for health checks
prometheus_port: port used to collect prometheus metrics. Used for autoscaling
log_level: debug, info, warn, or error (default info)
sip_port: port to listen and send SIP traffic (default 5060)
rtp_port: port to listen and send RTP traffic (default 10000-20000)

To run the LiveKit SIP service for testing and development, you can use the provided docker-compose.yaml. This setup includes a Redis instance, the LiveKit server, and the SIP service.

Note that the configuration uses network_mode: host to facilitate local networking. If you are running on MacOS, you may need to adjust the networking or ensure the services can communicate via localhost as configured in the environment variables.

services:
  redis:
    image: redis
    volumes:
      - redis_data:/data
    ports:
      - 6379:6379
  livekit:
    image: livekit/livekit-server
    command: --dev --redis-host localhost:6379
    network_mode: host
    depends_on:
        redis:
            condition: service_started
  sip:
    image: livekit/sip
    network_mode: host
    environment:
      SIP_CONFIG_BODY: |
        api_key: 'devkey'
        api_secret: 'secret'
        ws_url: 'ws://localhost:7880'
        redis:
          address: 'localhost:6379'
        sip_port: 5060
        rtp_port: 10000-20000
        use_external_ip: true
        logging:
          level: debug
volumes:
  redis_data: