@mhome/messaging-protocol 0.14.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) MHOME AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# mhome-messaging-api
+
+Transport-neutral control and normalized data-plane contracts for messaging providers. The crate
+owns typed Rust DTOs, target and capability inventories, strict JSON Schemas, and cross-language
+conformance fixtures.
+
+The common contract deliberately treats `data`, `providerData`, `options`, and `result` as provider
+extension objects. Their contents are decoded and validated by the selected provider; all fields
+outside those explicit extension points are closed and versioned here.
+
+Conformance frames contain `target`, `direction`, and `body`. `direction` is part of the contract
+artifact used by tests and generators; the surrounding MWS transport continues to carry request and
+response correlation.
+
+`control` models the MWS management API. `model` defines the canonical provider-independent address,
+external actor, and inbound content semantics implemented independently by local Rust and cloud
+Java runtimes. Neither module contains provider SDKs, transport callbacks, runtime lifecycle,
+persistence, or Agent integration.
+
+`commands` owns the small provider-independent chat command grammar. `/info`, `/help`, `/new`,
+`/clear`, and `/switch N` have identical parsing semantics in every runtime. Scope choices are
+ordered by their stable `scopeId`; providers remain free to render the resulting labels in their
+native format. The published command corpus is the cross-language source of truth.
+
+Every normalized message carries provider-neutral attention evidence: `addressed` means the
+provider determined that the bot was explicitly targeted, `unaddressed` means it determined the
+opposite, and `unknown` means the provider has no equivalent signal. Provider adapters extract this
+evidence; common runtimes ignore only `unaddressed` messages on shared surfaces. Personal messages,
+actions, and providers with unknown attention continue through the normal pipeline.
+
+Interactive delivery is modeled as an `ActionSet` of user-facing labels and opaque tokens. An
+inbound selection contains only `ActionSelected { token }`; approval decisions, dialog values, and
+provider callback payloads stay in runtime-owned route stores. Setup claims and account lifecycle
+are framework application ports rather than chat content, so they are intentionally not part of
+this public normalized data plane.
+
+Shared-conversation discovery, group binding challenges, and self-service actor links are common
+management operations. Actor-link challenges explicitly target either a personal conversation or
+one already-bound shared surface. A shared `/link` command records an immutable external-actor
+candidate and requires confirmation by the authenticated challenge creator; a personal command may
+complete immediately. Status is the recovery source of truth and the matching event target is only
+a realtime hint. Challenge requests never carry a target user: each runtime derives the user from
+its authenticated request context, authorizes scope ownership or membership, and stores only a
+short-lived one-time code hash. Provider adapters remain responsible only for translating provider
+events and sending provider-native replies.
+
+A personal route belongs to one linked mHome user. Its `scopeId` is only the conversation's current
+scope: authorization comes from live scope membership, and `/switch` may move it to any scope the
+user still belongs to. Personal routes never depend on an account grant.
+
+A shared account grant authorizes one provider account to serve one scope. It has no beneficiary
+user and no default flag; `grantedByUserId` is audit metadata. Every shared route is fixed to one
+scope, depends on the matching shared account grant, and cannot switch scopes. Current scope owners
+manage grants and shared routes. Any linked actor who is still a member of the bound scope may answer
+a shared interaction, while personal interactions remain restricted to the personal route owner.
+Routes deliberately address the provider's base conversation only; lane identity remains on each
+normalized address and canonical Conversation surface so topic-level threads do not multiply
+authorization records.
+
+Setup is provider-extensible but has a common lifecycle. A completed setup may return both the
+created provider `accountId` and the initial personal `routeId`; providers that only configure an
+account omit `routeId` until the first inbound conversation creates the route.
+
+Actor links are provider-account-scoped identities. One exact external identity maps to at most one
+mHome principal, while a principal may own any number of external identities across or within
+provider accounts. Actor-link management therefore targets an account, never a conversation
+surface; shared-surface binding remains a separate scope relationship.
+
+`fixtures/normalized-inbound.conformance.json` is the executable cross-language corpus. Every
+runtime implementation must accept every `valid` case and reject every `invalid` case; adding a
+content variant or validation rule requires updating this corpus in the same change.

package/fixtures/actor-link-claim-confirm.request.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-claim/confirm","direction":"request","body":{"provider":"telegram","placement":"local","challengeId":"challenge_01"}}

package/fixtures/actor-link-claim-confirm.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-claim/confirm","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"completed","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"},"linkId":"link_42"}}}}

package/fixtures/actor-link-claim-event.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-claim/event","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"awaiting_confirmation","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"}}}}}

package/fixtures/actor-link-claim-status.request.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-claim/status","direction":"request","body":{"provider":"telegram","placement":"local","challengeId":"challenge_01"}}

package/fixtures/actor-link-claim-status.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-claim/status","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"awaiting_confirmation","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"}}}}}

package/fixtures/actor-link-code-create.request.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-code/create","direction":"request","body":{"provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"}}}

package/fixtures/actor-link-code-create.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link-code/create","direction":"response","body":{"challenge":{"challengeId":"challenge_01","code":"P4V8N6","command":"/link P4V8N6","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000}}}

package/fixtures/actor-link-delete.request.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link/delete","direction":"request","body":{"provider":"telegram","placement":"local","linkId":"link_a"}}

package/fixtures/actor-link-delete.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link/delete","direction":"response","body":{"success":true}}

package/fixtures/actor-link-list.request.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link/list","direction":"request","body":{"provider":"telegram","placement":"local","accountId":"bot_a"}}

package/fixtures/actor-link-list.response.json

@@ -0,0 +1 @@
+{"target":"/messaging/actor/link/list","direction":"response","body":{"links":[{"linkId":"link_a","provider":"telegram","placement":"local","accountId":"bot_a","externalUserId":"user_42","displayName":"Alice","createdAtMs":1720000000000,"updatedAtMs":1720000000000}]}}

package/fixtures/invalid/mismatched-direction.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/shared-account-grant/create",
+  "direction": "response",
+  "body": { "provider": "telegram", "placement": "local", "accountId": "123456" }
+}

package/fixtures/invalid/missing-required-extension.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/test",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/invalid/unknown-request-field.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "unexpected": true }
+}

package/fixtures/messaging-commands.conformance.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "parseCases": [
+    { "name": "info", "input": "/info", "result": { "kind": "command", "command": "info" } },
+    { "name": "case-insensitive-help", "input": " /HELP ", "result": { "kind": "command", "command": "help" } },
+    { "name": "new-rotates", "input": "/new", "result": { "kind": "command", "command": "rotate" } },
+    { "name": "clear-rotates", "input": "/clear", "result": { "kind": "command", "command": "rotate" } },
+    { "name": "spaced-switch", "input": "/switch 3", "result": { "kind": "command", "command": "switch", "selection": 3 } },
+    { "name": "compact-switch", "input": "/SWITCH2", "result": { "kind": "command", "command": "switch", "selection": 2 } },
+    { "name": "missing-switch-selection", "input": "/switch", "result": { "kind": "invalid_switch" } },
+    { "name": "zero-switch-selection", "input": "/switch 0", "result": { "kind": "invalid_switch" } },
+    { "name": "negative-switch-selection", "input": "/switch -1", "result": { "kind": "invalid_switch" } },
+    { "name": "unknown-text", "input": "hello", "result": { "kind": "not_command" } },
+    { "name": "unknown-command", "input": "/usage", "result": { "kind": "not_command" } }
+  ],
+  "orderingCases": [
+    { "name": "stable-scope-id-order", "scopeIds": ["scope-z", "scope-a", "scope-m"], "expected": ["scope-a", "scope-m", "scope-z"] },
+    { "name": "lexical-order-is-case-sensitive", "scopeIds": ["scope-b", "Scope-a"], "expected": ["Scope-a", "scope-b"] }
+  ]
+}

package/fixtures/normalized-inbound.conformance.json

@@ -0,0 +1,148 @@
+{
+  "valid": [
+    {
+      "name": "personal_text",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-personal-text",
+        "address": { "provider": "telegram", "accountId": "bot-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-1", "externalUserId": "user-1", "displayName": "User One" },
+        "content": { "type": "message", "providerMessageId": "message-1", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] },
+        "occurredAtMs": 1
+      }
+    },
+    {
+      "name": "shared_text_with_lane",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-shared-text",
+        "address": { "provider": "feishu", "accountId": "app-1", "conversationId": "group-1", "laneId": "thread-1", "audience": "shared" },
+        "actor": { "provider": "feishu", "accountId": "app-1", "externalUserId": "open-id-1" },
+        "content": { "type": "message", "attention": "addressed", "parts": [{ "type": "text", "text": "group hello" }] },
+        "conversationDisplayName": "Project room"
+      }
+    },
+    {
+      "name": "audio_with_transcript",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-audio",
+        "address": { "provider": "telegram", "accountId": "bot-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-1", "externalUserId": "user-1" },
+        "content": {
+          "type": "message",
+          "providerMessageId": "message-2",
+          "attention": "unknown",
+          "parts": [{ "type": "media", "reference": { "handle": "file-1", "kind": "audio", "mimeType": "audio/ogg", "durationMs": 1200, "transcript": "hello" } }]
+        }
+      }
+    },
+    {
+      "name": "action_selected",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-action-selected",
+        "address": { "provider": "feishu", "accountId": "app-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "feishu", "accountId": "app-1", "externalUserId": "open-id-1" },
+        "content": { "type": "action_selected", "token": "route-1" }
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "name": "provider_starts_with_digit",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "1telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "1telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "negative_occurrence_time",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] },
+        "occurredAtMs": -1
+      }
+    },
+    {
+      "name": "actor_account_mismatch",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot-a", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-b", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "empty_message",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [] }
+      }
+    },
+    {
+      "name": "incomplete_media_dimensions",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "media", "reference": { "handle": "file", "kind": "image", "widthPx": 100 } }] }
+      }
+    },
+    {
+      "name": "unknown_schema_version",
+      "value": {
+        "schemaVersion": 2,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "missing_message_attention",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "shared" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "too_many_message_parts",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": {
+          "type": "message",
+          "attention": "unknown",
+          "parts": [
+            { "type": "text", "text": "1" }, { "type": "text", "text": "2" },
+            { "type": "text", "text": "3" }, { "type": "text", "text": "4" },
+            { "type": "text", "text": "5" }, { "type": "text", "text": "6" },
+            { "type": "text", "text": "7" }, { "type": "text", "text": "8" },
+            { "type": "text", "text": "9" }, { "type": "text", "text": "10" },
+            { "type": "text", "text": "11" }, { "type": "text", "text": "12" },
+            { "type": "text", "text": "13" }, { "type": "text", "text": "14" },
+            { "type": "text", "text": "15" }, { "type": "text", "text": "16" },
+            { "type": "text", "text": "17" }
+          ]
+        }
+      }
+    }
+  ]
+}

package/fixtures/normalized-inbound.shared-text.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 4,
+  "eventId": "telegram:update:41",
+  "address": {
+    "provider": "telegram",
+    "accountId": "bot-7",
+    "conversationId": "chat-42",
+    "laneId": "topic-3",
+    "audience": "shared"
+  },
+  "actor": {
+    "provider": "telegram",
+    "accountId": "bot-7",
+    "externalUserId": "user-9",
+    "displayName": "Yihan"
+  },
+  "content": {
+    "type": "message",
+    "providerMessageId": "message-5",
+    "attention": "addressed",
+    "parts": [{ "type": "text", "text": "hello" }]
+  },
+  "conversationDisplayName": "Project room",
+  "occurredAtMs": 1787760000000
+}

package/fixtures/provider-account-delete.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/messaging/provider-account/delete",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "accountId": "123456"
+  }
+}

package/fixtures/provider-account-delete.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/delete",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/provider-account-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/provider-account-list.response.json

@@ -0,0 +1,21 @@
+{
+  "target": "/messaging/provider-account/list",
+  "direction": "response",
+  "body": {
+    "accounts": [
+      {
+        "provider": "telegram",
+        "placement": "local",
+        "accountId": "123456",
+        "ownership": "user",
+        "displayName": "Home bot",
+        "enabled": true,
+        "status": "connected",
+        "providerData": {
+          "botUsername": "home_bot",
+          "transport": "long_polling"
+        }
+      }
+    ]
+  }
+}

package/fixtures/provider-account-status.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/status",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/provider-account-status.response.json

@@ -0,0 +1,12 @@
+{
+  "target": "/messaging/provider-account/status",
+  "direction": "response",
+  "body": {
+    "status": {
+      "provider": "telegram",
+      "placement": "local",
+      "enabled": true,
+      "providerData": { "connected": 1 }
+    }
+  }
+}

package/fixtures/provider-account-test.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/test",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "data": { "botToken": "secret" } }
+}

package/fixtures/provider-account-test.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/provider-account/test",
+  "direction": "response",
+  "body": { "result": { "reachable": true } }
+}

package/fixtures/provider-account-update.request.json

@@ -0,0 +1,10 @@
+{
+  "target": "/messaging/provider-account/update",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "accountId": "123456",
+    "data": { "enabled": true }
+  }
+}

package/fixtures/provider-account-update.response.json

@@ -0,0 +1,15 @@
+{
+  "target": "/messaging/provider-account/update",
+  "direction": "response",
+  "body": {
+    "account": {
+      "provider": "telegram",
+      "placement": "local",
+      "accountId": "123456",
+      "ownership": "user",
+      "enabled": true,
+      "status": "connected",
+      "providerData": {}
+    }
+  }
+}

package/fixtures/provider-list.request.json

@@ -0,0 +1,14 @@
+{
+  "target": "/messaging/provider/list",
+  "direction": "request",
+  "body": {
+    "placement": "cloud",
+    "frontendProviders": [
+      {
+        "provider": "telegram",
+        "deprecated": false,
+        "supportedPlacements": ["cloud", "local"]
+      }
+    ]
+  }
+}

package/fixtures/provider-list.response.json

@@ -0,0 +1,31 @@
+{
+  "target": "/messaging/provider/list",
+  "direction": "response",
+  "body": {
+    "providers": [
+      {
+        "provider": "telegram",
+        "displayName": "Telegram",
+        "placement": "cloud",
+        "deprecated": false,
+        "available": true,
+        "setupFlow": "pairing_code",
+        "audiences": ["personal", "shared"],
+        "inboundCapabilities": ["text", "audio", "action"],
+        "outboundCapabilities": ["text", "markdown", "action"],
+        "deliveryMode": "unrestricted",
+        "managementOperations": [
+          "provider_account.list",
+          "provider_account.status",
+          "route.list",
+          "route.update",
+          "route.delete",
+          "setup.options",
+          "setup.start",
+          "setup.status"
+        ],
+        "providerData": {}
+      }
+    ]
+  }
+}

package/fixtures/route-delete.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/route/delete",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "cloud", "routeId": "route-1" }
+}

package/fixtures/route-delete.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/route/delete",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/route-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/route/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "cloud", "audience": "personal" }
+}

package/fixtures/route-list.response.json

@@ -0,0 +1,37 @@
+{
+  "target": "/messaging/route/list",
+  "direction": "response",
+  "body": {
+    "routes": [
+      {
+        "provider": "telegram",
+        "placement": "cloud",
+        "routeId": "route-1",
+        "accountId": "official-bot",
+        "conversationId": "chat-1",
+        "audience": "personal",
+        "externalActorId": "user-1",
+        "tenantId": "tenant-1",
+        "userId": "mhome-user-1",
+        "scopeId": "scope-1",
+        "displayName": "Telegram",
+        "enabled": true,
+        "providerData": {}
+      },
+      {
+        "provider": "feishu",
+        "placement": "local",
+        "routeId": "route-2",
+        "accountId": "app-1",
+        "conversationId": "chat-2",
+        "audience": "shared",
+        "tenantId": "tenant-1",
+        "scopeId": "scope-2",
+        "boundByUserId": "mhome-user-1",
+        "displayName": "Project room",
+        "enabled": true,
+        "providerData": {}
+      }
+    ]
+  }
+}

package/fixtures/route-update.request.json

@@ -0,0 +1,12 @@
+{
+  "target": "/messaging/route/update",
+  "direction": "request",
+  "body": {
+    "audience": "personal",
+    "provider": "telegram",
+    "placement": "cloud",
+    "routeId": "route-1",
+    "scopeId": "scope-1",
+    "enabled": false
+  }
+}

package/fixtures/route-update.response.json

@@ -0,0 +1,20 @@
+{
+  "target": "/messaging/route/update",
+  "direction": "response",
+  "body": {
+    "route": {
+      "provider": "telegram",
+      "placement": "cloud",
+      "routeId": "route-1",
+      "accountId": "official-bot",
+      "conversationId": "chat-1",
+      "audience": "personal",
+      "externalActorId": "user-1",
+      "tenantId": "tenant-1",
+      "userId": "mhome-user-1",
+      "scopeId": "scope-1",
+      "enabled": false,
+      "providerData": {}
+    }
+  }
+}

package/fixtures/setup-options.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/setup/options",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/setup-options.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/messaging/setup/options",
+  "direction": "response",
+  "body": { "options": { "tokenRequired": true } }
+}

package/fixtures/setup-start.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/messaging/setup/start",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "data": { "botToken": "secret" }
+  }
+}