Introduce Bird module with API integration for voice calls and number management, along with configurable channelId and workplaceId.

2026-03-09 10:18:16 +01:00
parent 16bcc3a00c
commit 682bf8151c
3 changed files with 123 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Bird Module
+
+This module provides Bird API integration for voice calls and number management.
+
+## Endpoints
+
+### Voice calls
+- `POST /bird/voice/calls`
+  - Permission: `modules_bird_voice_calls_create`
+  - Required: `workspaceId`, `channelId`
+  - Body: passthrough to Bird call create API (except `workspaceId` and `channelId`).
+
+- `GET /bird/voice/calls`
+  - Permission: `modules_bird_voice_calls_list`
+  - Required query: `workspaceId`, `channelId`
+  - Query params are passed through to Bird.
+
+- `GET /bird/voice/calls/{id}`
+  - Permission: `modules_bird_voice_calls_get`
+  - Required query: `workspaceId`, `channelId`
+
+- `POST /bird/voice/calls/{id}/hangup`
+  - Permission: `modules_bird_voice_calls_hangup`
+  - Required: `workspaceId`, `channelId`
+
+- `POST /bird/voice/calls/test-outbound`
+  - Permission: `modules_bird_voice_calls_test_outbound`
+  - Required: `workspaceId`, `channelId`
+  - Places an outbound call to the fixed test number `+45 42 33 11 28` (`+4542331128`), polls call state, and sends hangup when state is `accepted` or `ongoing`.
+  - Optional tuning params:
+    - `pollIntervalSeconds` (default `2`)
+    - `maxPollSeconds` (default `30`)
+    - `hangupCause`
+
+### Numbers
+- `GET /bird/numbers`
+  - Permission: `modules_bird_numbers_list`
+  - Optional query: `workspaceId` (if not configured)
+  - Query params are passed through to Bird.
+
+- `GET /bird/numbers/{id}`
+  - Permission: `modules_bird_numbers_get`
+  - Optional query: `workspaceId` (if not configured)
+
+- `DELETE /bird/numbers/{id}`
+  - Permission: `modules_bird_numbers_delete`
+  - Optional query/body: `workspaceId` (if not configured)
+  - Releases/deletes a number if supported by Bird account policy.
+
+## Logging
+
+Bird requests are logged through `logs_o` with module `bird`, including:
+- Request start (`BIRD_HTTP_REQUEST`)
+- Response status (`BIRD_HTTP_RESPONSE`)
+- API or transport errors (`BIRD_HTTP_ERROR`, `BIRD_HTTP_CURL_ERROR`)
+- Test outbound flow events (`BIRD_TEST_OUTBOUND_CALL_*`)
+
+## Notes
+
+- Bird credentials and base URL are configured in Bird module config.
+- Route handlers enforce workspace/channel requirements before outbound API calls.
@@ -0,0 +1,31 @@
+<?php
+
+namespace bird\config;
+
+require_once WD . '/traits/module_config_variable_t.php';
+
+use Exception;
+use traits\module_config_variable;
+
+class bird_channelId_c
+{
+    use module_config_variable;
+
+    /**
+     * @throws Exception
+     */
+    public function __construct()
+    {
+        self::setupConfigVariable(
+            'bird',
+            'channelId',
+            'string',
+            false,
+            null,
+            'Default Bird channel identifier',
+            'channel_123',
+            false,
+            ''
+        );
+    }
+}
@@ -0,0 +1,31 @@
+<?php
+
+namespace bird\config;
+
+require_once WD . '/traits/module_config_variable_t.php';
+
+use Exception;
+use traits\module_config_variable;
+
+class bird_workplaceId_c
+{
+    use module_config_variable;
+
+    /**
+     * @throws Exception
+     */
+    public function __construct()
+    {
+        self::setupConfigVariable(
+            'bird',
+            'workplaceId',
+            'string',
+            false,
+            null,
+            'Default Bird workplace identifier',
+            'workplace_123',
+            false,
+            ''
+        );
+    }
+}