From d9327985496081daf19b7a7a7542927a69bdcd30 Mon Sep 17 00:00:00 2001
From: Sujip Thapa <sudiptpa@gmail.com>
Date: Sat, 31 Oct 2026 12:43:52 +0545
Subject: [PATCH] fix(api): let channels.voice update() send an explicit null
 agent_id

PATCH /v3/channels/voice/{number}'s own docs give agent_id three
states: a value binds an agent, null unbinds it, and omitting the key
leaves the binding alone. VoiceService::update() builds its request
body through Util::removeNulls(), which strips every null field before
the request goes out - so calling update(agentID: null) produces the
same wire request as not passing agentID at all. There's no way to
unbind an agent through this method today.

Give agentID its own default, a new Omit marker (same role as the
Omit/omit sentinel the Python SDK already uses for this exact problem),
instead of null. A real null now survives into the request body;
leaving the parameter out still omits the key. Every other field on
this method keeps going through removeNulls() unchanged.

Confirmed live against the free voice-agent fields that have the same
null-is-meaningful contract (no phone number needed to test): the
typed update() method 400s today when passed an explicit null, while
raw->update() with a plain array already accepts and applies it. This
patch brings the typed method in line with what the API and its own
docblock already promise.
---
 src/Core/Omit.php                             | 18 ++++++
 .../Channels/VoiceContract.php                |  8 ++-
 src/Services/Channels/VoiceService.php        | 16 +++--
 tests/Services/Channels/VoiceTest.php         | 59 +++++++++++++++++++
 4 files changed, 94 insertions(+), 7 deletions(-)
 create mode 100644 src/Core/Omit.php

diff --git a/src/Core/Omit.php b/src/Core/Omit.php
new file mode 100644
index 000000000..aaaaec4ee
--- /dev/null
+++ b/src/Core/Omit.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SentDm\Core;
+
+/**
+ * Marks a body param the caller didn't pass, distinct from one they passed as `null`.
+ *
+ * Every optional body param already defaults to `null`, so a method can't otherwise tell
+ * "leave this field alone" from "clear this field" when the API gives the two a different
+ * meaning. Use this as the default instead of `null` for such a param, and check for it
+ * with `$value instanceof Omit` before building the request body. Same role as the
+ * `Omit`/`omit` sentinel the Python SDK already uses for the same problem.
+ */
+final class Omit
+{
+}
diff --git a/src/ServiceContracts/Channels/VoiceContract.php b/src/ServiceContracts/Channels/VoiceContract.php
index ae39b07c4..783e043c3 100644
--- a/src/ServiceContracts/Channels/VoiceContract.php
+++ b/src/ServiceContracts/Channels/VoiceContract.php
@@ -11,6 +11,7 @@
 use SentDm\Channels\Voice\APIResponseOfVoiceSecret;
 use SentDm\Channels\Voice\VoiceUpdateParams\Status;
 use SentDm\Core\Exceptions\APIException;
+use SentDm\Core\Omit;
 use SentDm\RequestOptions;
 
 /**
@@ -76,8 +77,9 @@ public function retrieve(
      * @api
      *
      * @param string $number Path param: The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100
-     * @param string|null $agentID Body param: One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to
-     * the number, or null to unbind it so the callback URL answers them again. The agent wins over
+     * @param string|null|Omit $agentID Body param: One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to
+     * the number, or null to unbind it so the callback URL answers them again. Leave this
+     * parameter out entirely to leave the current binding alone. The agent wins over
      * callback_url for calls to the number; calls your app places from it still follow your app.
      * @param string|null $callbackURL Body param: A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL on a public host,
      * where Sent asks what to do with each call. The signing secret is kept.
@@ -96,7 +98,7 @@ public function retrieve(
      */
     public function update(
         string $number,
-        ?string $agentID = null,
+        string|null|Omit $agentID = new Omit,
         ?string $callbackURL = null,
         ?bool $defaultForAppCalls = null,
         ?bool $sandbox = null,
diff --git a/src/Services/Channels/VoiceService.php b/src/Services/Channels/VoiceService.php
index f12fc9907..e93cac568 100644
--- a/src/Services/Channels/VoiceService.php
+++ b/src/Services/Channels/VoiceService.php
@@ -12,6 +12,7 @@
 use SentDm\Channels\Voice\VoiceUpdateParams\Status;
 use SentDm\Client;
 use SentDm\Core\Exceptions\APIException;
+use SentDm\Core\Omit;
 use SentDm\Core\Util;
 use SentDm\RequestOptions;
 use SentDm\ServiceContracts\Channels\VoiceContract;
@@ -181,8 +182,9 @@ public function retrieve(
      * With `sandbox: true` nothing is written: the request is validated against the stored number and the number is reported with `200` as it would read after the change.
      *
      * @param string $number Path param: The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100
-     * @param string|null $agentID Body param: One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to
-     * the number, or null to unbind it so the callback URL answers them again. The agent wins over
+     * @param string|null|Omit $agentID Body param: One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to
+     * the number, or null to unbind it so the callback URL answers them again. Leave this
+     * parameter out entirely to leave the current binding alone. The agent wins over
      * callback_url for calls to the number; calls your app places from it still follow your app.
      * @param string|null $callbackURL Body param: A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL on a public host,
      * where Sent asks what to do with each call. The signing secret is kept.
@@ -201,7 +203,7 @@ public function retrieve(
      */
     public function update(
         string $number,
-        ?string $agentID = null,
+        string|null|Omit $agentID = new Omit,
         ?string $callbackURL = null,
         ?bool $defaultForAppCalls = null,
         ?bool $sandbox = null,
@@ -210,9 +212,9 @@ public function update(
         ?string $xProfileID = null,
         RequestOptions|array|null $requestOptions = null,
     ): APIResponseOfVoiceNumber {
+        /** @var array<string, mixed> $params */
         $params = Util::removeNulls(
             [
-                'agentID' => $agentID,
                 'callbackURL' => $callbackURL,
                 'defaultForAppCalls' => $defaultForAppCalls,
                 'sandbox' => $sandbox,
@@ -222,6 +224,12 @@ public function update(
             ],
         );
 
+        // agent_id carries meaning as an explicit null (unbind), so it skips removeNulls()
+        // entirely instead of being stripped alongside every other unset field above.
+        if (!($agentID instanceof Omit)) {
+            $params['agentID'] = $agentID;
+        }
+
         // @phpstan-ignore-next-line argument.type
         $response = $this->raw->update($number, params: $params, requestOptions: $requestOptions);
 
diff --git a/tests/Services/Channels/VoiceTest.php b/tests/Services/Channels/VoiceTest.php
index c9bb06038..540e59ede 100644
--- a/tests/Services/Channels/VoiceTest.php
+++ b/tests/Services/Channels/VoiceTest.php
@@ -2,6 +2,8 @@
 
 namespace Tests\Services\Channels;
 
+use Http\Discovery\Psr17FactoryDiscovery;
+use Http\Mock\Client as MockTransporter;
 use PHPUnit\Framework\Attributes\CoversNothing;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
@@ -71,6 +73,63 @@ public function testUpdate(): void
         $this->assertInstanceOf(APIResponseOfVoiceNumber::class, $result);
     }
 
+    #[Test]
+    public function testUpdateSendsExplicitNullToUnbindAgent(): void
+    {
+        $transporter = new MockTransporter;
+        $transporter->setDefaultResponse(
+            Psr17FactoryDiscovery::findResponseFactory()
+                ->createResponse()
+                ->withStatus(200)
+                ->withHeader('Content-Type', 'application/json')
+                ->withBody(Psr17FactoryDiscovery::findStreamFactory()->createStream(
+                    json_encode(['data' => []], flags: Util::JSON_ENCODE_FLAGS) ?: ''
+                ))
+        );
+
+        $client = new Client(
+            baseUrl: 'http://localhost',
+            apiKey: 'My API Key',
+            requestOptions: ['transporter' => $transporter],
+        );
+
+        $client->channels->voice->update('+12125550100', agentID: null);
+
+        $this->assertNotFalse($requested = $transporter->getRequests()[0] ?? false);
+        /** @var array<string, mixed> $sent */
+        $sent = json_decode((string) $requested->getBody(), true);
+        $this->assertArrayHasKey('agent_id', $sent);
+        $this->assertNull($sent['agent_id']);
+    }
+
+    #[Test]
+    public function testUpdateOmitsAgentIdWhenNotPassed(): void
+    {
+        $transporter = new MockTransporter;
+        $transporter->setDefaultResponse(
+            Psr17FactoryDiscovery::findResponseFactory()
+                ->createResponse()
+                ->withStatus(200)
+                ->withHeader('Content-Type', 'application/json')
+                ->withBody(Psr17FactoryDiscovery::findStreamFactory()->createStream(
+                    json_encode(['data' => []], flags: Util::JSON_ENCODE_FLAGS) ?: ''
+                ))
+        );
+
+        $client = new Client(
+            baseUrl: 'http://localhost',
+            apiKey: 'My API Key',
+            requestOptions: ['transporter' => $transporter],
+        );
+
+        $client->channels->voice->update('+12125550100', status: 'ACTIVE');
+
+        $this->assertNotFalse($requested = $transporter->getRequests()[0] ?? false);
+        /** @var array<string, mixed> $sent */
+        $sent = json_decode((string) $requested->getBody(), true);
+        $this->assertArrayNotHasKey('agent_id', $sent);
+    }
+
     #[Test]
     public function testList(): void
     {