Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions examples/socket/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ Socket Mode bots should not be submitted to Marketplace for publishing.

- **Enabling Socket Mode** — `App(socket_mode=True)` for WebSocket inbound delivery with no HTTP endpoint.
- **Multi-geo by default** — a single bot opens one connection per geo
(`amer`, `emea`, `apac`) so it has inbound coverage across regions. Override
with `geos=[...]` or point at a custom ring with `negotiate_base_url`.
(`amer`, `emea`, `apac`) so it has inbound coverage across regions.
Comment thread
Copilot marked this conversation as resolved.
Resolved
- **New bots only** — Socket Mode is currently available only for new bots.
Comment thread
teddyam marked this conversation as resolved.
Resolved
- **Lifecycle events** — subscribing to `app.socket_mode.events` for `ready`,
`disconnected`, and `reconnected`. Each event carries the `geo` it relates to,
since connections are per geo. Reconnects are automatic when `terminal=False`.
Expand Down Expand Up @@ -60,10 +60,5 @@ You should see per-geo `ready` logs as each connection comes up, then `you said

- **No HTTP surface** — tabs, remote functions, OAuth callbacks, and other
browser routes are unavailable in Socket Mode.
- **Canary and Pilot1 endpoints** — Socket Mode is currently available only on
the Canary (`https://canary.botapi.skype.com`) and Pilot1
(`https://pilot1.botapi.skype.com`) rings; the production default returns
503. The sample sets `negotiate_base_url` to the canary ring, but Pilot1 works
too. Remove the override when production is enabled.
- **Classic bot identity only** — Socket Mode connects with the bot's MSA App Id.
Agentic identities are not supported today.
9 changes: 1 addition & 8 deletions examples/socket/src/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
ActivityContext,
App,
SocketModeDisconnectedEvent,
SocketModeOptions,
SocketModeReadyEvent,
SocketModeReconnectedEvent,
)
Expand All @@ -25,13 +24,7 @@
logging.getLogger("microsoft_teams.apps.socket_mode").setLevel(logging.DEBUG)
logger = logging.getLogger(__name__)

app = App(
socket_mode=SocketModeOptions(
# Socket Mode is only available on the Canary and Pilot1 rings for now.
# Pilot1 (https://pilot1.botapi.skype.com) is supported as well.
negotiate_base_url="https://canary.botapi.skype.com",
)
)
app = App(socket_mode=True)


# Handlers are transport-agnostic: the exact same code works over HTTP or Socket Mode.
Expand Down
1 change: 1 addition & 0 deletions packages/apps/src/microsoft_teams/apps/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,7 @@ def socket_mode(self) -> Optional[SocketModeAdapter]:
"""The experimental Socket Mode adapter when enabled, else ``None``.

Exposes ``status``, ``geo_statuses``, and ``events`` for observing the connection.
Socket Mode is currently only available for new bots.
This API is in preview and may change in the future; recommended only for development.
Diagnostic: ExperimentalTeamsSocketMode
"""
Expand Down
2 changes: 2 additions & 0 deletions packages/apps/src/microsoft_teams/apps/options.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ class AppOptions(TypedDict, total=False):
have no listener to serve them. Mutually exclusive with ``http_server_adapter``,
and supported only in the public cloud.

Socket Mode is currently only available for new bots.
This API is in preview and may change in the future; recommended only for development.
Diagnostic: ExperimentalTeamsSocketMode
"""
Expand Down Expand Up @@ -240,6 +241,7 @@ class InternalAppOptions:
socket_mode: Optional[Union[bool, SocketModeOptions]] = None
"""Experimental: receive activities over an outbound WebSocket instead of an inbound HTTPS endpoint.

Socket Mode is currently only available for new bots.
This API is in preview and may change in the future; recommended only for development.
Diagnostic: ExperimentalTeamsSocketMode
"""
Expand Down
10 changes: 8 additions & 2 deletions packages/apps/src/microsoft_teams/apps/socket_mode/adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -82,15 +82,20 @@ class SocketModeOptions:
Preview configuration for the Socket Mode negotiate URL and geographies; may change in the future.

WebSocket is only recommended for use when developing agents.
Socket Mode is currently only available for new bots.
Diagnostic: ExperimentalTeamsSocketMode
"""

negotiate_base_url: str = DEFAULT_SOCKET_MODE_NEGOTIATE_BASE_URL
"""Service host used to negotiate the connection."""
"""
Service host used to negotiate the connection. Defaults to ``https://botapi.skype.com``.
Override this to target a different Teams backend service ring.
"""

geos: Sequence[str] = DEFAULT_GEOS
"""
Geographies to connect, one independent socket each. Every one must connect for
Geographies to connect, one independent socket each. Defaults to ``("amer", "emea", "apac")``;
override this to select the geographies to connect to. Every one must connect for
``start()`` to succeed, after which each is supervised on its own.
"""

Expand Down Expand Up @@ -140,6 +145,7 @@ class SocketModeAdapter:

This API is in preview and may change in the future.
WebSocket is only recommended for use when developing agents.
Socket Mode is currently only available for new bots.
Diagnostic: ExperimentalTeamsSocketMode
"""

Expand Down
8 changes: 4 additions & 4 deletions packages/apps/tests/test_socket_mode_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -442,13 +442,13 @@ def test_options_defaults_preserve_transport_policy():
def test_options_map_onto_transport_options():
geos = ["amer"]
options = SocketModeOptions(
negotiate_base_url="https://canary.botapi.skype.com",
negotiate_base_url="https://botapi.example",
geos=geos,
)
transport_options = options.to_transport_options()
geos.append("emea")

assert transport_options.negotiate_base_url == "https://canary.botapi.skype.com"
assert transport_options.negotiate_base_url == "https://botapi.example"
assert transport_options.geos == ("amer",)


Expand Down Expand Up @@ -532,12 +532,12 @@ def test_app_socket_mode_options_are_honoured():
client_id="client",
client_secret="secret",
tenant_id="tenant",
socket_mode=SocketModeOptions(negotiate_base_url="https://canary.botapi.skype.com", geos=("amer",)),
socket_mode=SocketModeOptions(negotiate_base_url="https://botapi.example", geos=("amer",)),
)

assert app.socket_mode is not None
assert app.socket_mode.geo_list == ("amer",)
assert app.socket_mode.negotiate_url == "https://canary.botapi.skype.com/amer/v3/websockets/connect"
assert app.socket_mode.negotiate_url == "https://botapi.example/amer/v3/websockets/connect"


def test_app_rejects_socket_mode_with_a_custom_http_adapter():
Expand Down
Loading