VAPI-3161: Add <Refer> BXML verb support - #295
Open
mramasubramanian-bw wants to merge 8 commits into
Open
Conversation
Adds support for the SIP REFER BXML verb to the python-sdk, mirroring the <Transfer> pattern but with the SIP-protocol-mandated success semantics: a successful REFER terminates the call on Bandwidth's side. Scope: BXML verb + unit tests only. The referCompleteCallback model will be regenerated from the OpenAPI spec once api-specs#2142 merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Unblocked by api-specs#2142 merging. Hand-written to match the OpenAPI generator output pattern (mirrors TransferCompleteCallback). Fields: standard call fields + referCallStatus, referSipResponseCode, notifySipResponseCode. Excludes cause/errorMessage/errorId (not in spec) and enqueuedTime (inbound SIP URI calls only). Adds scenario tests for all four referComplete outcomes: - Success (202 REFER, 200 NOTIFY) - Failure: REFER rejected (e.g. 405, no NOTIFY) - Failure: destination unreachable (202 REFER, 4xx NOTIFY) - Failure: NOTIFY timeout (202 REFER, no NOTIFY) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
stampercasey
marked this pull request as ready for review
June 18, 2026 19:58
The Transfer SipUri carries ~12 Transfer-specific params (transfer_answer_url, uui, auth, fallback URLs) that are invalid in a REFER context. A user passing any of those would silently produce malformed BXML. ReferSipUri accepts only uri — matching the spec and the C# SDK's nested Refer.SipUri class design. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
stampercasey
enabled auto-merge
June 18, 2026 20:26
stampercasey
previously approved these changes
Jun 19, 2026
Remove ReferCompleteCallback (will land later via a separate api-specs-driven PR once VAPI-3440 merges) and delete the distinct ReferSipUri type. Refer now takes the existing Transfer-flavored SipUri directly, matching the plain, validation-free style of the other BXML verb models in this SDK.
ckoegel
reviewed
Aug 3, 2026
| class Refer(NestableVerb): | ||
|
|
||
| def __init__( | ||
| self, sip_uri: SipUri, |
Contributor
There was a problem hiding this comment.
Suggested change
| self, sip_uri: SipUri, | |
| self, sip_uri: SipUri=None, |
this can be optional to match how the other verbs handle their nested verbs
| self.tag = tag | ||
| super().__init__( | ||
| tag="Refer", | ||
| nested_verbs=[self.sip_uri] |
Contributor
There was a problem hiding this comment.
Suggested change
| nested_verbs=[self.sip_uri] | |
| nested_verbs=[sip_uri] if sip_uri else [] |
to handle the uri being optional
| "referCompleteUrl": self.refer_complete_url, | ||
| "referCompleteMethod": self.refer_complete_method, | ||
| "tag": self.tag | ||
| } |
Contributor
There was a problem hiding this comment.
we should add something similar to ruby and node to allow the user to set the sip_uri after creation, we can't use add_verb but can write a setter
Comment on lines
+33
to
+44
| def test_minimal(self): | ||
| minimal_refer = Refer(sip_uri=SipUri(uri="sip:bob@example.com")) | ||
| expected = '<Refer><SipUri>sip:bob@example.com</SipUri></Refer>' | ||
| assert expected == minimal_refer.to_bxml() | ||
|
|
||
| def test_shares_sip_uri_with_transfer(self): | ||
| """Refer uses the same SipUri model as Transfer, including its | ||
| transfer-flavored attributes if the caller sets them.""" | ||
| sip_uri = SipUri(uri="sip:alice@atlanta.example.com", uui="test") | ||
| refer = Refer(sip_uri=sip_uri) | ||
| expected = '<Refer><SipUri uui="test">sip:alice@atlanta.example.com</SipUri></Refer>' | ||
| assert expected == refer.to_bxml() |
Contributor
There was a problem hiding this comment.
both of these are unnecessary. we should add a test to test setting the sip_uri though
Make sip_uri optional (default None) to match how other verbs handle their nested verbs, guard nested_verbs construction against None, and add a set_sip_uri() setter so callers can attach the SipUri after construction (mirrors the ruby/node Refer pattern). Replaced test_minimal/test_shares_sip_uri_with_transfer with a test covering the new setter.
…API-3161-add-refer-verb
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the
<Refer>BXML verb.bandwidth/models/bxml/verbs/refer.py: newReferverb (referCompleteUrl,referCompleteMethod,tagattributes, one requiredSipUrichild).SipUritype (bandwidth/models/bxml/verbs/sip_uri.py) for the child element instead of a separateReferSipUri- no cross-field validation restricting whichSipUriattributes are legal per verb (matches csharp-sdk#201, which dropped this as over-engineering).ReferCompleteCallbackmodel is out of scope here - lands separately once VAPI-3440 merges.test/unit/models/bxml/test_refer.py.Tests:
pytest test/unit/models/- 276/276 pass.VAPI-3435