feat(sip-dialout): ☎️ API "SIP dial-out"

appinfo/info.xml

@@ -16,7 +16,7 @@ And in the works for the [coming versions](https://github.com/nextcloud/spreed/m
 
 	]]></description>
 
-	<version>18.0.0-dev.8</version>
+	<version>18.0.0-dev.9</version>
 	<licence>agpl</licence>
 
 	<author>Daniel Calviño Sánchez</author>

appinfo/routes/routesCallController.php

@@ -36,6 +36,8 @@
 		['name' => 'Call#joinCall', 'url' => '/api/{apiVersion}/call/{token}', 'verb' => 'POST', 'requirements' => $requirements],
 		/** @see \OCA\Talk\Controller\CallController::ringAttendee() */
 		['name' => 'Call#ringAttendee', 'url' => '/api/{apiVersion}/call/{token}/ring/{attendeeId}', 'verb' => 'POST', 'requirements' => $requirements],
+		/** @see \OCA\Talk\Controller\CallController::sipDialOut() */
+		['name' => 'Call#sipDialOut', 'url' => '/api/{apiVersion}/call/{token}/dialout/{attendeeId}', 'verb' => 'POST', 'requirements' => $requirements],
 		/** @see \OCA\Talk\Controller\CallController::updateCallFlags() */
 		['name' => 'Call#updateCallFlags', 'url' => '/api/{apiVersion}/call/{token}', 'verb' => 'PUT', 'requirements' => $requirements],
 		/** @see \OCA\Talk\Controller\CallController::leaveCall() */

appinfo/routes/routesRoomController.php

@@ -96,12 +96,18 @@
 		['name' => 'Room#addToFavorites', 'url' => '/api/{apiVersion}/room/{token}/favorite', 'verb' => 'POST', 'requirements' => $requirementsWithToken],
 		/** @see \OCA\Talk\Controller\RoomController::removeFromFavorites() */
 		['name' => 'Room#removeFromFavorites', 'url' => '/api/{apiVersion}/room/{token}/favorite', 'verb' => 'DELETE', 'requirements' => $requirementsWithToken],
-		/** @see \OCA\Talk\Controller\RoomController::getParticipantByDialInPin() */
-		['name' => 'Room#getParticipantByDialInPin', 'url' => '/api/{apiVersion}/room/{token}/pin/{pin}', 'verb' => 'GET', 'requirements' => array_merge($requirementsWithToken, [
+		/** @see \OCA\Talk\Controller\RoomController::verifyDialInPin() */
+		['name' => 'Room#verifyDialInPin', 'url' => '/api/{apiVersion}/room/{token}/pin/{pin}', 'verb' => 'GET', 'requirements' => array_merge($requirementsWithToken, [
 			'pin' => '\d{7,32}',
 		])],
+		/** @see \OCA\Talk\Controller\RoomController::verifyDialInPin() */
+		['name' => 'Room#verifyDialInPin', 'url' => '/api/{apiVersion}/room/{token}/verify-dialin', 'verb' => 'POST', 'requirements' => $requirementsWithToken],
+		/** @see \OCA\Talk\Controller\RoomController::verifyDialOutNumber() */
+		['name' => 'Room#verifyDialOutNumber', 'url' => '/api/{apiVersion}/room/{token}/verify-dialout', 'verb' => 'POST', 'requirements' => $requirementsWithToken],
 		/** @see \OCA\Talk\Controller\RoomController::createGuestByDialIn() */
 		['name' => 'Room#createGuestByDialIn', 'url' => '/api/{apiVersion}/room/{token}/open-dial-in', 'verb' => 'POST', 'requirements' => $requirementsWithToken],
+		/** @see \OCA\Talk\Controller\RoomController::rejectedDialOutRequest() */
+		['name' => 'Room#rejectedDialOutRequest', 'url' => '/api/{apiVersion}/room/{token}/rejected-dialout', 'verb' => 'DELETE', 'requirements' => $requirementsWithToken],
 		/** @see \OCA\Talk\Controller\RoomController::setNotificationLevel() */
 		['name' => 'Room#setNotificationLevel', 'url' => '/api/{apiVersion}/room/{token}/notify', 'verb' => 'POST', 'requirements' => $requirementsWithToken],
 		/** @see \OCA\Talk\Controller\RoomController::setNotificationCalls() */

composer.json

@@ -43,7 +43,7 @@
 	},
 	"require": {
 		"bamarni/composer-bin-plugin": "^1.8",
-		"cuyz/valinor": "^1.6",
+		"cuyz/valinor": "1.6.0",
 		"firebase/php-jwt": "^6.3"
 	},
 	"extra": {

docs/call.md

@@ -77,6 +77,28 @@
         + `404 Not Found` When the conversation could not be found for the participant
         + `412 Precondition Failed` When the lobby is active and the user is not a moderator
 
+## Send SIP dial-out request
+
+* Required capability: `sip-support-dialout`
+* Method: `POST`
+* Endpoint: `/call/{token}/dialout/{attendeeId}`
+* Data:
+
+| field        | type | Description             |
+|--------------|------|-------------------------|
+| `attendeeId` | int  | The participant to call |
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `400 Bad Request` When the room has no call in process
+        + `400 Bad Request` When the actor is not in the call
+        + `403 Forbidden` When the current user does not have the "Start call" permission
+        + `404 Not Found` When the conversation could not be found for the participant
+        + `404 Not Found` When the target participant could not be found or is not a phone number (Guest, group, etc.)
+        + `412 Precondition Failed` When the lobby is active and the user is not a moderator
+        + `501 Not Implemented` When the SIP functionality is not configured
+
 ## Update call flags
 
 * Method: `PUT`

docs/capabilities.md

@@ -132,5 +132,9 @@
 * `session-state` - Sessions can mark themselves as inactive, so the participant receives notifications again
 * `note-to-self` - Support for "Note-to-self" conversation exists
 * `recording-consent` - Whether admins and moderators can require recording consent before joining a call
+* `sip-support-dialout` - Whether admins can enable SIP dial-out
 * `config => chat => has-translation-providers` - When true, translation tuples can be loaded from the [OCS Translation API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-translation-api.html#get-available-translation-options).
 * `config => call => recording-consent` - Whether users need to consent into call recording before joining a call (see [constants list](constants.md#recording-consent-required))
+* `config => call => sip-enabled` - Whether SIP is configured on the server allowing for SIP dial-in
+* `config => call => sip-dialout-enabled` - Whether SIP dial-out is configured on the server, additionally requires `config => call => sip-enabled`
+* `config => call => can-enable-sip` - Whether the current user is a member of the groups that are allowed to enable SIP dial-in on a conversation or use SIP dial-out

docs/constants.md

@@ -12,11 +12,12 @@
 
 ### Object types
 
-| Constant         | Can be created | Description                                                      | Object ID                             |
-|------------------|----------------|------------------------------------------------------------------|---------------------------------------|
-| `file`           | No             | Conversations about a file in the right sidebar of the files app | File ID                               |
-| `share:password` | No             | Video verification to verify the identity of the share recipient | Share token                           |
-| `room`           | Yes            | Room is a breakout room                                          | Token of the main/parent conversation |
+| Constant         | Can be created | Description                                                      | Object ID                                               |
+|------------------|----------------|------------------------------------------------------------------|---------------------------------------------------------|
+| `file`           | No             | Conversations about a file in the right sidebar of the files app | File ID                                                 |
+| `share:password` | No             | Video verification to verify the identity of the share recipient | Share token                                             |
+| `room`           | Yes            | Room is a breakout room                                          | Token of the main/parent conversation                   |
+| `phone`          | Yes            | Room is created when calling a phone number with SIP dial-out    | `phone` (not set atm, just used for the default avatar) |
 
 ### Read-only states
 * `0` Read-write

docs/participant.md

@@ -42,6 +42,8 @@
 | `statusIcon`          | string | v2    |         | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation                                                                       |
 | `statusMessage`       | string | v2    |         | Optional: Only available with `includeStatus=true`, for users with a set status and when there are less than 100 participants in the conversation                                                                       |
 | `roomToken`           | string | v4    |         | Optional: Only available with `breakout-rooms-v1` capability                                                                                                                                                            |
+| `phoneNumber`         | string | v4    |         | Optional: Only available with `sip-support-dialout` capability and only filled for moderators that are allowed to configure SIP for conversations                                                                       |
+| `callId`              | string | v4    |         | Optional: Only available with `sip-support-dialout` capability and only filled for moderators that are allowed to configure SIP for conversations                                                                       |
 
 
 ## Get list of participants in a conversation including its breakout rooms
@@ -265,7 +267,8 @@ Setting custom permissions for a self-joined user will also make them a permanen
 
 ## Get a participant by their pin
 
-Note: This is only allowed with validate SIP bridge requests
+Note: Deprecated - Use [Verify a dial-in PIN](#Verify-a-dial-in-PIN) instead
+Note: This is only allowed as validate SIP bridge requests
 
 * Required capability: `sip-support`
 * Method: `GET`
@@ -279,6 +282,73 @@ Note: This is only allowed with validate SIP bridge requests
 
     - Data: See array definition in `Get user´s conversations`
 
+## Verify a dial-in PIN
+
+Note: This is only allowed as validate SIP bridge requests
+
+* Required capability: `sip-support-dialout`
+* Method: `POST`
+* Endpoint: `/room/{token}/verify-dialin`
+* Data:
+
+| field | type   | Description                         |
+|-------|--------|-------------------------------------|
+| `pin` | string | PIN the participant used to dial-in |
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `401 Unauthorized` When the validation as SIP bridge failed
+        + `404 Not Found` When the conversation or participant could not be found
+        + `501 Not Implemented` When SIP is not configured
+
+    - Data: See array definition in `Get user´s conversations`
+
+## Verify a dial-out number
+
+Note: This is only allowed as validate SIP bridge requests
+
+* Required capability: `sip-support-dialout`
+* Method: `POST`
+* Endpoint: `/room/{token}/verify-dialout`
+* Data:
+
+| field     | type   | Description                                                                                                                     |
+|-----------|--------|---------------------------------------------------------------------------------------------------------------------------------|
+| `number`  | string | E164 formatted phone number                                                                                                     |
+| `options` | string | Additional details to verify the validity of the request as JSON encoded object (Should contain actorId, actorType, attendeeId) |
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `401 Unauthorized` When the validation as SIP bridge failed
+        + `404 Not Found` When the conversation or participant could not be found
+        + `501 Not Implemented` When SIP or SIP dial-out is not configured
+
+    - Data: See array definition in `Get user´s conversations`
+
+## Reset call ID of rejected dial-out
+
+Note: This is only allowed as validate SIP bridge requests
+
+* Required capability: `sip-support-dialout`
+* Method: `DELETE`
+* Endpoint: `/room/{token}/rejected-dialout`
+* Data:
+
+| field     | type   | Description                                    |
+|-----------|--------|------------------------------------------------|
+| `callId`  | string | The call ID that was rejected                  |
+| `options` | string | The options as received in the dialout request |
+
+* Response:
+    - Status code:
+        + `200 OK` Call ID reset
+        + `400 Bad Request` Call ID mismatch
+        + `401 Unauthorized` SIP request invalid
+        + `404 Not Found` Participant was not found
+        + `501 Not Implemented` When SIP or SIP dial-out is not configured
+
 ## Set display name as a guest
 
 * API: Only `v1`

docs/settings.md

@@ -95,6 +95,7 @@ Legend:
 | `breakout_rooms`                     | string<br>`yes` or `no`                                          | `yes`      | Yes  |        | Whether or not breakout rooms are allowed (Will only prevent creating new breakout rooms. Existing conversations are not modified.)                                               |
 | `call_recording`                     | string<br>`yes` or `no`                                          | `yes`      | Yes  |        | Enable call recording                                                                                                                                                             |
 | `call_recording_transcription`       | string<br>`yes` or `no`                                          | `no`       | No   |        | Whether call recordings should automatically be transcripted when a transcription provider is enabled.                                                                            |
+| `sip_dialout`                        | string<br>`yes` or `no`                                          | `no`       | Yes  |        | SIP dial-out is allowed when a SIP bridge is configured                                                                                                                           |
 | `federation_enabled`                 | string<br>`yes` or `no`                                          | `no`       | Yes  |        | 🏗️ *Work in progress:* Whether or not federation with this instance is allowed                                                                                                   |
 | `conversations_files`                | string<br>`1` or `0`                                             | `1`        | No   | 🖌️    | Whether the files app integration is enabled allowing to start conversations in the right sidebar                                                                                 |
 | `conversations_files_public_shares`  | string<br>`1` or `0`                                             | `1`        | No   | 🖌️    | Whether the public share integration is enabled allowing to start conversations in the right sidebar on the public share page (Requires `conversations_files` also to be enabled) |

lib/Capabilities.php

@@ -70,6 +70,9 @@ public function __construct(
 	 *                  supported-reactions: string[],
 	 *                  predefined-backgrounds: string[],
 	 *                  can-upload-background: bool,
+	 *                  sip-enabled: bool,
+	 *                  sip-dialout-enabled: bool,
+	 *                  can-enable-sip: bool,
 	 *              },
 	 *              chat: array{
 	 *                  max-length: int,
@@ -166,6 +169,7 @@ public function getCapabilities(): array {
 				'session-state',
 				'note-to-self',
 				'recording-consent',
+				'sip-support-dialout',
 			],
 			'config' => [
 				'attachments' => [
@@ -177,6 +181,8 @@ public function getCapabilities(): array {
 					'recording' => $this->talkConfig->isRecordingEnabled(),
 					'recording-consent' => $this->talkConfig->recordingConsentRequired(),
 					'supported-reactions' => ['❤️', '🎉', '👏', '👍', '👎', '😂', '🤩', '🤔', '😲', '😥'],
+					'sip-enabled' => $this->talkConfig->isSIPConfigured(),
+					'sip-dialout-enabled' => $this->talkConfig->isSIPDialOutEnabled(),
 				],
 				'chat' => [
 					'max-length' => ChatManager::MAX_CHAT_LENGTH,
@@ -260,8 +266,10 @@ public function getCapabilities(): array {
 				$quota = Util::computerFileSize($quota);
 			}
 			$capabilities['config']['call']['can-upload-background'] = $quota === 'none' || $quota > 0;
+			$capabilities['config']['call']['can-enable-sip'] = $this->talkConfig->canUserEnableSIP($user);
 		} else {
 			$capabilities['config']['call']['can-upload-background'] = false;
+			$capabilities['config']['call']['can-enable-sip'] = false;
 		}
 
 		return [