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\SipUri("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,97 @@
+<?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 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
+     *
+     * @param SipUri $sipUri The SipUri destination for the REFER
+     */
+    public function sipUri(SipUri $sipUri): Refer {
+        $this->sipUri = $sipUri;
+        return $this;
+    }
+
+    public function toBxml(DOMDocument $doc): DOMElement {
+        $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);
+        }
+
+        if(isset($this->sipUri)) {
+            $element->appendChild($this->sipUri->toBxml($doc));
+        }
+
+        return $element;
+    }
+}
+

src/Voice/Models/ReferCompleteCallback.php

@@ -0,0 +1,154 @@
+<?php
+/*
+ * BandwidthLib
+ *
+ * This file was automatically generated by APIMATIC v3.0 ( https://www.apimatic.io ).
+ */
+
+namespace BandwidthLib\Voice\Models;
+
+/**
+ *This object represents fields included in callbacks related to refer complete events
+ */
+class ReferCompleteCallback implements \JsonSerializable
+{
+    /**
+     * @todo Write general description for this property
+     * @var string|null $eventType public property
+     */
+    public $eventType;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $eventTime public property
+     */
+    public $eventTime;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $accountId public property
+     */
+    public $accountId;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $applicationId public property
+     */
+    public $applicationId;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $from public property
+     */
+    public $from;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $to public property
+     */
+    public $to;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $direction public property
+     */
+    public $direction;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $callId public property
+     */
+    public $callId;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $callUrl public property
+     */
+    public $callUrl;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $startTime public property
+     */
+    public $startTime;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $answerTime public property
+     */
+    public $answerTime;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $referCallStatus public property
+     */
+    public $referCallStatus;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $referSipResponseCode public property
+     */
+    public $referSipResponseCode;
+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $notifySipResponseCode public property
+     */
+    public $notifySipResponseCode;
+
+    /**
+     * @todo Write general description for this property
+     * @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);

tests/BxmlTest.php

@@ -540,4 +540,33 @@ public function testStopTranscription() {
         $responseXml = $response->toBxml();
         $this->assertEquals($expectedXml, $responseXml);
     }
+
+    public function testRefer() {
+        $sipUri = new BandwidthLib\Voice\Bxml\SipUri("sip:alice@atlanta.example.com");
+        $refer = new BandwidthLib\Voice\Bxml\Refer();
+        $refer->referCompleteUrl("https://example.com/handleRefer");
+        $refer->referCompleteMethod("POST");
+        $refer->tag("my-tag");
+        $refer->sipUri($sipUri);
+
+        $response = new BandwidthLib\Voice\Bxml\Response();
+        $response->addVerb($refer);
+
+        $expectedXml = '<?xml version="1.0" encoding="UTF-8"?><Response><Refer referCompleteUrl="https://example.com/handleRefer" referCompleteMethod="POST" tag="my-tag"><SipUri>sip:alice@atlanta.example.com</SipUri></Refer></Response>';
+        $responseXml = $response->toBxml();
+        $this->assertEquals($expectedXml, $responseXml);
+    }
+
+    public function testReferNoOptionalAttributes() {
+        $sipUri = new BandwidthLib\Voice\Bxml\SipUri("sip:bob@biloxi.example.com");
+        $refer = new BandwidthLib\Voice\Bxml\Refer();
+        $refer->sipUri($sipUri);
+
+        $response = new BandwidthLib\Voice\Bxml\Response();
+        $response->addVerb($refer);
+
+        $expectedXml = '<?xml version="1.0" encoding="UTF-8"?><Response><Refer><SipUri>sip:bob@biloxi.example.com</SipUri></Refer></Response>';
+        $responseXml = $response->toBxml();
+        $this->assertEquals($expectedXml, $responseXml);
+    }
 }