diff --git a/fern/advanced/sip/sip-didww.mdx b/fern/advanced/sip/sip-didww.mdx new file mode 100644 index 000000000..996763e7f --- /dev/null +++ b/fern/advanced/sip/sip-didww.mdx @@ -0,0 +1,309 @@ +--- +title: DIDWW SIP integration +subtitle: Connect DIDWW SIP trunks to Vapi so your assistants can receive calls, place outbound calls, and transfer active calls with SIP REFER. +description: Set up DIDWW SIP trunking with Vapi. Create inbound and outbound trunks, allowlist signaling IPs, and configure authenticated SIP REFER call transfers. +slug: advanced/sip/didww +--- + +## Before you begin + +- An active DIDWW account is required. [Sign in](https://my.didww.com/users/sign_in) or [create an account](https://my.didww.com/users/sign_up#/users/sign_up). +- Access to [DIDWW Outbound Trunks](https://doc.didww.com/voice/outbound-trunks/get-access.html) is required. +- A Vapi account and assistant is required. + +## 1. Route incoming calls to Vapi + +Create a DIDWW inbound SIP trunk that sends calls from your DIDWW numbers to Vapi. + + + + In the [DIDWW User Panel](https://my.didww.com/#/trunks), go to **Voice → Inbound Trunks** and select **Create New → SIP Trunk**. + + + + In the **General** tab, configure every field below: + + | Field | Value | + | --- | --- | + | **Name** | A descriptive name, such as `Vapi` | + | **Endpoint type** | **Static Endpoint** | + | **Host** | `sip.vapi.ai` for US organizations or `sip.eu.vapi.ai` for EU organizations | + | **Transport** | **UDP**, **TCP**, or **TLS** | + | **Port** | `5060` for UDP/TCP or `5061` for TLS | + | **Network Protocol** | Match the IP version allowed on the DIDWW outbound trunk; use **Prefer IPv4 over IPv6** or **IPv4 only** when allowlisting IPv4 addresses | + + + DIDWW inbound SIP trunk General tab with host, endpoint type, transport, and port fields configured for Vapi + + + + + {/* "Signalling" (double-l) intentionally matches DIDWW's on-screen tab label shown in the screenshot; do not change it. Use single-l "signaling" for our own prose everywhere else. */} + In the **Signalling** tab, set **Max transfers** to `1` or higher. This permits the in-dialog SIP REFER requests used for call transfers. + + + DIDWW inbound trunk Signalling tab with Max transfers set to 1 + + + + + Click **Create**. For additional DIDWW options, see the [inbound SIP trunk guide](https://doc.didww.com/voice/inbound-trunks/creating-a-new-sip-trunk.html). + + + +## 2. Enable outbound calling through DIDWW + +Create a DIDWW outbound trunk for Vapi calls and for authenticated SIP REFER transfers. + + + + In the DIDWW User Panel, go to **Voice → Outbound Trunks** and click **Create New**. + + + + Set a **Friendly Name**, such as `Vapi`, and keep **Credentials & IP-based** authentication selected. + + Under **Allowed SIP IP addresses**, add the signaling addresses for your Vapi region: + + | Region | Vapi signaling IPs | + | --- | --- | + | US | `44.229.228.186/32`, `44.238.177.138/32` | + | EU | `63.182.83.170/32` | + + To support call transfers, also add all DIDWW inbound signaling addresses: + + ```text + 46.19.209.14 + 46.19.210.14 + 46.19.212.14 + 46.19.213.14 + 46.19.214.14 + 46.19.215.14 + 185.238.173.14 + ``` + + + DIDWW outbound trunk Allowed SIP IP addresses list containing the Vapi and DIDWW signaling addresses + + + {/* The #sip-signalling anchor is intentionally double-l to match the current sip-networking heading; switch to #sip-signaling when that page is standardized to single-l (tracked as a separate issue). */} + + Do not use `0.0.0.0/0` in production. Restrict the trunk to the current [Vapi signaling IPs](/advanced/sip/sip-networking#sip-signalling) and [DIDWW SIP servers](https://doc.didww.com/voice/inbound-trunks/technical-data/sip.html#service-did-sip). + + + + + Click **Create** to save it. + + + + On **Voice → Outbound Trunks**, click the key icon in the trunk's **Credentials** column. Copy the **Username** and **Password**; you will use both in DIDWW and Vapi. + + + DIDWW outbound trunk credentials dialog showing the username and password fields + + + + + Edit the Vapi inbound trunk and open **Authorization**. Turn on **Enable Authorization**, paste the outbound trunk **Username** and **Password** into **Auth User** and **Auth Password**, then click **Submit**. + + + DIDWW inbound trunk Authorization tab with Enable Authorization turned on and the Auth User and Auth Password fields filled + + + For more detail, see [Add outbound credentials to the inbound trunk](https://doc.didww.com/integrations/vapi/index.html#step-5-add-outbound-credentials-to-the-inbound-trunk). + + + +## 3. Connect the SIP trunks in Vapi + +Use the same transport and port on both sides. In API examples, use `https://api.vapi.ai` for US organizations or replace it with `https://api.eu.vapi.ai` for EU organizations. + +### Step 1: Create the outbound trunk + + + + In the [Vapi dashboard](https://dashboard.vapi.ai), select your organization name in the top left, then click **Settings**. Under organization settings, go to **Integrations → SIP Trunk** and click **Configure New SIP Trunk**. + + 1. Set **Name** to `DIDWW Outbound Trunk`. + 2. Set **IP Address / Domain** to a [DIDWW outbound endpoint](https://doc.didww.com/voice/outbound-trunks/technical-data/sip-details.html#voice-out-signaling-endpoints), such as `fra.eu.out.didww.com`. + 3. Select the transport and port: `5060` for UDP/TCP or `5061` for TLS. + 4. Turn off **Allow inbound calls** and leave **Allow outbound calls** on. + + + Vapi SIP trunk configuration with the DIDWW outbound endpoint, transport, port, and outbound calls enabled + + + 5. Under **Authentication**, enter the DIDWW outbound username and password. Leave SIP registration off and save the trunk. + + + Vapi SIP trunk Authentication section with the DIDWW outbound username and password entered + + + + + ```bash + curl -X POST https://api.vapi.ai/credential \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "provider": "byo-sip-trunk", + "name": "DIDWW Outbound Trunk", + "gateways": [ + { + "ip": "YOUR_DIDWW_OUTBOUND_ENDPOINT", + "port": 5060, + "inboundEnabled": false, + "outboundEnabled": true, + "outboundProtocol": "udp" + } + ], + "outboundAuthenticationPlan": { + "authUsername": "YOUR_DIDWW_TRUNK_USERNAME", + "authPassword": "YOUR_DIDWW_TRUNK_PASSWORD" + } + }' + ``` + + Replace the endpoint with the DIDWW signaling endpoint selected for your deployment. + + + +### Step 2: Create the inbound trunk + + + + Create another Vapi SIP trunk named `DIDWW Inbound Trunk`. + + 1. Add one gateway for each DIDWW IP below, using netmask `32` and the same port as the DIDWW inbound trunk. + 2. For every gateway, turn on **Allow inbound calls** and turn off **Allow outbound calls**. + + + Vapi SIP trunk with one inbound gateway per DIDWW signaling IP address + + + 3. Under **Authentication**, enter the DIDWW outbound username and password, then save the trunk. + + ```text + 46.19.209.14 + 46.19.210.14 + 46.19.212.14 + 46.19.213.14 + 46.19.214.14 + 46.19.215.14 + 185.238.173.14 + ``` + + + Vapi inbound SIP trunk Authentication section with the DIDWW credentials entered + + + + + ```bash + curl -X POST https://api.vapi.ai/credential \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "provider": "byo-sip-trunk", + "name": "DIDWW Inbound Trunk", + "gateways": [ + { "ip": "46.19.209.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "46.19.210.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "46.19.212.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "46.19.213.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "46.19.214.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "46.19.215.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }, + { "ip": "185.238.173.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false } + ], + "outboundAuthenticationPlan": { + "authUsername": "YOUR_DIDWW_TRUNK_USERNAME", + "authPassword": "YOUR_DIDWW_TRUNK_PASSWORD" + } + }' + ``` + + Save the returned credential `id`; it is required when you [import the DIDWW number](/phone-numbers/didww). + + + +### Step 3: Create a call transfer tool + + + + In Vapi, go to **Tools → Create Tool → Transfer Call**. + + 1. Enter a tool name and describe when the assistant should transfer the caller. + 2. Add a **SIP** destination. + 3. Set **SIP URI** to `sip:+E164_NUMBER@OUTBOUND_ENDPOINT`, for example `sip:+447700900123@fra.eu.out.didww.com`. + 4. Add the customer message and destination description, keep **Blind Transfer**, and save. + + + Vapi Transfer Call tool with a SIP destination whose URI points to a DIDWW outbound endpoint + + + + + ```bash + curl -X POST https://api.vapi.ai/tool \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "type": "transferCall", + "destinations": [ + { + "type": "sip", + "sipUri": "sip:+447700900123@YOUR_DIDWW_OUTBOUND_ENDPOINT", + "message": "Please wait while I transfer your call.", + "description": "Use when the caller asks to speak with a live person.", + "transferPlan": { + "mode": "blind-transfer", + "sipVerb": "refer" + } + } + ] + }' + ``` + + Save the returned tool `id` for the next step. + + + +### Step 4: Add the transfer tool to your assistant + + + + Open the assistant, go to **Tools → Add tool**, and select the transfer tool. Click **Publish**, then confirm the publication. + + + Vapi assistant Tools section with the DIDWW transfer tool added + + + + + Retrieve the assistant, add the transfer tool ID to `model.toolIds`, and PATCH the complete model back. The example uses `jq` to preserve the existing model configuration and tool IDs. + + ```bash + VAPI_API_BASE="https://api.vapi.ai" + ASSISTANT_ID="YOUR_ASSISTANT_ID" + TRANSFER_TOOL_ID="YOUR_TRANSFER_TOOL_ID" + + CURRENT_MODEL=$(curl -s "$VAPI_API_BASE/assistant/$ASSISTANT_ID" \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" | jq '.model') + + UPDATED_MODEL=$(printf '%s' "$CURRENT_MODEL" | jq \ + --arg toolId "$TRANSFER_TOOL_ID" \ + '.toolIds = (((.toolIds // []) + [$toolId]) | unique)') + + jq -n --argjson model "$UPDATED_MODEL" '{model: $model}' | \ + curl -X PATCH "$VAPI_API_BASE/assistant/$ASSISTANT_ID" \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \ + -H "Content-Type: application/json" \ + --data-binary @- + ``` + + + +## Next step + +**[Import a number from DIDWW](/phone-numbers/didww):** Purchase or select a DIDWW number, assign the inbound trunk, and import the number into Vapi. diff --git a/fern/docs.yml b/fern/docs.yml index 9597b077b..ffeca0ae3 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -317,6 +317,8 @@ navigation: path: phone-numbers/import-twilio.mdx - page: Telnyx path: phone-numbers/telnyx.mdx + - page: DIDWW + path: phone-numbers/didww.mdx - section: SIP integration icon: fa-light fa-sitemap contents: @@ -332,6 +334,8 @@ navigation: path: advanced/sip/sip-twilio.mdx - page: Telnyx path: advanced/sip/sip-telnyx.mdx + - page: DIDWW + path: advanced/sip/sip-didww.mdx - page: Zadarma path: advanced/sip/sip-zadarma.mdx - page: Plivo diff --git a/fern/phone-numbers/didww.mdx b/fern/phone-numbers/didww.mdx new file mode 100644 index 000000000..ca674931b --- /dev/null +++ b/fern/phone-numbers/didww.mdx @@ -0,0 +1,82 @@ +--- +title: Import a number from DIDWW +subtitle: Purchase or select a DIDWW number, route it through your inbound trunk, and import it into Vapi as a BYO SIP trunk number. +description: Import a DIDWW phone number into Vapi as a BYO SIP trunk number. Assign the inbound trunk credential and an assistant, then test inbound and outbound calls. +slug: phone-numbers/didww +--- + +## Before you begin + +- An active DIDWW account is required. [Sign in](https://my.didww.com/users/sign_in) or [create an account](https://my.didww.com/users/sign_up#/users/sign_up). +- A completed [DIDWW SIP integration](/advanced/sip/didww) is required. +- A Vapi assistant for inbound calls is required. + +## Prepare the DIDWW number + + + + If needed, purchase a number from the [DIDWW Coverage page](https://my.didww.com/#/coverage). The number must support inbound calls and have available capacity. If you already own a suitable number, continue with it. + + For detailed purchasing instructions, see [Buy Numbers](https://doc.didww.com/phone-numbers/buy-numbers/index.html). + + + + In the DIDWW User Panel, go to **Phone Numbers → My Numbers** and select the number. Choose **Batch Actions → Update Trunks**, select the Vapi inbound trunk, and click **Confirm**. + + See [Assign inbound SIP trunk to your DID numbers](https://doc.didww.com/integrations/vapi/index.html#step-6-assign-inbound-sip-trunk-to-your-did-numbers) for the complete DIDWW procedure. + + + +## Import the number + + + + + + In the [Vapi dashboard](https://dashboard.vapi.ai), go to **Phone Numbers**, click **Create Phone Number**, and select **BYO SIP Trunk Number**. + + + + Enter the number in E.164 format, including the `+` prefix. Leave **Allow non-E164 phone numbers** off, select the **DIDWW Inbound Trunk** credential, and optionally add a label. Then click **Import SIP Phone Number**. + + + Vapi Create Phone Number form with BYO SIP Trunk Number selected and the DIDWW Inbound Trunk credential chosen + + + + + Open the imported number, select an assistant under **Inbound Settings**, and click **Save**. + + + Vapi phone number Inbound Settings with an assistant selected to handle inbound calls + + + + + + + Send the request to the API region where your organization is hosted. Use `https://api.vapi.ai` for US organizations or `https://api.eu.vapi.ai` for EU organizations. + + ```bash + curl -X POST https://api.vapi.ai/phone-number \ + -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "provider": "byo-phone-number", + "name": "DIDWW Number", + "number": "+14155550123", + "numberE164CheckEnabled": true, + "credentialId": "YOUR_CREDENTIAL_ID", + "assistantId": "YOUR_ASSISTANT_ID" + }' + ``` + + Use the credential `id` returned when you created the `DIDWW Inbound Trunk`. The optional `assistantId` assigns the assistant that handles inbound calls; omit it if you plan to configure inbound routing later. + + + +## Test the number + +Call the DIDWW number from an external phone and confirm that the assigned assistant answers. You can also use the imported number for [outbound calls](/calls/outbound-calling) to an external PSTN number to test outbound calling. + +If a call fails, verify that the number is assigned to the correct DIDWW inbound trunk and that all DIDWW signaling IPs are enabled for inbound calls in the Vapi credential. diff --git a/fern/static/images/quickstart/phone/didww-number-assign-assistant.png b/fern/static/images/quickstart/phone/didww-number-assign-assistant.png new file mode 100644 index 000000000..8b69f7c16 Binary files /dev/null and b/fern/static/images/quickstart/phone/didww-number-assign-assistant.png differ diff --git a/fern/static/images/quickstart/phone/import-didww-number-dashboard.png b/fern/static/images/quickstart/phone/import-didww-number-dashboard.png new file mode 100644 index 000000000..3ee711c8a Binary files /dev/null and b/fern/static/images/quickstart/phone/import-didww-number-dashboard.png differ diff --git a/fern/static/images/sip/sip-didww-assistant-tool.png b/fern/static/images/sip/sip-didww-assistant-tool.png new file mode 100644 index 000000000..a240cf564 Binary files /dev/null and b/fern/static/images/sip/sip-didww-assistant-tool.png differ diff --git a/fern/static/images/sip/sip-didww-authentication.png b/fern/static/images/sip/sip-didww-authentication.png new file mode 100644 index 000000000..cb11a633e Binary files /dev/null and b/fern/static/images/sip/sip-didww-authentication.png differ diff --git a/fern/static/images/sip/sip-didww-inbound-authorization.png b/fern/static/images/sip/sip-didww-inbound-authorization.png new file mode 100644 index 000000000..3f2d6d065 Binary files /dev/null and b/fern/static/images/sip/sip-didww-inbound-authorization.png differ diff --git a/fern/static/images/sip/sip-didww-inbound-general.png b/fern/static/images/sip/sip-didww-inbound-general.png new file mode 100644 index 000000000..d5b908126 Binary files /dev/null and b/fern/static/images/sip/sip-didww-inbound-general.png differ diff --git a/fern/static/images/sip/sip-didww-inbound-transfer-signaling.png b/fern/static/images/sip/sip-didww-inbound-transfer-signaling.png new file mode 100644 index 000000000..273c8800a Binary files /dev/null and b/fern/static/images/sip/sip-didww-inbound-transfer-signaling.png differ diff --git a/fern/static/images/sip/sip-didww-outbound-allowlist.png b/fern/static/images/sip/sip-didww-outbound-allowlist.png new file mode 100644 index 000000000..0bcf442fd Binary files /dev/null and b/fern/static/images/sip/sip-didww-outbound-allowlist.png differ diff --git a/fern/static/images/sip/sip-didww-outbound-credentials.png b/fern/static/images/sip/sip-didww-outbound-credentials.png new file mode 100644 index 000000000..5719f89e8 Binary files /dev/null and b/fern/static/images/sip/sip-didww-outbound-credentials.png differ diff --git a/fern/static/images/sip/sip-didww-outbound-gateway.png b/fern/static/images/sip/sip-didww-outbound-gateway.png new file mode 100644 index 000000000..0b81c5cbd Binary files /dev/null and b/fern/static/images/sip/sip-didww-outbound-gateway.png differ diff --git a/fern/static/images/sip/sip-didww-transfer-destination.png b/fern/static/images/sip/sip-didww-transfer-destination.png new file mode 100644 index 000000000..38aa70135 Binary files /dev/null and b/fern/static/images/sip/sip-didww-transfer-destination.png differ diff --git a/fern/static/images/sip/sip-didww-vapi-inbound-authentication.png b/fern/static/images/sip/sip-didww-vapi-inbound-authentication.png new file mode 100644 index 000000000..f404343d6 Binary files /dev/null and b/fern/static/images/sip/sip-didww-vapi-inbound-authentication.png differ diff --git a/fern/static/images/sip/sip-didww-vapi-inbound-gateways.png b/fern/static/images/sip/sip-didww-vapi-inbound-gateways.png new file mode 100644 index 000000000..0bb2a8138 Binary files /dev/null and b/fern/static/images/sip/sip-didww-vapi-inbound-gateways.png differ