dial-agentframework 0.14.0__tar.gz → 0.16.0__tar.gz

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/PKG-INFO

@@ -1,10 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dial-agentframework
-Version: 0.14.0
+Version: 0.16.0
 Summary: Official Dial tools for the Microsoft Agent Framework — phone numbers, SMS, OTP, and voice calls
 Requires-Python: >=3.11
 Requires-Dist: agent-framework-core>=1.0
-Requires-Dist: dial-sdk>=0.16.0
+Requires-Dist: dial-sdk>=0.22.0
 Description-Content-Type: text/markdown
 
 # dial-agentframework

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/dial_agentframework/__init__.py

@@ -4,6 +4,7 @@ from .tools import (
     purchase_number_tool,
     set_number_properties_tool,
     list_messages_tool,
+    list_groups_tool,
     send_message_tool,
     reply_to_message_tool,
     start_typing_tool,
@@ -21,6 +22,7 @@ __all__ = [
     "purchase_number_tool",
     "set_number_properties_tool",
     "list_messages_tool",
+    "list_groups_tool",
     "send_message_tool",
     "reply_to_message_tool",
     "start_typing_tool",

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/dial_agentframework/tools.py

@@ -76,6 +76,12 @@ def purchase_number_tool(client: DialClient) -> FunctionTool:
             "Voice gender for inbound calls to the new number: 'male' or 'female'. "
             "Omit to use the default female voice.",
         ] = None,
+        inbound_language: Annotated[
+            Optional[str],
+            "BCP-47 language tag (e.g. 'es-ES') pinning inbound calls to this number to "
+            "one language. Omit to detect the language from the caller's country prefix "
+            "on each call.",
+        ] = None,
         area_code: Annotated[
             Optional[str],
             "Preferred US area code to provision in, e.g. '415'. Omit for any available "
@@ -94,6 +100,7 @@ def purchase_number_tool(client: DialClient) -> FunctionTool:
                 explicit_programmatic_consent=explicit_programmatic_consent,
                 area_code=area_code,
                 inbound_voice_gender=inbound_voice_gender,
+                inbound_language=inbound_language,
                 include_imessage=include_imessage,
             )
         )
@@ -108,7 +115,8 @@ def set_number_properties_tool(client: DialClient) -> FunctionTool:
         description=(
             "Update a Dial phone number's properties: its inbound instruction (the system "
             "prompt its AI voice agent uses on inbound calls) and/or its nickname. "
-            "Provide at least one."
+            "On iMessage numbers you can also set the display identity (first/last name "
+            "and avatar photo) shown to recipients. Provide at least one."
         ),
     )
     async def set_number_properties(
@@ -121,6 +129,12 @@ def set_number_properties_tool(client: DialClient) -> FunctionTool:
             "Voice gender for inbound calls to this number: 'male' or 'female'. "
             "Pass an empty string to clear it (reverts to the default, female).",
         ] = None,
+        inbound_language: Annotated[
+            Optional[str],
+            "BCP-47 language tag (e.g. 'es-ES') pinning inbound calls to this number to "
+            "one language. Pass an empty string to clear it (reverts to detecting the "
+            "language from the caller's country prefix on each call).",
+        ] = None,
         nickname: Annotated[
             Optional[str],
             "Human-readable label for the number, e.g. 'Support line'. "
@@ -132,6 +146,24 @@ def set_number_properties_tool(client: DialClient) -> FunctionTool:
             "ceiling to both inbound and outbound calls. The effective cap on a call is "
             "the smallest of the per-number, account, and per-call limits.",
         ] = None,
+        first_name: Annotated[
+            Optional[str],
+            "First name of the iMessage display identity — the name shown beside this "
+            "number's messages in recipients' Messages apps. iMessage numbers only "
+            "(400 otherwise). Max 30 chars; pass an empty string to clear it.",
+        ] = None,
+        last_name: Annotated[
+            Optional[str],
+            "Last name of the iMessage display identity, shown beside first_name. "
+            "iMessage numbers only (400 otherwise). Max 30 chars; pass an empty string "
+            "to clear it.",
+        ] = None,
+        avatar_url: Annotated[
+            Optional[str],
+            "Public URL of a jpeg/png/gif/webp image (≤5 MB) the server downloads to use "
+            "as the number's iMessage display photo. iMessage numbers only (400 "
+            "otherwise). The photo can be replaced but not removed.",
+        ] = None,
     ) -> str:
         kwargs: dict = {}
         if inbound_instruction is not None:
@@ -139,14 +171,27 @@ def set_number_properties_tool(client: DialClient) -> FunctionTool:
         # Empty string clears the override (reverts to the default, female); else set it.
         if inbound_voice_gender is not None:
             kwargs["inbound_voice_gender"] = inbound_voice_gender or None
+        # Empty string clears the pin (reverts to per-call detection from the caller's country prefix); else set it.
+        if inbound_language is not None:
+            kwargs["inbound_language"] = inbound_language or None
         if nickname is not None:
             kwargs["nickname"] = nickname
         if max_call_duration_seconds is not None:
             kwargs["max_call_duration_seconds"] = max_call_duration_seconds
+        # Only forward names the caller actually provided — the client leaves them
+        # untouched when unset, but forwarding None would clear the existing name.
+        # An empty string is forwarded intentionally to clear the name.
+        if first_name is not None:
+            kwargs["first_name"] = first_name
+        if last_name is not None:
+            kwargs["last_name"] = last_name
+        if avatar_url is not None:
+            kwargs["avatar"] = avatar_url
         if not kwargs:
             return (
                 "Provide at least one of inbound_instruction, inbound_voice_gender, "
-                "nickname, or max_call_duration_seconds."
+                "inbound_language, nickname, max_call_duration_seconds, first_name, "
+                "last_name, or avatar_url."
             )
         number = await client.set_number_properties(number_id, **kwargs)
         nick = f' | nickname: "{number.nickname}"' if number.nickname else ""
@@ -161,7 +206,10 @@ def set_number_properties_tool(client: DialClient) -> FunctionTool:
 def list_messages_tool(client: DialClient) -> FunctionTool:
     @tool(
         name="list_messages",
-        description="List recent inbound and outbound messages on the account.",
+        description=(
+            "List recent inbound and outbound messages on the account. Pass group_id "
+            "to read one group conversation."
+        ),
     )
     async def list_messages(
         number_id: Annotated[
@@ -170,28 +218,73 @@ def list_messages_tool(client: DialClient) -> FunctionTool:
         direction: Annotated[
             Optional[str], "Filter by direction: 'inbound' or 'outbound'"
         ] = None,
+        group_id: Annotated[
+            Optional[str],
+            "Restrict to one group conversation (from list_groups). Combines with the "
+            "other filters.",
+        ] = None,
     ) -> str:
-        messages = await client.list_messages(number_id=number_id, direction=direction)
+        messages = await client.list_messages(
+            number_id=number_id, direction=direction, group_id=group_id
+        )
         if not messages:
             return "No messages found."
+        # A group message has no `to` — the destination is the group — so name the
+        # group rather than rendering "None" at the recipient.
         return "\n".join(
-            f"[{m.direction}] {m.from_} → {m.to}: {m.body[:50]}" for m in messages
+            f"[{m.direction}] {m.from_} → {m.to or f'group {m.group_id}'}: {m.body[:50]}"
+            for m in messages
         )
 
     return list_messages
 
 
+def list_groups_tool(client: DialClient) -> FunctionTool:
+    @tool(
+        name="list_groups",
+        description=(
+            "List the group conversations your lines are in. A group is a conversation "
+            "that isn't a phone number, so it has an id of its own: pass it as group_id "
+            "to send_message, or to list_messages to read that conversation. Groups "
+            "exist on WhatsApp lines. A group's name can be empty — it is read live "
+            "from the line holding the conversation, so a line that can't answer in "
+            "time yields no name rather than hiding the group. There is no join event: "
+            "list again to see a group your line was just added to."
+        ),
+    )
+    async def list_groups() -> str:
+        groups = await client.list_groups()
+        if not groups:
+            return "No groups found."
+        return "\n".join(
+            f"{g.id}: {g.name or '(unnamed)'} (since {g.created_at})" for g in groups
+        )
+
+    return list_groups
+
+
 def send_message_tool(client: DialClient) -> FunctionTool:
     @tool(
         name="send_message",
         description=(
-            "Send a message to a phone number, optionally with media attachments (MMS). "
-            "On an iMessage number, a single audio attachment is delivered as a voice "
-            "message unless force_audio_file is true."
+            "Send a message to a phone number or into a group conversation, optionally "
+            "with media attachments (MMS). On an iMessage number, a single audio "
+            "attachment is delivered as a voice message unless force_audio_file is "
+            "true. Address it with exactly one of to or group_id."
         ),
     )
     async def send_message(
-        to: Annotated[str, "Destination phone number in E.164 format, e.g. +1234567890"],
+        to: Annotated[
+            str,
+            "Destination phone number in E.164 format, e.g. +1234567890. Provide "
+            "exactly one of to or group_id.",
+        ] = "",
+        group_id: Annotated[
+            Optional[str],
+            "A group conversation to send into (from list_groups), instead of a `to` "
+            "number. The sending line comes from the group, so no from-number is "
+            "needed. Provide exactly one of to or group_id.",
+        ] = None,
         from_number: Annotated[
             Optional[str],
             "Number to send from: a phone number ID, one of your numbers in E.164, or "
@@ -205,7 +298,12 @@ def send_message_tool(client: DialClient) -> FunctionTool:
         body: Annotated[
             str, "Message body text; optional when media_urls is given (media-only send)"
         ] = "",
-        channel: Annotated[str, "Channel to use: 'sms'"] = "sms",
+        channel: Annotated[
+            Optional[str],
+            "Which channel to send on, for a line that carries more than one: "
+            "'imessage' or 'whatsapp'. Omit to use the number's own default. "
+            "WhatsApp sends are text-only.",
+        ] = None,
         media_urls: Annotated[
             Optional[list[str]],
             "Publicly reachable http(s) URLs of media to attach (MMS), max 10. "
@@ -220,6 +318,7 @@ def send_message_tool(client: DialClient) -> FunctionTool:
         msg = await client.send_message(
             SendMessageParams(
                 to=to,
+                group_id=group_id,
                 from_number=from_number,
                 from_number_id=from_number_id,
                 body=body,
@@ -294,8 +393,16 @@ def start_typing_tool(client: DialClient) -> FunctionTool:
             "Number the indicator appears from: a phone number ID, one of your numbers "
             "in E.164, or a nickname",
         ],
+        channel: Annotated[
+            Optional[str],
+            "Which channel to show it on, for a line that carries more than one: "
+            "'imessage' or 'whatsapp'. Omit to use the number's own default. Typing "
+            "inside a group is not supported.",
+        ] = None,
     ) -> str:
-        await client.start_typing(to_number=to_number, from_number=from_number)
+        await client.start_typing(
+            to_number=to_number, from_number=from_number, channel=channel
+        )
         return "Typing indicator shown (iMessage numbers only — SMS numbers ignore it)."
 
     return start_typing
@@ -319,8 +426,14 @@ def stop_typing_tool(client: DialClient) -> FunctionTool:
             "Number the indicator appears from: a phone number ID, one of your numbers "
             "in E.164, or a nickname",
         ],
+        channel: Annotated[
+            Optional[str],
+            "Which channel to clear it on. Pass the same channel start_typing was given.",
+        ] = None,
     ) -> str:
-        await client.stop_typing(to_number=to_number, from_number=from_number)
+        await client.stop_typing(
+            to_number=to_number, from_number=from_number, channel=channel
+        )
         return "Typing indicator cleared."
 
     return stop_typing
@@ -541,6 +654,7 @@ def dial_tools(client: DialClient) -> list[FunctionTool]:
         purchase_number_tool(client),
         set_number_properties_tool(client),
         list_messages_tool(client),
+        list_groups_tool(client),
         send_message_tool(client),
         reply_to_message_tool(client),
         start_typing_tool(client),

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dial-agentframework"
-version = "0.14.0"
+version = "0.16.0"
 description = "Official Dial tools for the Microsoft Agent Framework — phone numbers, SMS, OTP, and voice calls"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -8,7 +8,7 @@ dependencies = [
     # Core has `tool` + `FunctionTool` (all this package needs). Chat clients ship in
     # separate integration packages (agent-framework-openai, …) the user installs.
     "agent-framework-core>=1.0",
-    "dial-sdk>=0.16.0",
+    "dial-sdk>=0.22.0",
 ]
 
 [tool.uv.sources]

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/tests/test_tools.py

@@ -3,12 +3,14 @@ import asyncio
 from dial_agentframework import (
     dial_tools,
     purchase_number_tool,
+    set_number_properties_tool,
     send_message_tool,
     reply_to_message_tool,
     make_call_tool,
     start_typing_tool,
     stop_typing_tool,
     wait_for_message_tool,
+    list_groups_tool,
 )
 
 
@@ -30,6 +32,7 @@ class _FakeNumber:
     id = "pn_new"
     number = "+14155550000"
     country = "US"
+    nickname = None
 
 
 class FakeClient:
@@ -57,7 +60,7 @@ def _run(tool, **args) -> str:
 # ── Tools ────────────────────────────────────────────────────────────────────
 
 
-def test_dial_tools_bundles_all_thirteen():
+def test_dial_tools_bundles_all_fourteen():
     names = sorted(t.name for t in dial_tools(FakeClient()))
     assert names == sorted(
         [
@@ -65,6 +68,7 @@ def test_dial_tools_bundles_all_thirteen():
             "purchase_number",
             "set_number_properties",
             "list_messages",
+            "list_groups",
             "send_message",
             "reply_to_message",
             "start_typing",
@@ -128,7 +132,48 @@ def test_start_typing_invokes_client():
     assert "Typing indicator shown" in out
     call = client.calls["start_typing"]
     assert call["args"] == ()
-    assert call["kwargs"] == {"to_number": "+14155550123", "from_number": "pn_9"}
+    assert call["kwargs"] == {
+        "to_number": "+14155550123",
+        "from_number": "pn_9",
+        "channel": None,
+    }
+
+
+def test_typing_forwards_an_explicit_channel():
+    client = FakeClient(start_typing=None)
+    _run(start_typing_tool(client), to_number="+14155550123", from_number="pn_9", channel="whatsapp")
+    assert client.calls["start_typing"]["kwargs"]["channel"] == "whatsapp"
+
+
+def test_send_message_into_a_group():
+    client = FakeClient(send_message=_FakeMessage())
+    out = _run(send_message_tool(client), group_id="grp_1", body="hi")
+
+    assert "Message sent successfully" in out
+    params = client.calls["send_message"]["args"][0]
+    assert params.group_id == "grp_1"
+    # A group send names no recipient number: the group is the destination.
+    assert params.to == ""
+
+
+def test_list_groups_renders_ids_names_and_an_unnamed_group():
+    class _FakeGroup:
+        def __init__(self, id, name, created_at):
+            self.id = id
+            self.name = name
+            self.created_at = created_at
+
+    client = FakeClient(
+        list_groups=[
+            _FakeGroup("grp_1", "Planning bday party", "2026-09-01T00:00:00Z"),
+            _FakeGroup("grp_2", None, "2026-09-02T00:00:00Z"),
+        ]
+    )
+    out = _run(list_groups_tool(client))
+
+    assert "grp_1: Planning bday party" in out
+    # A group no line could name is still listed — never hidden.
+    assert "grp_2: (unnamed)" in out
 
 
 def test_stop_typing_invokes_client():
@@ -143,6 +188,7 @@ def test_stop_typing_invokes_client():
     assert call["kwargs"] == {
         "to_number": "+14155550123",
         "from_number": "+14155559999",
+        "channel": None,
     }
 
 
@@ -195,10 +241,56 @@ def test_purchase_number_include_imessage():
         inbound_instruction="Greet the caller.",
         explicit_programmatic_consent="Account holder approved programmatic provisioning.",
         include_imessage=True,
+        inbound_language="es-ES",
     )
 
     params = client.calls["purchase_number"]["args"][0]
     assert params.include_imessage is True
+    assert params.inbound_language == "es-ES"
+
+
+def test_set_number_properties_forwards_display_identity():
+    client = FakeClient(set_number_properties=_FakeNumber())
+    tool = set_number_properties_tool(client)
+    out = _run(
+        tool,
+        number_id="pn_9",
+        first_name="Ada",
+        last_name="Lovelace",
+        avatar_url="https://cdn.example.com/ada.png",
+    )
+
+    assert "pn_new" in out
+    call = client.calls["set_number_properties"]
+    assert call["args"] == ("pn_9",)
+    assert call["kwargs"]["first_name"] == "Ada"
+    assert call["kwargs"]["last_name"] == "Lovelace"
+    # avatar_url forwards to the client's `avatar` param (a URL string).
+    assert call["kwargs"]["avatar"] == "https://cdn.example.com/ada.png"
+
+
+def test_set_number_properties_empty_name_clears():
+    # An explicit empty string is forwarded (the server clears the name); it must
+    # not be swallowed like an omitted argument.
+    client = FakeClient(set_number_properties=_FakeNumber())
+    tool = set_number_properties_tool(client)
+    _run(tool, number_id="pn_9", first_name="")
+
+    assert client.calls["set_number_properties"]["kwargs"]["first_name"] == ""
+
+
+def test_set_number_properties_omits_unprovided_name_fields():
+    # Not passing first_name/last_name/avatar_url must NOT forward them — the client
+    # uses an _UNSET sentinel and forwarding None would clear the existing identity.
+    client = FakeClient(set_number_properties=_FakeNumber())
+    tool = set_number_properties_tool(client)
+    _run(tool, number_id="pn_9", nickname="Support")
+
+    kwargs = client.calls["set_number_properties"]["kwargs"]
+    assert "first_name" not in kwargs
+    assert "last_name" not in kwargs
+    assert "avatar" not in kwargs
+    assert kwargs["nickname"] == "Support"
 
 
 def test_make_call_passes_idempotency_key():

{dial_agentframework-0.14.0 → dial_agentframework-0.16.0}/uv.lock

@@ -345,7 +345,7 @@ wheels = [
 
 [[package]]
 name = "dial-agentframework"
-version = "0.14.0"
+version = "0.16.0"
 source = { editable = "." }
 dependencies = [
     { name = "agent-framework-core" },
@@ -368,7 +368,7 @@ dev = [{ name = "pytest", specifier = ">=8" }]
 
 [[package]]
 name = "dial-sdk"
-version = "0.16.0"
+version = "0.22.0"
 source = { editable = "../sdk-python" }
 dependencies = [
     { name = "httpx" },