Skip to content

armgit / meet

Public Imported from GitHub
0

Open source video conferencing app powered by LiveKit. Built with Django and React.

📝(docs) document telephony feature and component interactions

lebaudantoinecbea1c0c0150
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.