Add <Refer> BXML verb and referComplete webhook support

[Copilot]

This adds SDK support for the new Voice <Refer> flow and referComplete callback payload shape, modeled after existing transfer patterns while preserving REFER semantics (successful REFER hands the call off; no post-success continuation pattern). It includes BXML modeling, webhook models/enums, and docs/examples aligned to failure-aware callback handling.

• BXML: new <Refer> verb

  • Added Refer verb model with optional attributes:
    • referCompleteUrl
    • referCompleteMethod (default POST, validated to GET|POST)
    • tag (optional)
  • Added required nested <SipUri> child (Refer.SipUri) with SIP scheme validation (sip:).
  • Added fluent builder methods:
    • WithSipUri(...)
    • WithReferCompleteUrl(...)
    • WithReferCompleteMethod(...)
    • WithTag(...)

• Webhook: referComplete payload modeling

  • Added ReferCompleteCallback model for eventType=referComplete.
  • Added ReferCallStatusEnum (success, failure).
  • Included optional nullable fields:
    • tag
    • referSipResponseCode
    • notifySipResponseCode

• Unit coverage for new behavior

  • Added Refer BXML serialization/deserialization round-trip tests.
  • Added webhook scenario tests for:
    • success (no SIP codes)
    • REFER rejected (e.g., 405; no notify code)
    • destination unreachable (refer 202 + notify error code)
    • NOTIFY timeout (refer 202; no notify code)

• Docs and release notes

  • Added README example for <Refer> generation.
  • Added README failure-recovery callback example based on referCallStatus=failure.
  • Explicitly avoids “continue after success” examples for REFER.
  • Added docs pages for ReferCompleteCallback and ReferCallStatusEnum.
  • Added changelog entry for <Refer> and referComplete support (with pre-merge note for api-specs PR 2142).

var refer = new Refer()
    .WithSipUri("sip:alice@atlanta.example.com")
    .WithReferCompleteUrl("https://example.com/handleRefer")
    .WithReferCompleteMethod("POST")
    .WithTag("handoff-123");

var bxml = new Response(refer).ToBXML();

// callback handler
if (callback.ReferCallStatus == ReferCallStatusEnum.Failure)
{
    // fallback or retry routing
}

Original prompt

Overview

Add support for the new <Refer> BXML verb and referComplete webhook to the C# SDK. This mirrors the existing <Transfer> verb pattern with one critical asymmetry: <Refer> terminates the call on success (the remote SIP endpoint redirects away from Bandwidth), whereas <Transfer> keeps the call alive. SDK examples must not mimic Transfer's "play after success" pattern.

Reference: https://github.com/Bandwidth/api-specs/pull/2142 (do not ship before this is merged)

---

1. <Refer> BXML Verb

XML shape

<Response>
  <Refer referCompleteUrl="https://example.com/handleRefer" referCompleteMethod="POST">
    <SipUri>sip:alice@atlanta.example.com</SipUri>
  </Refer>
</Response>

Attributes (all optional)

Attribute	Type	Default	Notes
referCompleteUrl	URL string	—	May be relative
referCompleteMethod	GET | POST	POST
tag	string	—	Include if confirmed via VAPI-2916; add as optional

Child element

• <SipUri> — required, exactly one. Text content is a SIP URI (must start with sip:). No attributes.

Implementation requirements

• Add a Refer model class following existing verb conventions in the SDK (look at Transfer as the closest analogue).
• Add a nested SipUri child element/class that serializes correctly.
• XML namespace and element ordering must match existing verbs.
• Provide builder/fluent methods for sipUri (required), referCompleteUrl, referCompleteMethod, and tag.

---

2. referComplete Webhook

Payload fields

Field	Required?	Notes
eventType	always	Always "referComplete"
eventTime	always
accountId	always
applicationId	always
from	always
to	always
direction	always	Always "inbound"
callId	always
callUrl	always
startTime	always
answerTime	always
referCallStatus	always	"success" or "failure"
tag	optional
referSipResponseCode	optional	e.g. 202, 405, 603 — absent on success
notifySipResponseCode	optional	e.g. 200, 404, 486 — absent on REFER rejection or NOTIFY timeout

Implementation requirements

• Add a ReferComplete webhook event model (match the SDK's existing webhook naming convention).
• Register referComplete in the SDK's webhook event-type discriminator/enum so callback parsing routes to the new model.
• All optional fields (tag, referSipResponseCode, notifySipResponseCode) must be nullable/optional.

---

3. Unit Tests

Cover all of the following cases:

1. <Refer> verb XML round-trip — serialize and deserialize, verify output matches expected XML.
2. Webhook: success — referCallStatus=success, no referSipResponseCode, no notifySipResponseCode.
3. Webhook: REFER rejected (e.g. 405) — referCallStatus=failure, referSipResponseCode=405, no notifySipResponseCode.
4. Webhook: destination unreachable — referCallStatus=failure, referSipResponseCode=202, notifySipResponseCode=<error>.
5. Webhook: NOTIFY timeout — referCallStatus=failure, referSipResponseCode=202, no notifySipResponseCode.

---

4. Documentation

• Add one BXML example showing <Refer> usage to the README or relevant docs section.
• Add one failure-recovery example showing how to handle referCallStatus=failure in the referCompleteUrl callback.
• Do NOT include any "continue after success" examples — the call is terminated on success by SIP protocol design.

---

5. Changelog

Add a changelog entry for:

• New <Refer> BXML verb
• New referComplete webhook event

---

Critical notes

• Do not ship this before https://github.com/Bandwidth/api-specs/pull/2142 is merged.
• The tag attribute on <Refer> is pending confirmation (VAPI-2916) — add it as optional for now.
• Study the existing Transfer verb implementation as the closest pattern to follow, but remember the success-semantics difference.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: ```
Add SIP REFER verb support to csharp-sdk

Key details
Main
Operations
Description

Overview
Add support for the new BXML verb and referComplete webhook to the C# SDK. Mirrors the existing verb pattern, but note the critical success-semantics asymmetry below.

Repo
https://github.com/Bandwidth/csharp-sdk

References
Parent epic: VAPI-2459

API spec ticket: VAPI-2916

Spec PR (DRAFT — do not ship SDK before merge): https://github.com/Bandwidth/api-specs/pull/2142

Design doc: https://bandwidth-jira.atlassian.net/wiki/spaces/PV/pages/6901727392/SIP+REFER

Verb

sip:alice@atlanta.example.com Attributes (all optional):

referCompleteUrl — URL...

This pull request was created from Copilot chat.

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.