From 2f65182a7800e6dd73322430a40469af2d4750f4 Mon Sep 17 00:00:00 2001 From: nitinkumar Date: Tue, 26 May 2026 17:43:05 +0530 Subject: [PATCH] VAPI-3164 --- README.md | 1 + docs/Refer.md | 22 +++++ .../com/bandwidth/sdk/model/bxml/Bxml.java | 1 + .../com/bandwidth/sdk/model/bxml/Refer.java | 86 +++++++++++++++++++ .../sdk/unit/models/bxml/ReferVerbTest.java | 55 ++++++++++++ 5 files changed, 165 insertions(+) create mode 100644 docs/Refer.md create mode 100644 src/main/java/com/bandwidth/sdk/model/bxml/Refer.java create mode 100644 src/test/java/com/bandwidth/sdk/unit/models/bxml/ReferVerbTest.java diff --git a/README.md b/README.md index 0f80d7dc..9dd9e811 100644 --- a/README.md +++ b/README.md @@ -365,6 +365,7 @@ Class | Method | HTTP request | Description - [TranscribeRecording](docs/TranscribeRecording.md) - [Transcription](docs/Transcription.md) - [TranscriptionAvailableCallback](docs/TranscriptionAvailableCallback.md) + - [Refer (BXML verb)](docs/Refer.md) - [TransferAnswerCallback](docs/TransferAnswerCallback.md) - [TransferCompleteCallback](docs/TransferCompleteCallback.md) - [TransferDisconnectCallback](docs/TransferDisconnectCallback.md) diff --git a/docs/Refer.md b/docs/Refer.md new file mode 100644 index 00000000..70233600 --- /dev/null +++ b/docs/Refer.md @@ -0,0 +1,22 @@ +# Refer + +The BXML verb initiates a SIP REFER on an existing inbound SIP URI call, instructing the remote SIP endpoint to contact a third party directly. On success the call is terminated — the remote endpoint redirects away from Bandwidth entirely. On failure, BXML returned from referCompleteUrl can be used for recovery. + +## Properties + +| Name | Type | Description | Notes | +|------------ | ------------- | ------------- | -------------| +|**sipUri** | **SipUri** | The SIP URI to refer the call to. Must start with sip:. | required | +|**referCompleteUrl** | **URI** | URL to send the Refer Complete event to and request new BXML for failure recovery. May be a relative URL. | [optional] | +|**referCompleteMethod** | **String** | The HTTP method to use for the request to referCompleteUrl. GET or POST. Default value is POST. | [optional] | +|**referCompleteFallbackUrl** | **URI** | A fallback url which, if provided, will be used to retry the Refer Complete callback delivery in case referCompleteUrl fails to respond. | [optional] | +|**referCompleteFallbackMethod** | **String** | The HTTP method to use to deliver the Refer Complete callback to referCompleteFallbackUrl. GET or POST. Default value is POST. | [optional] | +|**username** | **String** | The username to send in the HTTP request to referCompleteUrl. | [optional] | +|**password** | **String** | The password to send in the HTTP request to referCompleteUrl. | [optional] | +|**fallbackUsername** | **String** | The username to send in the HTTP request to referCompleteFallbackUrl. | [optional] | +|**fallbackPassword** | **String** | The password to send in the HTTP request to referCompleteFallbackUrl. | [optional] | +|**tag** | **String** | A custom string that will be sent with these and all future callbacks unless overwritten by a future tag attribute or cleared. May be cleared by setting tag="". Max length 256 characters. | [optional] | + + + + diff --git a/src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java b/src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java index 3d09ad9e..53c5258b 100644 --- a/src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java +++ b/src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java @@ -43,6 +43,7 @@ public class Bxml { @XmlElement(name = PlayAudio.TYPE_NAME, type = PlayAudio.class), @XmlElement(name = Record.TYPE_NAME, type = Record.class), @XmlElement(name = Redirect.TYPE_NAME, type = Redirect.class), + @XmlElement(name = Refer.TYPE_NAME, type = Refer.class), @XmlElement(name = ResumeRecording.TYPE_NAME, type = ResumeRecording.class), @XmlElement(name = Ring.TYPE_NAME, type = Ring.class), @XmlElement(name = SendDtmf.TYPE_NAME, type = SendDtmf.class), diff --git a/src/main/java/com/bandwidth/sdk/model/bxml/Refer.java b/src/main/java/com/bandwidth/sdk/model/bxml/Refer.java new file mode 100644 index 00000000..dec5b613 --- /dev/null +++ b/src/main/java/com/bandwidth/sdk/model/bxml/Refer.java @@ -0,0 +1,86 @@ +/** + * The {@code } verb is used to initiate a SIP REFER on an existing call, + * instructing the remote SIP endpoint to contact a third party directly. + * On success the call is terminated — the remote endpoint redirects away from Bandwidth entirely. + */ + +package com.bandwidth.sdk.model.bxml; + +import static com.bandwidth.sdk.model.bxml.utils.BxmlConstants.DEFAULT_CALLBACK_METHOD; + +import jakarta.xml.bind.annotation.XmlAccessType; +import jakarta.xml.bind.annotation.XmlAccessorType; +import jakarta.xml.bind.annotation.XmlAttribute; +import jakarta.xml.bind.annotation.XmlElement; +import jakarta.xml.bind.annotation.XmlType; +import java.net.URI; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Builder.Default; +import lombok.EqualsAndHashCode; +import lombok.Getter; +import lombok.NoArgsConstructor; + +@XmlAccessorType(XmlAccessType.FIELD) +@XmlType(name = Refer.TYPE_NAME) +@Builder +@NoArgsConstructor +@AllArgsConstructor +@Getter +@EqualsAndHashCode +/** + * + * @param sipUri (SipUri, required): The SIP URI to refer the call to. Must start with "sip:". + * @param referCompleteUrl (str, optional): URL to send the Refer Complete event to and request new BXML for failure recovery. May be a relative URL. Defaults to None. + * @param referCompleteMethod (str, optional): The HTTP method to use for the request to referCompleteUrl. GET or POST. Default value is POST. + * @param referCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Refer Complete callback delivery in case referCompleteUrl fails to respond. Defaults to None. + * @param referCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Refer Complete callback to referCompleteFallbackUrl. GET or POST. Default value is POST. + * @param username (str, optional): The username to send in the HTTP request to referCompleteUrl. Defaults to None. + * @param password (str, optional): The password to send in the HTTP request to referCompleteUrl. Defaults to None. + * @param fallbackUsername (str, optional): The username to send in the HTTP request to referCompleteFallbackUrl. Defaults to None. + * @param fallbackPassword (str, optional): The password to send in the HTTP request to referCompleteFallbackUrl. Defaults to None. + * @param tag (str, optional): A custom string that will be sent with these and all future callbacks unless overwritten by a future tag attribute or cleared. May be cleared by setting tag="". Max length 256 characters. Defaults to None. + * + */ +public class Refer implements Verb { + + public static final String TYPE_NAME = "Refer"; + + @XmlElement(name = SipUri.TYPE_NAME, type = SipUri.class) + protected SipUri sipUri; + + @XmlAttribute + protected URI referCompleteUrl; + + @XmlAttribute + @Default + protected String referCompleteMethod = DEFAULT_CALLBACK_METHOD; + + @XmlAttribute + protected URI referCompleteFallbackUrl; + + @XmlAttribute + @Default + protected String referCompleteFallbackMethod = DEFAULT_CALLBACK_METHOD; + + @XmlAttribute + protected String username; + + @XmlAttribute + protected String password; + + @XmlAttribute + protected String fallbackUsername; + + @XmlAttribute + protected String fallbackPassword; + + @XmlAttribute + protected String tag; + + @Override + public String getVerbName() { + return TYPE_NAME; + } +} + diff --git a/src/test/java/com/bandwidth/sdk/unit/models/bxml/ReferVerbTest.java b/src/test/java/com/bandwidth/sdk/unit/models/bxml/ReferVerbTest.java new file mode 100644 index 00000000..893f54ac --- /dev/null +++ b/src/test/java/com/bandwidth/sdk/unit/models/bxml/ReferVerbTest.java @@ -0,0 +1,55 @@ +/** + * + * Unit tests for Refer Verb class + * + * @throws JAXBException if the test fails + */ + +package com.bandwidth.sdk.unit.models.bxml; + +import com.bandwidth.sdk.model.bxml.Bxml; +import com.bandwidth.sdk.model.bxml.Refer; +import com.bandwidth.sdk.model.bxml.SipUri; + +import jakarta.xml.bind.JAXBContext; +import jakarta.xml.bind.JAXBException; + +import org.junit.jupiter.api.Test; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.Matchers.is; + +import java.net.URI; + +public class ReferVerbTest { + + SipUri sipUri = SipUri.builder() + .uri("sip:alice@atlanta.example.com") + .build(); + + Refer refer = Refer.builder() + .sipUri(sipUri) + .referCompleteUrl(URI.create("https://example.com/webhooks/refer_complete")) + .referCompleteMethod("POST") + .tag("test-tag") + .build(); + + Refer referMinimal = Refer.builder() + .sipUri(sipUri) + .build(); + + @Test + public void referVerbWithAllAttributes() throws JAXBException { + JAXBContext jaxbContext = JAXBContext.newInstance(Bxml.class); + String expectedBxml = "sip:alice@atlanta.example.com"; + assertThat(new Bxml().with(refer).toBxml(jaxbContext), is(expectedBxml)); + } + + @Test + public void referVerbMinimal() throws JAXBException { + JAXBContext jaxbContext = JAXBContext.newInstance(Bxml.class); + String expectedBxml = "sip:alice@atlanta.example.com"; + assertThat(new Bxml().with(referMinimal).toBxml(jaxbContext), is(expectedBxml)); + } +} +