From cbea1c0c0150d482393d9990a172ce43d29dcdbd Mon Sep 17 00:00:00 2001
From: lebaudantoine <lebaud.antoine131@gmail.com>
Date: Mon, 29 Sep 2025 19:22:22 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(docs)=20document=20telephony=20fea?=
 =?UTF-8?q?ture=20and=20component=20interactions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive telephony documentation explaining system requirements
and component interactions to help administrators understand infrastructure
needs.
---
 docs/features/telephony.md | 87 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/features/telephony.md

diff --git a/docs/features/telephony.md b/docs/features/telephony.md
new file mode 100644
index 00000000..dc0c92d9
--- /dev/null
+++ b/docs/features/telephony.md
@@ -0,0 +1,87 @@
+# Telephony SIP (Beta)
+
+Enable participants to join a video conference via phone, allowing them to participate in the room even when their internet connection is poor or unavailable.
+
+**Current Limitations**:
+
+* Supports only a single SIP trunk provider per instance.
+* A participant joining over the phone cannot enter the room until the first WebRTC participant has connected.
+
+## Special requirements
+
+To use the telephony feature, the following components are required:
+* A running [LiveKit SIP server](https://github.com/livekit/sip) ([documentation](https://docs.livekit.io/home/self-hosting/sip-server/)) to handle SIP participants and connect them to room sessions.
+* A SIP trunk to route incoming and outgoing phone calls.
+* Webhook events configured between the LiveKit server and the backend.
+
+
+## How It Works
+
+### Room Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Backend
+    participant LiveKit as LiveKit Service
+    participant SIP as LiveKit SIP
+    participant Dispatch as SIP Dispatch
+
+    Backend->>Backend: Create new room
+    Backend->>Backend: Assign unique pin code to room
+
+    LiveKit-->>Backend: Webhook room_started
+    Backend->>Dispatch: Create LiveKit SIP dispatch rule
+
+    LiveKit-->>Backend: Webhook room_ended
+    Backend->>Dispatch: Clear LiveKit SIP dispatch rule
+```
+
+### Participant calling
+
+```mermaid
+sequenceDiagram
+    participant Caller as Caller
+    participant SIPProvider as SIP Trunk Provider
+    participant LiveKitSIP as LiveKit SIP
+    participant Dispatch as SIP Dispatch
+    participant Room as LiveKit Room
+
+    Caller->>SIPProvider: Dial phone number
+    SIPProvider->>LiveKitSIP: Route call to SIP server
+    LiveKitSIP->>Caller: Prompt for room pin code
+    Caller->>LiveKitSIP: Enter pin code
+    LiveKitSIP->>Dispatch: Check dispatch rule for pin and trunk ID
+    Dispatch-->>LiveKitSIP: Return room ID if found
+    LiveKitSIP->>Room: Connect participant to room
+```
+
+
+## Configuration
+
+| Option                         | Type             | Default | Description                                                                                                     |
+| ------------------------------ | ---------------- | ------- |-----------------------------------------------------------------------------------------------------------------|
+| ROOM_TELEPHONY_ENABLED         | Boolean          | False   | Enable or disable telephony (phone call) support for rooms.                                                     |
+| ROOM_TELEPHONY_PIN_LENGTH      | Positive Integer | 10      | Length of the PIN code participants must enter to join a call.                                                  |
+| ROOM_TELEPHONY_PIN_MAX_RETRIES | Positive Integer | 5       | Maximum number of attempts a participant can make when entering the PIN.                                        |
+| ROOM_TELEPHONY_PHONE_NUMBER    | String           | None    | The phone number associated with the room for incoming calls. Required to route calls via the telephony system. |
+| ROOM_TELEPHONY_DEFAULT_COUNTRY | String           | "US"    | Default country code for phone numbers, used for parsing and formatting phone numbers.                          |
+
+
+### SIP Trunk Authentication
+
+You may need to configure authentication between LiveKit SIP and your SIP trunk provider to enable participants to join via phone.
+Please refer to [the official documentation](https://docs.livekit.io/sip/quickstarts/configuring-sip-trunk/).
+
+> [!NOTE]
+> Questions? Open an issue on [GitHub](https://github.com/suitenumerique/meet/issues/new?assignees=&labels=bug&template=Bug_report.md) or join our [Matrix community](https://matrix.to/#/#meet-official:matrix.org).
+
+
+### Language Customization for Audio Prompts
+
+You may need to configure the default LiveKit voice to match your locale. By default, all LiveKit audio instructions are in English.
+To customize the prompts, mount the appropriate audio files as a volume in your deployment. The audio resources are available here: [LiveKit SIP audio files](https://github.com/livekit/sip/tree/main/res).
+
+
+## Documentation
+
+For detailed information on integrating and configuring SIP with LiveKit, refer to the official LiveKit SIP documentation: [LiveKit SIP Documentation](https://docs.livekit.io/sip/). This guide covers SIP server setup, trunk configuration, dispatch rules, etc.