VAPI-3160: Add <Refer> BXML Verb Support

README.md

@@ -92,6 +92,35 @@ $response = BandwidthLib\Voice\Bxml\Response::make()
 echo $response->toBxml();
 ```
 
+### Create A Refer BXML
+
+```php
+
+$sipUri = new BandwidthLib\Voice\Bxml\ReferSipUri("sip:alice@atlanta.example.com");
+$refer = new BandwidthLib\Voice\Bxml\Refer();
+$refer->referCompleteUrl("https://example.com/handleRefer");
+$refer->referCompleteMethod("POST");
+$refer->sipUri($sipUri);
+
+$response = new BandwidthLib\Voice\Bxml\Response();
+$response->addVerb($refer);
+echo $response->toBxml();
+```
+
+> **Note:** On success, the call is terminated — the remote SIP endpoint redirects away from Bandwidth entirely. Use `referCompleteUrl` only for failure recovery.
+
+```php
+// Failure recovery example in your referCompleteUrl handler:
+$requestBody = json_decode(file_get_contents('php://input'), true);
+if ($requestBody['referCallStatus'] === 'failure') {
+    // Handle failure: play a message or redirect
+    $speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("The transfer failed. Please try again.");
+    $response = new BandwidthLib\Voice\Bxml\Response();
+    $response->addVerb($speakSentence);
+    echo $response->toBxml();
+}
+```
+
 ### Create A MFA Request
 
 ```php

src/Voice/Bxml/Refer.php

@@ -0,0 +1,99 @@
+<?php
+/**
+ * Refer.php
+ *
+ * Implementation of the BXML Refer tag
+ *
+ *  * @copyright Bandwidth INC
+ */
+
+namespace BandwidthLib\Voice\Bxml;
+
+use DOMDocument;
+use DOMElement;
+
+require_once "Verb.php";
+
+class Refer extends Verb {
+    /**
+     * @var string
+     */
+    private $referCompleteUrl;
+    /**
+     * @var string
+     */
+    private $referCompleteMethod;
+    /**
+     * @var string
+     */
+    private $tag;
+    /**
+     * @var ReferSipUri|SipUri
+     */
+    private $sipUri;
+
+    /**
+     * Sets the referCompleteUrl attribute for Refer
+     *
+     * @param string $referCompleteUrl The URL to receive the refer complete callback
+     */
+    public function referCompleteUrl(string $referCompleteUrl): Refer {
+        $this->referCompleteUrl = $referCompleteUrl;
+        return $this;
+    }
+
+    /**
+     * Sets the referCompleteMethod attribute for Refer
+     *
+     * @param string $referCompleteMethod The HTTP method for the refer complete callback (GET or POST)
+     */
+    public function referCompleteMethod(string $referCompleteMethod): Refer {
+        $this->referCompleteMethod = $referCompleteMethod;
+        return $this;
+    }
+
+    /**
+     * Sets the tag attribute for Refer
+     *
+     * @param string $tag A custom string to be included in callbacks
+     */
+    public function tag(string $tag): Refer {
+        $this->tag = $tag;
+        return $this;
+    }
+
+    /**
+     * Sets the SipUri child element for Refer.
+     * Prefer ReferSipUri to avoid accidentally serializing Transfer-specific attributes.
+     *
+     * @param ReferSipUri|SipUri $sipUri The SipUri destination for the REFER
+     */
+    public function sipUri($sipUri): Refer {
+        $this->sipUri = $sipUri;
+        return $this;
+    }
+
+    public function toBxml(DOMDocument $doc): DOMElement {
+        if (!isset($this->sipUri)) {
+            throw new \InvalidArgumentException('Refer requires a SipUri child element.');
+        }
+
+        $element = $doc->createElement("Refer");
+
+        if(isset($this->referCompleteUrl)) {
+            $element->setAttribute("referCompleteUrl", $this->referCompleteUrl);
+        }
+
+        if(isset($this->referCompleteMethod)) {
+            $element->setAttribute("referCompleteMethod", $this->referCompleteMethod);
+        }
+
+        if(isset($this->tag)) {
+            $element->setAttribute("tag", $this->tag);
+        }
+
+        $element->appendChild($this->sipUri->toBxml($doc));
+
+        return $element;
+    }
+}

src/Voice/Bxml/ReferSipUri.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * ReferSipUri.php
+ *
+ * Implementation of the BXML SipUri tag for use inside the Refer verb.
+ * Unlike the Transfer SipUri, this only accepts a SIP URI — no transfer-specific attributes.
+ *
+ *  * @copyright Bandwidth INC
+ */
+
+namespace BandwidthLib\Voice\Bxml;
+
+use DOMDocument;
+use DOMElement;
+
+require_once "Verb.php";
+
+class ReferSipUri extends Verb {
+    /**
+     * @var string
+     */
+    private $sip;
+
+    /**
+     * Constructor for ReferSipUri
+     *
+     * @param string $sip The SIP URI destination (must start with "sip:")
+     */
+    public function __construct(string $sip) {
+        $this->sip = $sip;
+    }
+
+    public function toBxml(DOMDocument $doc): DOMElement {
+        $element = $doc->createElement("SipUri");
+        $element->appendChild($doc->createTextNode($this->sip));
+        return $element;
+    }
+}
+

src/Voice/Models/ReferCompleteCallback.php

@@ -0,0 +1,156 @@
+<?php
+/*
+ * BandwidthLib
+ *
+ * This file was manually added to support the Refer BXML verb.
+ */
+
+namespace BandwidthLib\Voice\Models;
+
+/**
+ * This object represents fields included in callbacks related to refer complete events.
+ * Fired when the REFER flow completes (success or failure), only if referCompleteUrl is set.
+ */
+class ReferCompleteCallback implements \JsonSerializable
+{
+    /**
+     * The event type of the callback. Always "referComplete".
+     * @var string|null $eventType public property
+     */
+    public $eventType;
+
+    /**
+     * The time the event occurred, in ISO 8601 format.
+     * @var string|null $eventTime public property
+     */
+    public $eventTime;
+
+    /**
+     * The user's Bandwidth account ID.
+     * @var string|null $accountId public property
+     */
+    public $accountId;
+
+    /**
+     * The ID of the application associated with the call.
+     * @var string|null $applicationId public property
+     */
+    public $applicationId;
+
+    /**
+     * The phone number that received the call, in E.164 format.
+     * @var string|null $from public property
+     */
+    public $from;
+
+    /**
+     * The phone number that made the call, in E.164 format.
+     * @var string|null $to public property
+     */
+    public $to;
+
+    /**
+     * The direction of the call. Always "inbound" for refer events.
+     * @var string|null $direction public property
+     */
+    public $direction;
+
+    /**
+     * The unique ID of the call.
+     * @var string|null $callId public property
+     */
+    public $callId;
+
+    /**
+     * The full URL of the call resource.
+     * @var string|null $callUrl public property
+     */
+    public $callUrl;
+
+    /**
+     * The time the call started, in ISO 8601 format.
+     * @var string|null $startTime public property
+     */
+    public $startTime;
+
+    /**
+     * The time the call was answered, in ISO 8601 format.
+     * @var string|null $answerTime public property
+     */
+    public $answerTime;
+
+    /**
+     * The outcome of the REFER operation. Either "success" or "failure".
+     * @var string|null $referCallStatus public property
+     */
+    public $referCallStatus;
+
+    /**
+     * The SIP response code for the REFER request (e.g. 202, 405).
+     * Absent when the REFER was not sent. Present on both success and failure.
+     * @var int|null $referSipResponseCode public property
+     */
+    public $referSipResponseCode;
+
+    /**
+     * The SIP response code from the NOTIFY (e.g. 200, 404, 486).
+     * Absent on REFER rejection or NOTIFY timeout.
+     * @var int|null $notifySipResponseCode public property
+     */
+    public $notifySipResponseCode;
+
+    /**
+     * A custom string provided in the Refer BXML tag, if any.
+     * @var string|null $tag public property
+     */
+    public $tag;
+
+    /**
+     * Constructor to set initial or default values of member properties
+     */
+    public function __construct()
+    {
+        if (15 == func_num_args()) {
+            $this->eventType             = func_get_arg(0);
+            $this->eventTime             = func_get_arg(1);
+            $this->accountId             = func_get_arg(2);
+            $this->applicationId         = func_get_arg(3);
+            $this->from                  = func_get_arg(4);
+            $this->to                    = func_get_arg(5);
+            $this->direction             = func_get_arg(6);
+            $this->callId                = func_get_arg(7);
+            $this->callUrl               = func_get_arg(8);
+            $this->startTime             = func_get_arg(9);
+            $this->answerTime            = func_get_arg(10);
+            $this->referCallStatus       = func_get_arg(11);
+            $this->referSipResponseCode  = func_get_arg(12);
+            $this->notifySipResponseCode = func_get_arg(13);
+            $this->tag                   = func_get_arg(14);
+        }
+    }
+
+    /**
+     * Encode this object to JSON
+     */
+    public function jsonSerialize(): array
+    {
+        $json = array();
+        $json['eventType']             = $this->eventType;
+        $json['eventTime']             = $this->eventTime;
+        $json['accountId']             = $this->accountId;
+        $json['applicationId']         = $this->applicationId;
+        $json['from']                  = $this->from;
+        $json['to']                    = $this->to;
+        $json['direction']             = $this->direction;
+        $json['callId']                = $this->callId;
+        $json['callUrl']               = $this->callUrl;
+        $json['startTime']             = $this->startTime;
+        $json['answerTime']            = $this->answerTime;
+        $json['referCallStatus']       = $this->referCallStatus;
+        $json['referSipResponseCode']  = $this->referSipResponseCode;
+        $json['notifySipResponseCode'] = $this->notifySipResponseCode;
+        $json['tag']                   = $this->tag;
+
+        return array_filter($json);
+    }
+}

tests/ApiTest.php

@@ -236,8 +236,6 @@ public function testSyncTnLookup() {
         $body->phoneNumbers = [getenv("USER_NUMBER")];
         $response = self::$bandwidthClient->getPhoneNumberLookup()->getClient()->createSyncLookupRequest(getenv("BW_ACCOUNT_ID"), $body);
         $this->assertInstanceOf(BandwidthLib\PhoneNumberLookup\Models\LookupResponse::class, $response->getResult());
-        $this->assertIsArray($response->getResult()->links);
-        $this->assertInstanceOf(BandwidthLib\PhoneNumberLookup\Models\Link::class, $response->getResult()->links[0]);
         $this->assertInstanceOf(BandwidthLib\PhoneNumberLookup\Models\LookupResponseData::class, $response->getResult()->data);
         $this->assertIsString($response->getResult()->data->requestId);
         $this->assertIsString($response->getResult()->data->status);