# Appeal a 10DLC Brand identity verification
Source: https://docs.wavix.com/api-reference/10dlc/appeal-a-10dlc-brand-identity-verification
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/appeals
Submits an appeal for 10DLC brand identity verification. Provide any additional documentation to support the appeal. Use `appeal_category` to specify the appeal type:
- `VERIFY_TAX_ID` — Use if the brand is UNVERIFIED due to a tax ID mismatch. Applies to private companies, public companies, non-profits, and government entities.
- `VERIFY_NON_PROFIT` — Use if a non-profit brand is UNVERIFIED or VERIFIED but missing tax-exempt status.
- `VERIFY_GOVERNMENT` — Use if a government brand is UNVERIFIED or VERIFIED but missing government entity status.
# Appeal external vetting
Source: https://docs.wavix.com/api-reference/10dlc/appeal-external-vetting
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/vettings/appeals
Submits an appeal for an external vetting of the 10DLC Brand identified by `brand_id`.
# Brand status changed
Source: https://docs.wavix.com/api-reference/10dlc/brand-status-changed
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook BrandStatusChanged
Sends a notification when a 10DLC Brand status is updated.
# Campaign status changed
Source: https://docs.wavix.com/api-reference/10dlc/campaign-status-changed
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook CampaignStatusChanged
Sends a notification when a 10DLC Campaign status is updated in TCR.
# Delete a 10DLC Brand
Source: https://docs.wavix.com/api-reference/10dlc/delete-a-10dlc-brand
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/10dlc/brands/{brand_id}
Deletes a 10DLC Brand. Brands with active campaigns cannot be deleted.
# Delete a 10DLC Campaign
Source: https://docs.wavix.com/api-reference/10dlc/delete-a-10dlc-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}
Deletes a 10DLC Campaign. Associated phone numbers cannot be used as Sender IDs once the Campaign is deleted.
# Delete Brand evidence
Source: https://docs.wavix.com/api-reference/10dlc/delete-brand-evidence
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/10dlc/brands/{brand_id}/evidence/{id}
Deletes the Brand evidence file identified by the evidence ID. Deletion is permanent.
# Delete event subscription
Source: https://docs.wavix.com/api-reference/10dlc/delete-event-subscription
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/10dlc/subscriptions
Removes the 10DLC event subscription for the specified event category.
# Download Brand evidence
Source: https://docs.wavix.com/api-reference/10dlc/download-brand-evidence
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/evidence/{id}
Returns the Brand evidence file identified by the evidence ID.
# Import external vetting
Source: https://docs.wavix.com/api-reference/10dlc/import-external-vetting
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v3/10dlc/brands/{brand_id}/vettings
Imports an existing external vetting record into the 10DLC Brand identified by `brand_id`.
# Link a number to a 10DLC Campaign
Source: https://docs.wavix.com/api-reference/10dlc/link-a-number-to-a-10dlc-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}/numbers/{number}
Links a phone number to a 10DLC Campaign. Wavix automatically creates a Sender ID once the number is approved.
# List 10DLC Brands
Source: https://docs.wavix.com/api-reference/10dlc/list-10dlc-brands
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands
Returns a paginated list of 10DLC Brands for the authenticated account, filtered by date, name, legal name, and status.
# List 10DLC Campaigns
Source: https://docs.wavix.com/api-reference/10dlc/list-10dlc-campaigns
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/campaigns
Returns a paginated list of 10DLC Campaigns for the authenticated account, filtered by date, status, and use case.
# List Brand Campaigns
Source: https://docs.wavix.com/api-reference/10dlc/list-brand-campaigns
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/campaigns
Returns a paginated list of 10DLC Campaigns associated with the 10DLC Brand identified by `brand_id`.
# List Brand evidence
Source: https://docs.wavix.com/api-reference/10dlc/list-brand-evidence
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/evidence
Returns the evidence files uploaded for the 10DLC Brand identified by `brand_id`.
# List Brand identity appeals
Source: https://docs.wavix.com/api-reference/10dlc/list-brand-identity-appeals
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/appeals
Returns the identity verification appeals submitted for the 10DLC Brand identified by `brand_id`.
# List Campaign phone numbers
Source: https://docs.wavix.com/api-reference/10dlc/list-campaign-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}/numbers
Returns the phone numbers linked to the 10DLC Campaign identified by `campaign_id`.
# List event subscriptions
Source: https://docs.wavix.com/api-reference/10dlc/list-event-subscriptions
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/subscriptions
Returns the 10DLC event subscriptions for the authenticated account.
# List external vetting appeals
Source: https://docs.wavix.com/api-reference/10dlc/list-external-vetting-appeals
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/vettings/appeals
Returns the external vetting appeals for the 10DLC Brand identified by `brand_id`.
# List external vettings
Source: https://docs.wavix.com/api-reference/10dlc/list-external-vettings
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/vettings
Returns the external vettings for the 10DLC Brand identified by `brand_id`.
# Nudge a 10DLC Campaign review
Source: https://docs.wavix.com/api-reference/10dlc/nudge-a-10dlc-campaign-review
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}/nudge
Requests action on a pending or rejected 10DLC Campaign. Use `nudge_intent` to specify the action:
- `REVIEW`: Request review for a pending Campaign. - `APPEAL_REJECTION`: Appeal a rejected Campaign.
Note:
- The Campaign must be at least 72 hours old.
- Only one nudge request per Campaign is allowed every 24 hours.
# Number status changed
Source: https://docs.wavix.com/api-reference/10dlc/number-status-changed
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook NumberStatusChanged
Sends a notification when a phone number status is updated.
# Qualify a 10DLC Brand for a use case
Source: https://docs.wavix.com/api-reference/10dlc/qualify-a-10dlc-brand-for-a-use-case
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/usecases/{use_case}
Returns the qualification results for a 10DLC Brand use case. Includes MNO-specific attributes, restrictions, and fees.
# Register a 10DLC Brand
Source: https://docs.wavix.com/api-reference/10dlc/register-a-10dlc-brand
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands
Registers a 10DLC Brand. Submits the company's legal identity data (EIN/Tax ID, legal company name, contact and address) to The Campaign Registry (TCR), which verifies the brand identity. Charges a 10DLC brand registration fee on successful submission; fails with an insufficient-funds error when the balance cannot cover it. Only brands with `VERIFIED` or `VETTED_VERIFIED` identity status can register 10DLC Campaigns.
# Register a 10DLC Campaign
Source: https://docs.wavix.com/api-reference/10dlc/register-a-10dlc-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/campaigns
Registers a 10DLC Campaign under the 10DLC Brand identified by `brand_id`. The Brand must have a verified identity status.
# Request external vetting
Source: https://docs.wavix.com/api-reference/10dlc/request-external-vetting
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/vettings
Requests external vetting for a 10DLC Brand. Supported providers: `AEGIS`, `CV`, `WMC`. Supported classes: `STANDARD`, `ENHANCED`. Charges a 10DLC brand vetting fee (Standard or Enhanced); fails with an insufficient-funds error when the balance cannot cover it.
# Retrieve a 10DLC Brand
Source: https://docs.wavix.com/api-reference/10dlc/retrieve-a-10dlc-brand
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}
Returns the 10DLC Brand identified by `brand_id`.
# Retrieve a 10DLC Campaign
Source: https://docs.wavix.com/api-reference/10dlc/retrieve-a-10dlc-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}
Returns the 10DLC Campaign identified by `campaign_id` under the Brand identified by `brand_id`.
# Subscribe to 10DLC events
Source: https://docs.wavix.com/api-reference/10dlc/subscribe-to-10dlc-events
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/subscriptions
Registers a callback URL to receive Wavix 10DLC event notifications.
# Unlink phone number
Source: https://docs.wavix.com/api-reference/10dlc/unlink-phone-number
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}/numbers/{number}
Unlinks a phone number from a 10DLC Campaign. The associated Sender ID is also deleted.
# Update a 10DLC Brand
Source: https://docs.wavix.com/api-reference/10dlc/update-a-10dlc-brand
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v3/10dlc/brands/{brand_id}
Updates the 10DLC Brand identified by `brand_id`. Changing identity fields, including `ein_taxid`, `ein_taxid_country`, and `entity_type`, resets the Brand status to `UNVERIFIED` and triggers automatic re-submission. Brands in `VETTED_VERIFIED` status or with active Campaigns cannot be updated.
# Update a 10DLC Campaign
Source: https://docs.wavix.com/api-reference/10dlc/update-a-10dlc-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v3/10dlc/brands/{brand_id}/campaigns/{campaign_id}
Updates the 10DLC Campaign identified by `campaign_id`. Only the provided fields are changed.
# Upload Brand evidence
Source: https://docs.wavix.com/api-reference/10dlc/upload-brand-evidence
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/10dlc/brands/{brand_id}/evidence
Uploads a supporting evidence file for the 10DLC Brand identified by `brand_id`. Supported formats include `.jpg`, `.png`, and `.pdf`. Maximum size is 10 MB.
# Cancel a 2FA verification
Source: https://docs.wavix.com/api-reference/2fa/cancel-a-2fa-verification
https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/two-fa/verification/{session_id}/cancel
Cancels the 2FA verification identified by `session_id`. No further codes are sent, and previously sent codes can no longer be validated. A new verification is required to send another code.
# Create a 2FA Verification
Source: https://docs.wavix.com/api-reference/2fa/create-a-2fa-verification
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/two-fa/verification
Creates a 2FA verification and sends a real one-time password (OTP) to the destination phone number over the selected channel; this bills the account per OTP sent. Requires a 2FA service configured in the Wavix portal; the service is reused to generate and validate OTPs.
The verification proceeds through three steps:
1. Create a verification to generate and send an OTP.
2. Resend the OTP on the same verification if needed.
3. Validate the OTP through the check endpoint.
# List 2FA verification events
Source: https://docs.wavix.com/api-reference/2fa/list-2fa-verification-events
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/two-fa/session/{session_id}/events
Returns the lifecycle events of the 2FA verification identified by `session_id`, such as number lookup and code delivery.
# List 2FA verifications
Source: https://docs.wavix.com/api-reference/2fa/list-2fa-verifications
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/two-fa/service/{service_id}/sessions
Returns the 2FA verifications for the service identified by `service_id`, within the requested date range.
# Resend a code
Source: https://docs.wavix.com/api-reference/2fa/resend-a-code
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/two-fa/verification/{session_id}
Resends the OTP for the verification identified by `session_id` over the specified channel. Previously sent codes are invalidated.
# Validate a code
Source: https://docs.wavix.com/api-reference/2fa/validate-a-code
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/two-fa/verification/{session_id}/check
Validates the OTP submitted by the end user against the verification identified by `session_id`. Non-idempotent — each call consumes one of a limited number of attempts tracked server-side; once exhausted, the verification returns `429` until a new verification is created.
# Create an API key
Source: https://docs.wavix.com/api-reference/api-keys/create-an-api-key
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/api-keys
Creates an API key for the authenticated account. Restrict access by listing permitted IP addresses in `permitted_ips`.
# Delete an API key
Source: https://docs.wavix.com/api-reference/api-keys/delete-an-api-key
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/api-keys/{id}
Deletes the API key identified by `id`. Deletion is permanent and revokes the key immediately.
# List API keys
Source: https://docs.wavix.com/api-reference/api-keys/list-api-keys
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/api-keys
Returns the API keys belonging to the authenticated account.
# Update an API key
Source: https://docs.wavix.com/api-reference/api-keys/update-an-api-key
https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/api-keys/{id}
Updates an API key identified by `id`. Only the provided fields are changed.
# Authentication
Source: https://docs.wavix.com/api-reference/authentication
Authenticate Wavix API requests with a Bearer token. Covers creating an API key, restricted key scopes, IP restrictions, and code examples.
Wavix uses API keys for authentication. An API key is a unique identifier that you include in your API requests to verify your identity and authorize access. You authenticate your requests using the `Authorization` header with a Bearer token.
## Get your API key
1. [Sign in](https://app.wavix.com/) to your Wavix account.
2. Go to **Administration** → **API Keys**.
3. Click **Create new**.
4. Fill in the form:
* **API key name** (required): Enter a descriptive name, for example: "Mobile App Production".
* **Key type**: Choose **Unrestricted** for full access to all API resources, or **Restricted** to configure per-resource permissions.
* **Restrict access to authorized IPs only** (optional): Toggle to limit the key to specific IP addresses.
5. Click **Create**.
After clicking **Create**, a confirmation screen displays your API key. Copy it now. Once you dismiss the screen, the key is masked in the table.
### Restricted keys and scopes
When you select the **Restricted** key type, you assign one of three permission levels to each resource:
| Permission | Description |
| - | - |
| No access | Requests using this key cannot interact with this resource. |
| Read | Read-only access. The key can retrieve data but cannot create, update, or delete. |
| Write | Full access. The key can read, create, update, and delete. |
The following resources are available:
| Resource | API field | Controls |
| - | - | - |
| Numbers | `numbers` | Phone number inventory, settings, and purchasing |
| Trunks | `trunks` | SIP trunk configuration and management |
| Calls | `calls` | Call records, active calls, transcriptions, and call control |
| Messages | `messages` | Sending and receiving messages, Sender IDs, and opt-outs |
| Recordings | `recordings` | Listing, downloading, and deleting call recordings |
| Campaigns | `campaigns` | Bulk voice/SMS campaigns, Brands, short links, and analytics |
| 2FA | `two_fa` | Two-factor authentication services, OTPs, and verification logs |
| Validator | `validator` | Single and bulk phone number validation and HLR lookups |
| Webhooks | `webhooks` | Webhook endpoint configuration |
| Embeddable | `embeddable` | Widget tokens and embeddable component configurations |
| Billing | `billing` | Invoices, balance, payment methods, and usage reports |
| Account | `account` | Account profile and settings |
| Subaccounts | `subaccounts` | Subaccount management and suspension |
### IP address restriction
Enabling **Restrict access to authorized IPs only** adds an extra layer of security. Even if your API key is compromised, it can only be used from your authorized servers. This is useful for backend services on fixed IPs, production environments, and compliance requirements.
IP address restriction and key type are independent — you can combine a Restricted key with IP allowlisting for the strongest security posture.
Store your API key securely. Don't share it publicly or commit it to version control. If your API key is compromised, revoke it immediately and generate a new one.
## Authenticate your requests
Include your API key in the `Authorization` header using Bearer token format:
```bash theme={null}
Authorization: Bearer
```
Replace `` with your actual API key.
### Code examples
Here are examples showing how to authenticate requests:
```bash cURL theme={null}
curl -X GET "https://api.wavix.com/v3/messages?type=outbound" \
-H "Authorization: Bearer your_api_key"
```
```http HTTP theme={null}
GET https://api.wavix.com/v3/messages?type=outbound
Authorization: Bearer your_api_key
```
```javascript JavaScript theme={null}
const axios = require('axios');
const response = await axios.get('https://api.wavix.com/v3/messages', {
params: {
type: 'outbound'
},
headers: {
'Authorization': 'Bearer your_api_key'
}
});
console.log(response.data);
```
```python Python theme={null}
import requests
headers = {
'Authorization': 'Bearer your_api_key'
}
params = {
'type': 'outbound'
}
response = requests.get('https://api.wavix.com/v3/messages', headers=headers, params=params)
print(response.json())
```
Keep your API key confidential. Don't share it or expose it in public repositories, client-side code, or unsecured environments.
## Manage API keys programmatically
You can create, list, and manage API keys using the API endpoints. For details, see the [API Keys endpoint reference](/api-reference/authentication).
## Deprecated method
Query parameter authentication using the `appid` parameter is deprecated and will be removed in a future version. Use Bearer token authentication instead.
Previously, you could authenticate requests by including your API key as the `appid` query parameter:
```http theme={null}
GET https://api.wavix.com/v3/messages?appid=your_api_key
```
This method is still supported for backward compatibility, but we recommend migrating to Bearer token authentication as soon as possible.
# Download statement PDF
Source: https://docs.wavix.com/api-reference/billing/download-statement-pdf
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/billing/invoices/{id}
Returns the financial statement identified by `id` as a PDF file.
# List financial statements
Source: https://docs.wavix.com/api-reference/billing/list-financial-statements
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/billing/invoices
Returns the auto-generated financial statements for the authenticated account, paginated and ordered by billing period.
# List transactions
Source: https://docs.wavix.com/api-reference/billing/list-transactions
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/billing/transactions
Returns a paginated list of billing transactions for the authenticated account within the requested date range.
# List available phone numbers
Source: https://docs.wavix.com/api-reference/buy/list-available-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/countries/{country_id}/cities/{city_id}/dids
Returns a paginated list of phone numbers available for purchase in the specified city.
# List cities
Source: https://docs.wavix.com/api-reference/buy/list-cities
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/countries/{country_id}/cities
Returns a list of cities for countries where
`has_provinces_or_states` is `false`.
# List countries
Source: https://docs.wavix.com/api-reference/buy/list-countries
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/countries
Returns a list of countries where phone numbers are available.
# List region cities
Source: https://docs.wavix.com/api-reference/buy/list-region-cities
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/countries/{country_id}/regions/{region_id}/cities
Returns a list of cities in the specified region for countries where `has_provinces_or_states` is `true`.
# List regions
Source: https://docs.wavix.com/api-reference/buy/list-regions
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/countries/{country_id}/regions
Returns a list of regions (states or provinces) for countries where `has_provinces_or_states` is `true`.
# Answer a call
Source: https://docs.wavix.com/api-reference/call-control/answer-a-call
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls/{id}/answer
Answers the inbound call identified by `id`. Optionally starts recording, post-call transcription, or live media streaming on answer.
# Collect DTMF input
Source: https://docs.wavix.com/api-reference/call-control/collect-dtmf-input
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls/{id}/collect
Collects DTMF keypad input from the caller on the active call identified by `id`.
# End a call
Source: https://docs.wavix.com/api-reference/call-control/end-a-call
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/calls/{id}
Ends the active call identified by `id` by hanging up. Irreversible — the call cannot be resumed once ended.
# List active calls
Source: https://docs.wavix.com/api-reference/call-control/list-active-calls
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/calls
Returns the calls currently in progress for the authenticated account.
# Play audio
Source: https://docs.wavix.com/api-reference/call-control/play-audio
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls/{id}/play
Plays an audio prompt into the active call identified by `id`. The audio is audible to the remote party in real time.
# Retrieve a call
Source: https://docs.wavix.com/api-reference/call-control/retrieve-a-call
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/calls/{id}
Returns the call identified by `id`, including its current event and timestamps.
# Start a call
Source: https://docs.wavix.com/api-reference/call-control/start-a-call
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls
Places a real, billable outbound PSTN call. Returns the call with its `uuid` for tracking and control.
# Stop audio playback
Source: https://docs.wavix.com/api-reference/call-control/stop-audio-playback
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/calls/{id}/audio
Stops audio playback in the active call identified by `id`.
# Update a call
Source: https://docs.wavix.com/api-reference/call-control/update-a-call
https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/calls/{id}
Updates the active call identified by `id`. Only the `tag` field can be changed.
# Delete a call recording
Source: https://docs.wavix.com/api-reference/call-recording/delete-a-call-recording
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/recordings/{id}
Deletes the call recording identified by `id`. Deletion is permanent — the audio file is unrecoverable.
# List call recordings
Source: https://docs.wavix.com/api-reference/call-recording/list-call-recordings
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/recordings
Returns a paginated list of call recordings for the authenticated account, filtered by date range, number, call, or SIP trunk.
# Retrieve a recording
Source: https://docs.wavix.com/api-reference/call-recording/retrieve-a-recording
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/recordings/{id}
Returns the call recording identified by `id`, including its metadata and download URL.
# Retrieve a recording by call ID
Source: https://docs.wavix.com/api-reference/call-recording/retrieve-a-recording-by-call-id
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/recordings/{call_id}
Redirects to the recording file for the call identified by `call_id`. The download URL is returned in the `Location` header.
# Start call streaming
Source: https://docs.wavix.com/api-reference/call-streaming/start-call-streaming
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls/{call_id}/streams
Starts streaming the audio of the call identified by `call_id` to the WebSocket destination in `stream_url`, in the direction (`stream_type`) and channel (`stream_channel`) you configure. The streamed audio can include the remote party's voice.
# Stop call streaming
Source: https://docs.wavix.com/api-reference/call-streaming/stop-call-streaming
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/calls/{call_id}/streams/{id}
Stops the media stream identified by `id` on the call identified by `call_id`.
# Create a call webhook
Source: https://docs.wavix.com/api-reference/call-webhooks/create-a-call-webhook
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/calls/webhooks
Registers a callback URL for the `on-call` or `post-call` event. Wavix sends a POST callback to the URL when the event occurs. Creates persistent configuration that forwards call metadata to the URL on every matching call until the webhook is deleted.
# Delete a call webhook
Source: https://docs.wavix.com/api-reference/call-webhooks/delete-a-call-webhook
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/calls/webhooks
Removes the call webhook for the given event type. Wavix stops sending callbacks for that event.
# List call webhooks
Source: https://docs.wavix.com/api-reference/call-webhooks/list-call-webhooks
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/calls/webhooks
Returns the configured call webhooks for the authenticated account. Wavix sends POST callbacks for `on-call` and `post-call` events.
# On call event
Source: https://docs.wavix.com/api-reference/call-webhooks/on-call-event
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook OnCallEvent
Sends a notification to track the lifecycle of an active call.status updates. It's triggered when a call is initiated, answered, and ends.
# Post call event
Source: https://docs.wavix.com/api-reference/call-webhooks/post-call-event
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook PostCallEvent
The `post-call` callback includes details such as call disposition, duration, and cost. It's triggered after the call ends.
# Add to cart
Source: https://docs.wavix.com/api-reference/cart/add-to-cart
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/buy/cart
Adds the listed phone numbers to the purchase cart.
# Check out the cart
Source: https://docs.wavix.com/api-reference/cart/check-out-the-cart
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/buy/cart/checkout
Purchases the listed phone numbers from the cart. Activation and monthly fees are debited from the account balance immediately, and the purchase cannot be reversed through this API.
# Remove from cart
Source: https://docs.wavix.com/api-reference/cart/remove-from-cart
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/buy/cart
Removes the listed phone numbers from the purchase cart.
# Retrieve the cart
Source: https://docs.wavix.com/api-reference/cart/retrieve-the-cart
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/buy/cart
Returns the current purchase cart, including the phone numbers it contains and the documents each requires.
# Export CDRs
Source: https://docs.wavix.com/api-reference/cdrs/export-cdrs
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/cdrs/all
Streams matching call detail records as newline-delimited JSON (NDJSON), one record per line, for bulk export.
# List CDRs
Source: https://docs.wavix.com/api-reference/cdrs/list-cdrs
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/cdrs
Returns a paginated list of call detail records for the authenticated account, within the requested date range.
# Retrieve a CDR
Source: https://docs.wavix.com/api-reference/cdrs/retrieve-a-cdr
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/cdrs/{call_id}
Returns the call detail record for the call identified by `call_id`.
# Retrieve a transcription
Source: https://docs.wavix.com/api-reference/cdrs/retrieve-a-transcription
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/cdrs/{call_id}/transcription
Returns the transcription of the recorded call identified by `call_id`, including the transcript, speaker turns, and summary.
# Retrieve a transcription
Source: https://docs.wavix.com/api-reference/cdrs/retrieve-a-transcription-1
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/cdrs/{call_id}/transcriptions
Returns the transcription of the recorded call identified by `call_id`. Alias of the `transcription` endpoint.
# Search transcriptions
Source: https://docs.wavix.com/api-reference/cdrs/search-transcriptions
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/cdrs
Searches call transcriptions for the given keywords or phrases and returns the matching CDRs with their transcriptions.
# Transcribe a call recording
Source: https://docs.wavix.com/api-reference/cdrs/transcribe-a-call-recording
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/cdrs/{call_id}/retranscribe
Transcribes the recording of the call identified by `call_id`. Transcription is asynchronous; poll the transcription endpoint for the result. When it completes, the new transcription replaces any earlier one that the transcription endpoints return. Billed per minute at the account's call-transcription rate; fails with an insufficient-funds error when the balance cannot cover it.
# Get your API key
Source: https://docs.wavix.com/api-reference/get-your-api-key
Step-by-step instructions for creating Wavix API keys.
Wavix uses API keys for authentication. An API key is a unique identifier that you include in your API requests to verify your identity and authorize access. You authenticate your requests using the `Authorization` header with a Bearer token. For detailed authentication instructions and code examples, see the [Authentication guide](/api-reference/authentication).
Wavix uses API keys for authentication. An API key is a unique identifier that you include in your API requests to verify your identity and authorize access. You authenticate your requests using the `Authorization` header with a Bearer token.
## Get your API key
1. [Sign in](https://app.wavix.com/) to your Wavix account.
2. Go to **Administration** → **API Keys**.
3. Click **Create new**.
4. Fill in the form:
* **API key name** (required): Enter a descriptive name, for example: "Mobile App Production".
* **Key type**: Choose **Unrestricted** for full access, or **Restricted** to configure per-resource permissions.
* **Restrict access to authorized IPs only** (optional): Toggle to limit the key to specific IP addresses.
5. Click **Create**.
After clicking **Create**, a confirmation screen displays your API key. Copy it now — for security reasons, it won't be shown again. Once you dismiss the screen, the key is masked in the table.
For details on IP restriction and scope configuration, see the [Authentication guide](/api-reference/authentication).
Store your API key securely. Don't share it publicly or commit it to version control. If your API key is compromised, revoke it immediately and generate a new one.
# Getting started
Source: https://docs.wavix.com/api-reference/getting-started
Get started with the Wavix API: prerequisites, API keys and authentication, per-endpoint versioning, base URLs, and sandbox limitations.
## Prerequisites
* Before you can use the Wavix API, you need to [create a Wavix account](/getting-started/create-account).
* You also need to [create or get your API key](/api-reference/authentication).
Sandbox accounts can use the API before they select an account level. Some features and endpoints aren't available. For details, see [Sandbox](/getting-started/sandbox).
## Versioning
All endpoints and examples are designated with a specific version. Versions vary per endpoint and are not global.
Endpoint versions follow the base URL and come before the endpoint. For example:
```http theme={null}
https://api.wavix.com/v3/messages
```
This example shows the v3 endpoint for [sending messages](/api-reference/sms-and-mms/send-a-message).
For new projects, use the latest version. If you have existing integrations on v1, plan to migrate to v3 for full feature support and future compatibility.
## Authentication
Wavix APIs use API keys for secure authentication. You must include your API key in every request to access all endpoints.
### How to use your API key
1. Retrieve your API key from your Wavix account (see [Get your API key](/api-reference/authentication#get-your-api-key)).
2. Include your API key in the `Authorization` header using Bearer token format.
Example request:
```http theme={null}
GET https://api.wavix.com/v3/messages
Authorization: Bearer your_api_key
```
Replace `your_api_key` with your actual API key.
Keep your API key confidential. Do not share it or expose it in public repositories, client-side code, or unsecured environments.
If your API key is compromised, revoke it immediately in your Wavix account and generate a new one. For detailed authentication instructions and code examples, see the [Authentication guide](/api-reference/authentication).
## Next steps
* Explore the API reference for available endpoints and usage details.
* Review guides for specific messaging use cases:
* [Send an SMS message](/messaging/send-sms)
* [10DLC API](/messaging/10dlc-api)
* Subscribe to webhooks to receive real-time updates on your account and messaging events.
* Start building and testing your integration using your API key.
# Create a short link
Source: https://docs.wavix.com/api-reference/link-shortener/create-a-short-link
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/short-links
Creates a short link that redirects to the target URL and tracks click metrics.
# List short link metrics
Source: https://docs.wavix.com/api-reference/link-shortener/list-short-link-metrics
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/short-links/metrics
Returns per-click metrics for short links, including device, location, and campaign attribution, within the requested date range.
# Bulk update phone numbers
Source: https://docs.wavix.com/api-reference/my-numbers/bulk-update-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/numbers
Applies the same changes to every listed phone number. Only the provided fields are changed. Destination and SMS callback changes are applied asynchronously and may not be reflected in the response immediately.
# List phone numbers
Source: https://docs.wavix.com/api-reference/my-numbers/list-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/numbers
Returns a paginated list of the phone numbers owned by the authenticated account.
# Release phone numbers
Source: https://docs.wavix.com/api-reference/my-numbers/release-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/numbers
Releases the listed phone numbers back to stock. Selection accepts either `ids` (record IDs) or `dids` (phone numbers), but not both.
# Retrieve a phone number
Source: https://docs.wavix.com/api-reference/my-numbers/retrieve-a-phone-number
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/numbers/{id}
Returns the phone number identified by `id`, including its destinations, documents, and feature settings.
# Update a phone number
Source: https://docs.wavix.com/api-reference/my-numbers/update-a-phone-number
https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/numbers/{id}
Updates the phone number identified by `id`. Only the provided fields are changed.
# Upload a document
Source: https://docs.wavix.com/api-reference/my-numbers/upload-a-document
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/numbers/papers
Uploads a verification document for one or more phone numbers.
Uploaded files must meet the following requirements:
- Allowed formats: PNG, JPG, JPEG, TIFF, BMP, or PDF
- Maximum file size: 10 MB
- Files can't be password protected
- PDF files must not contain digital signatures
# Retrieve validation results
Source: https://docs.wavix.com/api-reference/number-validator/retrieve-validation-results
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/validation/{request_id}
Returns the results of an asynchronous batch validation identified by `request_id`.
# Validate a number
Source: https://docs.wavix.com/api-reference/number-validator/validate-a-number
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/validation
Validates a single phone number and returns line type, carrier, portability, and reachability details. The response's `error_code` is a per-number result code (`000` success; `013` internal error; `021` invalid format; `041` remote timeout; `042` remote query failed; `091` insufficient funds) — distinct from the HTTP status codes below.
# Validate multiple numbers
Source: https://docs.wavix.com/api-reference/number-validator/validate-multiple-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/validation
Validates a batch of phone numbers. When `async` is `true`, returns a `request_id` to poll for results instead of the validation details.
# OpenAPI specification
Source: https://docs.wavix.com/api-reference/openapi
Download the Wavix API OpenAPI specification in YAML or JSON, and use it with Swagger UI, Postman, or an SDK generator of your choice.
## Download OpenAPI specification
Download YAML format
Download JSON format
## Tooling
* **Swagger UI**: Import the YAML file at [editor.swagger.io](https://editor.swagger.io)
* **Postman**: Import using the YAML URL: `https://wavix.github.io/wavix-openapi/wavix-api.yaml`
* **Generate SDKs**: Use with [OpenAPI Generator](https://openapi-generator.tech/) or [Swagger Codegen](https://swagger.io/tools/swagger-codegen/)
## GitHub official repository
Source files and updates
# Retrieve a profile
Source: https://docs.wavix.com/api-reference/profile/retrieve-a-profile
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/profile
Returns the profile and billing details of the authenticated account.
# Retrieve account settings
Source: https://docs.wavix.com/api-reference/profile/retrieve-account-settings
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/profile/config
Returns the balance and global limits configured for the authenticated account.
# Update a profile
Source: https://docs.wavix.com/api-reference/profile/update-a-profile
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/profile
Updates the profile and billing details of the authenticated account.
# Create a SIP trunk
Source: https://docs.wavix.com/api-reference/sip-trunks/create-a-sip-trunk
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/trunks
Creates a SIP trunk for routing inbound and outbound calls. Returns the trunk with its generated `access_token`.
# Delete a SIP trunk
Source: https://docs.wavix.com/api-reference/sip-trunks/delete-a-sip-trunk
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v1/trunks/{id}
Deletes the SIP trunk identified by `id`. Deletion is permanent and stops call routing through the trunk.
# List SIP trunks
Source: https://docs.wavix.com/api-reference/sip-trunks/list-sip-trunks
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/trunks
Returns a paginated list of SIP trunks for the authenticated account.
# Retrieve a SIP trunk
Source: https://docs.wavix.com/api-reference/sip-trunks/retrieve-a-sip-trunk
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/trunks/{id}
Returns the SIP trunk identified by `id`.
# Update a SIP trunk
Source: https://docs.wavix.com/api-reference/sip-trunks/update-a-sip-trunk
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/trunks/{id}
Updates the SIP trunk identified by `id`. Only the provided fields are changed. On trial accounts, every update also applies the trial limits: a `call_limit` of at most 300 seconds (300 when omitted) and one concurrent call.
# Create a Sender ID
Source: https://docs.wavix.com/api-reference/sms-and-mms/create-a-sender-id
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/messages/sender-ids
Creates a Sender ID. Use the 10DLC API to create Sender IDs in the US. Registering a Sender ID incurs a recurring monthly fee, billed to the account balance.
# Create an opt-out
Source: https://docs.wavix.com/api-reference/sms-and-mms/create-an-opt-out
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/messages/opt-outs
Opts a phone number out of receiving messages from a Sender ID, a 10DLC campaign, or all outbound messages.
# Delete a Sender ID
Source: https://docs.wavix.com/api-reference/sms-and-mms/delete-a-sender-id
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v3/messages/sender-ids/{id}
Deletes the Sender ID identified by `id`. Deletion is permanent.
# Delivery report
Source: https://docs.wavix.com/api-reference/sms-and-mms/delivery-report
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook DeliveryReport
Sends a notification when an outbound message delivery status changes.
# Export messages
Source: https://docs.wavix.com/api-reference/sms-and-mms/export-messages
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages/all
Streams matching SMS and MMS messages as newline-delimited JSON (NDJSON), one message per line, for bulk export.
# Inbound message
Source: https://docs.wavix.com/api-reference/sms-and-mms/inbound-message
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook InboundMessage
Sends a notification when a message is received by an SMS-enabled phone number.
# List messages
Source: https://docs.wavix.com/api-reference/sms-and-mms/list-messages
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages
Returns a paginated list of SMS and MMS messages for the authenticated account, filtered by direction, date, and other criteria.
# List opted-out phone numbers
Source: https://docs.wavix.com/api-reference/sms-and-mms/list-opted-out-phone-numbers
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages/opt-outs
Returns a paginated list of phone numbers that have opted out of receiving messages from the authenticated account.
# List Sender IDs
Source: https://docs.wavix.com/api-reference/sms-and-mms/list-sender-ids
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages/sender-ids
Returns the Sender IDs registered for the authenticated account.
# Retrieve a message
Source: https://docs.wavix.com/api-reference/sms-and-mms/retrieve-a-message
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages/{id}
Returns the SMS or MMS message identified by `id`, including its delivery status and content.
# Retrieve a Sender ID
Source: https://docs.wavix.com/api-reference/sms-and-mms/retrieve-a-sender-id
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages/sender-ids/{id}
Returns the Sender ID identified by `id`.
# Send a message
Source: https://docs.wavix.com/api-reference/sms-and-mms/send-a-message
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v3/messages
Sends an SMS or MMS message. MMS is supported for U.S. numbers only. Track delivery using the returned `message_id` and the message status callback. The recipient must be opted in to receive messages from the account; sending to an opted-out number fails.
# Audio file transcription completed
Source: https://docs.wavix.com/api-reference/speech-analytics/audio-file-transcription-completed
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook AudioFileTranscriptionCompleted
Sends a notification when an audio file transcription is complete.
# Call transcription completed
Source: https://docs.wavix.com/api-reference/speech-analytics/call-transcription-completed
https://wavix.github.io/wavix-openapi/wavix-api.yaml webhook CallTranscriptionCompleted
Sends a notification when a call transcription is complete.
# Retranscribe a file
Source: https://docs.wavix.com/api-reference/speech-analytics/retranscribe-a-file
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/speech-analytics/{request_id}
Re-runs transcription on the file identified by `request_id`, replacing the existing transcript.
# Retrieve a transcription
Source: https://docs.wavix.com/api-reference/speech-analytics/retrieve-a-transcription
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/speech-analytics/{request_id}
Returns the transcription for the request identified by `request_id`, including transcript, speaker turns, and insights when available.
# Retrieve the original file
Source: https://docs.wavix.com/api-reference/speech-analytics/retrieve-the-original-file
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/speech-analytics/{request_id}/file
Returns the original audio file submitted for the transcription identified by `request_id`.
# Upload a file
Source: https://docs.wavix.com/api-reference/speech-analytics/upload-a-file
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/speech-analytics
Uploads an audio file for transcription. Transcription is asynchronous; Wavix sends a POST callback to `callback_url` when it completes, including the `request_id` returned by this request.
Callback body:
```json
{
"request_id": "e865ea07-25af-4fdd-876e-04b0d41d5ebd",
"status": "completed",
"error": null
}
```
- `request_id`: ID of the transcription request.
- `status`: One of `completed` (transcription succeeded) or `failed` (transcription encountered an error).
- `error`: Error description, or `null` when the transcription succeeded.
# Create a sub-account
Source: https://docs.wavix.com/api-reference/sub-accounts/create-a-sub-account
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/sub-organizations
Creates a sub-account under the authenticated master account. Returns the sub-account with its generated `api_key`.
# List sub-account transactions
Source: https://docs.wavix.com/api-reference/sub-accounts/list-sub-account-transactions
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/sub-organizations/{id}/billing/transactions
Returns a paginated list of billing transactions for the sub-account identified by `id`, within the requested date range.
# List sub-accounts
Source: https://docs.wavix.com/api-reference/sub-accounts/list-sub-accounts
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/sub-organizations
Returns a paginated list of sub-accounts under the authenticated master account.
# Retrieve a sub-account
Source: https://docs.wavix.com/api-reference/sub-accounts/retrieve-a-sub-account
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/sub-organizations/{id}
Returns the sub-account identified by `id`.
# Update a sub-account
Source: https://docs.wavix.com/api-reference/sub-accounts/update-a-sub-account
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v1/sub-organizations/{id}
Updates the sub-account identified by `id`. Only the provided fields are changed.
# Retrieve a voice campaign
Source: https://docs.wavix.com/api-reference/voice-campaigns/retrieve-a-voice-campaign
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/voice-campaigns/{id}
Returns the voice campaign identified by `id`, including its current status.
# Trigger a scenario
Source: https://docs.wavix.com/api-reference/voice-campaigns/trigger-a-scenario
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/voice-campaigns
Launches a voice campaign that places a real outbound call using a pre-configured scenario. Track progress with the returned voice campaign `id`.
# Create a widget token
Source: https://docs.wavix.com/api-reference/wavix-embeddable/create-a-widget-token
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v2/webrtc/tokens
Creates a Wavix Embeddable widget token that authenticates a browser-based softphone session. The token expires after `ttl` seconds.
# Delete a widget token
Source: https://docs.wavix.com/api-reference/wavix-embeddable/delete-a-widget-token
https://wavix.github.io/wavix-openapi/wavix-api.yaml delete /v2/webrtc/tokens/{id}
Deletes the Wavix Embeddable widget token identified by `id`. The token can no longer authenticate widget sessions, and any active session using it ends.
# List widget tokens
Source: https://docs.wavix.com/api-reference/wavix-embeddable/list-widget-tokens
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v2/webrtc/tokens
Returns a paginated list of Wavix Embeddable widget tokens for the authenticated account.
# Retrieve a widget token
Source: https://docs.wavix.com/api-reference/wavix-embeddable/retrieve-a-widget-token
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v2/webrtc/tokens/{id}
Returns the Wavix Embeddable widget token identified by `id`.
# Update a widget token
Source: https://docs.wavix.com/api-reference/wavix-embeddable/update-a-widget-token
https://wavix.github.io/wavix-openapi/wavix-api.yaml put /v2/webrtc/tokens/{id}
Updates the `payload` carried by the Wavix Embeddable widget token identified by `id`.
# Call streaming
Source: https://docs.wavix.com/api-reference/websocket/websockets/callstreaming
Bidirectional WebSocket channel for call audio streaming. Wavix opens the connection when a stream starts and closes it when the call ends.
# Create a WhatsApp template
Source: https://docs.wavix.com/api-reference/whatsapp/create-a-whatsapp-template
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/whatsapp/templates
Creates a WhatsApp template in one of your account's WhatsApp Business Accounts, submits it for review, and returns the new template.
Every WhatsApp message you send uses a template, so new message content starts with a new template.
**Behavior:** Returns `201` with the new template. Poll `whatsapp_templates_get` for the review outcome. Returns `409` when the WhatsApp Business Account already has a template with the same `name` and `language`.
**Requires:** Your account must have WhatsApp and its templates capability enabled, must have a subscription plan, and must not be blocked or suspended. The WhatsApp Business Account must have a connected sender; when your account has more than one WhatsApp Business Account, specify `waba_id` or `sender`.
# List WhatsApp Business Accounts
Source: https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-business-accounts
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/wabas
Returns a paginated list of the WhatsApp Business Accounts linked to your account, each with its messaging limit and number of senders.
**Behavior:** WhatsApp Business Accounts are ordered from newest to oldest.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# List WhatsApp messages
Source: https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-messages
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/messages
Returns a paginated list of the WhatsApp messages your account sent and received, each with its direction, delivery status, and phone numbers.
Messages that customers send to your senders appear here alongside the messages you sent.
**Behavior:** Messages are ordered from newest to oldest. If `direction` isn't specified, the response includes both directions, and when several filters are specified, a message must match all of them. Returns `400` when `direction`, `from`, or `to` isn't valid.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# List WhatsApp senders
Source: https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-senders
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/senders
Returns a paginated list of the WhatsApp senders in your account's WhatsApp Business Accounts, each with the WhatsApp Business Account it belongs to.
Every send needs a registered sender's number in `from`, and this is where that number comes from.
**Behavior:** Senders are ordered from newest to oldest. When both `status` and `waba_id` are specified, a sender must match both filters.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# List WhatsApp templates
Source: https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-templates
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/templates
Returns a paginated list of the WhatsApp templates in your account's WhatsApp Business Accounts, each with its review status and components.
Every send names a template by its `name` and `language`, and this is where those values come from.
**Behavior:** Templates are ordered from newest to oldest. When several filters are specified, a template must match all of them. Returns `404` when `sender` doesn't match a sender on your account.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# Retrieve a WhatsApp Business Account
Source: https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-business-account
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/wabas/{waba_id}
Returns the WhatsApp Business Account linked to your account with the given ID, including its messaging limit and number of senders.
**Behavior:** Returns `404` when the WhatsApp Business Account isn't linked to your account.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# Retrieve a WhatsApp message
Source: https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-message
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/messages/{uuid}
Returns the WhatsApp message with the given ID, sent or received, including its direction and current delivery status.
The send response carries only the initial status, so the delivered or undelivered outcome shows up here.
**Behavior:** Returns `404` when no message with this ID belongs to your account.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# Retrieve a WhatsApp sender
Source: https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-sender
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/senders/{number}
Returns the WhatsApp sender registered on your account for the given phone number, including its status, quality rating, and WhatsApp Business Account.
Creating a template needs a connected sender, and the sender's `status` shows whether it's connected.
**Behavior:** Returns `404` when no sender on your account has this phone number.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# Retrieve a WhatsApp template
Source: https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-template
https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/templates/{uuid}
Returns the WhatsApp template with the given ID, including its review status, components, and WhatsApp Business Account.
A new template's review outcome isn't known when `whatsapp_templates_create` returns, so the `approved` or `rejected` status shows up here.
**Behavior:** Returns `404` when no template with this ID belongs to your account's WhatsApp Business Accounts.
**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.
# Send a WhatsApp message
Source: https://docs.wavix.com/api-reference/whatsapp/send-a-whatsapp-message
https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/whatsapp/messages
Sends a WhatsApp template message from one of your registered senders to a recipient, and returns the message with its ID.
The API sends only template messages, so every send names one of your templates.
**Behavior:** Returns `201` with the new message. Poll `whatsapp_messages_get` for the delivery outcome. A repeat send with the same `idempotency_key` returns `200` with the original message and sends nothing.
**Requires:** Your account must have WhatsApp and its sending capability enabled, must have a subscription plan, and must not be blocked or suspended. `from` must be a sender registered on your account.
# Create a Wavix account
Source: https://docs.wavix.com/getting-started/create-account
Sign up for a Wavix account, verify your email and phone number, test your integration in the sandbox, and choose an account level to go live.
Go to [wavix.com](https://wavix.com/sign-up) and create an account.
Confirm your email address and phone number during the sign-up process.
After you sign up, the Wavix team reviews your account. While it's under review, your account is in the [sandbox](/getting-started/sandbox), where you can use the API to test your integration by sending messages and voice calls to your verified number. Once your account is approved, you can choose an account level and start live traffic.
After approval, choose either the Wavix Flex or Flex Pro account level.
For the steps and what each level unlocks, see [Go live](/getting-started/go-live).
Need help? Visit the [Wavix Account FAQ](https://wavix.com/faq/account) for answers to common account questions.
## Next steps
* [Send your first SMS](/getting-started/send-first-sms)
* [Getting started with the APIs](/api-reference/getting-started)
# Go live
Source: https://docs.wavix.com/getting-started/go-live
Select an account level to leave the sandbox and start sending to real recipients, without changing any code.
When you're ready to send to real recipients, select an account level to leave the [sandbox](/getting-started/sandbox). The sandbox uses the same endpoints and API key as a paid account, so you don't change any code to go live.
## Select an account level
Before you can select a level, the Wavix team reviews your account for compliance. You stay in the sandbox during the review. Once your account is approved, sign in to the [Wavix portal](https://app.wavix.com) and select an account level. For details on the review, see [Create a Wavix account](/getting-started/create-account).
You can choose Wavix Flex or Flex Pro. For a comparison of what each level includes, see the [Account Levels](https://wavix.com/account-levels) page.
## What changes when you go live
After you select a level:
* **You can send to any recipient.** The verified-number restriction is removed.
* **Messages aren't marked as test traffic.** The `[WAVIX TRIAL]` prefix is no longer added to SMS messages, so they go out the same way they will in production.
* **More endpoints become available.** Capabilities that depend on an account level, such as purchasing numbers, start working.
* **Your code stays the same.** You use the same endpoints and API key as before, so nothing in your integration changes.
## Prepare for production
Going live removes the sandbox restrictions, but most channels need extra setup before you send to real recipients at scale. Set up the ones you use:
**Voice and Voice AI**
* Create a [SIP trunk](/sip-trunking/create-sip-trunk) to connect your PBX or communications platform.
* Add your server's IP addresses to the [allowlist](/sip-trunking/ip-allowlisting) so the platform accepts your traffic.
* Connect an AI agent over SIP, using [LiveKit](/sip-trunking/guides/livekit), [OpenAI](/sip-trunking/guides/openai), [Vapi](/sip-trunking/guides/vapi), or [Retell AI](/sip-trunking/guides/retellai). See [Voice AI](/voice/voice-ai).
* Stream live call audio to your application with [call media streaming](/voice/call-streaming).
**Messaging**
* Register a [Sender ID](/messaging/send-sms#sender-id-registration) for each country you send to.
* Register for [US A2P 10DLC](/messaging/10dlc) if you send to US numbers.
**Numbers**
* [Buy or port numbers](/numbers/buy-number) to receive inbound calls and messages.
# Sandbox
Source: https://docs.wavix.com/getting-started/sandbox
Test SMS and voice with the Wavix API before you select an account level. Learn what the sandbox includes and its restrictions.
When you sign up, Wavix places your account in the sandbox while the team reviews it. The Wavix portal shows when sandbox API access is active.
The sandbox gives you access to the Wavix API before you choose an account level or add funds. Use it to test your integration and learn how the API works.
Sandbox messages and calls use live providers and can be sent only to the verified number on your account. Responses, delivery reports, and call behavior are the same as on a paid account.
Sandbox API access is rolling out gradually, so it isn't available to every new account yet.
For the full account setup flow, see [Create a Wavix account](/getting-started/create-account).
## What's available
When your sandbox becomes active, Wavix adds a free phone number to your account. This number is your sender: the Sender ID for SMS and the Caller ID for voice. You can find it on the **Numbers & trunks** page in the Wavix portal.
While your account is in the sandbox, you may see a different Sender ID or Caller ID than the free phone number added to your account. This is a sandbox limitation.
In the sandbox, you can:
* Send and receive SMS messages.
* Make and receive voice calls.
These are the main flows to test, but most of the API is available. You can explore other endpoints, such as listing your numbers or checking delivery reports. Endpoints that require a selected account level return an error (see [What's not available](#whats-not-available)).
The sandbox uses the same API endpoints and API key as a paid account. There's no separate sandbox URL or test key, so the same code works after you select an account level.
To start testing, send to your verified number. You can do this two ways:
* **Write code.** Follow [Send your first SMS](/getting-started/send-first-sms).
* **Use an AI client.** Send a message or place a call in natural language through the [Wavix MCP server](/mcp/overview).
## Restrictions
The sandbox is for testing your own integration, not for reaching real recipients. These restrictions apply:
* **Verified number only**: Calls and messages are limited to the phone number you verified during sign-up. The platform rejects any request that targets a different number.
* **Marked as test traffic**: Sandbox SMS messages are prefixed with `[WAVIX TRIAL]`. The prefix is removed when you upgrade to a paid account.
* **Lower rate limits and volume caps**: The sandbox applies lower rate limits and usage caps than a paid account.
## What's not available
Some features and endpoints depend on a selected account level and aren't available in the sandbox, such as purchasing numbers or sending traffic to anyone other than your verified number.
## Leave the sandbox
To leave the sandbox and use the full platform, select an account level. You don't need to change any code, since the sandbox uses the same endpoints and API key as a paid account. For the steps and what becomes available, see [Go live](/getting-started/go-live).
# Send your first SMS
Source: https://docs.wavix.com/getting-started/send-first-sms
Send your first SMS with the Wavix API in a few minutes. The same request works in the sandbox and after you go live, with no code changes.
**This quickstart is for sandbox accounts.** New accounts start in the [sandbox](/getting-started/sandbox), so you'll send an SMS to your own verified number and receive it on your phone. The same request works for any recipient after you [go live](/getting-started/go-live), with no code changes.
This tutorial walks you through sending your first SMS with the Wavix API.
## Prerequisites
* A [Wavix account](/getting-started/create-account). A sandbox account works.
* Your [API key](/api-reference/authentication).
Prefer not to write code? Connect an AI client to the [Wavix MCP server](/mcp/overview) and send the same test message in natural language.
When your sandbox becomes active, Wavix provisions a free phone number to your account. You'll use it as the sender.
1. Sign in to the [Wavix portal](https://app.wavix.com).
2. Go to **Numbers & trunks**.
3. Copy the number listed under **My numbers**, in E.164 format.
If you've already gone live, use any registered [Sender ID](/messaging/send-sms#sender-id-registration) as the sender instead.
Send a `POST` request to the messages endpoint. Replace the API key, the sender number (`from`), and the destination (`to`).
In the sandbox, `to` must be your verified number. The platform rejects any other destination. For the full rules, see [Sandbox](/getting-started/sandbox).
```bash cURL theme={null}
curl --request POST \
--url https://api.wavix.com/v3/messages \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"from": "447441477410",
"to": "12015551234",
"message_body": {
"text": "Hello from Wavix."
}
}'
```
```javascript Node.js theme={null}
const response = await fetch("https://api.wavix.com/v3/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WAVIX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "447441477410", // your provisioned number (sandbox) or registered Sender ID
to: "12015551234", // in the sandbox, this must be your verified number
message_body: { text: "Hello from Wavix." },
}),
});
if (!response.ok) {
throw new Error(`Wavix API error: ${response.status} ${await response.text()}`);
}
const message = await response.json();
console.log(message.message_id, message.status);
```
If successful, the service returns the `HTTP 201 Created` status code and the message details, including a `message_id` and a `status` of `accepted`. Your verified number should receive the message shortly.
Use the `message_id` from the response to check the delivery status:
```http theme={null}
GET https://api.wavix.com/v3/messages/{message_id}
Authorization: Bearer your_api_key_here
```
The `status` field moves from `accepted` to `sent` to `delivered`. For what each status means, see [Send SMS messages](/messaging/send-sms#get-message-details).
You can also check delivery in the Wavix portal. In the top menu, select **History** → **SMS history**, then open the **Outbound** tab to see your sent messages and their status.
## Next steps
* Send to any recipient: [Go live](/getting-started/go-live).
* Use MMS, tags, and other options: [Send SMS messages](/messaging/send-sms).
* Receive and reply to messages: [Receive SMS messages](/messaging/receive-sms).
# Welcome
Source: https://docs.wavix.com/index
Product guides, API references, and resources to help you integrate Wavix SMS and Voice services into your applications.
Sign up for an account and start building.
Explore endpoints and learn how to integrate Wavix into your workflow.
Find official SDKs and client libraries.
Need help? Contact our support team for technical assistance.
## Featured content
Step-by-step guides for sending SMS messages using the Wavix API.
Learn how to stream live call audio to your application in real time.
Connect 3CX to SIP trunks.
Integrate LiveKit AI agents.
# MCP authorization reference
Source: https://docs.wavix.com/mcp/authorization
OAuth 2.1 reference for the Wavix MCP server: discovery endpoints, dynamic client registration, PKCE, scope values, token lifetimes, and revocation.
The Wavix MCP server is an OAuth 2.1 protected resource. Wavix operates the authorization server. For what a grant binds and how permissions behave at runtime, see the [MCP server overview](/mcp/overview).
## Identifiers
| | |
| - | - |
| Protected resource | `https://mcp.wavix.com/mcp` |
| Authorization server issuer | `https://app.wavix.com` |
| Token audience (`aud`) | `https://mcp.wavix.com/mcp` |
| Access token format | JWT, signed by the issuer |
## Discovery and endpoints
An unauthenticated request returns `401` with an [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) `WWW-Authenticate` challenge naming the protected resource metadata document, which names the authorization server.
| Purpose | URL |
| - | - |
| Protected resource metadata (RFC 9728) | `https://mcp.wavix.com/.well-known/oauth-protected-resource` |
| Authorization server metadata (RFC 8414) | `https://app.wavix.com/.well-known/oauth-authorization-server` |
| OpenID Connect discovery | `https://app.wavix.com/.well-known/openid-configuration` |
| JSON Web Key Set | `https://app.wavix.com/.well-known/jwks.json` |
| Authorization | `https://app.wavix.com/oauth/authorize` |
| Token | `https://app.wavix.com/oauth/token` |
| Revocation (RFC 7009) | `https://app.wavix.com/oauth/revoke` |
| Client registration (RFC 7591) | `https://app.wavix.com/oauth/register` |
The step from `mcp.wavix.com` to `app.wavix.com` is a metadata pointer the client resolves itself, not an HTTP redirect.
## Client registration
Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)) is **enabled and open**: a client registers itself at `https://app.wavix.com/oauth/register` with no initial access token and no prior arrangement with Wavix. Clients that publish a client-ID metadata document are supported alongside it.
Registration alone grants nothing. Every token still requires a Wavix user to complete the consent screen, and mandatory PKCE plus exact `redirect_uri` matching bound what a registration can do. A client registering a plaintext `http://` loopback redirect URI is treated as a native application, so the callback matches on any port; every other component must match exactly.
## Authorization request
| Requirement | |
| - | - |
| Grant type | `authorization_code` |
| PKCE | **Required on every request.** `code_challenge_method` must be `S256`; `plain` is rejected |
| Client authentication | None — public clients only |
| `resource` ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)) | Accepted and validated, never required. When omitted, `aud` defaults to `https://mcp.wavix.com/mcp`. A non-matching value is rejected with `invalid_target` |
| Refresh tokens | Request the `offline_access` scope |
## Token lifetimes
| Token | Lifetime |
| - | - |
| Access token | 900 seconds (15 minutes) |
| Refresh token | 2,592,000 seconds (30 days) |
| Authorization code | 60 seconds, single use |
| Consent interaction | 300 seconds (5 minutes), single use |
Refresh tokens rotate: each refresh invalidates the token presented. A replayed authorization code revokes the grant.
## Scopes
The Wavix MCP server advertises **27 scope values**: 13 permission groups, each with `:read` and `:write`, plus `offline_access`. A `:write` grant includes read access to the same group.
| Scope group | Consent screen label | Covers |
| - | - | - |
| `account` | Account | Profile details and account settings |
| `billing` | Billing | Balance, invoices, and payment history |
| `calls` | Calls | Placing calls, call history, and speech analytics |
| `campaigns` | Campaigns | Voice campaigns, 10DLC brands, and short links |
| `embeddable` | Embeddable | Tokens for the in-browser calling widget |
| `messages` | Messages | Sending and reading SMS and MMS |
| `numbers` | Numbers | Searching, buying, and managing phone numbers |
| `recordings` | Recordings | Stored call recordings |
| `subaccounts` | Subaccounts | Sub-organizations and their settings |
| `trunks` | Trunks | Viewing and configuring SIP trunks |
| `two_fa` | 2FA and OTP | Sending and verifying one-time passcodes |
| `validator` | Number validation | Carrier and line-type lookups |
| `webhooks` | Webhooks | Call webhook endpoints |
`offline_access` is not a permission group and does not appear on the consent screen. It requests a refresh token.
### Permission levels
A grant assigns each group **No access**, **Read**, or **Write** — the same three levels a restricted API key uses. There is no higher level: an OAuth grant can never exceed write on any group.
### Scopes are bounded by the user's permissions
A scope is grantable only if the user's own account permissions allow it, and granted scopes are intersected with those permissions again on every request. Most groups map to one account permission. Three require several, and are grantable only when the user's role permits all of them:
| Scope group | Requires all of |
| - | - |
| `numbers` | `dids`, `buy`, `cart` |
| `calls` | `cdr`, `call_transcription` |
| `campaigns` | `voice_campaign`, `ten_dlc` |
`webhooks` and `embeddable` have no account permission counterpart and are grantable to any authenticated user.
## How scopes are enforced
1. **Tool listing.** A tool the granted scopes do not cover is omitted from `tools/list` and is not visible to the agent at all.
2. **Tool call.** A call from a stale tool list is refused with an MCP-level tool error inside a `200` response, not an HTTP status. The message names the missing scope.
3. **API gateway.** A request reaching the Wavix API without a covering scope is refused with `403`.
API-key management endpoints (`/v1/api-keys`) match no scope rule and are denied to every OAuth token by design, so their tools are hidden from all OAuth connections. A connection authenticated with a Wavix API key is not scope-filtered: it sees the full catalogue, and the Wavix API enforces that key's own scopes.
## Revocation
| Method | Effect |
| - | - |
| **Connected apps** in the Wavix portal | Revokes the grant. Any user manages their own; the master account and any sub-account whose role is **Admin** manages every grant across the account |
| `POST https://app.wavix.com/oauth/revoke` | RFC 7009. A client revokes its own tokens and the grant behind them |
| Account state change | Blocking or suspending a user, or removing their account level, revokes every grant that user created |
Revocation is immediate. OAuth tokens bypass the gateway's authorization cache, so the grant's state is re-read on every request rather than at token expiry.
## Rate limits and network access
The Wavix MCP server applies no IP allowlisting, user-agent filtering, or bot protection. Rate limits on the OAuth endpoints are not yet defined.
# Wavix MCP server
Source: https://docs.wavix.com/mcp/overview
Connect any MCP-compatible AI client to your Wavix account with OAuth 2.1 or an API key, and manage SMS, voice, numbers, and billing through natural language.
The **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** is an open standard for connecting AI assistants to external tools and services. The **Wavix MCP server** exposes your Wavix account as tools any MCP-compatible client can call: SMS, voice, numbers, SIP trunking, 2FA, speech analytics, and billing.
```http theme={null}
https://mcp.wavix.com/mcp
```
## When to use MCP vs. the REST API
| | MCP | REST API |
| - | - | - |
| **Best for** | AI-assisted workflows, exploration, prototyping | Production applications, automation pipelines |
| **How you interact** | Natural language prompts | Code (HTTP requests, SDK calls) |
| **Who uses it** | Developers, operations teams, AI agents | Backend services, scheduled jobs |
## How you authorize
Two credentials work, both fully supported. Neither is scheduled for removal.
| | OAuth 2.1 | API key |
| - | - | - |
| **How you connect** | Approve a consent screen in the browser | Paste a Bearer token into your client's config |
| **Client stores** | A 15-minute token plus a rotating refresh token | A long-lived secret, in plain text |
| **Identifies** | The Wavix user who approved it | The Wavix account the key belongs to |
| **Permissions** | Chosen per group, re-checked on every request | Fixed when you create the key |
| **Revoking** | **Connected apps** in the Wavix portal, immediate | Delete the key in the Wavix portal |
Use OAuth where your client supports it: no long-lived secret on disk, per-group permissions, self-service revocation. Use an API key everywhere else — it works with every MCP client, carries most MCP traffic today, and suits CI, where nobody is present to approve a consent screen.
For the OAuth path you only need to sign in to your Wavix account in a browser. For the API-key path, create a key under **Administration** → **API Keys** in the Wavix portal — see [Authentication](/api-reference/authentication) — and substitute it for `YOUR_API_KEY` below.
OAuth support varies by client. Claude Code runs the flow natively and is verified against the Wavix authorization server. For Cursor, VS Code, and Codex, the API-key configuration below is the documented path.
## Connect a client
**OAuth — recommended.** Add the server with no credentials:
```bash theme={null}
claude mcp add wavix https://mcp.wavix.com/mcp
```
Claude Code discovers the authorization server, registers itself, and opens your browser so you can grant permissions.
**API key.** Pass the key as an `Authorization` header instead:
```bash theme={null}
claude mcp add wavix https://mcp.wavix.com/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
```
Because a header is supplied, Claude Code uses it as-is and doesn't start the OAuth flow.
Either way, confirm the result:
```bash theme={null}
claude mcp list
```
Open the command palette with Cmd+Shift+P (Ctrl+Shift+P on Windows), search for **Open MCP settings**, and select **Add custom MCP** to open `mcp.json`:
```json theme={null}
{
"mcpServers": {
"wavix": {
"url": "https://mcp.wavix.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Create `.vscode/mcp.json` in your project:
```json theme={null}
{
"servers": {
"wavix": {
"type": "http",
"url": "https://mcp.wavix.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Open (or create) `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.wavix]
url = "https://mcp.wavix.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
```
Any other client that speaks streamable HTTP can connect too. Send a Wavix API key as a Bearer token, or implement the flow described in [Authorization](/mcp/authorization).
## Granting permissions
Every OAuth client sends you to the same consent screen at `app.wavix.com`. It is the only part of the flow you interact with, and what you choose there decides what the agent can do.
The heading names the application requesting access. Below it, the screen shows the Wavix user you are signed in as — the grant is recorded against **that user**, so use **Switch account** if it is the wrong one.
A logo appears only when the application serves it over HTTPS from the same host as its redirect URL. Treat a missing logo as normal, not as a warning sign.
**Requested access** summarizes what the client asked for, as a count of write and read permissions. Below it, permissions are grouped into five sections. Expand one to set its capabilities individually.
| Section | Capabilities |
| - | - |
| Messaging | Messages, Campaigns, 2FA |
| Voice | Calls, Trunks, Recordings |
| Numbers | Numbers, Validator |
| Account and billing | Billing, Account, Subaccounts |
| Developer | Webhooks, Embeddable |
Each carries a **No access**, **Read**, or **Write** selector, pre-set to what the client requested. **Your job here is to narrow it**, not to opt in — anything you leave alone is granted as asked.
Sections your role does not permit are not shown at all. If you expected one and it is missing, your Wavix role lacks that permission.
Selecting **Write** anywhere raises a warning: write access lets the application send messages, make calls, and buy numbers using your account balance. These actions are immediate and billable.
**Authorize** completes the connection and returns you to the client. **Cancel** grants nothing.
**Authorize** stays disabled while every section is set to **No access** — a grant has to carry at least one permission.
## Example prompts
* **"The SMS I sent to +12125551234 an hour ago hasn't been delivered. Can you check what happened?"** — finds the message with `sms_and_mms_messages_list`, then reads its delivery status and error codes.
* **"Show me all outbound calls from yesterday that weren't answered."** — queries `cdrs_search` by date, direction, and disposition.
* **"Search last month's inbound calls for 'refund' or 'escalate.' Show me the call UUIDs."** — scans transcriptions through `cdrs_search`.
* **"Find available US local numbers containing '555' and buy the first one."** — searches with `buy_numbers_list` and adds to the cart, asking you to confirm before checkout.
* **"What's my current balance, and is it enough for 10,000 SMS to US numbers?"** — totals recent activity from `billing_transactions_list` and estimates the send.
## What an OAuth grant binds
* **One Wavix user, not an account.** The grant belongs to whoever approved the consent screen.
* **No API key is created.** Nothing new is minted, stored, or exposed to leak or rotate.
* **Permissions are re-checked on every request.** Granted scopes are intersected with the user's *current* permissions, so removing one takes effect on the next call.
* **Revocation is immediate.** Revoking under **Connected apps** stops the next request; you don't wait for a token to expire.
* **Losing access revokes the grants.** Blocking or suspending a user, or removing their account level, revokes every grant they created.
### Sub-accounts
Each sub-account authorizes independently, under its own user and its own permissions — even though its access level, plan, and blocked state come from the master account. A manager (the master account, or a sub-account whose role is **Admin**) sees and revokes every grant across the account.
**There is no organization-level or admin-level consent.** An administrator cannot pre-approve a connector for everyone, and cannot approve one on another user's behalf. Every user authorizes for themselves. A permission the user's role forbids is blocked at the consent screen, not routed to an administrator.
## When a tool is missing or fails
Under OAuth, **a tool outside your granted permissions is omitted from the tool list entirely** — not listed and then refused.
Choose **No access** for **Numbers** at the consent screen and your agent never learns that number search exists. Asked to buy a number, it reports having no tool for the job, not that you lack permission. To widen a grant, revoke it under **Connected apps** and connect again.
Every tool and the permission it needs is listed in the [tool catalogue](/mcp/tools).
Three related cases:
* **The `api_keys_*` tools are never available over OAuth.** They are hidden from every OAuth connection by design: a delegated grant must never mint or manage your account's API keys. Connect with an API key if you need them.
* **A tool is listed but the call is refused.** Your client is working from a stale tool list. Restart it so it re-reads the catalogue.
* **API-key connections aren't filtered.** They see the full catalogue, and the Wavix API enforces that key's own scopes. A `401` on every call means the key itself is inactive, deleted, or mistyped — check it under **Administration** → **API Keys** in the Wavix portal.
## Review and revoke access
**OAuth grants** — go to **My Account** → **Connected apps** in the Wavix portal and revoke the application. Revocation takes effect on the connector's next request. Any user manages their own grants; the master account and any sub-account whose role is **Admin** manages every grant across the account. To change granted permissions, revoke and connect again.
**API keys** — go to **Administration** → **API Keys** and delete the key. This breaks every integration using it, so give MCP a dedicated restricted key.
## Recommendations
* **Grant only what the agent needs.** Set every unused section to **No access**. With an API key, create a dedicated restricted key: a key scoped to `messages` doesn't need SIP trunks or number purchasing.
* **Review your grants.** **Connected apps** in the Wavix portal lists everything with access to your account and revokes it in one click.
* **Some actions are immediate and billable.** The agent confirms before purchasing numbers, but sends messages and places calls without a follow-up prompt.
* **Don't put it behind a customer-facing agent.** A connected agent acts with your account's authority and balance, so anything it can be talked into doing, it does for real. Keep MCP connections to agents your own team operates.
The Wavix MCP server is open source — [browse the code, file issues, or contribute on GitHub](https://github.com/Wavix/wavix-mcp-server).
# Wavix MCP tool catalogue
Source: https://docs.wavix.com/mcp/tools
Every tool the Wavix MCP server exposes, grouped by product area, with the OAuth permission group that gates each one.
The Wavix MCP server exposes 116 tools, generated from the [Wavix OpenAPI specification](/api-reference/openapi). Tool arguments mirror the path, query, and body fields of the endpoint behind each tool.
Each section names the permission group that gates it. Tools that retrieve data require `group:read`; tools that create, update, or delete require `group:write`, which also covers read.
Under OAuth, a tool outside the permissions you granted is **omitted from the tool list entirely**, not listed and refused — see [When a tool is missing or fails](/mcp/overview#when-a-tool-is-missing-or-fails). A client authenticating with a Wavix API key sees every tool, and the Wavix API enforces that key's own scopes. If a tool listed here is missing and your permissions cover it, refresh the connection.
## SMS and MMS
Permission group: `messages`
| Tool | Description |
| - | - |
| `sms_and_mms_messages_send` | Send an SMS or MMS message |
| `sms_and_mms_messages_get` | Retrieve a message by ID |
| `sms_and_mms_messages_list` | List messages with optional filters |
| `sms_and_mms_sender_ids_list` | List Sender IDs on the account |
| `sms_and_mms_sender_ids_create` | Provision a new Sender ID |
| `sms_and_mms_sender_ids_get` | Retrieve a Sender ID by ID |
| `sms_and_mms_sender_ids_delete` | Delete a Sender ID |
| `sms_and_mms_opt_outs_list` | List opted-out phone numbers |
| `sms_and_mms_opt_outs_create` | Add a phone number to the opt-out list |
## Call control
Permission group: `calls`
| Tool | Description |
| - | - |
| `call_control_list` | List active calls |
| `call_control_create` | Start an outbound call |
| `call_control_get` | Retrieve a call |
| `call_control_update` | Update a call |
| `call_control_delete` | End a call |
| `call_control_answer` | Answer a call |
| `call_control_audio_play` | Play audio into a call |
| `call_control_audio_stop` | Stop audio playback |
| `call_control_collect` | Collect DTMF input from a caller |
| `call_control_streams_create` | Start call streaming |
| `call_control_streams_delete` | Stop call streaming |
## Call detail records
Permission group: `calls`
| Tool | Description |
| - | - |
| `cdrs_list` | List call detail records |
| `cdrs_get` | Retrieve a single CDR |
| `cdrs_search` | Search transcriptions for keywords or phrases |
| `cdrs_retranscribe` | Transcribe a call recording |
| `cdrs_transcription_get` | Retrieve a transcription |
| `cdrs_transcriptions` | Retrieve a transcription |
## Speech Analytics
Permission group: `calls`
| Tool | Description |
| - | - |
| `speech_analytics_get` | Retrieve a transcription |
| `speech_analytics_retranscribe` | Retranscribe a file |
| `speech_analytics_file_get` | Retrieve the original file as a pre-signed download URL |
## Call recording
Permission group: `recordings`
| Tool | Description |
| - | - |
| `call_recording_list` | List call recordings |
| `call_recording_get` | Retrieve a recording |
| `call_recording_get_by_call` | Retrieve a recording by call ID as a pre-signed download URL |
| `call_recording_delete` | Delete a call recording |
## Call webhooks
Permission group: `webhooks`
| Tool | Description |
| - | - |
| `call_webhooks_list` | List call webhooks |
| `call_webhooks_create` | Create a call webhook |
| `call_webhooks_delete` | Delete a call webhook |
## Phone numbers
Permission group: `numbers`
| Tool | Description |
| - | - |
| `buy_countries_list` | List countries available for number purchase |
| `buy_regions_list` | List regions within a country |
| `buy_cities_list` | List cities within a country |
| `buy_region_cities_list` | List cities within a specific region |
| `buy_numbers_list` | Search phone numbers available for purchase |
| `cart_get` | Retrieve the cart |
| `cart_add` | Add phone numbers to the cart |
| `cart_remove` | Remove phone numbers from the cart |
| `cart_checkout` | Check out the cart and purchase the numbers |
| `my_numbers_list` | List phone numbers on the account |
| `my_numbers_get` | Retrieve a phone number |
| `my_numbers_update` | Update a phone number |
| `my_numbers_bulk_update` | Update several phone numbers at once |
| `my_numbers_delete` | Release phone numbers back to stock |
## SIP trunking
Permission group: `trunks`
| Tool | Description |
| - | - |
| `sip_trunks_list` | List SIP trunks on the account |
| `sip_trunks_create` | Create a SIP trunk |
| `sip_trunks_get` | Retrieve a SIP trunk |
| `sip_trunks_update` | Update a SIP trunk |
| `sip_trunks_delete` | Delete a SIP trunk |
## 10DLC brands
Permission group: `campaigns`
| Tool | Description |
| - | - |
| `ten_dlc_brands_list` | List 10DLC brands |
| `ten_dlc_brands_create` | Register a 10DLC brand |
| `ten_dlc_brands_get` | Retrieve a 10DLC brand |
| `ten_dlc_brands_update` | Update a 10DLC brand |
| `ten_dlc_brands_delete` | Delete a 10DLC brand |
| `ten_dlc_brand_appeals_list` | List brand identity verification appeals |
| `ten_dlc_brand_appeals_create` | Appeal a brand identity verification |
| `ten_dlc_brand_evidence_list` | List brand appeal evidence |
| `ten_dlc_brand_evidence_get` | Download brand evidence as a pre-signed URL |
| `ten_dlc_brand_evidence_delete` | Delete brand evidence |
| `ten_dlc_brand_vettings_list` | List external vettings |
| `ten_dlc_brand_vettings_create` | Request an external vetting |
| `ten_dlc_brand_vettings_import` | Import an external vetting |
| `ten_dlc_brand_vetting_appeals_list` | List external vetting appeals |
| `ten_dlc_brand_vetting_appeals_create` | Appeal an external vetting |
| `ten_dlc_brand_usecase_qualify` | Check which use cases a brand qualifies for |
## 10DLC campaigns
Permission group: `campaigns`
| Tool | Description |
| - | - |
| `ten_dlc_campaigns_list` | List all 10DLC campaigns |
| `ten_dlc_brand_campaigns_list` | List campaigns for a specific brand |
| `ten_dlc_brand_campaigns_create` | Register a 10DLC campaign |
| `ten_dlc_brand_campaigns_get` | Retrieve a 10DLC campaign |
| `ten_dlc_brand_campaigns_update` | Update a 10DLC campaign |
| `ten_dlc_brand_campaigns_delete` | Delete a 10DLC campaign |
| `ten_dlc_campaign_numbers_list` | List phone numbers linked to a campaign |
| `ten_dlc_campaign_numbers_link` | Link a phone number to a campaign |
| `ten_dlc_campaign_numbers_unlink` | Unlink a phone number from a campaign |
| `ten_dlc_campaigns_nudge` | Nudge a carrier to review a campaign |
| `ten_dlc_subscriptions_list` | List 10DLC event subscriptions |
| `ten_dlc_subscriptions_create` | Subscribe to 10DLC events |
| `ten_dlc_subscriptions_delete` | Delete an event subscription |
## Voice campaigns
Permission group: `campaigns`
| Tool | Description |
| - | - |
| `voice_campaigns_create` | Trigger a voice campaign scenario |
| `voice_campaigns_get` | Retrieve a voice campaign |
## Link shortener
Permission group: `campaigns`
| Tool | Description |
| - | - |
| `link_shortener_create` | Create a trackable short link |
| `link_shortener_metrics_list` | List click metrics for short links |
## 2FA and OTP
Permission group: `two_fa`
| Tool | Description |
| - | - |
| `two_fa_verification_create` | Send a verification code to a phone number |
| `two_fa_verification_resend` | Resend a verification code |
| `two_fa_verification_check` | Validate a code submitted by the user |
| `two_fa_verification_cancel` | Cancel a verification |
| `two_fa_sessions_list` | List verifications |
| `two_fa_events_list` | List verification events |
## Number validation
Permission group: `validator`
| Tool | Description |
| - | - |
| `number_validator_get` | Validate a single phone number |
| `number_validator_create_bulk` | Validate multiple phone numbers |
| `number_validator_results_get` | Retrieve asynchronous validation results |
## Wavix Embeddable (WebRTC)
Permission group: `embeddable`
| Tool | Description |
| - | - |
| `webrtc_tokens_list` | List widget tokens |
| `webrtc_tokens_create` | Create a widget token for browser-based calling |
| `webrtc_tokens_get` | Retrieve a widget token |
| `webrtc_tokens_update` | Update a widget token |
| `webrtc_tokens_delete` | Delete a widget token |
## Billing
Permission group: `billing`
| Tool | Description |
| - | - |
| `billing_transactions_list` | List transactions on the account |
| `billing_invoices_list` | List financial statements |
## Account
Permission group: `account`
| Tool | Description |
| - | - |
| `profile_get` | Retrieve the account profile |
| `profile_update` | Update the account profile |
| `profile_config_get` | Retrieve account settings |
## Sub-accounts
Permission group: `subaccounts`
| Tool | Description |
| - | - |
| `sub_accounts_list` | List sub-accounts |
| `sub_accounts_create` | Create a sub-account |
| `sub_accounts_get` | Retrieve a sub-account |
| `sub_accounts_update` | Update a sub-account |
| `sub_accounts_transactions_list` | List sub-account transactions |
## API keys
**These tools are unavailable to every OAuth connection.** A delegated OAuth grant must never mint or manage the account's API keys, so no OAuth scope covers them and they are hidden from OAuth clients. They are available only to a client that authenticates with an API key.
| Tool | Description |
| - | - |
| `api_keys_list` | List API keys on the account |
| `api_keys_create` | Create an API key |
| `api_keys_update` | Update an API key |
| `api_keys_delete` | Delete an API key |
# 10DLC Brand and Campaign registration
Source: https://docs.wavix.com/messaging/10dlc
This guide explains how to register a 10DLC Brand and Campaign to send messages using US local 10-digit long codes.
## What is 10DLC?
10DLC stands for "10-digit long code". It lets businesses send Application-to-Person messages using standard, local 10-digit phone numbers as Sender IDs. In the US, carriers treat all messages (SMS and MMS) sent through a messaging provider like Wavix as Application-to-Person traffic.
This guide covers:
* Registering your Brand
* Registering your Campaign and outbound numbers (also called 10DLCs or Sender IDs)
## What is The Campaign Registry?
The Campaign Registry (TCR) is the central hub for registering application-to-person messaging campaigns in North America.
You must register a Brand and a Campaign if you're using 10-digit local phone numbers as sender IDs. This requirement doesn't apply if you use toll-free numbers or short codes.
Keep in mind:
* Each Brand registration must be approved by mobile carriers.
* Message throughput is determined by carriers after approval and depends on your Brand details and message content.
## 10DLC Brand and Campaign registration
You can register 10DLC Brands and Campaigns directly from the Wavix platform.
The information you provide during registration affects message throughput. Make sure your details are accurate and up to date.
## Brand registration
### Registration types
Choose either **Quick** or **Standard** Brand registration, depending on your business's legal status.
* **Quick** registration is for sole proprietors without an EIN or Tax ID and requires fewer details. If you select Quick registration, you're limited to a single 10DLC phone number and have low messaging throughput.
* **Standard** registration requires detailed company information and offers higher throughput. Brands can have up to 50 10DLC Campaigns, with up to 45 10DLC phone numbers per Campaign.
Mobile carriers automatically allocate message throughput based on your submitted Brand details and message content.
### Brand registration process
To register a Brand, provide complete, accurate, and up-to-date information about your organization, including:
* Brand name or DBA name
* Website address (optional for Quick registration)
* Company legal name
* Industry or vertical
* Country of registration
* EIN for US companies or Tax ID for companies in other countries, if applicable
* Company type, if applicable
* Stock exchange and stock symbol (for publicly traded companies only)
* Contact details
* Company support email address and phone number
* Business address (must match the legal address in your registration documents)
If you choose **Quick** registration, provide the business owner's contact details. For **Standard** registration, include the first and last name of the person submitting the Brand registration.
After you enter the information, select **Next** to view the Brand registration summary and review your details. To update other fields, select **Back**.
If the information is correct, confirm the non-refundable Brand registration fee and select **Submit**.
### Brand registration status
Your Brand registration status depends on the accuracy of your information. The Campaign Registry (TCR) Administrator will verify your company using several databases and verification software. Make sure your legal company name, address, and EIN or Tax ID are correct to obtain a "Verified" status.
If your Brand cannot be verified, update the details and resubmit the form.
Wavix provides feedback to help you identify possible data inaccuracies.
## Campaign registration
### Prerequisites
Before registering a 10DLC Campaign, make sure you have an active US local phone number on your account.
### Campaign registration process
Each 10DLC Campaign should describe your specific use case and the content of the SMS and MMS messages you plan to send.
To register a new 10DLC Campaign, provide the following information:
* Campaign name (for reference)
* Detailed Campaign description
* Use case that describes your messaging scenario
* Exact examples of messages you'll send
The Campaign description, use case, and message samples must be as specific as possible. Mobile carriers may review them to confirm they match the content of your messages.
Depending on your selected use case, provide up to five message examples. We recommend using exact samples without placeholders or variables.
Select all Campaign attributes that apply to your Campaign and message content using the YES/NO toggle.
Select **Next** to specify additional Campaign details.
#### Handling STOP, START, and HELP keywords (optional)
Wavix supports all standard opt-in and opt-out keywords by default. All additional keywords are case-insensitive.
**STOP keywords:**\
Add custom, comma-separated opt-out keywords if needed. US mobile carriers require you to provide a response (acknowledgment) when a person sends any STOP keyword. Enter the acknowledgment message your customers will receive if they opt out.
**START keywords:**\
Add custom, comma-separated opt-in keywords if needed. US mobile carriers require you to provide a response when a person sends any START keyword. Enter the acknowledgment message your customers will receive if they opt in.
**HELP keywords:**\
Your customers might reply with "HELP" or any custom HELP keyword to learn more about your messages. List all comma-separated HELP keywords and specify the message to send when any HELP keyword is received.
### Adding phone numbers to your Campaign
You can add up to five phone numbers to your Campaign, depending on your registration type. Choose the numbers you want to use as sender IDs and select **Next**.
Each phone number can be assigned to only one Campaign. If a phone number is grayed out, unassign it from its current Campaign before proceeding.
### Summary and Campaign registration
Review your Campaign details. To make changes, select **Back** and update the necessary fields. Select **Register** to complete the process.
Campaign registration and monthly fees for the first three months are deducted from your account automatically.
Standard use case Campaigns are automatically approved and become active. Special use case Campaigns may require additional carrier approval before activation. Once your Campaign is active, you can start messaging.
# 10DLC API
Source: https://docs.wavix.com/messaging/10dlc-api
Register 10DLC brands and campaigns to send compliant traffic to U.S. subscribers using the Wavix API.
## Prerequisites
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## What is 10DLC?
10DLC (10-digit long code) allows businesses to send A2P (application-to-person) messages using standard, local U.S. 10-digit phone numbers as sender IDs.
## What is The Campaign Registry (TCR)?
The Campaign Registry (TCR) is the central hub for registering A2P messaging campaigns in the U.S.
* Each brand registration must be pre-approved by mobile carriers.
* Message throughput is determined by carriers after registration and depends on brand details and message content.
You only need to register a 10DLC brand and campaign if you use 10-digit local phone numbers as sender IDs. This does not apply to toll-free numbers or short codes.
## Brand and Campaign registration flow
1. Register a brand on your account.
2. After brand verification, register one or more campaigns for the brand.
3. After campaign approval, associate one or more local U.S. phone numbers with the campaigns.
Wavix automatically creates a sender ID for these numbers. You can then send messages to U.S. subscribers.
## Subscribe to 10DLC webhooks
Subscribe to webhooks to be notified about events related to brands, campaigns, and phone numbers.
```http theme={null}
POST https://api.wavix.com/v3/10dlc/subscriptions
```
Request body:
```json theme={null}
{
"subscription_category": "brand",
"url": "https://your.site"
}
```
* `subscription_category`: Event category to subscribe to (`brand`, `campaign`, or `number`).
* `url`: Webhook URL to send events to.
All parameters are mandatory and cannot be left blank.
If successful, the method returns the `HTTP 201 Created` status. The response will contain an acknowledgment of the subscription.
```json theme={null}
{
"subscription_category": "brand",
"url": "https://your.site"
}
```
Wavix will automatically post events to the specified webhooks once your Brand, Campaign, or number status is updated in TCR. Depending on the `subscription_category` the following JSON objects will be sent to the webhook.
1. If subscription\_category is **brand**, brand status updates will be posted to your webhook
```json theme={null}
{
"brand_id": "BX12JH90",
"status": "VERIFIED"
}
```
* `brand_id`: the unique identifier of the Brand
* `status`: the updated status of the Brand
You can use the [Retrieve a 10DLC Brand](/api-reference/10dlc/retrieve-a-10dlc-brand) method to retrieve the Brand details, including feedback from TCR, if needed.
2. If subscription\_category is **campaign**, campaign status updates will be posted to your webhook
```json theme={null}
{
"brand_id": "BX12JH90",
"campaign_id": "CA0DFK10",
"status": "APPROVED"
}
```
* `brand_id`: the unique identifier of the Brand
* `campaign_id`: the unique identifier of the Campaign
* `status`: the updated status of the Campaign
You can use the [Retrieve a 10DLC Campaign](/api-reference/10dlc/retrieve-a-10dlc-campaign) method to retrieve the Campaign details.
## Register a 10DLC brand
Entity types supported: `private-profit`, `public-profit`, `non-profit`, `government`.
* `GOVERNMENT`: Only US government agencies can register a brand under this entity type. For government entities outside the US, use the `PRIVATE_PROFIT` entity type.
* `NON_PROFIT`: Only US-based non-profit organizations can register under this entity type. Non-profit organizations outside the US should use the `PRIVATE_PROFIT` entity type.
* `PUBLIC_PROFIT`: When registering a brand under this entity type, you must specify the stock exchange and provide the brand’s stock ticker.
To register a 10DLC Brand, use the following method:
```http theme={null}
POST https://api.wavix.com/v3/10dlc/brands
```
Request body:
```json theme={null}
{
"city": "Miami",
"company_name": "Company legal name",
"country": "US",
"dba_name": "New Brand",
"ein_taxid": "123456789",
"ein_taxid_country": "US",
"email": "email@brand.com",
"entity_type": "PRIVATE_PROFIT",
"first_name": "John",
"last_name": "Doe",
"mock": false,
"phone_number": "12123450099",
"status": "VERIFIED",
"stock_exchange": null,
"stock_symbol": null,
"street_address": "10, Street name",
"vertical": "HEALTHCARE",
"website": "https://brand.com",
"zip": "12345"
}
```
Ensure all brand information is **accurate** and **up-to-date**. The details you submit will be subject to an Identity Verification process conducted by the TCR. Any inconsistencies or mismatches between the submitted information and official records will result in the rejection of the Brand. The TCR specifically verifies the EIN/Tax ID, company legal name, and company legal address.
If successful, the method returns the `HTTP 201 Created` status. The response will include the newly created Brand object.
```json theme={null}
{
"brand_id": "BM20QP9",
"city": "Miami",
"company_name": "Company legal name",
"country": "US",
"created_at": "2024-07-24T08:10:49",
"dba_name": "New Brand",
"ein_taxid": "12345",
"ein_taxid_country": "US",
"email": "email@brand.com",
"entity_type": "PRIVATE_PROFIT",
"feedback": null,
"first_name": "John",
"last_name": "Doe",
"mock": false,
"phone_number": "12123450099",
"state_or_province": "FL",
"status": "REVIEW",
"stock_exchange": null,
"stock_symbol": null,
"street_address": "10, Street name",
"updated_at": "2024-07-24T08:29:09",
"vertical": "HEALTHCARE",
"website": "https://brand.com",
"zip": "12345"
}
```
Once the status of your Brand’s verification changes in TCR, you’ll receive a callback via your webhook.
## Appeal a brand identity verification
If your brand is `UNVERIFIED`, review and update details. If you believe the information is correct, you can submit an appeal for the Brand identity verifications and optionally upload supporting documents.
```http theme={null}
POST https://api.wavix.com/v3/10dlc/brands/:brand_id/appeals
```
Request body:
```json theme={null}
{
"appeal_categories": ["VERIFY_TAX_ID"],
"evidence": ["7c27328f-584e-415d-aa21-3a9f9fce2540"],
"explanation": "Find the company incorporation docs attached and please review the Brand Identity status."
}
```
* `brand_id`: Unique identifier of the brand.
* `appeal_categories`: Array of appeal categories.
* `evidence`: Array of evidence UUIDs (optional).
* `explanation`: Justification for your appeal (optional).
The applicable appeal categories vary based on your entity type and current identity verification status:
* `VERIFY_TAX_ID`: For `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, and `GOVERNMENT` entities with an identity verification status of `UNVERIFIED`.
* `VERIFY_NON_PROFIT`: For `NON_PROFIT` entities with an identity verification status of `UNVERIFIED` or `VERIFIED` but missing the `Tax Exempt` status.
* `VERIFY_GOVERNMENT`: For `GOVERNMENT` entities with an identity verification status of `UNVERIFIED` or `VERIFIED` but missing the `Government Entity` status.
## Brand vetting
Apply for brand vetting to access special use cases, improve throughput, or pass verification. You can import external vettings.
Use the following method to request external vetting for the Brand:
```http theme={null}
POST https://api.wavix.com/v3/10dlc/brands/:brand_id/vettings
```
Request body:
```json theme={null}
{
"evp_id": "AEGIS",
"vetting_class": "STANDARD"
}
```
* `brand_id`: Unique identifier of the brand.
* `evp_id`: External vetting provider code (`AEGIS`, `CV`, `WMC`).
* `vetting_class`: Requested vetting type (`STANDARD`, `ENHANCED`, `POLITICAL`).
## Register a 10DLC campaign
You can register a campaign after your brand is `VERIFIED` or `VETTED_VERIFIED`.
As mandated by US MNOs (Mobile Network Operators), you must declare a use case for your Campaign. Select the most appropriate use case and include additional details in the Campaign description. Wavix supports two types of use case categories:
* **Standard use cases**: Available for all qualified brands.
* **Special use cases**: Sensitive/critical, may require vetting or approval.
Once a campaign is created, the use case cannot be changed.
When submitting a Campaign for registration, you must provide the following details:
* **Campaign description** - give a clear, detailed description of the Campaign’s purpose.
* **Opt-in workflow** - describe the process through which consumers opt-in to the Campaign, ensuring they give informed consent to receive messages. This description should be explicit and inform consumers about the nature of the program. If there are multiple opt-in methods, include them all.
* **Message samples** - provide at least one sample message for the Campaign. Some Campaign types require a minimum of two samples. Use the ‘Qualify a 10 DLC Brand for a Use Case’ method to check the required number of samples.
* **Message content attributes** - specify the attributes of the message content to help MNOs better understand what will be sent.
* **Opt-in, opt-out, and help keywords and acknowledgments**: include keywords for opting in, opting out, and seeking help, along with any required acknowledgments.
Use the following method to submit a Campaign for registration.
```http theme={null}
POST https://api.wavix.com/v3/10dlc/brands/:brand_id/campaigns
```
Request body:
```json theme={null}
{
"name": "Customer verification",
"usecase": "2FA",
"description": "Our campaign aims to enhance the security and user experience of the registration process by sending …",
"embedded_links": false,
"embedded_phones": false,
"age_gated": false,
"direct_lending": false,
"optin": true,
"optout": true,
"help": true,
"sample1": "Your verification code is XXXXXX",
"optin_workflow": "Our customers explicitly request an SMS code to verify …",
"help_message": "For help, please visit www.brandname.com. To opt-out, reply STOP.",
"optin_message": "You are now opted-in. For help please reply HELP, to stop please reply STOP",
"optout_message": "You are now opted out and will receive no further messages",
"optin_keywords": "begin,start",
"optout_keywords": "quit,stop",
"help_keywords": "help"
}
```
If successful, the method returns the `HTTP 201 Created` status. The response will include the created Campaign object.
```json theme={null}
{
"affiliate_marketing": false,
"age_gated": false,
"auto_renewal": false,
"brand_id": "BAL08VM",
"campaign_id": "C1W1J07",
"created_at": "2024-08-13T14:45:36",
"description": "Our campaign aims to enhance the security and user experience of the registration process by sending …",
"direct_lending": false,
"embedded_link_sample": null,
"embedded_links": false,
"embedded_phones": false,
"feedback": null,
"help": true,
"help_keywords": "help",
"help_message": "For help, please visit www.brandname.com. To opt-out, reply STOP.",
"last_bill_date": "2024-08-13T14:45:37",
"mock": false,
"monthly_fee": "10.0",
"name": "Customer verification",
"next_bill_date": "2024-11-13T00:00:00",
"optin": true,
"optin_keywords": "begin,start",
"optin_message": "You are now opted-in. For help please reply HELP, to stop please reply STOP",
"optin_workflow": "Our customers explicitly request an SMS code to verify …",
"optout": true,
"optout_keywords": "stop,quit,unsubscribe",
"optout_message": "You are now opted out and will receive no further messages",
"phone_numbers": [],
"privacy_policy": null,
"sample1": "Your verification code is XXXXXX",
"sample2": null,
"sample3": null,
"sample4": null,
"sample5": null,
"status": "REVIEW",
"terms_conditions": null,
"updated_at": "2024-08-13T14:45:42",
"usecase": "2FA"
}
```
The time it takes the Campaign to be reviewed depends on multiple factors and the process might take several days. You’ll receive a callback to your webhook once the Campaign status is changed in TCR.
All campaigns require a minimum 3-month commitment. Wavix bills for the first three months upfront. Afterward, campaigns renew monthly. Political campaigns are renewed monthly with no minimum commitment.
## Associate phone numbers with a campaign
After campaign registration, associate phone numbers with the campaign. Sender IDs are created automatically once numbers are activated.
You can associate phone numbers before campaign registration is complete, but outbound messaging is only enabled after successful registration.
```http theme={null}
POST https://api.wavix.com/v3/10dlc/brands/:brand_id/campaigns/:campaign_id/:number
```
* `brand_id`: Unique identifier of the brand.
* `campaign_id`: Unique identifier of the campaign.
* `number`: Phone number to associate with the campaign.
Response example:
```json theme={null}
{
"success": true,
"number": "+1234567890",
"brand_id": "brd_abc123",
"campaign_id": "cmp_xyz456",
"status": "pending",
"message": "Number association request received. Provisioning in progress."
}
```
Provisioning for outbound messaging may take several hours. You’ll receive a webhook callback when the number status is updated in TCR.
# Wavix 2FA API overview
Source: https://docs.wavix.com/messaging/2fa
Learn how the Wavix 2FA API works, including verification flows, failover logic, and service restrictions.
Use the Wavix [2FA](https://wavix.com/2fa) API to generate one-time passwords (OTPs), send them via voice or SMS, and validate responses. Wavix automatically fails over between channels. For example, it calls a user if an SMS fails to ensure reliable delivery.
## How Wavix 2FA works
To use the 2FA API, you must first create a **2FA Service**. Each service defines:
* The length of one-time passwords
* Active delivery channels: voice, SMS, or both
* Automatic failover settings
* Phone number validation settings
You only need to create a service once. You can use it to send and verify as many OTPs as needed.
When you send an OTP via voice, Wavix calls the user and reads the code once they answer. Messages are read in English.
### Verification flow
The following diagram provides a high-level view of the interaction between the User, your Application, and Wavix:
```mermaid actions={false} theme={null}
graph LR
U[User] -- Phone number --> A[Your Application]
A -- Request OTP --> W[Wavix API]
W -- Deliver code --> U
U -- Enter code --> A
A -- Validate code --> W
W -- Success/Failure --> A
```
The general 2FA flow is outlined below:
1. A user provides their phone number to your application (e.g. through a form).
2. You call the Wavix 2FA API to create a **Verification**.
3. Wavix generates a unique OTP and sends it via the specified channel.
4. The user enters the code in your application.
5. You call the Wavix 2FA API to verify the code against the **Verification ID**.
6. Wavix returns the results (`success` or `failure`).
## Service restrictions
To prevent abuse, the following limits apply:
1. **Expiration**: Codes are valid for 5 minutes.
2. **Validation attempts**: You have a maximum of 5 attempts to validate a single code.
3. **Resend limit**: You can send a maximum of 5 codes within a single Verification session.
## Next steps
* **[Service setup](/messaging/2fa-setup)**: A guide to creating and configuring a 2FA service in the Wavix portal.
* **[API integration](/messaging/2fa-integration)**: A technical guide to implementing the verification flow in your application.
# Integrate SMS and Voice 2FA via API
Source: https://docs.wavix.com/messaging/2fa-integration
Implement one-time passcode verification with the Wavix 2FA API: send a code over SMS or voice, verify the code your user enters, and handle failover.
Once you have created a [2FA Service](/messaging/2fa-setup), use the methods below to implement the verification flow in your application.
## Send a verification code
To send a code, [create a Verification](/api-reference/2fa/create-a-2fa-verification). Wavix automatically generates and sends the OTP.
```http theme={null}
POST https://api.wavix.com/v1/two-fa/verification
Authorization: Bearer your_api_key
Content-Type: application/json
```
**Request body:**
```json theme={null}
{
"service_id": "7204a030201211ee9fb47d093f2f127c",
"to": "37128782931",
"channel": "sms"
}
```
* `service_id`: The unique ID of your 2FA Service.
* `to`: The destination phone number in E.164 format.
* `channel`: Use `sms` or `voice`.
**Response example:**
```json theme={null}
{
"success": true,
"service_id": "7204a030201211ee9fb47d093f2f127c",
"destination": "37128782931",
"session_id": "5f1a8680201511eeafdfcfc3dedfac51",
"created_at": "2023-07-11T18:04:25.786Z",
"number_lookup": {
"number_type": "mobile",
"country": "LV",
"current_carrier": "Latvijas Mobilais Telefons"
}
}
```
* `session_id`: Use this ID to validate the OTP or resend the code.
* `number_lookup`: Returned only if **Number validation** is enabled for the service.
## Resend a verification code
If a user doesn't receive the initial code or you want to try a different delivery method, use the [resend method](/api-reference/2fa/resend-a-code). While Wavix supports automatic channel failover, this method gives you manual control to resend a code via a specific `channel` (`sms` or `voice`).
```http theme={null}
POST https://api.wavix.com/v1/two-fa/verification/{session_id}
Authorization: Bearer your_api_key
Content-Type: application/json
```
**Request body:**
```json theme={null}
{
"channel": "voice"
}
```
## Validate an OTP
In order to [validate an OTP](/api-reference/2fa/validate-a-code) entered by a user, use the method below:
```http theme={null}
POST https://api.wavix.com/v1/two-fa/verification/{session_id}/check
Authorization: Bearer your_api_key
Content-Type: application/json
```
**Request body:**
```json theme={null}
{
"code": "749503"
}
```
**Response:**
```json theme={null}
{
"is_valid": true
}
```
## Additional operations
### Cancel a Verification
You can [cancel a Verification](/api-reference/2fa/cancel-a-2fa-verification) to invalidate all codes and prevent further resends.
```http theme={null}
PATCH https://api.wavix.com/v1/two-fa/verification/{session_id}/cancel
Authorization: Bearer your_api_key
```
### Query service logs
Retrieve [active Verifications](/api-reference/2fa/list-2fa-verifications) and their associated events.
```http theme={null}
GET https://api.wavix.com/v1/two-fa/service/{service_id}/sessions?from=2023-07-01&to=2023-07-31
Authorization: Bearer your_api_key
```
To see [specific events](/api-reference/2fa/list-2fa-verification-events) for a session:
```http theme={null}
GET https://api.wavix.com/v1/two-fa/session/{session_id}/events
Authorization: Bearer your_api_key
```
**Event types:**
* `Number lookup`: Wavix checked if the destination number is valid.
* `Code sent via SMS`: OTP sent via text.
* `Code sent via voice`: OTP sent via automated call.
* `Verification`: A code validation attempt.
# Set up and configure a 2FA service
Source: https://docs.wavix.com/messaging/2fa-setup
Create and manage a 2FA service in the Wavix portal. Set the code length, delivery channels, and failover before you send verification codes.
Before you can send authentication codes, you must create a **2FA Service**. This service stores your configuration, such as delivery channels and password length.
## Prerequisites
Before creating a service, ensure you have:
* A [Wavix account](https://wavix.com/sign-up).
* Your [API key](/api-reference/authentication#get-your-api-key).
## How to create a 2FA service
Follow these steps to configure your 2FA service in the Wavix portal:
1. Go to **Solutions** → **2FA**.
2. Select **Create new**.
**Service details**\
Enter a name and code length. The service name appears in messages so users recognize your brand. We recommend enabling **Validate phone numbers** to verify destination numbers before codes are sent.
**Delivery channels**\
Enable **SMS**, **Voice**, or both. For SMS, you can use a **Shared Sender ID** for instant setup or a **Dedicated Sender ID** (requires per-country registration). You can also enable **Fallback to Voice** for improved delivery.
If using Voice, select a **Caller ID** from your account.
Select **Next**.
1. Review settings on the **Summary** page.
2. Select **Save and close** or **Save and preview** to test the service immediately.
To fallback to voice calls when SMS delivery fails, you must enable **Channel failover** and select **Voice** as a delivery channel.
Once created, you can copy the **Service ID** from the list of services. You'll need this ID to send and verify OTPs in your [API implementation](/messaging/2fa-integration).
# Email campaigns
Source: https://docs.wavix.com/messaging/email
Send email campaigns to your customers with a managed service from the Wavix team, including personalization, scheduling, and engagement tracking.
Email campaigns let you reach your customers in their inbox, alongside your SMS and voice communications. The Wavix team sends each campaign for you, from your own domain.
## How email campaigns work
Email campaigns are a managed service. You don't build or send the campaign yourself:
1. **Request access.** Contact the Wavix team with your use case and expected volume. Wavix reviews each request individually.
2. **Authenticate your domain.** After approval, the Wavix team gives you the DNS records to add to your sending domain. These records prove to mailbox providers that Wavix can send email on your behalf.
3. **Send your campaign brief.** Share your recipient list, email content, and schedule with the Wavix team.
4. **Get your results.** The Wavix team sends the campaign and shares the campaign report with you.
## Supported features
### Email content
* **HTML emails** with your own design, images, and links.
* **Responsive layouts** that adapt to desktop and mobile screens.
* **Reusable templates** for recurring campaigns.
### Your own domain
Emails come from an address on your domain, such as `news@example.com`. Domain authentication helps your emails reach the inbox instead of the spam folder.
### Personalization
Add placeholders to the subject line, content, and links, such as the customer name or an account number. The Wavix team fills them in for each recipient from your recipient list.
### Scheduling
Send your campaign right away or schedule it for later. You can set a delivery window, so emails arrive at the time that works best for your customers.
### Recipient validation
Before sending, the Wavix team can check your recipient list for invalid or risky email addresses. Removing them protects your sender reputation.
### Unsubscribe handling
Every campaign includes an unsubscribe link. The campaign report lists the recipients who unsubscribed, so you can keep your recipient lists up to date.
### Campaign reports
After the campaign, you get a report with deliveries, opens, clicks, unsubscribes, bounces, and spam complaints.
## Get started
To request access to email campaigns, contact [sales@wavix.com](mailto:sales@wavix.com).
# MMS can be sent to the US and CA phone numbers only
Source: https://docs.wavix.com/messaging/errors/12
## Error description
Wavix only allows sending MMS messages to the US and Canadian phone numbers.
## How to fix it
Ensure the destination number originates from the US or Canada. You can use the Wavix Number validator — available in the API or the Customer portal — to verify the number and its type.
# Media file size can be 1MB or less
Source: https://docs.wavix.com/messaging/errors/13
## Error description
Each MMS message attachment must be 1 MB or smaller.
## How to fix it
Make sure your attachment doesn't exceed the 1 MB size limit.
# Unsupported media format
Source: https://docs.wavix.com/messaging/errors/14
## Error description
You're trying to send an MMS message with a media file format that isn't supported.
## How to fix it
Make sure your media file matches one of the supported content types and uses the correct file extension.
| Content type | File extension |
| - | - |
| Image | `jpg`, `jpeg`, `png`, `bmp` |
| Audio | `wav`, `mp3`, `amr`, `aac`, `midi`, `mid` |
| Animation | `gif` |
| Video | `3gpp` |
| vCard | `vcf` |
# Media file must be publicly accessible
Source: https://docs.wavix.com/messaging/errors/15
## Error description
Wavix wasn't able to access a media file while sending your MMS message.
## How to fix it
Make sure the file URL is valid and publicly accessible.
# Destination forbidden
Source: https://docs.wavix.com/messaging/errors/17
## Error description
Wavix couldn't send the message to the destination number due to administrative restrictions.
## How to fix it
Contact [support@wavix.com](mailto:support@wavix.com) and include the following details:
* Sender ID
* Destination number
* The date and time of the message
# Destination is invalid or not mobile phone number
Source: https://docs.wavix.com/messaging/errors/18
## Error description
Wavix couldn't deliver the message because the destination number is invalid or isn't a mobile number.
## How to fix it
Make sure you're sending to a valid mobile number. You can use the [Wavix Number validator](/numbers/number-validator) — available in the API or the Customer portal — to verify the number and its type.
# Destination blocked
Source: https://docs.wavix.com/messaging/errors/19
## Error description
Wavix couldn't send the message to the destination number due to administrative restrictions.
## How to fix it
Contact [support@wavix.com](mailto:support@wavix.com) and include the following details:
* Sender ID
* Destination number
* The date and time of the message
# You can only have up to 5 attachments per MMS message
Source: https://docs.wavix.com/messaging/errors/21
## Error description
You can include up to five attachments in a single MMS message.
## How to fix it
Make sure your MMS message includes no more than five attachments.
# Sender ID not found
Source: https://docs.wavix.com/messaging/errors/22
## Error description
You're trying to send an SMS or MMS using a Sender ID that isn't registered.
## How to fix it
To send SMS or MMS messages, make sure you're using a registered Sender ID.
# Rejected by a far-end carrier
Source: https://docs.wavix.com/messaging/errors/23
## Error description
Wavix received a delivery report (DLR) indicating the recipient's carrier rejected the message. This usually happens due to carrier policies or restrictions on the recipient's number.
## How to fix it
Messages can be rejected for a few common reasons:
* The recipient's phone is off or out of network coverage
* The phone's memory is full
* Do-not-disturb mode is turned on
* The recipient has blocked your Sender ID
If none of these apply, contact [support@wavix.com](mailto:support@wavix.com). Include the following details to help us investigate:
* Sender ID
* Destination number
* Date and time of the message
# Gateway rejected
Source: https://docs.wavix.com/messaging/errors/24
## Error description
Wavix couldn't send the message through one of our local partners.
## How to fix it
Try sending the message again. If the issue persists, contact [support@wavix.com](mailto:support@wavix.com) and include:
* Sender ID
* Destination number
* Date and time of the message
# Callback URL is invalid
Source: https://docs.wavix.com/messaging/errors/25
## Error description
Wavix couldn't validate the `callback_url` parameter in your Send message request.
## How to fix it
Check that the `callback_url` parameter in your Send message request is correct and starts with http\:// or https\://.
# You are only allowed to send _X_ SMS per second
Source: https://docs.wavix.com/messaging/errors/26
## Error description
You've exceeded the allowed number of SMS requests per second for your account.
## How to fix it
Contact [support@wavix.com](mailto:support@wavix.com) to address this error.
# Messaging is not supported by the destination carrier or handset
Source: https://docs.wavix.com/messaging/errors/29
## Error description
The device you're trying to reach can't receive SMS or MMS messages, or the carrier doesn't support these message types.
## How to fix it
Remove the phone number from your contact list to avoid sending future messages.
# Insufficient funds
Source: https://docs.wavix.com/messaging/errors/3
## Error description
Your account balance is too low to send messages.
## How to fix it
[Add funds](https://app.wavix.com/pay/payments) to continue sending messages.
# The number is inactive, lacks credits, or opted out of SMS
Source: https://docs.wavix.com/messaging/errors/31
## Error description
Wavix received a delivery report (DLR) indicating that the number is either inactive or has opted out of receiving messages.
In some cases, especially with US Verizon, this can also happen if the carrier blocks traffic due to non-compliance.
## How to fix it
Remove the phone number from your contact list to avoid sending messages to an inactive line.
If you keep seeing this error, check that:
* Your message content complies with CTIA and carrier policies.
* The content matches what you registered for your 10DLC Campaign.
* The traffic aligns with the use case registered in your 10DLC Campaign.
* Any links or phone numbers in the message are registered under the same 10DLC Campaign tied to your Sender ID.
Non-compliant traffic may be blocked. Repeated violations can also result in your 10DLC Campaign suspension or permanent Wavix account termination.
# The message was rejected as SPAM or the Sender ID is associated with an inactive 10DLC Campaign
Source: https://docs.wavix.com/messaging/errors/33
## Error description
This error applies to messages sent to US and Canadian numbers. Wavix received a delivery report (DLR) showing that the carrier blocked the message, usually because of non-compliant content.
## How to fix it
If you keep seeing this error, check that:
* Your message content complies with CTIA and carrier policies.
* The content matches what you registered for your 10DLC Campaign.
* The traffic aligns with the use case registered in your 10DLC Campaign.
* Any links or phone numbers in the message are registered under the same 10DLC Campaign tied to your Sender ID.
Non-compliant traffic may be blocked. Repeated violations can also result in your 10DLC Campaign suspension or permanent Wavix account termination.
# 10DLC Brand or Campaign messaging limit exceeded
Source: https://docs.wavix.com/messaging/errors/34
## Error description
You've reached the daily messaging limit set for your 10DLC brand or campaign.
* **T-Mobile** enforces limits at the **Brand** level, no matter how many Campaigns are linked.
* **AT\&T** enforces limits at the **Campaign** level, based on the number of messages per minute (TPM), no matter how many phone numbers are linked.
## How to fix it
To raise your daily limit, you can:
* Apply for 10DLC Brand vetting.
* Import an existing external Brand vet.
If you have questions about either option, contact [support@wavix.com](mailto:support@wavix.com).
# Daily quota exceeded (T-Mobile)
Source: https://docs.wavix.com/messaging/errors/36
## Error description
T-Mobile limits the number of messages you can send per day for each 10DLC Brand. The limit applies across all Campaigns linked to that Brand.
## How to fix it
To increase your daily limit, you can:
* Apply for 10DLC Brand vetting.
* Import an existing external Brand vet.
If you have questions about either option, contact [support@wavix.com](mailto:support@wavix.com).
# Spam message detected/rejected (AT&T)
Source: https://docs.wavix.com/messaging/errors/37
## Error description
Wavix received a delivery report (DLR) showing that AT\&T blocked the message due to its content filtering system.
## How to fix it
If you keep seeing this error, check that:
* Your message content complies with CTIA and carrier policies.
* The content matches what you registered for your 10DLC Campaign.
* The traffic aligns with the use case registered in your 10DLC Campaign.
* Any links or phone numbers in the message are registered under the same 10DLC Campaign tied to your Sender ID.
Non-compliant traffic may be blocked. Repeated violations can also result in your 10DLC Campaign suspension or permanent Wavix account termination.
# Sending limit reached (AT&T)
Source: https://docs.wavix.com/messaging/errors/38
## Error description
AT\&T limits the number of messages you can send per minute (TPM) for each 10DLC Campaign. The limit applies across all phone numbers linked to that Campaign.
## How to fix it
To raise your limit, you can:
* Apply for 10DLC Brand vetting.
* Import an existing external Brand vet.
If you have questions about either option, contact [support@wavix.com](mailto:support@wavix.com).
# Message too long
Source: https://docs.wavix.com/messaging/errors/41
## Error description
You're trying to send a message that exceeds the maximum allowed length.
Wavix supports:
* Up to **670 characters** for Unicode (UCS-2) messages
* Up to **1,630 characters** for GSM-7 (non-Unicode) messages
## How to fix it
Check your message length and encoding.
If you're not sure about the encoding, set the `smart_encoding` parameter to `true` in your Send message request. This automatically converts Unicode characters to non-Unicode equivalents to help keep your message within the limit.
# The message was blocked by the Verizon content filtering mechanism
Source: https://docs.wavix.com/messaging/errors/43
## Error description
Wavix received a delivery report (DLR) showing that the message was blocked by the Verizon content filtering system.
## How to fix it
If you keep seeing this error, check that:
* Your message content complies with CTIA and carrier policies.
* The content matches what you registered for your 10DLC Campaign.
* The traffic aligns with the use case registered in your 10DLC Campaign.
* Any links or phone numbers in the message are registered under the same 10DLC Campaign tied to your Sender ID.
Non-compliant traffic may be blocked. Repeated violations can also result in your 10DLC Campaign suspension or permanent Wavix account termination.
# The destination number is no longer active and should be removed from any subscriptions
Source: https://docs.wavix.com/messaging/errors/44
## Error description
This error usually occurs when sending to US or Canadian numbers. Wavix received a delivery report (DLR) showing that the destination phone number is no longer active.
## How to fix it
Remove the phone number from your contact list to avoid sending future messages to it.
# Unsupported carrier
Source: https://docs.wavix.com/messaging/errors/45
## Error description
Wavix couldn't send the message — no valid delivery route available.
## How to fix it
Contact [support@wavix.com](mailto:support@wavix.com) and include the following details:
* Sender ID
* Destination number
* The date and time of the message
# Non-compliant content or URL(s) detected and blocked
Source: https://docs.wavix.com/messaging/errors/46
## Error description
Wavix received a delivery report (DLR) showing that the message was blocked because of non-compliant content or unapproved URLs in the message body.
## How to fix it
If you keep seeing this error, check that:
* Your message content complies with CTIA and carrier policies.
* The content matches what you registered for your 10DLC Campaign.
* The traffic aligns with the use case registered in your 10DLC Campaign.
* Any links or phone numbers in the message are registered under the same 10DLC Campaign tied to your Sender ID.
Non-compliant traffic may be blocked. Repeated violations can also result in your 10DLC Campaign suspension or permanent Wavix account termination.
# Messaging to the destination number is blocked for the next 60 minutes
Source: https://docs.wavix.com/messaging/errors/47
## Error description
You've sent too many messages to the same phone number in a short period. By default, you can send up to **5 identical** SMS messages to the same destination number within **60 minutes**.
## How to fix it
Wait 60 minutes before sending the message again.
If it's urgent, contact [support@wavix.com](mailto:support@wavix.com) to request an unblock. Include:
* Sender ID
* Destination number
* The date and time of the message
# The Sender ID is not provisioned for the country
Source: https://docs.wavix.com/messaging/errors/5
## Error description
This error appears when you try to send an SMS to a country that isn't approved for your SMS Sender ID.
## How to fix it
Ensure the destination country is allowed for your Sender ID. You can:
* Use the Wavix API to check which countries your Sender ID is approved for
* View the list of allowed destinations in the Wavix portal
The time it takes to allow-list the Sender ID varies depending on the destination country.
# Idempotency violation
Source: https://docs.wavix.com/messaging/errors/55
## Error description
You're trying to send more than one message with the same idempotency key.
Wavix supports idempotent requests only through the `X-Cio-Idempotency-Key` request header.
## How to fix it
Wait 12 hours before reusing the same idempotency key, or use a new key for your message.
# Potential SMS flooding attack
Source: https://docs.wavix.com/messaging/errors/7
## Error description
This error appears when you try to send multiple identical SMS messages to the same phone number.
By default, you can send up to **5 identical** SMS messages or **20 messages with the same Sender ID** to the same destination number within **60 minutes**.
## How to fix it
If you need to remove this limit, contact [support@wavix.com](mailto:support@wavix.com). Include the following details:
* Sender ID
* Destination number
* Date and time you've faced the error
# Unsubscribed recipient
Source: https://docs.wavix.com/messaging/errors/9
## Error description
Wavix won't send messages to subscribers who replied with a recognized stop word. This error means the person opted out.
By default, Wavix recognizes these stop words: **STOP**, **QUIT**, and **UNSUBSCRIBE**. All the words are case insensitive. If you're using a 10DLC campaign, Wavix also recognizes any custom stop words configured for your Campaign.
# How to configure 3CX SMS with Wavix
Source: https://docs.wavix.com/messaging/guides/3cx-sms
This document explains how you can configure your 3CX in order to send and receive SMS and MMS messages with Wavix
## Prerequisites
Before configuring 3CX SMS, ensure you have:
1. A [Wavix account](https://app.wavix.com).
2. An active phone number ([How to buy a phone number](/numbers/buy-number)).
## Register a sender ID
Before sending an SMS or MMS message, you need to activate a sender ID on the Wavix platform. A sender ID is the message sender details recipients will see on their devices. Sender IDs can be either numeric or alphanumeric, presenting your brand or service name.
You must use numeric sender IDs if you want to enable 2-way messaging service. For one-way SMS, you can use both numeric and alphanumeric sender IDs.
The steps below are only mandatory if you're planning to send messages using a U.S. or Canadian phone number as sender ID. If you will be using a mobile number from other countries or an alphanumeric sender ID, scroll down to the `Create a sender ID on the Wavix platform` section.
### SMS-enable your number
1. Open **Numbers & trunks** → **My numbers**.
2. Select the number you want to use.
3. On the right side of the row, select the down arrow to expand the details.
4. Select **Activate** to enable SMS for the number.
Inbound SMS can be enabled only on US and Canadian phone numbers. For non-US or Canadian numbers, it will be supported on a case-by-case basis.
## Create a sender ID on the Wavix platform
To create a sender ID:
1. Select **SMS** in the top menu and click on **Sender IDs**
2. Then click add new Sender ID and select the Sender ID type, i.e. Alphanumeric or Numeric
An alphanumeric sender ID can be up to 11 characters long and can only include upper- and lower-case letters, digits from 0 through 9, and spaces. A numeric sender ID can be associated with an SMS-enabled number in your account only.
If you have chosen the numeric sender ID type but do not see any of your numbers in the sender ID drop-down list, make sure the number you are looking for is actually SMS-enabled.
3. Select country or countries you will be sending SMS to. Depending on the destination countries, additional restrictions for sender IDs may apply. Hover over the info icon next to the country name to see the details. If the sender ID type you've selected is not supported for the destination, the country will be greyed out.
Alphanumeric sender IDs are not supported in a variety of countries, including the US and Canada, and may require pre-registration by local carriers in some others.
4. Review your sender ID and the list of destinations. Your sender ID will be automatically allow-listed in countries that do not require additional paperwork. A member of the Wavix provisioning team will reach out to you with additional information regarding the process of sender ID registration in countries that do.
## Configure SMS sender ID on your 3CX SIP trunk
To send and receive SMS and MMS messages you must have a 3CX SIP trunk connected to Wavix. See the 3CX SIP trunk setup guide for more details.
When adding a new SIP Trunk in 3CX you need to specify the previously created Sender ID in the field labeled **Main Trunk No.**
## Enable SMS on your 3CX SIP trunk
For your 3CX instance to send and receive messages, you need to add your Wavix account API key in the field labeled **Api Key** and set up **Default SMS endpoint** in your Wavix account.
Click on the registered SIP trunk in 3CX and then on the SMS tab.
1. Log in to your Wavix account at app.wavix.com
2. Click on the **My account** icon in the top-right corner and then click API keys.
3. Copy an active Wavix API key and paste it into the field **Api Key** in your 3CX.
4. Copy Webhook URL from 3CX and paste it into the **Default SMS endpoint** field in your Wavix account. Click **Save all**.
5. Click OK to save 3CX SIP Trunk configuration.
## Verify configuration
To test your 3CX setup send an SMS to your mobile phone number. Go to Users in the left-hand side menu, click on the default 100 extension and download a mobile application by scanning the QR code on the page. Log in to the app, go to the Chat tab and send an SMS.
## Troubleshooting
If outbound SMS fails, check the following:
* You've completed all the steps in this guide
* The destination phone number is in the international E.164 format
* The sender ID you're using is allow-listed for the country you're sending the message to
# Receive SMS messages
Source: https://docs.wavix.com/messaging/receive-sms
Receive inbound SMS and MMS with the Wavix Messaging API. Enable SMS on a number, register a webhook URL, and handle the inbound message payload.
When building Wavix integrations, you might want your applications or services to receive inbound messages as soon as they reach an SMS-enabled phone number on your account. Your systems can then process them right away.
## Prerequisites
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Enable inbound SMS for a number
1. Open **Numbers & trunks** → **My numbers**.
2. Select the number you want to use.
3. On the right side of the row, select the down arrow to expand the details.
4. Select **Activate** to enable SMS for the number.
Inbound SMS can be enabled only on US and Canadian phone numbers. For non-US or Canadian numbers, it will be supported on a case-by-case basis.
### Create a webhook endpoint
To receive inbound messages, you need to create a [webhook endpoint](/messaging/webhooks-inbound-messages) that can accept HTTP POST requests. This endpoint will process the incoming messages sent by Wavix.
# Send SMS messages
Source: https://docs.wavix.com/messaging/send-sms
Send, manage, and track SMS and MMS messages using the Wavix Messaging API, including Sender ID registration and message delivery.
## Prerequisites
* Before you can use the Wavix Messaging API, you need to [create a Wavix account](/getting-started/create-account).
* You also need to [create or get your API key](/api-reference/authentication).
## Sender ID registration
A Sender ID is what recipients see as the message sender on their devices. It can be a numeric (phone numbers) or alphanumeric (brand names) Sender IDs. Before you send an SMS message, register your Sender ID on the Wavix platform.
**Alphanumeric Sender ID:**
* Must be between 3 and 11 characters long.
* Can contain uppercase and lowercase ASCII letters, digits, hyphen (-), plus (+), underscore (\_), ampersand (&), and space.
* Should not contain only digits.
**Numeric Sender ID:**
* Must be an SMS-enabled DID on your account.
* Third-party numbers and DIDs that do not support inbound SMS cannot be used as a Sender ID.
You can register Sender IDs in the Wavix portal or by using the API.
## Register a Sender ID using the app
1. Sign in to your [Wavix account](https://app.wavix.com).
2. In the top menu, select **SMS** → **Sender IDs**.
3. Select **Create new**.
* Select **Alphanumeric** to use a brand or service name as your Sender ID.
* Select **Numeric** to use a phone number as your Sender ID.
Then select **Next**.
Select your destination countries. Sender ID regulation varies by country and Sender ID type; some destinations may be unavailable. Then select **Next**.
Select your use case for messaging. Options include Promotional, Transactional, or Authentication. Enter your Sender ID name, estimate your monthly message volume, and provide sample messages you plan to send.
Then select **Next**.
Review the Sender ID, type, and destination countries. Your Sender ID will be automatically allow-listed for countries where no additional paperwork is required. Countries that require manual registration will be highlighted.
Select **Confirm**.
You can immediately start sending messages to countries that do not require manual sender ID registration.
## Register a Sender ID using the API
Sender ID regulations vary by country. You can register a Sender ID using the API only in countries where it can be provisioned in self-service mode. To check if a numeric or alphanumeric Sender ID can be registered in self-service mode for a particular country, use:
```http theme={null}
GET https://api.wavix.com/v3/messages/sender_ids/restrictions?country=country_code&type=sender_type
Authorization: Bearer your_api_key
```
* `country_code`: 2-letter ISO code of the country
* `sender_type`: Sender ID type, can be either `numeric` or `alphanumeric`
All parameters are required.
If successful, the method returns the `HTTP 200 OK` status code. The response body indicates if a numeric or an alphanumeric Sender ID can be registered in self-service mode in the country.
```json theme={null}
{
"self_service": true
}
```
If the `self_service` attribute value is `true`, the Sender ID can be registered using the API. Otherwise, create the Sender ID in the Wavix portal and go through the review or registration procedure.
To [register a new Sender ID](/api-reference/sms-and-mms/create-a-sender-id), use the following method:
```http theme={null}
POST https://api.wavix.com/v3/messages/sender_ids
Authorization: Bearer your_api_key
Content-Type: application/json
```
Paste the following JSON in the request body:
```json theme={null}
{
"sender_id": "1313xxxxxxx",
"countries": [
"US"
],
"type": "numeric"
}
```
* `sender_id`: the name of the Sender ID
* `countries`: an array of countries the Sender ID needs to be registered in
* `type`: Sender ID type
If successful, the method returns the `HTTP 200 OK` status code. The response body contains the Sender ID details.
```json theme={null}
{
"id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
"allowlisted_in": [
"US"
],
"sender_id": "1313xxxxxxx",
"type": "numeric"
}
```
* `id`: system-generated unique ID of the Sender ID
* `allowlisted_in`: an array of countries the Sender ID is automatically provisioned in
* `sender_id`: name of the Sender ID
* `type`: sender ID type
## Get a list of Sender IDs on the account
To [get a list of Sender IDs](/api-reference/sms-and-mms/list-sender-ids), use the following method. This method does not require any parameters.
```http theme={null}
GET https://api.wavix.com/v3/messages/sender_ids
Authorization: Bearer your_api_key
```
If successful, the method returns the `HTTP 200 OK` status code. The response body contains an array of Sender IDs provisioned on the account and their details.
```json theme={null}
{
"items": [
{
"id": "5108c63f-af4d-4852-88e0-ce06e82db5d3",
"allowlisted_in": [
"GB",
"FR"
],
"sender_id": "Wavix",
"type": "alphanumeric"
},
{
"id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
"allowlisted_in": [
"US",
"CA"
],
"sender_id": "1313xxxxxxx",
"type": "numeric"
}
]
}
```
* `id`: unique ID of the Sender ID
* `allowlisted_in`: an array of countries the Sender ID is automatically provisioned in
* `sender_id`: the name of the Sender ID
* `type`: Sender ID type
## Delete a Sender ID
To [delete a Sender ID](/api-reference/sms-and-mms/delete-a-sender-id), use the following method:
```http theme={null}
DELETE https://api.wavix.com/v3/messages/sender_ids/id
Authorization: Bearer your_api_key
Content-Type: application/json
```
* `id`: unique ID of the Sender ID
If successful, the method returns the `HTTP 204 No Content` status code without the response body.
## Send a message
*Using a sandbox account? A few rules apply to this request—see [Sandbox](/getting-started/sandbox).*
To [send an SMS or MMS message](/api-reference/sms-and-mms/send-a-message), use the following method:
```http theme={null}
POST https://api.wavix.com/v3/messages
Authorization: Bearer your_api_key
Content-Type: application/json
```
Paste the following JSON in the request body:
```json theme={null}
{
"from": "SenderID",
"to": "1686xxxxxxx",
"message_body": {
"text": "Message text.",
"media": ["https://publicly-available-resource.com/media"]
}
}
```
* `from`: the Sender ID to be used to send an SMS, must be a registered Sender ID on your account.
* `to`: the recipient phone number, must be in E.164 format (international format with + and country code, e.g., +12015551234).
* `message_body.text`: the text of the SMS message to be sent.
* `message_body.media`: an array of URLs to media files to be included in the message attachments. In case the parameter is specified and its value is different from `null`, the message will be sent as MMS. The URLs must point to publicly available resources.
All parameters are required.
If successful, the service returns the `HTTP 201 Created` status code. The response body contains the sent message details.
Response example:
```json theme={null}
{
"message_id": "871b4eeb-f798-4105-be23-32df9e991456",
"message_type": "mms",
"from": "13137890021",
"to": "13137890021",
"mcc": "301",
"mnc": "204",
"message_body": {
"text": "This is an MT message",
"media": ["https://publicly-available-resource.com"]
},
"tag": null,
"status": "accepted",
"segments": 1,
"charge": "0.02",
"submitted_at": "2022-04-14T13:51:16.096Z",
"sent_at": null,
"delivered_at": null,
"error_message": null
}
```
## Get message details
To get the message details, including delivery status, use the following method:
```http theme={null}
GET https://api.wavix.com/v3/messages/{{message_id}}
Authorization: Bearer your_api_key
```
* `message_id`: the unique identifier of the message on the Wavix platform for which the details are requested.
If successful, the service returns the `HTTP 200 OK` status code. The response body contains the message details.
Response example:
```json theme={null}
{
"message": {
"direction": "outbound",
"message_id": "871b4eeb-f798-4105-be23-32df9e991456",
"message_type": "mms",
"from": "13137890021",
"to": "13137890021",
"mcc": "301",
"mnc": "204",
"message_body": {
"text": "This is an MT message",
"media": ["https://publicly-available-resource.com"]
},
"tag": "1234",
"status": "delivered",
"segments": 1,
"charge": "0.02",
"submitted_at": "2022-04-14T13:51:16.096Z",
"sent_at": "2022-04-14T13:51:16.096Z",
"delivered_at": "2022-04-14T13:51:16.096Z",
"error_message": null
}
}
```
For outbound messages, the `status` field shows the delivery status:
* **accepted**: Message queued for delivery
* **sent**: Message delivered to carrier
* **delivered**: Delivery confirmed by recipient's network
* **failed**: Delivery failed; check `error_message` for details
## Unsubscribe a recipient
If you need to [unsubscribe a recipient](/api-reference/sms-and-mms/create-an-opt-out) from receiving SMS or MMS messages, use the following method:
```http theme={null}
POST https://api.wavix.com/v3/messages/opt_outs
Authorization: Bearer your_api_key
Content-Type: application/json
```
Paste the following JSON in the request body:
```json theme={null}
{
"sender_id": "1716xxxxxxx",
"phone_number": "1686xxxxxxx"
}
```
* `sender_id`: Sender ID of which the phone number will be opted out. If not specified, the phone number will be opted out of all SMS messages.
* `phone_number`: the phone number to be opted out
If successful, the service returns the `HTTP 204 No Content` status code.
# SMPP
Source: https://docs.wavix.com/messaging/smpp
Connect to the Wavix SMPP gateway to send and receive SMS at scale using SMPP v3.4, with bind parameters, supported PDUs, and error codes.
Wavix customers can connect to our SMPP gateway to send and receive [SMS](https://wavix.com/sms) messages and delivery reports (DLRs). Wavix supports **SMPP protocol version 3.4**.
## SMPP bind parameters
You can connect to Wavix SMPP host using the following parameters:
| Parameter | Mandatory | Description |
| - | :- | :- |
| system\_id | Yes | Your SMPP connection username |
| password | Yes | Your SMPP connection password |
| host/IP address | Yes | Always use `smpp.wavix.net` |
| port | Yes | Use `11337` as the primary port. Use `11338` for the encrypted SSL/TLS endpoint. |
The length of the password required depends on your SMPP library rather than the SMPP v3.4 protocol itself. It is advised to use a library that enables a setup with a password length greater than 8 characters.
## IP restrictions
Access to the Wavix SMPP service is limited to pre-registered IP addresses. Be sure to share your IPs in advance to ensure access.
## Supported PDUs
Wavix supports the following PDUs:
* `bind_transmitter`
* `bind_receiver`
* `bind_transceiver`
* `unbind`
* `submit_sm`
* `deliver_sm`
* `enquire_link`
* `generic_nack`
Each request to our system gets an acknowledgment, as defined in the SMPP v3.4 standard.
## Submitting messages via SMPP
Submit messages using the **submit\_sm** PDU, and include content in either the `short_message` or `message_payload` field.
If the request is successful, Wavix returns the **submit\_sm\_resp** with a success status (`ESME_ROK`) and a non-null message ID.
If the request fails, the response includes an error code.
### Character sets, message class, and data coding
Wavix supports the following data coding schemes:
* **GSM 03.38 (default)**. To use GSM 03.38 encoding, set `data_coding` to `0`.
* **Unicode**. To use UCS2 encoding, set `data_coding` to `0x08`. The message is expected in UTF-16 Big Endian format.
### Message originators and destinations
Set the `source_addr_ton` and `source_addr_npi` fields based on your Sender ID type:
* **Alphanumeric**: set the `source_addr_ton` to 5 and `source_addr_npi` to 0
* **Numeric**: set the `source_addr_ton` to 1 and `source_addr_npi` to 1
The destination phone number must be in international E.164 format. Set the `dest_addr_ton` and `dest_addr_npi` fields to 1.
### Concatenated messages
You can send messages longer than 160 characters (GSM 03.38) or 70 characters (UCS2). Such messages are automatically concatenated and appear as a single message on the recipient’s device.
To send long messages, use one of these supported methods:
* Use the `message_payload` field of the **submit\_sm** PDU. Recommended method.
* Use optional `sar_msg_ref_num`, `sar_segment_seqnum`, and `sar_total_segments` TLVs of the **submit\_sm** PDU.
* Use a UDH for concatenation with 8-bit or 16-bit reference numbers and set `esm_class` to `0x40`.
## Delivery reports
Delivery reports are sent in the `short_message` field of the **deliver\_sm** PDU.
Each delivery report includes these TLVs:
* `receipted_message_id` – the message ID assigned by Wavix.
* `message_state` – the current status of the message delivery.
* `user_message_reference` – A message reference number set by the customer, if included in the **submit\_sm** request.
* `network_error_code` – A [Wavix-specific error code](/messaging/smpp#wavix-specific-error-codes), provided only when `message_state` is `REJECTD`.
### Delivery report format
```ini theme={null}
id:{message_id} sub:{message_sub} dlvrd:{message_dlvrd} submit date:{message_submit_date} done date:{message_done_date} stat:{message_stat} err:{message_err}
```
### Delivery statuses
The delivery report can show one of the following message statuses:
| Status | Description |
| - | :- |
| `ENROUTE` | Submitted for delivery (interim) |
| `DELIVRD` | Successfully delivered (final) |
| `UNDELIV` | Couldn’t be delivered (final) |
| `REJECTD` | Rejected by a carrier, mobile device, or Wavix (final) |
| `EXPIRED` | Message validity period has expired (final) |
### Wavix-specific error codes
To help you troubleshoot your SMPP transaction, here’s what each error code means.
| Delivery status | Error code | Description |
| - | :- | :- |
| `REJECTD` | 1005 | [The Sender ID is not provisioned for the country](/messaging/errors/5) |
| `REJECTD` | 1007 | [Potential SMS flooding attack](/messaging/errors/7) |
| `REJECTD` | 1009 | [Unsubscribed recipient](/messaging/errors/9) |
| `REJECTD` | 1017 | [Destination forbidden](/messaging/errors/17) |
| `REJECTD` | 1018 | [Destination is invalid or not mobile phone number](/messaging/errors/18) |
| `REJECTD` | 1019 | [Destination blocked](/messaging/errors/19) |
| `REJECTD` | 1022 | [Sender ID not found](/messaging/errors/22) |
| `REJECTD` | 1023 | [Rejected by a far-end carrier](/messaging/errors/23) |
| `REJECTD` | 1024 | [Gateway rejected](/messaging/errors/24) |
| `REJECTD` | 1029 | [Messaging is not supported by the destination carrier or handset](/messaging/errors/29) |
| `REJECTD` | 1031 | [The number is inactive, lacks credits, or opted out of SMS](/messaging/errors/31) |
| `REJECTD` | 1033 | [The message was rejected as SPAM or the Sender ID is associated with an inactive 10DLC Campaign](/messaging/errors/33) |
| `REJECTD` | 1034 | [10DLC Brand or Campaign messaging limit exceeded](/messaging/errors/34) |
| `REJECTD` | 1036 | [Daily quota exceeded (T-Mobile)](/messaging/errors/36) |
| `REJECTD` | 1037 | [Spam message detected/rejected (AT\&T)](/messaging/errors/37) |
| `REJECTD` | 1038 | [Sending limit reached (AT\&T)](/messaging/errors/38) |
| `REJECTD` | 1041 | [Message too long](/messaging/errors/41) |
| `REJECTD` | 1043 | [The message was blocked by the Verizon content filtering mechanism](/messaging/errors/43) |
| `REJECTD` | 1044 | [The destination number is no longer active and should be removed from any subscriptions](/messaging/errors/44) |
| `REJECTD` | 1045 | [Unsupported carrier](/messaging/errors/45) |
| `REJECTD` | 1046 | [Non-compliant content or URL(s) detected and blocked](/messaging/errors/46) |
## Throughput and throttling
By default, each account is limited to 20 requests per second (RPS).
We recommend setting the SMPP window size (maximum number of open requests) to 10 for optimal performance.
## Enquire link
To maintain a stable connection, send the `enquire_link` request every 30 seconds.
# SMS troubleshooting guide
Source: https://docs.wavix.com/messaging/troubleshooting
Troubleshoot Wavix SMS and MMS errors. Look up generic, Sender ID, delivery, and 10DLC error codes, and follow the steps to fix each one.
Use this guide to troubleshoot common Wavix SMS and MMS API errors. Each error links to detailed steps to help you quickly resolve delivery and configuration issues.
## Generic errors
* [Unsubscribed recipient](/messaging/errors/9): The recipient has opted out of receiving messages.
* [Destination blocked](/messaging/errors/19): The destination is blocked.
* [Destination forbidden](/messaging/errors/17): The destination number is not allowed for messaging.
* [Invalid or non-mobile destination](/messaging/errors/18): The destination number is invalid or not a mobile number.
* [Invalid callback URL](/messaging/errors/25): The callback URL is incorrect.
* [Rate limit exceeded](/messaging/errors/26): You can send only *X* SMS messages per second.
* [Message too long](/messaging/errors/41): The message exceeds the allowed length.
* [Messaging temporarily blocked](/messaging/errors/47): Messaging to this number is temporarily blocked for 60 minutes.
## Sender ID errors
* [Sender ID not provisioned for country](/messaging/errors/5): The Sender ID is not available in the destination country.
* [Sender ID not found](/messaging/errors/22): The specified Sender ID does not exist.
## Delivery errors
* [Rejected by carrier](/messaging/errors/23): The carrier rejected the message.
* [Gateway rejected](/messaging/errors/24): The gateway did not accept the message.
* [Messaging not supported](/messaging/errors/29): The destination carrier or handset does not support messaging.
* [Unsupported carrier](/messaging/errors/45): The destination carrier or handset does not support messaging.
* [Inactive number, insufficient credits, or opted out](/messaging/errors/31): The destination number is inactive, lacks credits, or has opted out of SMS.
* [Idempotency violation](/messaging/errors/55): A duplicate message was detected.
## 10DLC errors
* [Rejected as spam or inactive campaign](/messaging/errors/33): The message was rejected as spam or the Sender ID is linked to an inactive 10DLC campaign.
* [Inactive destination number](/messaging/errors/44): The destination number is no longer active.
* [Brand or campaign limit exceeded](/messaging/errors/34): The messaging limit for the brand or campaign has been reached.
* [Daily quota exceeded (T-Mobile)](/messaging/errors/36): The daily messaging quota for T-Mobile has been exceeded.
* [Spam detected or rejected (AT\&T)](/messaging/errors/37): AT\&T detected or rejected the message as spam.
* [Blocked by Verizon content filter](/messaging/errors/43): Verizon blocked the message due to content filtering.
* [Non-compliant content or URLs blocked](/messaging/errors/46): The message contains non-compliant content or URLs.
## MMS errors
* [Media file size exceeds limit](/messaging/errors/13): The media file size must not exceed 1 MB.
* [MMS supported only for US and CA numbers](/messaging/errors/12): You can send MMS only to US and Canada phone numbers.
* [Unsupported media format](/messaging/errors/14): The media format is not supported.
* [Media file URL must be public](/messaging/errors/15): The media file URL must be publicly accessible.
* [Maximum attachments exceeded](/messaging/errors/21): You can include up to five attachments per MMS message.
***
Select any error above for detailed troubleshooting steps.
# Viber campaigns
Source: https://docs.wavix.com/messaging/viber
Reach customers on Viber with branded campaigns that the Wavix team sends for you, with rich media, scheduling, SMS failover, and delivery reports.
With Viber campaigns, you send branded messages to your customers on Viber. Only businesses approved by Viber can send these messages, and the Wavix team sends each campaign for you.
## How Viber campaigns work
Viber campaigns are a managed service. You don't build or send the campaign yourself:
1. **Request access.** Contact the Wavix team with your use case, target countries, and expected volume. Wavix reviews each request individually.
2. **Register your sender.** After approval, the Wavix team registers your business as a Viber sender, with your business name and logo. Viber reviews and approves each sender.
3. **Send your campaign brief.** Share your recipient list, message content, and schedule with the Wavix team.
4. **Get your results.** The Wavix team sends the campaign and shares the delivery report with you.
## Supported features
### Message content
* **Text** messages with links and emojis.
* **Images**, **videos**, and **files**.
* **Buttons** that open a link, combined with text and an image.
### Branded sender
Your messages show your business name and logo. Viber marks verified business senders with a badge, so customers know the message comes from you.
### Message types
* **Promotional** messages, such as offers and announcements.
* **Transactional** messages, such as order updates and reminders.
Viber applies different rules and prices to each type. The Wavix team helps you choose the right type for your campaign.
### Personalization
Add placeholders to your message, such as the customer name or an order number. The Wavix team fills them in for each recipient from your recipient list.
### Scheduling
Send your campaign right away or schedule it for later. You can set a delivery window, so messages don't reach customers outside business hours in their time zone.
### SMS failover
If a recipient doesn't use Viber or the message isn't delivered, the campaign can send the message as an SMS instead. This way, you reach customers who can't receive Viber messages.
### Delivery reports
After the campaign, you get a report with the number of messages sent, delivered, and seen, plus the messages sent through SMS failover.
## Get started
To request access to Viber campaigns, contact [sales@wavix.com](mailto:sales@wavix.com).
# Webhook IP addresses
Source: https://docs.wavix.com/messaging/webhook-ip-addresses
Allowlist the Wavix webhook server IP so your application can receive SMS delivery reports and inbound messages.
Wavix sends webhooks for [delivery reports](/messaging/webhooks-delivery-reports) and [inbound messages](/messaging/webhooks-inbound-messages) to the URL you configure. If your application is behind a firewall, allow inbound HTTPS traffic from the Wavix webhook server so these requests can reach it.
| Service | IP address | Protocol | Port |
| - | :- | :- | :- |
| Webhooks | 62.212.73.112 | HTTPS | 443 |
Allowlist by IP address only if your firewall requires it. Where possible, accept HTTPS requests to your webhook endpoint and validate them in your application instead.
# Receiving message delivery reports
Source: https://docs.wavix.com/messaging/webhooks-delivery-reports
Receive SMS and MMS delivery reports (DLRs) from the Wavix platform. Set a default webhook URL in the Wavix portal, or a callback URL per message.
A delivery report (DLR) is a confirmation message sent by a mobile carrier to the sender, indicating whether an SMS or MMS message was successfully delivered to the recipient.
Wavix supports delivery report (DLR) webhooks and sends delivery status updates to your specified endpoint. Set a default webhook URL in the Wavix portal, or include a `callback_url` parameter in your [Send SMS or MMS Message](/api-reference/sms-and-mms/send-a-message) API request. If you provide a `callback_url` in the API request, Wavix sends the DLR to that URL. Otherwise, Wavix sends the DLR to the default webhook in your account settings.
If you need to allow Wavix IP addresses in your firewall settings, see [Webhook IP addresses](/messaging/webhook-ip-addresses).
## Set up your DLR webhook URL
### Using the app
To set a default DLR webhook:
1. [Sign in](https://app.wavix.com) to your account.
2. Go to **Account & billing**, then select **My account**.
3. Select the **Default destinations** tab.
4. Enter your callback URL in the **DLR webhook** field.
5. Select **Save changes**.
### In each API request
You can also include the `callback_url` parameter in your API request when sending a message. If you specify this parameter, Wavix uses it for the DLR instead of the account default.
Request example:
```json theme={null}
{
"from": "SenderID",
"to": "1686xxxxxxx",
"message_body": {
"text": "Your message text",
"media": []
},
"callback_url": "https://service.com/callbacks/wavix/dlr"
}
```
## Handling the callbacks
Wavix sends delivery reports as POST requests to your webhook URL. These updates are triggered when a message status changes:
1. The first report is sent when the message is sent or fails to send.
2. The second report is sent when the final delivery status is known (e.g. delivered, undelivered, rejected).
Sample payload:
```json theme={null}
{
"delivered": null,
"error": null,
"from": "SenderID",
"message_id": "62845007-931a-4c3c-a581-6bdeffec75dc",
"message_type": "sms",
"segments_count": 1,
"sent": "2025-03-21T08:09:02",
"status": "sent",
"to": "1686xxxxxxx",
"tag": "Message tag"
}
```
### Delivery report attributes
| Attribute | Description |
| - | - |
| status | The message's interim or final status. • `sent` - Submitted for delivery (interim) • `delivered` - Successfully delivered (final) • `undelivered` - Couldn't be delivered (final) • `rejected` - Rejected by a carrier, mobile device, or Wavix (final) |
| sent | Timestamp when Wavix submitted the message for delivery |
| delivered | Timestamp when final status was received |
| from | Sender ID |
| to | Recipient's phone number |
| message\_id | Unique identifier for the message |
| message\_type | `sms` or `mms` |
| segments\_count | Number of SMS segments sent |
| tag | Custom tag from the original request |
| error | Error details, if any |
# Using webhooks to receive inbound messages
Source: https://docs.wavix.com/messaging/webhooks-inbound-messages
Set an inbound SMS webhook URL for a phone number or for your whole Wavix account, and handle the inbound message payload the Wavix platform posts.
When building Wavix integrations, you might want your applications or services to receive inbound messages as soon as they reach an SMS-enabled phone number on your account. This allows your backend systems to process them accordingly.
To activate this feature, set a webhook URL as the default SMS endpoint for your SMS-enabled DID, or your Wavix account. You can do this using the Wavix GUI, the Wavix Profile API, or the Wavix DID numbers API.
Once a message is received by an SMS-enabled DID on your Wavix account, Wavix will automatically forward the message to a webhook registered to the DID, if one is specified. In cases where no webhook is registered to the DID, the platform will automatically forward the message to a webhook configured in your account.
If you need to allow Wavix IP addresses in your firewall settings, see [Webhook IP addresses](/messaging/webhook-ip-addresses).
## Set up your Inbound SMS webhook
To set a default DLR webhook URL:
1. [Sign in](https://app.wavix.com) to your account.
2. Go to **Account & billing**, then select **My account**.
3. Select the **Default destinations** tab.
4. Enter your callback URL in the **Inbound SMS webhook** field.
5. Select **Save changes**.
## Message object
The message object below is forwarded to a webhook.
```json theme={null}
{
"message_id": "3c7a5a90-43e0-43e0-b006-fdfea30c5a7c",
"from": "43720115661",
"to": "447712345661",
"message_body": {
"text": "SMS message",
"media": null
},
"received_at": "2022-04-14T13:51:16.096Z"
}
```
# WhatsApp concepts
Source: https://docs.wavix.com/messaging/whatsapp/concepts
Understand WhatsApp Business Accounts, senders, message templates, the customer service window, quality ratings, and messaging limits.
Meta defines how businesses use WhatsApp. This page explains the concepts you need before you send WhatsApp messages through the Wavix platform.
## WhatsApp Business Account
A WhatsApp Business Account (WABA) represents your business on WhatsApp. It belongs to your business portfolio in Meta Business Suite, and it holds your senders and message templates.
Meta verifies your business before it lets you message customers at scale. Keep your business details in Meta Business Suite accurate and up to date — they affect approval and your messaging limits.
## Senders
A sender is a phone number registered to your WABA. Each sender has:
* **Display name**: The business name customers see in WhatsApp. Meta reviews the display name, and it must relate to your business.
* **Status**: Whether the sender can send messages. For example, a sender can be connected, pending, flagged, or restricted.
* **Quality rating**: How customers have responded to your recent messages.
* **Messaging limit**: How many customers you can start conversations with in a rolling 24-hour period.
A phone number registered as a WhatsApp sender can't be used in the WhatsApp or WhatsApp Business app at the same time.
## Message templates
A message template is a message format that Meta approves before you can use it. You must use an approved template to start a conversation with a customer.
Each template has a name, a language, and a category. It can include placeholders for content that changes per message, such as a customer name or an order number. Templates can also include a header with text or media, a footer, and buttons.
### Template categories
| Category | Use it for | Examples |
| :- | :- | :- |
| **Marketing** | Promotions, offers, and announcements | Sales, product launches, re-engagement |
| **Utility** | Updates about a transaction or an account that the customer started | Order confirmations, delivery updates, appointment reminders |
| **Authentication** | One-time passwords and verification codes | Sign-in codes, account recovery |
Meta can change the category of a template during review if the content doesn't match the category you chose.
### Template review
Meta reviews every template before you can use it. Most templates are reviewed within minutes. A template that needs manual review can take up to 48 hours.
After review, a template is either **approved** or **rejected**. Meta can also **pause** or **disable** an approved template later if it receives negative customer feedback.
## Customer service window
When a customer sends you a message, a 24-hour customer service window opens. Each new message from the customer restarts the window.
* **Inside the window**, businesses can reply with free-form messages.
* **Outside the window**, you can only reach the customer with an approved template.
## Opt-in
Meta requires your customers to agree to receive WhatsApp messages from your business before you message them. Collect opt-in through your own channels, such as your website, app, or checkout flow. State clearly that the customer will receive messages on WhatsApp and from which business.
Respect opt-out requests immediately. Messages that customers don't expect lower your quality rating.
## Quality rating
Meta assigns a quality rating based on how customers respond to your messages over recent days. Blocks, reports, and negative feedback lower the rating.
| Rating | Meaning |
| :- | :- |
| **High** | Customers respond well to your messages. |
| **Medium** | Some customers report or block your messages. |
| **Low** | Many customers report or block your messages. Meta can restrict your sender if the rating stays low. |
To keep a high rating, send relevant messages only to customers who opted in, and don't send messages too often.
## Messaging limits
Messaging limits control how many unique customers you can start conversations with in a rolling 24-hour period. Replies inside the customer service window don't count toward the limit.
New businesses start with a limit of 250 customers. Meta raises the limit to 2,000, 10,000, 100,000, and then unlimited, as you send more high-quality messages.
# WhatsApp overview
Source: https://docs.wavix.com/messaging/whatsapp/overview
Learn how WhatsApp on Wavix works, how onboarding works, and what you can do once WhatsApp is enabled for your account.
WhatsApp is in preview. Features, limits, and the WhatsApp API can change before general availability.
WhatsApp lets your business reach customers on the messaging app they already use. With WhatsApp on Wavix, you send WhatsApp messages through the same Wavix account, API, and billing you use for SMS and voice. You don't need a separate provider contract or a third-party interface.
## How WhatsApp on Wavix works
Meta operates WhatsApp and sets the rules for business messaging. To send messages, your business needs:
* A **WhatsApp Business Account (WABA)** that belongs to your business and is verified by Meta.
* A **sender** — a phone number registered to your WABA. Customers see its display name when they receive your messages.
* Approved **message templates** for messages that your business starts.
The Wavix platform connects your WABA to your Wavix account. Your application then sends messages through the Wavix API, and the Wavix platform delivers them to WhatsApp and tracks their status.
For definitions of these terms, see [WhatsApp concepts](/messaging/whatsapp/concepts).
## Onboarding
Wavix enables WhatsApp for a limited number of accounts at a time. The Wavix team works with you to connect your WABA, register your sender, and submit your first templates.
## What you can do
When WhatsApp is enabled for your account, you can:
* **Send template messages** through the Wavix API or the [Wavix MCP server](/mcp/overview).
* **Check your senders** in the Wavix portal, including their status, quality rating, and messaging limit.
* **Track your templates** in the Wavix portal, including their category, language, and approval status.
* **Review message history** in the Wavix portal to follow each message and its delivery status.
## Get started
To get started, [request WhatsApp access](/messaging/whatsapp/request-access) in the Wavix portal.
# Request WhatsApp access
Source: https://docs.wavix.com/messaging/whatsapp/request-access
Request WhatsApp access in the Wavix portal and learn what happens after you submit your request.
WhatsApp is in preview. Features, limits, and the WhatsApp API can change before general availability.
Wavix enables WhatsApp for a limited number of accounts at a time. Request access in the Wavix portal to get started.
## Prerequisites
* A Wavix account. If you don't have one, [create a Wavix account](/getting-started/create-account).
* Access to the main Wavix account. Sub-accounts, sub-users, and sandbox accounts can't request WhatsApp access.
## Submit your request
1. Sign in to your Wavix account.
2. In the Wavix portal, select **WhatsApp** in the main menu.
3. Under **Request access**, answer the questions that apply to you:
* **Expected monthly messages**: Select the range closest to your expected volume.
* **Destination countries**: Enter two-letter country codes separated by commas, for example `US, GB, PT`.
* **How you plan to use WhatsApp**: Describe your use case, for example order updates or appointment reminders.
4. Select **Send request**.
All questions are optional, but your answers help the Wavix team prepare your account.
## What happens next
After you submit your request, the WhatsApp page in the Wavix portal shows that your request is received. You don't need to submit it again.
When your account is selected, the Wavix team contacts you to:
1. Connect your WhatsApp Business Account to your Wavix account.
2. Register your phone number as a WhatsApp sender.
3. Prepare and submit your first message templates for Meta review.
When WhatsApp is on for your account, the WhatsApp page in the Wavix portal shows your senders and templates.
To prepare, make sure your business has a verified business portfolio in Meta Business Suite and a phone number that isn't registered in the WhatsApp or WhatsApp Business app. For more information, see [WhatsApp concepts](/messaging/whatsapp/concepts).
## Get help
If you have questions about your request, contact [support@wavix.com](mailto:support@wavix.com).
# How to buy a phone number
Source: https://docs.wavix.com/numbers/buy-number
Buy a phone number in the Wavix portal: pick a country and number type, browse the available inventory, and complete checkout to activate it.
Before you can start making or receiving calls, you need to have an active [phone number](https://wavix.com/did-numbers) on your Wavix account. This guide walks you through the process of selecting and purchasing a number.
## Buy a phone number in the Wavix portal
To purchase a new phone number:
1. **Sign in** to your [Wavix account](https://app.wavix.com).
2. In the top menu, click on **Numbers & Trunks → Buy**.
3. Select the **country** and **region** (type of number) you want to purchase.
4. Browse the available numbers and click **Select** for the ones you wish to buy.
5. Review your selection in the **Cart** and click **Buy now** to complete the purchase.
Some numbers (such as local numbers in certain countries) require proof of address or other documentation due to local regulations. If requested, you must upload these documents in the **Numbers → Documents** section. The numbers will become active once our Provisioning team approves the documentation.
## Next steps
Once you have purchased a number, you can proceed with the following:
* [Configure a SIP trunk](/sip-trunking/sip-trunks).
* [Verify your caller ID](/sip-trunking/ip-allowlisting) (if using your own number).
* [Set up inbound call routing](/numbers/numbers).
# How to port a phone number
Source: https://docs.wavix.com/numbers/number-porting
Port your existing phone number to Wavix and keep the same number. Learn what documents you need, each step of the process, and how to track it.
## What is Number Porting?
Number porting (also called "local number portability" or LNP) lets you transfer your existing phone number from your current service provider to the Wavix platform.
The number itself does not change—your customers continue to call or message the same number—but the underlying infrastructure and capabilities do. On the Wavix platform, ported numbers become programmable assets that you can connect directly to your applications, workflows, and AI systems.
## Why port a number to Wavix?
* **Unified Communications**: Consolidate voice and SMS on a single platform.
* **Enable programmable communications**: Route calls to application endpoints, send and receive SMS programmatically, and trigger workflows using APIs.
* **Power AI and real-time use cases**: The Wavix platform enables live call media streaming, allowing you to build AI voice agents that interact live with callers.
## Step-by-step porting process
**U.S. number porting (paperless process)**
This guide explains how to port U.S. phone numbers using a paperless process.
**International number porting**
Wavix supports number porting in 36 countries. Requirements and procedures vary by country.
While this guide focuses on U.S. number porting, reviewing it can help you understand the general porting process in other countries.
For assistance with international porting, contact the Wavix [Porting team](mailto:lnp@wavix.com) or [Support](mailto:support@wavix.com) and include the numbers you want to port. The team will verify number portability and provide the required details and costs.
## Prerequisites
Before you start the [porting](https://wavix.com/porting) process, verify you have the following:
### Information you'll need
* **Account Number**: Your current provider's account number for the number(s) you're porting.
* **Billing Phone Number**: The phone number on the account that owns the ported number(s).
* **Service PIN or Password**: A security code from your current provider (usually 4-6 digits).
* **Account Holder Name**: The name registered on the account.
* **Account Address**: The service address associated with the number(s).
### Eligibility requirements
* Numbers must be **active and in use** with your current provider
* The account must be in **good standing** (no unpaid balances that would prevent transfer)
### Step 1: Prepare your current provider account
Before submitting the port request, gather the required information from your current provider:
1. Log in to your current provider's portal or call their customer service.
2. Locate your **Account Number** (usually found on your invoice or account settings).
3. Find your **Service PIN** or Password (if you don't have one, request the provider create one for you).
4. Note the **Billing Phone Number** (the phone number associated with the account itself, not the number being ported).
5. Confirm the **Service Address** on file.
6. Verify that the numbers are active.
### Step 2: Submit the Porting request in the Wavix portal
Once you have the information from Step 1, create your port request:
1. Go to **Numbers** → **Porting**.
2. Select **Create new**.
Review and agree to the porting terms.
Select **Next**.
Select the port type and enter the numbers to port.
You can enter single numbers, ranges, or both.
Select **Next**.
Optionally, preconfigure inbound call routing for the ported numbers.
Select **Next**.
Provide your account details with the losing carrier.
Select **Next**.
Provide the losing carrier details and upload the most recent phone bill.
Select **Next**.
Review and digitally sign the Letter of Authorization (LOA).
Once you submit the request, you'll immediately receive an email notification with the **LNP order** number.
### Step 3: Authorize the port with your current provider
When you submit the port request in the Wavix portal, Wavix files a port order with your current carrier.
**What to expect:**
* You may receive an email from your current provider asking to confirm the port.
* If your carrier denies the port, Wavix will contact you with the reason.
* **You do not need to contact your current provider directly** unless they reach out to you.
### Step 4: Monitor your port status
To track the progress:
1. In the Wavix portal, go to **Numbers** → **Port Requests**
2. Find your port order by **Port Order Number** or **Phone Number**
3. View the current **Status** and **Timeline**:
If you don't see progress after 7 days, contact Wavix support with your Port Order Number.
### Step 5: Cutover and activation
The cutover is when your number officially switches to Wavix. Here's what happens:
**The day before cutover:**
* You'll receive a confirmation from Wavix with the cutover date and time.
* The Wavix team pre-provisions the number(s) to your Wavix account to ensure a smooth cutover.
* Plan to have a short testing window available (15-30 minutes).
* Inform your team that the number(s) will be briefly unavailable.
**During cutover:**
* Your number(s) will be temporarily unavailable for a few minutes.
* Calls and messages to the number(s) will fail briefly, then route to Wavix.
**Immediately after cutover:**
* You'll receive a confirmation from Wavix that the porting is complete.
* Your number(s) are now provisioned to your Wavix account.
**If something goes wrong:**
* Contact [Wavix Support](mailto:support@wavix.com) immediately with your **LNP order** number.
* Provide details about what's not working.
# Number Validator API
Source: https://docs.wavix.com/numbers/number-validator
Check phone number validity, reachability, roaming, and carrier details with the Wavix Number Validator API, one number or a batch per request.
The Wavix [Number Validator](https://wavix.com/number-validator) API allows customers to automate the phone number validation process by checking the phone number validity, reachability, and roaming status. Using the API, Wavix customers can also get the name of the current carrier of the phone number, check if it was ported, and more.
All phone numbers are validated using the latest international numbering plan databases.
Based on your specific business needs, you can get detailed information about either a single phone number or several numbers with one request. You can also choose one of three validation request types: `format`, `analysis`, or `validation`.
The table below shows phone number details returned depending on the request type.
**Phone number details returned by request type**
| Parameter | Format | Analysis | Validation |
| - | :- | :- | :- |
| Phone number validity | Yes | Yes | Yes |
| Phone number country | Yes | Yes | Yes |
| Local format | Yes | Yes | Yes |
| E.164 format | Yes | Yes | Yes |
| MCC, MNC for mobile numbers | — | Yes | Yes |
| Type (mobile/toll-free/etc.) | — | Yes | Yes |
| Current carrier | — | Yes | Yes |
| Ported status | — | Yes | Yes |
| Unallocated range | — | Yes | Yes |
| Risky destination | — | Yes | Yes |
| Timezone | — | — | Yes |
| Reachability\* | — | — | Yes |
| Roaming status\* | — | — | Yes |
\*Reachability and roaming statuses are returned for mobile phone numbers only. The feature is available in selected countries only. Please contact your account manager for more details.
## Prerequisites
Before you can access the Wavix Number Validator API, you need to sign up for Wavix.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## How to validate a single phone number
To get detailed information about [a single phone number](/api-reference/number-validator/validate-a-number), use the following method:
```http theme={null}
GET https://api.wavix.com/v1/validation?phone_number=number&type=validation_type
Authorization: Bearer your_api_key
Content-Type: application/json
```
Pass the following parameters in the request URL:
* `number` - the phone number to be validated.
* `validation_type` - the Wavix Number validator request type: `format`, `analysis`, or `validation`.
All parameters are mandatory and cannot be blank.
If successful, the method returns the `HTTP 200 OK` status code. The response body will contain information about the phone number.
```json theme={null}
{
"phone_number": "+6288736592000",
"is_valid": true,
"country_code": "ID",
"e164_format": "+6288736592000",
"national_format": "087-36592-000",
"ported": false,
"mcc": "510",
"mnc": "10",
"phone_type": "mobile",
"carrier_name": "PT. Telekomunikasi Selular",
"risky_destination": false,
"unallocated_range": false,
"reachable": true,
"roaming": false,
"timezone": "UTC+07:00",
"cost": "0.015",
"error_code": "000"
}
```
## How to validate multiple phone numbers
The Wavix Number Validator API allows you to get detailed information about [several phone numbers](/api-reference/number-validator/validate-multiple-numbers) with a single request.
Under most circumstances, it takes about 30 seconds to validate a batch of 500 phone numbers. We recommend you use `async:true` if you're planning to validate more than 500.
```http theme={null}
POST https://api.wavix.com/v1/validation
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request body example:
```json theme={null}
{
"async": false,
"type": "validation",
"phone_numbers": [
"+6288736592000",
"+6288736592001",
"+6288736592002"
]
}
```
* `async` — whether the request executes asynchronously.
* `type` — validation type: `format`, `analysis`, or `validation`.
* `phone_numbers` — array of E.164-formatted numbers to validate.
All parameters are mandatory and cannot be blank.
### Response
For synchronous requests, if successful, the method returns the `HTTP 200 OK` status code. The response contains detailed information about each phone number.
```json theme={null}
{
"status": "success",
"pending": 0,
"items": [
{
"phone_number": "+6288736592000",
"is_valid": true,
"country_code": "ID",
"e164_format": "+6288736592000",
"national_format": "087-36592-000",
"ported": false,
"mcc": "510",
"mnc": "10",
"phone_type": "mobile",
"carrier_name": "PT. Telekomunikasi Selular",
"risky_destination": false,
"unallocated_range": false,
"reachable": true,
"roaming": false,
"timezone": "UTC+07:00",
"cost": "0.015",
"error_code": "000"
},
{
"phone_number": "+6288736592001",
"is_valid": true,
"country_code": "ID",
"e164_format": "+6288736592001",
"national_format": "087-36592-001",
"ported": false,
"mcc": "510",
"mnc": "10",
"phone_type": "mobile",
"carrier_name": "PT. Telekomunikasi Selular",
"risky_destination": false,
"unallocated_range": false,
"reachable": true,
"roaming": false,
"timezone": "UTC+07:00",
"cost": "0.015",
"error_code": "000"
}
]
}
```
For asynchronous requests, if successful, the method returns the `HTTP 201 Created` status code, which means the validation process has started. The response contains a token that needs to be used to poll the results.
```json theme={null}
{
"request_uuid": "12542c5c-1a17-4d12-a163-5b68543e75f6"
}
```
To [poll asynchronous validation results](/api-reference/number-validator/retrieve-validation-results), use the following method:
```http theme={null}
GET https://api.wavix.com/v1/validation/{request_uuid}
Authorization: Bearer your_api_key
Content-Type: application/json
```
If successful, the response will contain detailed information about the phone numbers that have already been validated and the status of the asynchronous validation.
```json theme={null}
{
"status": "progress",
"count": 4,
"pending": 2,
"items": [
{
"phone_number": "+6288736592000",
"is_valid": true,
"country_code": "ID",
"e164_format": "+6288736592000",
"national_format": "087-36592-000",
"ported": false,
"mcc": "510",
"mnc": "10",
"phone_type": "mobile",
"carrier_name": "PT. Telekomunikasi Selular",
"risky_destination": false,
"unallocated_range": false,
"reachable": true,
"roaming": false,
"timezone": "UTC+07:00",
"cost": "0.015",
"error_code": "000"
},
{
"phone_number": "+6288736592001",
"is_valid": true,
"country_code": "ID",
"e164_format": "+6288736592001",
"national_format": "087-36592-001",
"ported": false,
"mcc": "510",
"mnc": "10",
"phone_type": "mobile",
"carrier_name": "PT. Telekomunikasi Selular",
"risky_destination": false,
"unallocated_range": false,
"reachable": true,
"roaming": false,
"timezone": "UTC+07:00",
"cost": "0.015",
"error_code": "000"
}
]
}
```
# Number Validator
Source: https://docs.wavix.com/numbers/number-validator-portal
Validate phone numbers in the Wavix portal: upload a list, choose format, analysis, or validation, and export carrier and reachability results.
## Overview
The Wavix Number validator helps you reach real customers by cleaning invalid and unreachable numbers from your data. It gives your sales and marketing teams an easy way to validate leads and improve outreach.
This guide walks you through using the Wavix Number validator.
## Prerequisites
To get started, you'll need:
* An active [Wavix account](/getting-started/create-account)
* A list of phone numbers in E.164 format (e.g., +12345678900)
Number validator is available for [Flex Pro](https://wavix.com/account-levels) customers only
## Number validation types
Wavix uses the latest international numbering data to quickly confirm if phone numbers are real and reachable.
You can choose from three types of validation: **Format**, **Analysis**, or **Validation**.
**What each request type returns**
| Parameter | Format | Analysis | Validation |
| - | :- | :- | :- |
| Phone number validity | Yes | Yes | Yes |
| Phone number country | Yes | Yes | Yes |
| Local format | Yes | Yes | Yes |
| E.164 format | Yes | Yes | Yes |
| MCC, MNC for mobile numbers | — | Yes | Yes |
| Type (mobile/toll-free/etc.) | — | Yes | Yes |
| Current carrier | — | Yes | Yes |
| Ported status | — | Yes | Yes |
| Unallocated range | — | Yes | Yes |
| Risky destination | — | Yes | Yes |
| Timezone | — | — | Yes |
| Reachability\* | — | — | Yes |
| Roaming status\* | — | — | Yes |
\*Reachability and roaming statuses are available for mobile numbers in selected countries. Contact your account manager for details.
## Validate one or more numbers
Follow the steps below to validate phone numbers.
Go to **Solutions** → [**Number validator**](https://app.wavix.com/validator/numbers) in the top menu.
Select **Create new**
1. (Optional) Enter a request name.
2. Enter up to 1,000 numbers by pasting them (separated by commas or new lines), or upload a CSV file with up to 100,000 rows. The file must include a single column of E.164-formatted numbers. Don't include a column header.
3. Select the request type.
4. Choose **Create**
When the request is complete, select the three-dot menu and choose **Download report** to get a CSV file with the results.
Here's an example:
```csv theme={null}
Number, Country, Country code, Valid, Local format, E164 format
35677600964, Malta, MT, YES, 7760 0964, 35677600964
33237913520, France, FR, YES, 02 37 91 35 20, 33237913520
48605724178, Poland, PL, YES, 605 724 178, 48605724178
13602935393, United States of America, US, YES, (360) 293-5393, 13602935393
```
# Numbers API Overview
Source: https://docs.wavix.com/numbers/numbers
Search, buy, configure, and release phone numbers in over 140 countries with the Wavix Numbers API. Includes request and response examples.
The Wavix platform provides access to a global inventory of local, mobile, national, and toll-free numbers in over 140 countries.
In this section, you will learn how to search, purchase, configure, and release [phone numbers](https://wavix.com/did-numbers) using the Wavix API.
## Prerequisites
Before you can search for and buy your first phone number, sign up for a Wavix account.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## Search for phone numbers
To receive calls from your customers, purchase a phone number from the Wavix global inventory.
[Get a list of countries](/api-reference/buy/list-countries) with phone numbers available. You can search for geo, toll-free, or both types of phone numbers. You can also filter by SMS-enabled numbers.
Request sample:
```http theme={null}
GET https://api.wavix.com/v1/buy/countries?type_filter=all&text_enabled_only=false
Authorization: Bearer your_api_key
Content-Type: application/json
```
Response sample:
```json theme={null}
{
"countries": [
{
"id": 8652,
"name": "United States",
"short_name": "US",
"has_provinces_or_states": true
}
]
}
```
This step is required only for countries with provinces or states, such as the USA, Canada, and Australia.
For countries with provinces or states, [get a list of cities in a region](/api-reference/buy/list-region-cities) or [a list of cities](/api-reference/buy/list-cities) for countries without regions. Use the `country_id` and, optionally, the `region_id` parameters from the responses above.
Request sample:
```http theme={null}
GET https://api.wavix.com/v1/buy/countries/8652/regions/379/cities
Authorization: Bearer your_api_key
Content-Type: application/json
```
Response sample:
```json theme={null}
{
"cities": [
{
"id": 200,
"name": "LOS ANGELES, CA",
"area_code": 213568
}
]
}
```
For USA the `area_code` parameter in the response is in NPA-NXX format.
[Get a list of phone numbers](/api-reference/buy/list-available-phone-numbers) in the selected city. Use the IDs of the selected country and city from the responses above.
Request sample:
```http theme={null}
GET https://api.wavix.com/v1/buy/countries/8652/city/200/dids?type_filter=all&text_enabled_only=true
Authorization: Bearer your_api_key
Content-Type: application/json
```
The response will contain phone numbers and their details, such as ID, activation fee, monthly fee, and the number of inbound channels.
## Buy phone numbers
To purchase phone numbers, follow these steps.
[Add the selected phone numbers](/api-reference/cart/add-to-cart) to your cart.
```http theme={null}
PUT https://api.wavix.com/v1/buy/cart
Authorization: Bearer your_api_key
Content-Type: application/json
```
The request body must contain an array of phone numbers you want to purchase.
```json theme={null}
{
"ids": ["18022551119"]
}
```
The response will contain phone numbers successfully added to the cart and their details, such as activation fee, monthly fee, and the number of inbound channels for the number.
Check out numbers from the cart.
After phone numbers are added to the cart, [check them out](/api-reference/cart/check-out-the-cart) to finalize the purchase.
```http theme={null}
POST https://api.wavix.com/v1/buy/cart/checkout
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request sample:
```json theme={null}
{
"ids": ["18022551119"]
}
```
Activation fee and monthly fee will be automatically deducted from your balance. Make sure you have enough funds in your account or a primary card linked to your account with sufficient funds.
## List purchased numbers
You can [get a list of purchased numbers](/api-reference/my-numbers/list-phone-numbers) on your Wavix account by using the following method:
```http theme={null}
GET https://api.wavix.com/v1/mydids
Authorization: Bearer your_api_key
```
The response will contain numbers and their details, such as status, activation, monthly fees, and the number of inbound channels.
A number status can be one of the following:
* `active` - The number is fully configured and can receive inbound calls.
* `inactive` - Additional documents are required to activate the number. For inactive numbers, the response will contain a description of the documents required to activate the number.
## Update number destination
For active numbers, Wavix can route inbound calls to:
* a SIP trunk
* a SIP URI
* a dedicated PSTN number
To [update inbound call routing and SMS endpoint](/api-reference/my-numbers/update-a-phone-number) for a number, use the following API method. You can update destinations for several numbers in a single request.
```http theme={null}
POST https://api.wavix.com/v1/mydids/update-destinations
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request body example:
```json theme={null}
{
"ids": [
1,
2
],
"destinations": [
{
"transport": 1,
"destination": "sip@example.com",
"priority": 1,
"callhunt": false,
"active": true
}
]
}
```
## Return number
Return numbers you no longer use to the Wavix global inventory.
To [return unused numbers](/api-reference/my-numbers/release-phone-numbers), use the following API method:
```http theme={null}
DELETE https://api.wavix.com/v1/mydids
Authorization: Bearer your_api_key
Content-Type: application/json
```
# Product updates
Source: https://docs.wavix.com/release-notes
Follow the latest Wavix product updates, new features, and improvements across SMS, voice, phone numbers, SIP trunking, and the Wavix API.
## WhatsApp
WhatsApp is now available in preview. Send WhatsApp template messages through the same Wavix account and API you use for SMS and voice. Wavix enables a limited number of accounts at a time — request access in the Wavix portal to get started.
[Learn more about WhatsApp on Wavix](/messaging/whatsapp/overview).
## Official Wavix SDKs
The Go, Node.js, and Ruby Wavix official SDKs have been updated, and the new Python SDK is now available. Use them to integrate with the Wavix API faster and add SMS, voice, and other Wavix features to your applications with language-specific client libraries.
[Learn more about the Wavix SDKs](/sdks/overview).
## MCP server
The Wavix MCP server is now available. Connect any MCP-compatible AI client — Claude Code, Cursor, VS Code, or Codex — to your Wavix account and manage SMS, voice, numbers, SIP trunking, 2FA, and more through natural language prompts.
[Learn more about the Wavix MCP server](/mcp/overview).
## API key scopes
API keys now support per-resource permissions. Assign **No access**, **Read**, or **Write** to each resource to limit what each key can do.
[Learn more about restricted keys and scopes](/api-reference/authentication#restricted-keys-and-scopes).
## Shared sender ID for 2FA
You can now send two-factor authentication (2FA) codes using shared sender IDs. This removes the requirement to register a dedicated sender ID for each destination, enabling you to launch your 2FA service instantly.
Shared sender IDs are pre-configured and managed by Wavix to ensure optimal delivery rates across all networks.
[Learn more about Wavix 2FA](/messaging/2fa).
## Bearer token authentication
API authentication now uses Bearer tokens in the `Authorization` header. The previous `appid` query parameter method is deprecated and will be removed in a future version.
[Learn more about authentication](/api-reference/authentication).
## SMPP connectivity
You can now connect to the Wavix SMS Gateway over SMPP to send, receive, and monitor messages in real time.
[Learn more about the Wavix SMPP gateway](/messaging/smpp).
## SMS troubleshooting
You can now access detailed message logs directly in the app to review and resolve delivery issues.
## SIP REFER for inbound calls
You can now transfer inbound calls seamlessly to different recipients. Route calls from AI assistants to human agents, specialists, or other destinations.
[Learn more about inbound call transfers with LiveKit](/sip-trunking/guides/livekit#transfer-a-call).
## Call Streaming
Call Streaming is now available. You can stream raw call audio to third-party services, such as speech analytics platforms, recording tools, or large language models (LLMs).
This feature lets you use live transcription, AI-powered assistants, and real-time sentiment analysis.\
[Learn more about call streaming](/voice/call-streaming).
## User section redesign
The user section in the app now matches our design system.
# Go SDK
Source: https://docs.wavix.com/sdks/go-sdk
# Node.js SDK
Source: https://docs.wavix.com/sdks/node-sdk
# SDKs and widgets
Source: https://docs.wavix.com/sdks/overview
Build on the Wavix API with the official Go, Node.js, Ruby, and Python server SDKs, or add the Wavix Embeddable voice widget to your web app.
Wavix maintains official server SDKs and a ready-to-use voice widget, so you can build on the API with less code.
## Server SDKs
The server SDKs wrap the Wavix API in idiomatic clients, so you call native methods instead of building raw HTTP requests. Each one is open source on [Wavix's GitHub](https://github.com/Wavix):
Go client for the Wavix API.
Node.js client for the Wavix API.
Ruby client for the Wavix API.
Python client for the Wavix API.
## Wavix Embeddable
Wavix Embeddable is a ready-to-use web phone you can embed in any web app, such as a CRM or support portal. It adds inbound and outbound voice calling with minimal code. For the full integration guide, see [Wavix Embeddable](/sdks/wavix-embeddable).
# Python SDK
Source: https://docs.wavix.com/sdks/python-sdk
# Ruby SDK
Source: https://docs.wavix.com/sdks/ruby-sdk
# Wavix Embeddable
Source: https://docs.wavix.com/sdks/wavix-embeddable
Add a ready-made web phone to your CRM or support portal with Wavix Embeddable: inbound and outbound calling, call history, events, and custom styling.
Wavix Embeddable is a ready-to-use web phone you can add to any web app, such as a CRM or support portal. It gives your users inbound and outbound calling, call history, custom styling, and real-time call events, with little code. Answering Machine Detection (AMD) and call recording work out of the box.
## Prerequisites
* A Wavix account on the **Flex Pro** account level. See [Go live](/getting-started/go-live).
* Your [API key](/api-reference/authentication).
* A phone number on your account. See [Buy a number](/numbers/buy-number).
* A SIP trunk that uses Digest authentication with a strong password. See [Create a SIP trunk](/sip-trunking/create-sip-trunk).
## How it works
The widget loads from a script that Wavix hosts. It signs in with a short-lived **widget token** tied to your SIP trunk: you create the token on your server, then start the widget in the browser. You can embed it inline on the page, or open it in a separate window.
## Step 1: Generate a widget token
Create the token on your server so your API key never reaches the browser.
```bash cURL theme={null}
curl --request POST \
--url 'https://api.wavix.com/v2/webrtc/tokens?appid=your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"sip_trunk": "your_sip_trunk_id",
"payload": {},
"ttl": 3600
}'
```
* `sip_trunk`: the ID of the SIP trunk the widget connects through.
* `payload`: optional custom data to store with the token. It's returned when you look the token up.
* `ttl`: token lifetime, in seconds. The widget disconnects when the token expires.
If successful, the service returns the `HTTP 201 Created` status code:
```json theme={null}
{
"token": "WIDGET_TOKEN",
"uuid": "TOKEN_ID",
"sip_trunk": "SIP trunk ID",
"payload": {},
"ttl": 3600
}
```
Use the `token` value as `WIDGET_TOKEN` in the next step.
Always create widget tokens on your server. The widget signs in with the token, not your API key, so the key stays on your server.
## Step 2: Embed the widget
Load the widget script and start it. For `sip.server`, use the SIP gateway with the lowest ping from your users (find the gateway list on the **Numbers & trunks** page in the Wavix portal). Replace `WIDGET_TOKEN` with the token from Step 1.
Add the script to your page's ``:
```html theme={null}
```
Add a container element where the widget should appear:
```html theme={null}
```
Start the widget and open it in a separate window when needed:
```html theme={null}
```
Open the window from a button. Pass a number as `to` to pre-fill the dialer:
```html theme={null}
```
## Step 3: Enable inbound calls
Outbound calls work as soon as you embed the widget. Inbound calls reach the widget only if the number the customer dials is routed to the widget's SIP trunk. **If the number has no destination, or points to a different trunk, it won't ring the widget**, even though the widget loads and signs in correctly.
In the Wavix portal, go to **Numbers & trunks**, open the number, and set its destination to the SIP trunk your widget token uses. You can also set the destination with the API. See [Update number destination](/numbers/numbers#update-number-destination).
If inbound calls don't reach the widget, the usual cause is a number with no destination, or one routed to a different SIP trunk. Check that the number's destination is the widget's SIP trunk.
## Configuration options
Pass these in the `init` object.
| Option | Description |
| - | - |
| `widget.containerId` | ID of the element the widget renders into (inline mode). |
| `widget.windowTitle` | Title of the dialog window (dialog mode). |
| `widget.customStyles` | URL of a stylesheet to override the default appearance. |
| `widget.customLogo` | URL of a logo to display in the widget. |
| `widget.customLink` | URL the logo links to. |
| `widget.withLogo` | Whether to show the logo. Defaults to `false`. |
| `sip.server` | The Wavix SIP gateway to connect through. |
| `sip.token` | The widget token from Step 1. |
| `sip.autoDial` | Whether to dial automatically. Defaults to `false`. |
## Customize the appearance
Override the widget's CSS variables under the `#webrtc-widget` selector.
```css theme={null}
#webrtc-widget {
--text-high-contrast: #fff;
--text-medium-contrast: #d0d5dd;
--text-low-contrast: #667085;
--text-accent: #d4efdf;
--text-inverted: #fff;
--text-negative: #ff5655;
--bg-background: #292d33;
--bg-header: #292d33;
--bg-navigation: #292d33;
--bg-status: #333842;
--bg-brand: #333842;
--bg-border: #333842;
--fg-high-contrast: #667085;
--fg-accent: #22aa5c;
--fg-negative: #ff5655;
--fg-warning: #e7b006;
--fg-brand: #34c1ca;
--fg-inverted: #fff;
--fg-logo: #fff;
--a-high-contrast: #fff;
--a-active: #22aa5c;
--a-inactive: #667085;
--text-inverted-disabled: #98a2b3;
--bg-hover: #333842;
--bg-pressed: #333842;
--bg-border-active: #22aa5c;
--fg-accent-hover: #289c5c;
--fg-accent-pressed: #2c7351;
--fg-accent-disabled: #333842;
--fg-negative-hover: #e52625;
--fg-negative-pressed: #b61f1e;
--fg-negative-disabled: #333842;
--fg-high-contrast-hover: #333842;
--fg-high-contrast-pressed: #333842;
--fg-high-contrast-disabled: #333842;
--fg-inverted-disabled: #98a2b3;
--a-hover: #98a2b3;
--a-pressed: #fff;
--a-disabled: #333842;
--switch-background: #333842;
--switch-background-checked: #22aa5c;
--switch-foreground: #fff;
}
```
## Manage tokens
You can manage widget tokens through the API:
* List active tokens, or get a token by its ID.
* Update a token's `payload`. The new payload replaces the old one.
* Delete a token. The widget using it disconnects right away.
## Troubleshooting
**The incoming-call screen appears, but answering fails.** The call shows the answer buttons, then either throws a JavaScript error (such as `Cannot read properties of null (reading 'invite')`) or connects for about a second and drops with no audio.
This almost always means the dialed number isn't routed to the widget's SIP trunk. Set the number's destination to that trunk, as shown in [Enable inbound calls](#step-3-enable-inbound-calls).
## Learn more
For the full reference and the latest updates, see the [Wavix Embeddable repository](https://github.com/Wavix/wavix-embeddable) on GitHub.
# How to create a SIP trunk
Source: https://docs.wavix.com/sip-trunking/create-sip-trunk
Create a SIP trunk in the Wavix portal: choose Digest or IP authentication, set a Caller ID and call limits, and enable recording or transcription.
A [SIP trunk](https://wavix.com/sip-trunk) allows you to connect your IP-PBX or communications platform to the Wavix platform to make and receive calls. This guide walks you through the process of creating a SIP trunk in the Wavix portal.
## Create a SIP trunk in the Wavix portal
To purchase or configure a new SIP trunk:
1. **Sign in** to your [Wavix account](https://app.wavix.com).
2. In the top menu, click on **Numbers & Trunks → Trunks**.
3. Click **Create new**.
4. Under **Authentication Method**, select **Digest** (for username/password authentication) or **IP Authentication** (if you have a dedicated static IP).
5. Enter a **SIP trunk name**, set a **SIP trunk password** (for Digest only), and choose one of your numbers as the **Caller ID**.
6. (Optional) Configure additional limits. If not specified, global account limits apply:
* Max outbound call duration
* Max number of simultaneous calls via the SIP trunk
* Max call cost
7. (Optional) Under **Trunk features**, enable functionality like **Call recording**, **Call transcription**, or **Voicemail detection** (AMD).
8. Click **Save and close** (or **Next** to configure advanced options).
Once the SIP trunk is successfully created, it will appear in your account's SIP trunks list.
Your 5-digit SIP trunk username is generated automatically and shown in the **SIP trunk ID** column.
# How to configure 3CX with Wavix
Source: https://docs.wavix.com/sip-trunking/guides/3cx
Configure 3CX with Wavix SIP trunks for inbound and outbound calls, using IP authentication, trunk settings, outbound rules, and inbound routing.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Configure SIP trunk in 3CX
To configure inbound and outbound calls on your 3CX instance:
1. **Log in** to the 3CX management console
2. In the left-hand menu, go to **Voice & Chat**
3. Click the **Add SIP Trunk** button
Next, select your country and choose Wavix from the list of SIP Trunk providers in your country. If you do not see Wavix listed, try selecting ‘Worldwide’ in the Country list. You can check the list of supported SIP trunk providers on the 3CX website at [https://www.3cx.com/partners/sip-trunks/](https://www.3cx.com/partners/sip-trunks/).
If you do not see Wavix on the list of supported SIP trunk providers, download and import the `wavix.pv.xml` file. This will automatically populate some of the SIP trunk configuration parameters.
Follow these steps to add Wavix as your SIP trunk provider:
1. In the **Account Details** section, enter the **SIP trunk ID** and **password** that you set up for the SIP trunk on the Wavix platform
2. Enter your default **Caller ID** into the **Main Trunk Number** field. The Caller ID should be an active or verified phone number from your Wavix account.
3. In the **Server Details** section, enter the address of one of Wavix's regional SIP proxies in the field labeled **Registrar/Server**. We recommend using the address of the regional SIP proxy closest to your location. You can find the full list of Wavix regional gateways at the bottom of the Trunks section in Wavix.
4. Add a name for your 3CX Trunk
5. Click the **Save** button to save your configuration
By default, a new 3CX Trunk supports up to 10 calls in parallel. However, all new Wavix accounts are initially limited to 2 simultaneous calls for security reasons. To request an increase, please contact [support@wavix.com](mailto:support@wavix.com).
Click on the **Options** tab and ensure that both **inbound** and **outbound** calls are allowed in the **Configuration** section.
Scroll down to the **Codec priority** section. Wavix supports all the codecs listed, but **PCMU** is recommended for most cases. To save the SIP trunk configuration, click **OK** at the top of the page. It will take a moment for 3CX to register the SIP Trunk.
A green bubble will indicate that the SIP Trunk is successfully registered. If any issues occur, check the **Event logs** in the 3CX Management Console dashboard for more details.
## Activate IP authentication
The Wavix platform supports IP authentication for dedicated IP addresses. To activate IP authentication for your SIP device, you need to enable this feature in your 3CX device and on the Wavix platform.
Follow these steps in your 3CX:
1. Open your 3CX **SIP Trunk** settings
2. Select the Worldwide option in the Country list and choose **Generic SIP Trunk (IP Based)** in the Provider list
3. In the **Account Details** section, enter the **SIP trunk ID** for the SIP trunk from the Wavix platform
4. Enter your default Caller ID in the **Main Trunk Number** field. The Caller ID should be an active or verified phone number from your Wavix account.
5. Set the **Type of authentication** to **Do not require - IP based** from the drop-down menu
6. In the **Server Details** section, enter the address of one of Wavix's regional SIP proxies in the field labeled **Registrar/Server**. We recommend using the address of the regional SIP proxy closest to you. The full list of Wavix regional gateways can be found at the bottom of the [Trunks section](https://app.wavix.com/trunks) in Wavix.
7. Add a name for your 3CX Trunk
8. Click the **Save** button to save the configuration
To activate the IP authentication on the Wavix platform:
1. Open the Wavix **SIP trunk** settings
2. Select **IP Authentication** in the Authentication method section
3. Enter your 3CX dedicated IP and click **Submit**
4. Click **Save** to apply the changes
IP authentication will be activated on your Wavix SIP trunk once the request is approved by the Wavix OPS team.
After submitting the IP authentication request, you cannot update your IP address or change the authentication method. By default, an IP address can only be mapped to a single SIP trunk. If you need to have several Wavix SIP trunks sharing the same IP address, please contact [support@wavix.com](mailto:support@wavix.com).
## Configure outbound calls
To place outbound calls you need to configure outbound rules. Follow these steps to configure your outbound rules:
1. Click on the **Outbound Rules** option in the left-hand side menu and click the **Add** button
2. Assign a name to your Outbound Rule and apply it to the default extension group by:
* Clicking the **Add** button in the **Apply this rule to these calls** section
* Selecting the **DEFAULT** group name
* Clicking **OK**
3. Scroll down to the **Make outbound calls on** section, select **Wavix**, and save the Outbound Rule
All destination phone numbers must be in the `E.164` international format. The E.164 format can handle numbers with up to 15 digits and is usually written as: `[+][country code][subscriber number including area code]`.\
**Example:** A US number in E.164 format would be `+16561223344`.
Calls to numbers without a country code or carrying national access codes will be rejected by the Wavix platform.
Below are typical examples of phone numbers incorrectly formatted according to the E.164 international standard:
| Country | Number | Reason | Number in E.164 format |
| - | - | - | - |
| US | 6561223344 | No country code | +16561223344 |
| UK | 020 1122 3344 | No country code, national access code with 0 | +442011223344 |
| Switzerland | 0041797000777 | Leading 00 international prefix | +41797000777 |
Depending on your users’ dialing habits, you may want to strip leading digits or prepend a country code. For example, the configuration below can be used to prepend all dialed numbers with the leading 1 if your users are accustomed to US domestic numbers in the national format.
## Configure inbound calls
If you have enabled IP authentication for your SIP trunk, scroll down to the "Configure inbound call routing for trunks with IP authentication" section.
Open the **SIP Trunk configuration settings** and select the **Default route** for inbound calls.
Depending on your business needs, you can set specific office hours for inbound calls and route them to different extensions, voicemail, or drop calls based on schedule.
For calls to be routed to your 3CX instance, follow these steps in your Wavix account:
1. **Log in** to your Wavix account
2. Select **My numbers** under **Numbers & trunks** in the top menu
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**
4. **Select** the destination trunk in the **Destination** section
5. Click **Add** to add the destination for the DID
6. Click **Save** to confirm the settings
Changes will be applied to all selected numbers.
***
### Configure inbound call routing for trunks with IP authentication
Skip this section if your trunks are configured to use account-based authentication.
When an inbound call reaches Wavix, it can be routed to your SIP trunk, a SIP URI, or a PSTN number.
SIP trunks with IP authentication enabled cannot be used for inbound call routing as they do not maintain registration with Wavix SIP proxies. To configure inbound routing for your numbers, you must specify a valid SIP URI address instead.
To configure inbound call routing to a valid SIP URI:
1. **Log in to** your Wavix account
2. Select **My numbers** under **Numbers & trunks**
3. Click on the three dots on the right-hand side and select **Edit number**. Double-click is also supported.
4. In the **Transport** drop-down menu, select **SIP URI**
5. **Enter a valid SIP URI** using the following format: `+[did]@FQDN:port;transport=connection`, where:
* `FQDN`: fully qualified domain name or IP address of your 3CX instance
* `Port`: SIP port used by the PBX
* `Connection`: can be `udp`, `tcp`, or `tls`. The default transport is udp.
6. Click **Add** to add the destination for the DID
7. Click **Save** to apply settings
The `[did]` parameter will be automatically updated with the actual dialed phone number when routing the call.
You can also edit multiple numbers simultaneously. To do this, select multiple numbers you want to modify, then click on the **Bulk actions** button. The changes will apply to all selected numbers.
Make sure that all your Wavix numbers are listed under the DIDs tab of the 3CX SIP trunk.
***
## Verifying the setup
To test the SIP trunk, place a call to your mobile phone number. Follow these steps:
1. Go to Users in the left-hand side menu
2. Click on the default 100 extension
3. Download the 3CX mobile application by scanning the **QR code** displayed on the page
4. Place a test call using the app
## Troubleshooting
If an outbound call fails, check the following:
* You have completed all the steps in this guide.
* The phone number you are dialing is in the international E.164 format.
* The maximum call rate limit on your SIP trunk or account is enough to call the desired destination. You can check your effective rates in the My account section at [app.wavix.com](https://app.wavix.com).
# How to configure Asterisk using Wavix SIP trunks
Source: https://docs.wavix.com/sip-trunking/guides/asterisk
This guide provides a basic configuration of Asterisk to make inbound and outbound calls over the Wavix network
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Configure a SIP trunk in Asterisk
This guide provides configuration instructions for both the `chan_pjsip` and `chan_sip` modules. Follow the instructions that correspond to the module used on your Asterisk PBX.
The `chan_sip` module is deprecated and was officially removed in Asterisk version 21.
For the purpose of this guide, we will use:
1. Internal Asterisk extensions: `11111` and `99999`
2. Primary gateway domain name: `nl.wavix.net`
3. Primary gateway IP address: `95.211.82.14`
Choose the primary gateway with the lowest ping from your location. A full list of Wavix regional gateways is available at the bottom of the page: [https://app.wavix.com/trunks](https://app.wavix.com/trunks)
### Configure the chan\_sip module
To configure outbound calls on your Asterisk server:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `sip.conf` file for editing.
3. Add or modify the following configuration:
```ini theme={null}
[general]
register => :@nl.wavix.net/YOUR_NUMBER
[Wavix]
type=friend
host=nl.wavix.net
username=
fromuser=
secret=
context=from-siptrunk
insecure=port,invite
disallow=all
allow=ulaw,alaw
nat=force_rport,comedia
canreinvite=no
; ===== SIP devices =====
[11111]
type=friend
username=11111
secret=
host=dynamic
context=from-internal
disallow=all
allow=ulaw,alaw
nat=force_rport,comedia
canreinvite=no
qualify=yes
[99999]
type=friend
username=99999
secret=
host=dynamic
context=from-internal
disallow=all
allow=ulaw
nat=force_rport,comedia
canreinvite=no
qualify=yes
```
* Replace `` and `` with the SIP trunk credentials configured on the Wavix platform.
* Replace `` with the phone number purchased on your Wavix account.
* Use strong passwords instead of `` and ``.
Verify the Wavix SIP trunk registration:
1. Reload the `chan_sip` module configuration using the following command: `asterisk -x "sip reload"`
2. Check the SIP trunk registration status using the following command: `asterisk -x "sip show registry"`
### Configure the chan\_pjsip module
To configure outbound calls on your Asterisk server:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `pjsip.conf` file for editing.
3. Add or modify the following configuration:
```ini theme={null}
[transport-udp-main]
type=transport
protocol=udp
bind=0.0.0.0:5060
[auth_wavix]
type=auth
auth_type=userpass
username=
password=
[Wavix_aor]
type=aor
contact=sip:@nl.wavix.net:5060
[Wavix]
type=endpoint
context=from-siptrunk
disallow=all
allow=ulaw,alaw
direct_media=no
from_user=
from_domain=nl.wavix.net
aors=Wavix_aor
outbound_auth=auth_wavix
[Wavix_identify]
type=identify
endpoint=Wavix
match=nl.wavix.net
match=us.wavix.net
match=sg.wavix.net
match=au.wavix.net
[reg_wavix]
type=registration
transport=transport-udp-main
outbound_auth=auth_wavix
server_uri=sip:nl.wavix.net:5060
client_uri=sip:@nl.wavix.net
expiration=120
retry_interval=20
max_retries=10
[11111]
type=endpoint
transport=transport-udp-main
context=from-internal
disallow=all
allow=ulaw,alaw
aors=11111
auth=11111
[11111]
type=auth
auth_type=userpass
username=11111
password=
[11111]
type=aor
max_contacts=2
[99999]
type=endpoint
transport=transport-udp-main
context=from-internal
disallow=all
allow=ulaw,alaw
aors=99999
auth=99999
[99999]
type=auth
auth_type=userpass
username=99999
password=
[99999]
type=aor
max_contacts=2
```
* Replace `` and `` with the SIP trunk credentials configured on the Wavix platform.
* Replace `` with the phone number purchased on your Wavix account.
* Use strong passwords instead of `` and ``.
Verify the Wavix SIP trunk registration:
1. Reload the `chan_pjsip` module configuration using the following command: `asterisk -x "module reload chan_pjsip"`
2. Check the SIP trunk registration status using the following command: `asterisk -x "pjsip show registrations"`
## Enable IP Auth for the Wavix SIP trunk
You may wish to enable IP Authentication on Wavix SIP trunks. When IP Authentication is enabled, Wavix will accept all calls originating from a specified IP address without requiring login credentials.
You must have a dedicated IP for this option to work correctly.
To create a new SIP trunk with IP authentication on the Wavix platform:
1. In the top menu, navigate to Numbers & trunks and select Trunks
2. Click the Create new button
3. Under Authentication Method, select IP Authentication
4. Enter a public static IP address of your Asterisk PBX
5. Enter a SIP trunk Name and choose one of your account’s numbers as the Caller ID
6. Optionally, configure additional limits. If not specified, global account limits apply:
* Max outbound call duration
* Max number of simultaneous calls via the SIP trunk
* Max call cost
7. Click Create
Once you submit the request, the Wavix Support team will review and enable IP Authentication on the SIP trunk.
After submitting the IP authentication request, you won’t be able to update your IP address or change the authentication method
* When IP Authentication is enabled on a SIP trunk, it cannot be used as a destination for a DID. You must use a SIP URI instead
* After submitting the IP authentication request, you'll not be able to update your IP address or change the authentication method. By default, an IP address can only be mapped to a single SIP trunk. If you need to have several Wavix SIP trunks sharing the same IP address, please contact [support@wavix.com](mailto:support@wavix.com)
### Configure IP Auth in Asterisk
This guide provides configuration instructions for both the `chan_pjsip` and `chan_sip` modules. Follow the instructions that correspond to the module used on your Asterisk PBX.
The `chan_sip` module is deprecated and was officially removed in Asterisk version 21.
For the purpose of this guide, we will use:
1. Internal Asterisk extensions: `11111` and `99999`
2. Primary gateway domain name: `nl.wavix.net`
3. Primary gateway IP address: `95.211.82.14`
Choose the primary gateway with the lowest ping from your location. A full list of Wavix regional gateways is available at the bottom of the page:
[https://app.wavix.com/trunks](https://app.wavix.com/trunks)
#### Configure the chan\_sip module
To configure IP authentication on your Asterisk server:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `sip.conf` file for editing.
3. Add or modify the following configuration:
```ini theme={null}
[general]
; Remove the 'register' line. SIP registration is not used for IP authentication.
disallow=all
allow=ulaw,alaw
nat=force_rport,comedia
canreinvite=no
[Wavix]
type=friend
host=nl.wavix.net
fromuser=
context=from-siptrunk
insecure=port,invite
canreinvite=no
disallow=all
allow=ulaw,alaw
qualify=yes
directmedia=no
; ===== SIP devices =====
[11111]
type=friend
username=11111
secret=
host=dynamic
context=from-internal
disallow=all
allow=ulaw,alaw
nat=force_rport,comedia
canreinvite=no
qualify=yes
[99999]
type=friend
username=99999
secret=
host=dynamic
context=from-internal
disallow=all
allow=ulaw
nat=force_rport,comedia
canreinvite=no
qualify=yes
```
* Replace `` with the phone number purchased on your Wavix account.
* Use strong passwords instead of `` and ``.
Reload the `chan_sip` module configuration using the following command: `asterisk -x "sip reload"`
#### Configure the chan\_pjsip module
To configure IP authentication on your Asterisk server:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `pjsip.conf` file for editing.
3. Add or modify the following configuration:
```ini theme={null}
[transport-udp-main]
type=transport
protocol=udp
bind=0.0.0.0:5060
[auth_wavix]
type=auth
auth_type=userpass
username=
password=
[Wavix_aor]
type=aor
; Static contact for SIP trunk
contact=sip:@nl.wavix.net:5060
[Wavix]
type=endpoint
context=from-siptrunk
disallow=all
allow=ulaw,alaw
direct_media=no
from_user=
from_domain=nl.wavix.net
aors=Wavix_aor
outbound_auth=auth_wavix
[Wavix_identify]
type=identify
endpoint=Wavix
match=nl.wavix.net
match=sg.wavix.net
match=au.wavix.net
match=us.wavix.net
[reg_wavix]
type=registration
transport=transport-udp-main
outbound_auth=auth_wavix
server_uri=sip:nl.wavix.net:5060
client_uri=sip:@nl.wavix.net:5060
expiration=120
retry_interval=20
max_retries=10
[11111]
type=endpoint
transport=transport-udp-main
context=from-internal
disallow=all
allow=ulaw,alaw
aors=11111
auth=11111
[11111]
type=auth
auth_type=userpass
username=11111
password=
[11111]
type=aor
; Allow dynamic registration for endpoint 11111
max_contacts=2
[99999]
type=endpoint
transport=transport-udp-main
context=from-internal
disallow=all
allow=ulaw,alaw
aors=99999
auth=99999
[99999]
type=auth
auth_type=userpass
username=99999
password=
[99999]
type=aor
; Allow dynamic registration for endpoint 99999
max_contacts=2
```
* Replace `` with the phone number purchased on your Wavix account.
* Use strong passwords instead of `` and ``.
Reload the `chan_pjsip` module configuration using the following command: `asterisk -x "pjsip reload"`
## Configure outbound calls in Asterisk
To configure outbound calls:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `extensions.conf` file for editing.
3. Depending on the module you use, `chan_sip` or `chan_pjsip`, add or modify the following configuration:
**For `chan_sip`:**
```ini theme={null}
; Outbound calls via Wavix for chan_sip
exten => _X.,1,NoOp(Outbound call through Wavix SIP trunk)
same => n,Set(CALLERID(num)=) ; Set the outbound Caller ID
same => n,Dial(SIP/${EXTEN}@Wavix,60)
same => n,Hangup()
```
**For `chan_pjsip`:**
```ini theme={null}
; Outbound calls via Wavix for chan_pjsip
exten => _X.,1,Set(CALLERID(num)=) ; Set your outbound caller ID
same => n,Dial(PJSIP/${EXTEN}@Wavix,60,g)
same => n,Hangup()
```
Provide the number you’ve purchased on your account instead of the `` variable.
All destination phone numbers must be in the E.164 international format. This format can handle numbers with up to 15 digits and is usually written as \[+]\[country code]\[subscriber number including area code]. For example, a US number in E.164 format would be +16561223344. The Wavix platform will reject calls to numbers without a country code or carrying national access codes.
| Country | Number | Reason | Number in E.164 format |
| - | - | - | - |
| US | 6561223344 | No country code | +16561223344 |
| UK | 020 1122 3344 | No country code, national access code with leading 0 | +442011223344 |
| Switzerland | 0041797000777 | Leading 00 international prefix | +41797000777 |
The Caller ID can also be configured in `sip.conf` or `pjsip.conf`. However, the settings in the `extensions.conf` file will take precedence.
To ensure proper audio transmission, **RTP ports 10000-20000** must be allowed from any IP address:
1. Navigate to the Asterisk configuration directory: `/etc/asterisk/`
2. Open the `rtp.conf` file for editing.
3. Add or modify the following configuration:
```ini theme={null}
[general]
rtpstart=10000
rtpend=20000
```
4. Save the file and restart your Asterisk using the following command: `sudo systemctl restart asterisk`
Ensure that ports 10000-20000 are also allowed in your firewall to avoid connectivity issues.
## Configure inbound calls on Wavix
If you have enabled IP authentication for your SIP trunk, scroll down to the [Configure inbound call routing for trunks with IP authentication](#configure-inbound-call-routing-for-trunks-with-ip-authentication) section.
Make sure that your Asterisk SIP trunk is registered with Wavix. If the trunk is not registered, ensure you’ve completed all the steps provided in the "Configure a SIP trunk in Asterisk" section.
1. Log in to your Wavix account
2. Navigate to **My numbers** under the **Numbers & trunks** in the top menu
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**
4. Select the destination trunk in the **Destination** section
5. Click **Add** to add the destination for the phone number
6. Click **Save** to apply the settings
You can also edit multiple numbers simultaneously. To do this, select the multiple numbers you want to modify, then click the **Bulk actions** button. The changes will apply to all selected numbers.
### Configure inbound call routing for trunks with IP authentication
Skip this section if your trunks are configured to use digest authentication.
SIP trunks with IP authentication enabled cannot be used for inbound call routing, as they do not maintain registration with Wavix proxies. To set up inbound routing for your numbers, you must use a valid SIP URI address instead.
To configure inbound call routing to a valid SIP URI:
1. **Log in** to your Wavix account
2. Navigate to **My numbers** under the **Numbers & trunks** in the top menu
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**
4. Select **SIP URI** in the **Transport** drop-down menu
5. **Enter a valid SIP URI** in the following format: `+[did]@FQDN:port;transport=connection`, where:
* a. **FQDN** is the fully qualified domain name or IP address of your Asterisk PBX
* b. **Port** is the SIP port used by the PBX
* c. **A connection** can be udp, tcp, or tls, with udp as the default transport
6. Click **Add** to set the destination for the phone number
7. Click **Save** to apply the settings
The `[did]` parameter will be automatically updated with the actual dialed phone number when routing the call.
## Configure inbound calls in Asterisk
This guide provides configuration instructions for both the `chan_pjsip` and `chan_sip` modules. Follow the instructions that correspond to the module used on your Asterisk PBX.
The `chan_sip` module is deprecated and was officially removed in Asterisk version 21.
### Configure the chan\_sip module
To configure inbound calls on your Asterisk:
1. Navigate to the Asterisk configuration directory `/etc/asterisk/`
2. Open the `extensions.conf` file for editing
3. Add or modify the following configuration
```ini theme={null}
[general]
static=yes
writeprotect=no
clearglobalvars=no
[globals]
; Define any global variables if needed
[from-internal]
exten => 1001,1,Dial(SIP/11111,20)
exten => 1002,1,Dial(SIP/99999,20)
[from-siptrunk]
; Handle inbound calls without the leading '+' sign
exten => ,1,NoOp(Inbound call to )
same => n,Dial(SIP/11111,60)
same => n,Voicemail(1001@default,u) ; Send to voicemail if the call is not answered
same => n,Hangup()
; Handle inbound calls with the leading '+' sign
exten => +,1,NoOp(Inbound call to )
same => n,Dial(SIP/11111,60)
same => n,Voicemail(1001@default,u) ; Send to voicemail if the call is not answered
same => n,Hangup()
; Catch-All for Unknown or Invalid Calls
exten => _.,1,NoOp(Unknown inbound call received)
same => n,Hangup()
```
Replace `` with the phone number purchased on your Wavix account.
Make sure you reload your Asterisk configuration.
### Configure the chan\_pjsip module
To configure inbound calls on your Asterisk:
1. Navigate to the Asterisk configuration directory `/etc/asterisk/`
2. Open the `pjsip.conf` file for editing
3. Add or modify the following configuration
```ini theme={null}
[general]
static=yes
writeprotect=no
clearglobalvars=no
[globals]
; Define any global variables here if needed
[from-internal]
exten => 1001,1,Dial(PJSIP/11111,20)
exten => 1002,1,Dial(PJSIP/99999,20)
; Inbound Call Handling from Wavix
[from-siptrunk]
; Handle inbound calls without the leading '+' sign
exten => ,1,Dial(PJSIP/11111,60)
; Send to voicemail if the call is not answered
same => n,Voicemail(1001@default,u)
same => n,Hangup()
; Handle inbound calls with the leading '+' sign
exten => +,1,Dial(PJSIP/11111,60)
; Send to voicemail if the call is not answered
same => n,Voicemail(1001@default,u)
same => n,Hangup()
; Catch-All for Unhandled Inbound Calls
exten => _X.,1,NoOp(Unknown inbound call received)
same => n,Hangup()
```
Replace `` with the phone number purchased on your Wavix account.
Make sure you reload your Asterisk configuration.
## Troubleshooting outbound calls
* 603 Declined response might be received when calling the destination with the per-minute rate higher than the Max call rate set for your account. You can find your effective Max call rate on the Trunks page. Please contact [support@wavix.com](mailto:support@wavix.com) to request a change to your Max call rate.
* The destination phone number is in an incorrect format. Please make sure the number is dialed in the international E.164 format. Strip prefixes like 0, 00, or 011 before the dialed number if needed.
# How to connect ElevenLabs Agents with Wavix
Source: https://docs.wavix.com/sip-trunking/guides/elevenlabs
This guide explains how to connect ElevenLabs Agents with Wavix voice infrastructure to place and receive calls.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. An active [ElevenLabs account](https://elevenlabs.io/) with access to ElevenLabs Agents.
Most steps in this guide can be completed in the Wavix portal and the ElevenLabs dashboard, or programmatically using the [Wavix API](/api-reference/getting-started) and the [ElevenLabs API](https://elevenlabs.io/docs/api-reference/introduction). Both paths are provided where available.
## How it works
1. A customer calls your Wavix phone number, or your ElevenLabs agent places an outbound call.
2. Wavix and ElevenLabs exchange call signaling and audio over SIP.
3. Your ElevenLabs agent processes the audio and generates spoken responses in real time.
```mermaid actions={false} theme={null}
sequenceDiagram
participant Caller as Caller
participant Wavix as Wavix platform
participant EL as ElevenLabs Agents
Caller->>Wavix: Telephony network
Wavix->>EL: SIP
EL->>EL: Voice AI orchestration (LLM, TTS, conversation logic)
EL->>Wavix: SIP
Wavix->>Caller: Telephony network
```
## Create a SIP trunk in Wavix
ElevenLabs authenticates outbound calls with your Wavix SIP trunk credentials using digest authentication.
1. In the top menu, go to **Numbers & trunks → Trunks**.
2. Click **Create new**.
3. Under **Authentication method**, select **Digest**.
4. Enter a **SIP trunk name**, set a **SIP trunk password**, and choose one of your account's numbers as the Caller ID.
5. Optionally, configure additional limits. If not specified, global account limits apply:
* Max outbound call duration.
* Max number of simultaneous calls via the SIP trunk.
* Max call cost.
6. Click **Create**.
Once created, the trunk appears in your account's SIP trunk list.
Create a SIP trunk with the [Create a SIP trunk](/api-reference/sip-trunks/create-a-sip-trunk) endpoint:
```bash theme={null}
curl -X POST "https://api.wavix.com/v1/trunks" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"label": "ElevenLabs",
"password": "YOUR_SIP_TRUNK_PASSWORD",
"callerid": "YOUR_WAVIX_NUMBER",
"ip_restrict": false,
"didinfo_enabled": true,
"call_restrict": false,
"cost_limit": false,
"channels_restrict": false,
"rewrite_enabled": false
}'
```
* Replace `YOUR_SIP_TRUNK_PASSWORD` with a strong password.
* Replace `YOUR_WAVIX_NUMBER` with an active number on your Wavix account, for example `14067704205`.
Copy the value of the `name` field from the response — it's the system-generated 5-digit SIP trunk ID that you'll use as the SIP trunk username in ElevenLabs. Don't use the `id` field, which is an internal identifier.
Your 5-digit SIP trunk username is generated automatically. In the Wavix portal, it's displayed in the **SIP trunk ID** column on the Trunks page.
## Import your number into ElevenLabs
1. Sign in to your ElevenLabs account.
2. In the ElevenLabs Agents dashboard, open the **Phone Numbers** section.
3. Import a phone number from a SIP trunk.
4. Enter your Wavix phone number in E.164 format with the leading `+` sign, for example `+61290597521`, and assign a **Label** to it. ElevenLabs can't import numbers without the leading `+`.
5. Leave the **Inbound Configuration** unchanged.
6. In the **Outbound Configuration** section:
* In the **Address** field, enter `us.wavix.net`, the recommended Wavix SIP gateway. ElevenLabs hosts its infrastructure in the US.
* Set **Transport Type** to **TCP**.
* Keep **Media Encryption** set to **Allowed**.
* Under **Authentication**, enter your Wavix **SIP trunk ID** in the **SIP Trunk Username** field and your SIP trunk password in the **SIP Trunk Password** field.
7. Click **Import**.
Import a number with the ElevenLabs [Create phone number](https://elevenlabs.io/docs/api-reference/phone-numbers/create) endpoint:
```bash theme={null}
curl -X POST "https://api.elevenlabs.io/v1/convai/phone-numbers" \
-H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "sip_trunk",
"phone_number": "+YOUR_WAVIX_NUMBER",
"label": "Wavix number",
"outbound_trunk_config": {
"address": "us.wavix.net",
"transport": "tcp",
"media_encryption": "allowed",
"credentials": {
"username": "YOUR_WAVIX_SIP_TRUNK_ID",
"password": "YOUR_WAVIX_SIP_TRUNK_PASSWORD"
}
}
}'
```
* Replace `YOUR_ELEVENLABS_API_KEY` with your ElevenLabs API key.
* Replace `YOUR_WAVIX_NUMBER` with your Wavix number in E.164 format with the leading `+` sign, for example `+61290597521`.
* Replace `YOUR_WAVIX_SIP_TRUNK_ID` and `YOUR_WAVIX_SIP_TRUNK_PASSWORD` with the SIP trunk credentials configured in Wavix.
If successful, the response contains the `phone_number_id`. Copy it for later use.
`us.wavix.net` is the recommended gateway because ElevenLabs hosts its infrastructure in the US. A full list of regional gateways is shown at the bottom of the Trunks page in the [Wavix portal](https://app.wavix.com/trunks).
Optionally, you can encrypt call media on your Wavix numbers and SIP trunks:
1. Contact [support@wavix.com](mailto:support@wavix.com) with a list of the numbers and trunks you want to encrypt media for.
2. Wait for the Wavix Support team to confirm that encryption is active.
3. After confirmation, set **Media Encryption** to **Required** in the **Inbound Configuration** and **Outbound Configuration** sections of the number in ElevenLabs.
To learn more about ElevenLabs SIP trunk configuration, see the [ElevenLabs SIP trunking documentation](https://elevenlabs.io/docs/eleven-agents/phone-numbers/sip-trunking).
## Create an ElevenLabs agent
1. Sign in to your ElevenLabs account.
2. In the ElevenLabs Agents dashboard, open the **Agents** section.
3. Create a new agent from a template or start from a blank one.
4. Configure your agent: set the system prompt and first message, choose an LLM and spoken language, and select the ElevenLabs voice you want the agent to use.
For more information, see the [ElevenLabs Agents quickstart](https://elevenlabs.io/docs/eleven-agents/quickstart). You can also create agents programmatically with the [Create agent](https://elevenlabs.io/docs/api-reference/agents/create) endpoint.
### Assign the agent to your number
1. In the **Phone Numbers** section, select your imported Wavix number.
2. Click **Assign Agent** and select the agent you want to answer calls to this number.
Assign an agent with the ElevenLabs [Update phone number](https://elevenlabs.io/docs/api-reference/phone-numbers/update) endpoint:
```bash theme={null}
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/YOUR_PHONE_NUMBER_ID" \
-H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "YOUR_AGENT_ID"
}'
```
* Replace `YOUR_PHONE_NUMBER_ID` with the `phone_number_id` returned when you imported the number.
* Replace `YOUR_AGENT_ID` with the ID of your ElevenLabs agent.
## Set up inbound call routing in Wavix
Wavix can route inbound calls to a SIP trunk on the platform, a SIP URI, or forward them to a phone number. ElevenLabs requires calls to be routed to a **SIP URI**.
1. In Wavix, open **Numbers & trunks → My numbers**.
2. Select your number by clicking the **⋯** menu → **Edit number**.
3. Set the **inbound call destination type** to **SIP URI**, and enter the destination. The port is required:
* If media encryption is not enforced on your number:
```bash theme={null}
[did]@sip.rtc.elevenlabs.io:5060;transport=tcp
```
* If media encryption is enabled on your number:
```bash theme={null}
[did]@sip.rtc.elevenlabs.io:5061;transport=tls
```
4. **Save** your changes. Wavix will automatically replace `[did]` with your actual number.
First, find the ID of your phone number with the [List phone numbers](/api-reference/my-numbers/list-phone-numbers) endpoint:
```bash theme={null}
curl -X GET "https://api.wavix.com/v1/numbers" \
-H "Authorization: Bearer your_api_key"
```
Then update the number's inbound call destination with the [Update a phone number](/api-reference/my-numbers/update-a-phone-number) endpoint:
```bash theme={null}
curl -X PATCH "https://api.wavix.com/v1/numbers/YOUR_NUMBER_ID" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"destinations": [
{
"destination": "[did]@sip.rtc.elevenlabs.io:5060;transport=tcp",
"priority": 1,
"transport": 1
}
]
}'
```
* Replace `YOUR_NUMBER_ID` with the ID of your Wavix number.
* `transport: 1` sets the destination type to SIP URI.
* The port in the destination is required. If media encryption is enabled on your number, use `[did]@sip.rtc.elevenlabs.io:5061;transport=tls` instead.
Now, all calls to your Wavix number are routed to your ElevenLabs agent.
## Test your configuration
To test inbound calls, dial your Wavix number. You'll be connected to your ElevenLabs agent shortly.
To place an outbound test call:
1. In the ElevenLabs Agents dashboard, open the **Phone Numbers** section.
2. Select the imported Wavix number.
3. Select **Outbound call**.
4. Select an agent and enter a destination phone number.
5. Click **Send Test Call**.
Place an outbound call with the ElevenLabs [Outbound call via SIP trunk](https://elevenlabs.io/docs/api-reference/sip-trunk/outbound-call) endpoint:
```bash theme={null}
curl -X POST "https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call" \
-H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "YOUR_AGENT_ID",
"agent_phone_number_id": "YOUR_PHONE_NUMBER_ID",
"to_number": "+DESTINATION_NUMBER"
}'
```
* Replace `YOUR_AGENT_ID` with the ID of your ElevenLabs agent.
* Replace `YOUR_PHONE_NUMBER_ID` with the `phone_number_id` of the imported Wavix number.
* Replace `DESTINATION_NUMBER` with the phone number you want to call in E.164 format.
## Send a call follow-up SMS
You can let an ElevenLabs agent send an SMS after a call when the caller asks for a written follow-up. For example, after a scheduling call, the agent can send an appointment confirmation, reference number, or support link to the same phone number that placed the call.
Before you enable SMS follow-ups:
* Register the SMS Sender ID you want to use. For setup instructions, see [Sender ID registration](/messaging/send-sms#sender-id-registration).
* Create a dedicated Wavix API key with only the scopes required to send SMS.
* Confirm that the caller has agreed to receive the follow-up SMS.
* Keep the SMS content short and include opt-out text when required by your destination country or messaging use case.
### Connect the Wavix MCP server to ElevenLabs
The Wavix MCP server exposes Wavix messaging tools, including `sms_and_mms_messages_send`, to your ElevenLabs agent.
1. In the ElevenLabs dashboard open **Settings** and add a new **Auth Connection**:
* **Auth Type**: `Bearer token`
* **Name**: `Wavix API`
* **Authentication Token**: `YOUR_WAVIX_API_KEY`
2. In the ElevenLabs **Agent's** dashboard, open **Tool**, then open the MCP server integrations page.
3. Select **Add Custom MCP Server**.
4. Enter the following values:
* **Name**: `Wavix`
* **Description**: `Wavix MCP server`
* **Server type**: `Streamable HTTP`
* **Server URL**: `https://mcp.wavix.com/mcp`
* **Authentication**: `Wavix API`
* **Tool Approval Mode**: Leave recommended `Fine-Grained Tool Approval`.
5. Leave custom HTTP headers empty unless your security policy requires additional headers.
6. Select **I trust this server**, test the connection, and save the integration.
7. Attach the Wavix MCP server to the ElevenLabs agent that handles calls.
8. In the MCP tool approval settings, keep only the tools the agent needs. For follow-up SMS, enable `sms_and_mms_messages_send`.
Wavix MCP uses bearer authentication. Send the Wavix API key in the `Authorization` header as `Bearer YOUR_WAVIX_API_KEY`.
Create the MCP server configuration with the ElevenLabs [Create MCP server](https://elevenlabs.io/docs/eleven-agents/api-reference/mcp/create) endpoint:
```bash theme={null}
curl -X POST "https://api.elevenlabs.io/v1/convai/mcp-servers" \
-H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"url": "https://mcp.wavix.com/mcp",
"name": "Wavix MCP server",
"description": "Send Wavix SMS follow-up messages after calls.",
"transport": "STREAMABLE_HTTP",
"approval_policy": "require_approval_per_tool",
"request_headers": {
"Authorization": "Bearer YOUR_WAVIX_API_KEY"
}
}
}'
```
Then attach the MCP server to your agent with the ElevenLabs [Update agent](https://elevenlabs.io/docs/eleven-agents/api-reference/agents/update) endpoint:
```bash theme={null}
curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/YOUR_AGENT_ID" \
-H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"conversation_config": {
"agent": {
"prompt": {
"mcp_server_ids": ["YOUR_MCP_SERVER_ID"]
}
}
}
}'
```
* Replace `YOUR_ELEVENLABS_API_KEY` with your ElevenLabs API key.
* Replace `YOUR_WAVIX_API_KEY` with a restricted Wavix API key.
* Replace `YOUR_AGENT_ID` with the ID of your ElevenLabs agent.
* Replace `YOUR_MCP_SERVER_ID` with the `id` returned when you created the MCP server.
If you configure the MCP server through the API, store the Wavix API key as an ElevenLabs secret where possible instead of keeping it as a plain request header value.
### Capture the caller number
ElevenLabs provides `{{system__caller_id}}` as an automatic dynamic variable for voice calls. Use this value as the SMS recipient when the agent calls the Wavix `sms_and_mms_messages_send` tool.
Configure the agent so it sends SMS only after explicit caller consent. In the agent prompt or tool configuration, use:
* `from`: Your registered Sender ID.
* `to`: `{{system__caller_id}}`.
* `message_body.text`: The follow-up text the caller requested.
For example, the agent instruction can say:
```text theme={null}
If the caller asks for a written follow-up and confirms consent, use the Wavix SMS tool to send one message to {{system__caller_id}} from SENDER_ID. Keep the message under 160 characters when possible. Do not send sensitive personal, payment, authentication, or health information by SMS.
```
### Security requirements
* Use a Wavix API key scoped only to messaging. Don't use a full-access account key.
* Store API keys in ElevenLabs secrets or protected headers. Don't put keys in prompts, first messages, or public URLs.
* Require caller consent before sending an SMS. The agent should not send follow-ups automatically for every call.
* Keep tool approvals restrictive. Start with approval required for `sms_and_mms_messages_send`, then allow automatic execution only for that tool after testing.
* Don't send one-time passwords, payment details, health information, or other sensitive data in a follow-up SMS.
* Follow destination-country SMS rules, including Sender ID registration, opt-out language, and message content restrictions.
* Monitor Wavix message delivery reports and ElevenLabs tool execution logs during rollout.
## Transfer a call
Wavix supports cold transfers using the `SIP REFER` command. To transfer a call, you need two Wavix numbers, one for an active call and one to receive the transferred call. Make sure inbound call routing is set up on the second number.
To enable call transfers in ElevenLabs:
1. In the ElevenLabs Agents dashboard, open the **Agents** section and select your agent.
2. In the agent configuration, add the **Transfer to number** system tool.
3. Add a transfer rule:
* Select **SIP REFER** as the **Transfer type**.
* Select **Phone** in the **Number type** dropdown menu.
* Enter the destination number to transfer active calls to.
* Specify the condition for the call transfer, for example "A caller wants to speak to a human agent."
4. Select **Save**.
SIP REFER transfers don't support warm transfer messages. The call is transferred without speaking to the new recipient.
To learn more about ElevenLabs call transfers, see the [Transfer to number documentation](https://elevenlabs.io/docs/eleven-agents/customization/tools/system-tools/transfer-to-number).
## Troubleshooting
* **603 Declined** can occur if the destination's per‑minute rate is higher than your account's Max call rate (check the value on the Trunks page). Contact [**support@wavix.com**](mailto:support@wavix.com) to request a change if needed.
* **SIP trunk authentication errors**. In the Wavix portal, go to **Numbers & trunks → Trunks** and verify that the **SIP trunk ID** and **password** match exactly what you entered in ElevenLabs. Credentials are case-sensitive.
* **Wrong number format**. Dial the full international E.164 number, e.g. `19085594899` (US) or `4408001218915` (UK). Do not dial local formats like `9085594899`. Strip prefixes like `0`, `00`, or `011` before the dialed number.
* **Inbound calls not reaching the agent**. Verify that the inbound call destination for your number is set to `[did]@sip.rtc.elevenlabs.io:5060;transport=tcp`, or `[did]@sip.rtc.elevenlabs.io:5061;transport=tls` if media encryption is enabled. The port is required. Also check that an agent is assigned to the imported number in ElevenLabs.
If you face any other issues, contact [support@wavix.com](mailto:support@wavix.com) and provide the origination and destination numbers, and the date and time of the call.
# How to configure FreePBX using Wavix SIP trunks
Source: https://docs.wavix.com/sip-trunking/guides/freepbx
This guide provides a basic configuration of FreePBX to make inbound and outbound calls over the Wavix network
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Configure a SIP trunk in FreePBX
For this guide, we will use `nl.wavix.net` as the primary SIP gateway.
Choose the primary gateway with the lowest ping from your location. A full list of Wavix regional gateways is available at the bottom of the page: [https://app.wavix.com/trunks](https://app.wavix.com/trunks)
To configure outbound calls on your FreePBX server:
1. **Sign in** to your FreePBX instance.
2. In the top menu, go to **Connectivity → Trunks**.
3. Click **Add trunk** and select **Add SIP (chan\_pjsip) Trunk**.
4. Enter a **Trunk Name**, set an **Outbound CallerID**, and specify **Maximum Channels**:
* **Trunk Name** - the name of your FreePBX SIP trunk.
* **Outbound CallerID** should be an active or verified phone number from your Wavix account.
* **Maximum Channels** limit the maximum number of concurrent calls for this trunk.
5. Navigate to **pjsip Settings** and open the **General** tab:
* **Username** and **Auth username** should contain a 5-digit Wavix SIP trunk username.
* **Secret**: Your Wavix SIP trunk password.
* **SIP server**: Wavix regional SIP gateway with the lowest ping from your location.
* **Port**: Set to 5060.
6. Keep the default values for all other parameters.
7. Click **Submit**.
## Enable IP Authentication
You may wish to enable IP Authentication on Wavix SIP trunks. When IP Authentication is enabled, Wavix will accept all calls originating from a specified IP address without requiring login credentials.
You must have a dedicated IP for this option to work correctly.
### Activate IP Auth on Wavix SIP trunk
To enable IP Authentication on your Wavix SIP trunk:
1. [Create new](/sip-trunking/create-sip-trunk) or open an existing Wavix SIP trunk settings.
2. Under **Authentication Method**, select **IP Authentication**.
3. Enter a public static IP address of your FreePBX and click **Submit**.
4. Click **Save** to apply the changes.
Once submitted, the Wavix Support team will review and enable IP Authentication on the SIP trunk.
After submitting the IP authentication request, you won't be able to update your IP address or change the authentication method.
* When IP Authentication is enabled, the SIP trunk cannot be used as a destination for a DID (phone number). You must use a **SIP URI** instead.
* By default, an IP address can only be mapped to a single SIP trunk. If you need several Wavix SIP trunks sharing the same IP address, please contact [support@wavix.com](mailto:support@wavix.com).
### Activate IP Auth in FreePBX
To enable IP Authentication on your FreePBX SIP trunk:
1. [Create new](/sip-trunking/guides/freepbx#configure-a-sip-trunk-in-freepbx) or open an existing FreePBX SIP trunk settings.
2. Navigate to **pjsip Settings** and open the **General** tab:
* Set **Authentication** to **None**.
* Set **Registration** to **None**.
* Make sure **SIP server** contains a domain name of Wavix's SIP proxy with the lowest ping from your premises.
3. Click **Submit** to apply the changes.
## Configure outbound calls in FreePBX
To configure outbound calls:
1. In the top menu, go to **Connectivity → Outbound Routes**.
2. Select **Add Outbound Route**:
* Specify the **Route Name**.
* Select the Wavix trunk in the **Trunk Sequence for Matched Routes**.
3. Select **Dial Patterns** and define the rules for routing calls to the Wavix trunk. If the dialed number matches one of these patterns, no other routes are checked.
Wavix only allows phone numbers in the E.164 international format. This format can handle numbers with up to 15 digits and is usually written as \[+]\[country code]\[subscriber number including area code]. For example, a US number in E.164 format would be +16561223344. The Wavix platform will reject calls to numbers without a country code or carrying national access codes.
| Country | Number | Reason | Number in E.164 format |
| - | - | - | - |
| US | 6561223344 | No country code | +16561223344 |
| UK | 020 1122 3344 | No country code, national access code with leading 0 | +442011223344 |
| Switzerland | 0041797000777 | Leading 00 international prefix | +41797000777 |
## Configure inbound calls
### Configure inbound calls on Wavix
If you have enabled IP authentication for your SIP trunk, scroll down to the [Configure inbound call routing for trunks with IP authentication](#configure-inbound-call-routing-for-trunks-with-ip-authentication) section.
1. **Sign in** to your Wavix account.
2. In the top menu, go to **Numbers & Trunks → My numbers**.
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**.
4. Select the destination trunk in the **Destination** section.
5. Click **Add** to add the destination for the phone number.
6. Click **Save** to apply the settings.
You can also edit multiple numbers simultaneously. To do this, select the multiple numbers you want to modify, then click the **Bulk actions** button. The changes will apply to all selected numbers.
### Configure inbound call routing for trunks with IP authentication
Skip this section if your trunks are configured to use digest authentication.
SIP trunks with IP authentication enabled cannot be used for inbound call routing, as they do not maintain registration with Wavix proxies. To set up inbound routing for your numbers, you must use a valid SIP URI address instead.
To configure inbound call routing to a valid SIP URI:
1. **Log in** to your Wavix account
2. Navigate to **My numbers** under the **Numbers & trunks** in the top menu
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**
4. Select **SIP URI** in the **Transport** drop-down menu
5. **Enter a valid SIP URI** in the following format: `+[did]@FQDN:port;transport=connection`, where:
* a. **FQDN** is the fully qualified domain name or IP address of your Asterisk PBX
* b. **Port** is the SIP port used by the PBX
* c. **A connection** can be udp, tcp, or tls, with udp as the default transport
6. Click **Add** to set the destination for the phone number
7. Click **Save** to apply the settings
The `[did]` parameter will be automatically updated with the actual dialed phone number when routing the call.
### Configure inbound calls in FreePBX
To configure inbound call routing:
1. **Sign in** to your FreePBX instance.
2. In the top menu, go to **Connectivity → Inbound Routes**.
3. Select **Add Inbound Route**:
* Specify the route **Description**
* Set the **DID Number**, if needed
* In **Set Destination**, choose where to route inbound calls from the Wavix trunk. This can be an IVR, extension, agent queue, or another destination.
4. Select **Submit** to apply changes.
Leave **DID Number** blank to apply this route to any phone number on your Wavix account.
## Troubleshooting outbound calls
* 603 Declined response might be received when calling the destination with the per-minute rate higher than the Max call rate set for your account. You can find your effective Max call rate on the Trunks page. Please contact [support@wavix.com](mailto:support@wavix.com) to request a change to your Max call rate.
* The destination phone number is in an incorrect format. Please make sure the number is dialed in the international E.164 format. Strip prefixes like 0, 00, or 011 before the dialed number if needed.
# How to configure FreeSWITCH using Wavix SIP trunks
Source: https://docs.wavix.com/sip-trunking/guides/freeswitch
Step-by-step guide for connecting FreeSWITCH to Wavix SIP trunks, including authentication, dialplan setup, redundancy, and troubleshooting.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Basic SIP trunk setup on FreeSWITCH
For this guide, we use the following Wavix gateways:
* Domain name: `us.wavix.net`; IP address: `209.58.144.243` as the primary gateway.
* Domain name: `nl.wavix.net`; IP address: `95.211.82.14` as a secondary gateway.
Choose the primary and backup gateways that offer the lowest ping from your premises. The full list of Wavix regional gateways can be found at the bottom of the page: [https://app.wavix.com/trunks](https://app.wavix.com/trunks).
### Set up outbound calls
To configure outbound calls on your FreeSWITCH server:
1. Navigate to `/usr/local/FreeSwitch/conf/sip_profiles/external`
2. Create a new file `wavix.xml`
```xml theme={null}
```
* The authentication realm must match the domain name of the regional Wavix gateway you would be routing your calls over
* Enter the SIP trunk ID and password you configured for the SIP trunk on the Wavix platform in the **"username"** and **"password"** variables respectively
After you create the file, assign the FreeSWITCH user as the owner so the application can access it:
```bash theme={null}
root@FreeSwitch:/usr/local/FreeSwitch/conf/sip_profiles/external/# chown FreeSwitch:FreeSwitch wavix.xml
```
3. Navigate to `/usr/local/FreeSwitch/conf/dialplan/`
4. Create a new dialplan file `wavix_dialplan.xml`
```xml theme={null}
```
expression=- a regular expression matching dialed number. In this example, the rule will work if the dialed phone number contains 10 to 15 digits.
After you create the file, give FreeSWITCH access so it can read it.
All destination phone numbers must be in E.164 international format. E.164 numbers can have up to fifteen digits and are usually formatted as `[+][country code][subscriber number including area code]`. For example, a US number in E.164 format is `+16561223344`. Calls to numbers without a country code or with national access codes will be rejected by Wavix.
Below are typical examples of incorrectly formatted phone numbers:
| Country | Number | Reason | Number in E.164 format |
| - | - | - | - |
| US | 6561223344 | No country code | +16561223344 |
| UK | 020 1122 3344 | No country code, national access code with 0 | +442011223344 |
| Switzerland | 0041797000777 | Leading 00 international prefix | +41797000777 |
5. Navigate to `/usr/local/FreeSwitch/conf/directory/default/`
6. Modify extension configuration file `1000.xml`
```xml theme={null}
```
The value of the `user_context` variable must match the name of the gateway configuration you created in the external SIP profile directory (without the `.xml` extension).
7. Navigate to `/usr/local/FreeSwitch/conf/autoload_configs/default/`
8. Define RTP port range to 10000-20000 in `switch.conf.xml`:
```xml theme={null}
```
9. To reload the configuration files, run:
```bash theme={null}
fs_cli -x reloadxml
```
### Enable IP authentication
Wavix will accept all calls originating from a particular IP address, without requiring login info, when IP authentication is enabled. You must have a dedicated IP for this option to work correctly.
Follow these steps to enable IP authentication on the Wavix platform:
1. Select **Trunks** under **Numbers & trunks** in the top menu
2. Click the **More** icon for the desired SIP trunk and click **Edit**
3. Select **IP Authentication** under the **Authentication method**
4. Put the public IP address of your endpoint
5. Click **Submit**
6. Click **Save** to apply changes
Wavix support team will review your request and enable IP Authentication on the SIP trunk.
* When IP authentication is enabled on a SIP trunk, it cannot be used as a destination for a DID. You must use a SIP URI instead.
* After submitting the IP authentication request, you will not be able to update your IP address or change the authentication method. By default, an IP address can only be mapped to a single SIP trunk. If you need to have several Wavix SIP trunks sharing the same IP address, contact [support@wavix.com](mailto:support@wavix.com).
Once your request is approved, IP authentication will be activated on your Wavix SIP trunk, and you can configure it on FreeSWITCH:
1. Navigate to `/usr/local/FreeSwitch/conf/`
2. Update the `vars.xml` file with the lines below:
```xml theme={null}
```
3. Uncomment the lines for `ext-rtp-ip` and `ext-sip-ip` in the global configuration file `external.xml` and set them to reference the variables from `vars.xml`:
```xml theme={null}
```
4. Navigate to `/usr/local/FreeSwitch/conf/sip_profiles/external/`
5. Create a new SIP profile `wavix_ip.xml`
```xml theme={null}
```
6. Add the following line to the dialplan:
```xml theme={null}
```
```xml theme={null}
```
7. Once you've created the file, assign the FreeSWITCH user as the owner:
```bash theme={null}
root@FreeSwitch:/usr/local/FreeSwitch/conf/sip_profiles/external/# chown FreeSwitch:FreeSwitch wavix_ip.xml
```
Configuration is complete and outbound calls should work now.
### Placing outbound calls with caller ID passthrough
Typically, you use one of the DID numbers you purchased as the caller ID for the SIP trunk.
Alternatively, you can enable the caller ID passthrough option on the Wavix platform. This allows you to send your own A-numbers directly from FreeSWITCH:
1. Select **Trunks** under **Numbers & trunks** in the top menu
2. Click on the **three dots** on the right hand side and select the **Edit** option
3. Select **Passthrough** under the **Caller ID**
4. Click **Activate**
5. Click **Save** to apply changes
Wavix support team will review your request and enable Caller ID Passthrough on the SIP trunk.
### Configure custom caller ID on FreeSWITCH
Once your request is approved, the caller ID passthrough option will be activated on your Wavix SIP trunk and you can send your own caller IDs from FreeSWITCH:
1. Navigate to `/usr/local/FreeSwitch/conf/sip_profiles/external/`
2. Update the outbound SIP gateway configuration file `wavix.xml`:
```xml theme={null}
```
3. Assign the caller ID to the variable `effective_caller_id_number` in the extension configuration file:
```xml theme={null}
```
### Set up inbound calls
Registering your SIP trunk with one of the regional Wavix gateways is necessary (for digest authentication only) to receive inbound calls.
Register and send SIP traffic to regional gateways for low latency access.
| Amsterdam, NL | Dallas, USA | Singapore, SG | Australia, AU |
| - | - | - | - |
| nl.wavix.net | us.wavix.net | sg.wavix.net | au.wavix.net |
Select a regional gateway with the lowest latency to your device (in this example, `us.wavix.net`):
1. Navigate to `/usr/local/FreeSWITCH/conf/sip_profiles/external/`
2. Create or update SIP external profile `wavix.xml`:
```xml theme={null}
```
* Each regional gateway has a unique authentication `realm` that corresponds to its domain name.
* Enter the SIP trunk ID and password you configured for the SIP trunk on the Wavix platform in the `username` and `password` parameters.
You can check the status of your SIP trunk registration using the `"fs_cli -x "sofia status gateway wavix" | grep State"` command:
```bash theme={null}
root@freeswitch:~# fs_cli -x "sofia status gateway wavix" | grep State
PingState 0/0/0
State REGED
```
If registration is successful, you will see `REGED` in the "State" column. If the SIP gateway is not registered, incoming calls will not be routed to your FreeSWITCH.
To configure the destination for inbound calls on the Wavix platform:
1. Select **My numbers** under **Numbers & trunks** in the top menu
2. Click on the **three dots** on the right-hand side and select the **Edit number** option.
3. Select the destination trunk in the **Destination** section
4. Click **Add** to add the destination for the DID
5. Click **Save** to apply changes
Configuration is complete and inbound calls should work now.
## SIP trunk redundancy
Considering SIP trunk redundancy is important to ensure business continuity and protect against service interruptions. This guide provides configuration options to ensure redundancy for both incoming and outgoing calls.
### Redundancy options for inbound calls
In case of a regional gateway failure, Wavix may originate inbound calls from any other gateway. You can find the full list of gateways at [https://app.wavix.com/trunks](https://app.wavix.com/trunks). There are two options to prevent disruptions of inbound calls: set up a SIP URI destination for the DID number or enable dual SIP trunk registrations from FreeSWITCH. In this guide, we'll use a SIP URI.
To configure a SIP URI destination on the Wavix platform:
1. Select **My numbers** under **Numbers & trunks** in the top menu
2. Click the **three dots** icon for the desired DID and click Edit number
3. Select **SIP URI** under the **Destination** and enter URI in the format: DID@``
4. Click **Add**
5. Click **Save** to apply changes
6. Navigate to /usr/local/FreeSwitch/conf/dialplan/
7. Specify your DID numbers in dialplan in `` extension
```xml theme={null}
```
### Redundancy options for outbound calls
1. Navigate to `/usr/local/FreeSwitch/conf/sip_profiles/external/`
2. Create a new file `wavix_fo.xml`
```xml theme={null}
```
3. Update the dialplan for outbound calls by adding the following lines:
```xml theme={null}
```
See a dialplan example below:
```xml theme={null}
```
## Troubleshooting
### Inbound call issues
* Make sure you have granted FreeSWITCH access to the XML files you have created.
* Make sure that the context name in the dialplan, internal extension, and SIP profile extension are matching.
### Outbound calls issues
* A `603 Declined` response might be received when calling a destination with a per-minute rate higher than the max call rate set for your account. You can find your effective max call rate on the `Trunks` page. Contact `support@wavix.com` to request a change to your max call rate.
* Another possible reason for `603 Declined` responses is lack of active registration. You can check the registration status of the SIP trunk as outlined above.
* Wrong destination number format. Make sure you dial the full international number (E.164): `19085594899` (US), `4408001218915` (UK). Dialing `9085594899` won't work. Strip prefixes like `0`, `00`, or `011` in front of the dialed number.
### FreeSWITCH diagnostics
* Verify SIP trunk registration with `sofia status gateway ` in the `fs_cli` command prompt. If registration is successful, you will see `REGED` in the "State" column. If the SIP gateway is not registered, incoming calls will not be routed to your FreeSWITCH.
* To analyze SIP traffic, use the `sngrep` tool with appropriate filters.
# How to connect LiveKit AI voice agents with Wavix
Source: https://docs.wavix.com/sip-trunking/guides/livekit
This guide explains connecting LiveKit AI voice agents with Wavix voice infrastructure to place and receive calls.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
3. To follow the CLI steps, the [LiveKit CLI](https://docs.livekit.io/home/cli/cli-setup) installed and authenticated with your LiveKit Cloud project:
```shell theme={null}
lk cloud auth
```
## Receive calls with Wavix and LiveKit
### Create LiveKit inbound trunk
1. **Sign in** to your LiveKit project.
2. In the left-hand side menu, select **Telephony → Configuration**.
3. Select **Create new** and choose **Trunk**.
4. Enter a **comma‑separated list** of Wavix numbers to associate with this trunk.
Create a JSON file describing the inbound trunk:
```json inbound-trunk.json theme={null}
{
"trunk": {
"name": "Wavix inbound trunk",
"numbers": ["+61290597521"]
}
}
```
Replace the `numbers` array with your Wavix numbers in E.164 format with the leading `+` sign.
Then create the trunk with the LiveKit CLI:
```shell theme={null}
lk sip inbound create inbound-trunk.json
```
The CLI output includes the `trunk_id` of the new trunk. Copy it — you'll use it to connect a dispatch rule to this trunk in the next step.
For more information about creating a LiveKit inbound trunk using the CLI or code, see the [LiveKit documentation](https://docs.livekit.io/telephony/accepting-calls/inbound-trunk).
### Create a dispatch rule
Dispatch rules determine how inbound calls are routed to LiveKit rooms.
1. Click **Create new** and select **Dispatch rule**.
2. (Optional) Under **Match trunks**, associate the rule with a specific trunk; otherwise, it applies to all inbound calls in the project.
Create a JSON file describing the dispatch rule. The rule must be connected to an inbound trunk through the `trunk_ids` field:
```json dispatch-rule.json theme={null}
{
"dispatch_rule": {
"name": "My dispatch rule",
"trunk_ids": ["LIVEKIT_TRUNK_ID"],
"rule": {
"dispatch_rule_individual": {
"room_prefix": "call-"
}
},
"room_config": {
"agents": [
{
"agent_name": "YOUR_AGENT_NAME"
}
]
}
}
}
```
* Replace `LIVEKIT_TRUNK_ID` with the `trunk_id` returned when you created the inbound trunk.
* Replace `YOUR_AGENT_NAME` with the name of the LiveKit agent that should answer the calls.
Then create the rule with the LiveKit CLI:
```shell theme={null}
lk sip dispatch create dispatch-rule.json
```
For more information about dispatch rules and instructions for creating them using the LiveKit CLI or code, see the [LiveKit documentation](https://docs.livekit.io/telephony/accepting-calls/dispatch-rule).
### Set up inbound call routing on Wavix
Wavix can route inbound calls to a SIP trunk on the platform, SIP URI, or forward them to a phone number. LiveKit requires calls to be routed to a **SIP URI**.
1. In your LiveKit project, go to **Settings → Project**.
2. Copy the value from **SIP URI** (e.g., `sip:2mpbww13htk.sip.livekit.cloud`).
To route calls from your Wavix number to the LiveKit platform:
1. In Wavix, open **Numbers & trunks → My numbers**.
2. Select your number by clicking the **⋯** menu → **Edit number**.
3. Set the **inbound call destination type** to **SIP URI**, and enter the destination in the format of:
```bash theme={null}
[did]@[LIVEKIT_SIP_URI]
```
In the example above, it would be:
```bash theme={null}
[did]@2mpbww13htk.sip.livekit.cloud
```
4. **Save** your changes.
Make sure you entered the correct LiveKit SIP URI.
Now, all calls to your Wavix number are routed to your LiveKit AI project. Deploy a LiveKit agent to answer the calls. Check the [LiveKit recipes](https://docs.livekit.io/recipes/) for voice AI and LiveKit Agent use cases.
You can choose to encrypt call media. To enable encryption on your Wavix numbers, contact [support@wavix.com](mailto:support@wavix.com) and provide a list of numbers.
## Place calls with Wavix and LiveKit
To place outbound calls, you need both a **Wavix SIP trunk** and a **LiveKit outbound trunk**.
### Create an outbound trunk on LiveKit
1. **Sign in** to your LiveKit account.
2. Go to **Telephony** → **Configuration**.
3. Select **Create new** and replace the following variables:
* Replace `YOUR_SIP_TRUNK_ID` and `YOUR_SIP_TRUNK_PASSWORD` with the SIP trunk credentials configured at Wavix.
* Replace `61290597521` with the phone number purchased at Wavix.
Create a JSON file describing the outbound trunk:
```json outbound-trunk.json theme={null}
{
"trunk": {
"name": "Wavix outbound trunk",
"address": "us.wavix.net",
"numbers": ["+61290597521"]
}
}
```
* In the `address` field, enter one of Wavix's regional gateways. A full list is shown at the bottom of the Trunks page in the [Wavix portal](https://app.wavix.com/trunks).
* Replace the `numbers` array with your Wavix numbers in E.164 format with the leading `+` sign.
Then create the trunk with the LiveKit CLI, passing your Wavix SIP trunk credentials:
```shell theme={null}
lk sip outbound create outbound-trunk.json \
--auth-user "YOUR_SIP_TRUNK_ID" \
--auth-pass "YOUR_SIP_TRUNK_PASSWORD"
```
Replace `YOUR_SIP_TRUNK_ID` and `YOUR_SIP_TRUNK_PASSWORD` with the SIP trunk credentials configured at Wavix.
For more information about creating a LiveKit outbound trunk using the CLI or code, see the [LiveKit documentation](https://docs.livekit.io/telephony/making-calls/outbound-trunk).
You can encrypt call media on your Wavix trunk. Contact [support@wavix.com](mailto:support@wavix.com) and provide your SIP trunk ID.
You've connected LiveKit with Wavix and now can place outbound calls. Check the [LiveKit recipes](https://docs.livekit.io/recipes/) for voice AI and LiveKit Agent use cases.
## Transfer a call
Wavix supports cold transfers using the `SIP REFER` command. To transfer a call, you need two Wavix numbers, one for an active call and one to receive the transferred call. Make sure inbound call routing is set up on the second number.
To transfer an active LiveKit call, use the **TransferSIPParticipant** server API:
```ts theme={null}
import { SipClient } from 'livekit-server-sdk';
// ...
async function transferParticipant(participant) {
console.log("transfer participant initiated");
const sipTransferOptions = {
playDialtone: false
};
const sipClient = new SipClient(process.env.LIVEKIT_URL,
process.env.LIVEKIT_API_KEY,
process.env.LIVEKIT_API_SECRET);
const transferTo = "sip:+@"; // e.g., sip:+61290597520@au.wavix.net
await sipClient.transferSipParticipant('open-room', participant.identity,
transferTo, sipTransferOptions);
console.log('transfer participant');
}
```
Replace transfer\_destination with your Wavix number. Use the following format: `sip:+[YOUR_WAVIX_NUMBER]@[WAVIX_SIP_GATEWAY]`. Example: `sip:+61290597520@au.wavix.net`
Choose the primary Wavix gateway with the lowest ping from your location. A list of regional gateways is shown at the bottom of the Trunks page in the [Wavix portal](https://app.wavix.com/trunks).
Learn more about LiveKit call transfer in the [LiveKit documentation](https://docs.livekit.io/sip/transfer-cold/).
## Troubleshooting
* **603 Declined** can occur if the destination's per‑minute rate is higher than your account's Max call rate (check the value on the Trunks page). Contact [**support@wavix.com**](mailto:support@wavix.com) to request a change if needed.
* **603 Declined** can also occur if there is no active registration on your SIP trunk. Verify registration status as described above.
* **Wrong number format**. Dial the full international E.164 number, e.g. `19085594899` (US) or `4408001218915` (UK). Do not dial local formats like `9085594899`. Strip prefixes like `0`, `00`, or `011` before the dialed number.
# How to connect Wavix to the OpenAI Realtime API
Source: https://docs.wavix.com/sip-trunking/guides/openai
Route inbound calls from your Wavix phone number to the OpenAI Realtime API, using a SIP trunk and a webhook to hand each call to your voice agent.
## Prerequisites
Before you begin, ensure you have an active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
## Receive calls with Wavix and OpenAI Realtime API
### Create OpenAI webhook
1. **Sign in** to your OpenAI account at [https://platform.openai.com](https://platform.openai.com).
2. Go to your [Organization settings](https://platform.openai.com/settings).
3. In the left menu, select **Webhooks**, then choose **Create**.
4. Enter the URL where OpenAI should send events, select `realtime.call.incoming` from the **Event types** dropdown, and optionally add a name.
OpenAI automatically generates a **signing secret**. Save this secret in a secure location, because you will not be able to view it again. OpenAI uses the signing secret to sign webhook requests. You can use it to verify that each request is from OpenAI and not from a third party.
### Set up inbound call routing in Wavix
Wavix can route inbound calls to a SIP trunk on the platform, SIP URI, or forward them to a phone number. OpenAI requires calls to be routed to a **SIP URI**.
Before setting up a Wavix number:
1. In your OpenAI account, go to **General** → **Project**.
2. Copy the value from **Project ID**. You'll need it to configure inbound call routing in Wavix.
To route calls from your Wavix number to the OpenAI platform:
1. In Wavix, open **Numbers & trunks → My numbers**.
2. Select your number by clicking the **⋯** menu → **Edit number**.
3. Set the **inbound call destination type** to **SIP URI**, and enter the destination in the format of:
```bash theme={null}
[OpenAI_PROJECT_ID]@sip.api.openai.com;transport=tls
```
In the example above, it would be:
```bash theme={null}
proj_XnGzQBp38qGPqjV5GaYVXVGY@sip.api.openai.com;transport=tls
```
4. **Save** your changes.
Now, all calls to your Wavix number are routed to your OpenAI project.
## Managing calls using OpenAI Realtime API
You can answer, decline, monitor, refer, and hang up calls using the OpenAI API.
To learn more, see the [OpenAI Realtime SIP API documentation](https://platform.openai.com/docs/guides/realtime-sip).
### Answer a call
When OpenAI receives SIP traffic linked to your project, it triggers your webhook. The event type is `realtime.call.incoming`, as shown in the example below:
```http theme={null}
POST https://your-app.com/call/inbound
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_68df8a55937881909c0db29329f4df96 # unique id for idempotency
webhook-timestamp: 1759480406 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI
{
"object": "event",
"id": "evt_68df8a5585808190968c8d1243ab3f9f",
"type": "realtime.call.incoming",
"created_at": 1759480405,
"data": {
"call_id": "rtc_5bfabb18c4574e30a75f4bfaad13f878",
"sip_headers": [
{"name": "From", "value": "\"+14067704205\" ;tag=as6442942c"},
{ "name": "To", "value": "sip:proj_XnGzQBp38qGPqjV5GaYVXVGY@sip.api.openai.com;transport=tls" },
{ "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"},
{"name": "x-number", "value": "17134810111"}
]
}
}
```
The `call_id` parameter is a unique identifier of the call in the OpenAI platform. Use it when answering the call.
To answer the call, use the OpenAI [Accept call](https://platform.openai.com/docs/api-reference/realtime-calls/accept-call) endpoint.
When answering the call, you should provide the required configuration, including instructions, voice, and other settings, for the Realtime API session.
```bash theme={null}
curl -X POST "https://api.openai.com/v1/realtime/calls/$call_id/accept" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "realtime",
"model": "gpt-realtime",
"instructions": "You are Alex, a friendly support agent for Wavix."
}'
```
* `$call_id`: unique identifier of the call in OpenAI.
* `$OPENAI_API_KEY`: your OpenAI API Key.
The SIP INVITE request from Wavix includes the `x-number` header, which contains the dialed number from your Wavix account. You can use this value to provide different instructions based on the number that was called.
### Decline the call
To decline the call, use the OpenAI [Reject call](https://platform.openai.com/docs/api-reference/realtime-calls/reject-call) endpoint. You can optionally include a SIP response code to return to the caller.
### Transfer the call
Wavix supports cold transfers using the `SIP REFER` command. To transfer a call, you need two Wavix numbers, one for an active call and one to receive the transferred call. Make sure inbound call routing is set up on the second number.
To transfer an active call, use the OpenAI [Refer call](https://platform.openai.com/docs/api-reference/realtime-calls/refer-call) endpoint. In the request, the `target_uri` parameter should contain the Wavix number.
### Hang up the call
To hang up the call, use the OpenAI [Hang up call](https://platform.openai.com/docs/api-reference/realtime-calls/hangup-call) endpoint. In the request, the `call_id` parameter should contain the OpenAI unique call identifier.
### Monitor call events
After you answer a call, open a WebSocket connection to the session to stream events and send realtime commands.
```http theme={null}
GET wss://api.openai.com/v1/realtime?call_id={call_id}
```
* `call_id` - unique identifier of the call in OpenAI.
See OpenAI [Webhooks and server-side controls](https://platform.openai.com/docs/guides/realtime-server-controls) for more information.
## Troubleshooting
* If inbound calls aren't reaching your OpenAI project, make sure [Inbound call routing](/sip-trunking/guides/openai#set-up-inbound-call-routing-in-wavix) is set up correctly in Wavix.
* Make sure all phone numbers are in international E.164 format, e.g. `19085594899` (US) or `4408001218915` (UK). Do not dial local formats like `9085594899`. Strip prefixes like `0`, `00`, or `011` if needed.
# How to connect Retell AI voice agents with Wavix
Source: https://docs.wavix.com/sip-trunking/guides/retellai
This guide explains how to connect Retell AI agents with Wavix voice infrastructure, import phone numbers, and make and receive calls.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number in your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A Wavix [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
3. An active [Retell AI account](https://www.retellai.com/).
## How it works
### Inbound calls
1. A customer calls your Wavix phone number.
2. Wavix routes the call via SIP to your Retell AI voice agent.
3. Retell AI voice agent processes the audio and generates responses.
4. Responses are streamed back into the call through Wavix.
```mermaid actions={false} theme={null}
sequenceDiagram
participant Caller as Caller
participant Wavix as Wavix platform
participant Retell as Retell AI
Caller->>Wavix: Telephony network
Wavix->>Retell: SIP and SRTP
Retell->>Retell: Voice AI orchestration (LLM, TTS, conversation logic)
Retell->>Wavix: SIP and SRTP
Wavix->>Caller: Telephony network
```
### Outbound calls
1. Your application or Retell AI dashboard triggers a call.
2. Retell AI connects to Wavix via SIP.
3. Wavix connects the call to your customer via the telephony network.
4. The customer answers the call.
5. Retell AI voice agent processes the audio and generates responses.
6. Responses are streamed back into the call.
```mermaid actions={false} theme={null}
sequenceDiagram
participant App as Your app / Retell AI dashboard
participant Retell as Retell AI
participant Wavix as Wavix platform
participant Callee as Callee
App->>Retell: Triggers a call
Retell->>Wavix: SIP and SRTP
Wavix->>Callee: Telephony network
Callee->>Wavix: Telephony network
Retell->>Retell: Voice AI orchestration (LLM, TTS, conversation logic)
Wavix->>Retell: SIP and SRTP
```
## Receive calls with Wavix and Retell AI
### Import a number into Retell AI
1. **Sign in** to your Retell AI account.
2. In the left-hand menu, select **Phone Numbers**.
3. Select the **+** button and choose **Connect to your number via SIP trunking**.
4. Enter the imported Wavix number details:
* **Phone Number**: A Wavix phone number in your account.
* **Termination URI**: Use `us.wavix.net` to ensure the lowest audio latency.
* **SIP Trunk User Name**: Enter the **SIP trunk ID** from your Wavix account.
* **SIP Trunk Password**: Your Wavix SIP trunk password.
* **Outbound Transport**: Use **TCP**.
5. Select **Save**.
Import a number with the Retell AI [Import phone number](https://docs.retellai.com/api-references/import-phone-number) endpoint. Run the POST request below using your favorite tool, such as Postman or terminal.
```bash theme={null}
curl -X POST "https://api.retellai.com/import-phone-number" \
-H "Authorization: Bearer YOUR_RETELLAI_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+YOUR_WAVIX_NUMBER",
"termination_uri": "us.wavix.net",
"sip_trunk_auth_username": "YOUR_SIP_TRUNK_ID",
"sip_trunk_auth_password": "YOUR_SIP_TRUNK_PASSWORD",
"transport": "TCP",
"nickname": "Wavix number"
}'
```
* Replace `YOUR_WAVIX_NUMBER` with a number on your Wavix account in E.164 format with the leading `+` sign, i.e., `+61290597521`.
* Replace `YOUR_SIP_TRUNK_ID` and `YOUR_SIP_TRUNK_PASSWORD` with the SIP trunk credentials configured in the Wavix portal.
* Replace `YOUR_RETELLAI_KEY` with your Retell AI API key.
### Create a Retell AI voice agent
1. In your Retell AI dashboard, open the left-hand menu and select **Agents**.
2. In the top-right corner, select **Create an Agent** and choose **Voice Agent**.
3. Select an **Agent Type** and use one of Retell AI's templates or build a new agent from scratch.
4. Once finished, publish your agent:
* Give your agent a descriptive name.
* (Optionally) Provide information about what your agent does.
* Associate it with an imported phone number.
5. Select **Publish**.
You can assign an agent to a number when configuring the number itself.
### Configure your Wavix number
To route inbound calls to your Retell AI agent:
1. In the Wavix portal, open **Numbers & trunks → My numbers**.
2. Select your number by clicking the **⋯** menu → **Edit number**.
3. Set the **inbound call destination type** to **SIP URI**, and enter the destination:
```bash theme={null}
[did]@sip.retellai.com;transport=tcp
```
4. Select **Save** to apply changes. Wavix will automatically replace `[did]` with your actual number.
Now, all calls to your Wavix number are routed to your Retell AI voice assistant.
### Verify the configuration
Place a test call to the Wavix number. You'll be connected to your agent shortly.
## Place calls with Wavix and Retell AI
Before placing an outbound call, make sure:
* An **Outbound Call Agent** is assigned to the number.
* The country you plan to call is listed in **Allowed Outbound Countries** or all countries are allowed.
To place an outbound call with Retell AI, you can use:
* Dashboard
* API
* Batch Call tool
### Place a call using the dashboard
In the Retell AI dashboard:
1. In the left-hand menu, select **Phone Numbers**.
2. Choose the imported Wavix number.
3. In the top-right corner, select **Make an outbound call**:
* **Phone Number**: Enter the number you want to call.
* **Dynamic Variables**: Provide dynamic variables to prepopulate in your assistant.
4. Select **Call**.
### Place a call using API
To make a call using the API, you'll need a Retell AI API key:
1. Navigate to **Settings** and select **API Keys**.
2. Copy your API key.
You may need to create a new API Key first.
3. Run the POST request below using your favorite tool, such as Postman or terminal.
```bash theme={null}
curl -L 'https://api.retellai.com/v2/create-phone-call' \
-H 'Authorization: Bearer YOUR_RETELLAI_KEY' \
-H 'Content-Type: application/json' \
-d '{
"from_number": "+YOUR_WAVIX_NUMBER",
"to_number": "+DESTINATION_NUMBER",
"ignore_e164_validation": false
}'
```
* `from_number`: Originating number, the Wavix number imported to Retell AI.
* `to_number`: Destination number you want to call.
Retell AI lets you override the default agent bound to the originating number and pass optional dynamic variables to the Response Engine.
Check the Retell AI [API documentation](https://docs.retellai.com/api-references/create-phone-call) for more details.
If successful, the Retell AI places a call to the destination number.
### Batch Call tool
Batch calls let you create, schedule, and monitor calls in bulk.
To place calls using Retell AI Batch Call:
1. In the Retell AI dashboard, navigate to **Batch call** and select **Create a batch call**.
2. Give your campaign a name and select an imported Wavix number.
3. Upload a list of contacts.
4. (Optionally) Schedule your campaign.
5. Select **Send** to launch the campaign.
Make sure your Retell AI allowed CPS (calls per second) does not exceed your Wavix account limit:
* Find your Retell AI CPS (calls per second) in the [account settings](https://dashboard.retellai.com/settings/limits)
* Wavix allows 3 CPS by default. To increase this limit, contact [support@wavix.com](mailto:support@wavix.com)
## Send a call follow-up SMS
You can let a Retell AI voice agent send an SMS after a call when the caller asks for a written follow-up. For example, after a scheduling call, the agent can send an appointment confirmation, reference number, or support link to the same phone number that joined the call.
Before you enable SMS follow-ups:
* Register the SMS Sender ID you want to use. For setup instructions, see [Sender ID registration](/messaging/send-sms#sender-id-registration).
* Create a dedicated Wavix API key with only the scopes required to send SMS.
* Confirm that the caller has agreed to receive the follow-up SMS.
* Keep the SMS content short and include opt-out text when required by your destination country or messaging use case.
### Connect the Wavix MCP server to Retell AI
The Wavix MCP server exposes Wavix messaging tools, including `sms_and_mms_messages_send`, to your Retell AI agent. Retell AI supports MCP through an MCP node in a conversation flow.
1. In the Retell AI dashboard, open the conversation flow used by your voice agent.
2. Add an **MCP** node to the point in the flow where the agent should send the follow-up SMS.
3. Add an MCP server with the Wavix MCP server URL:
```bash theme={null}
https://mcp.wavix.com/mcp
```
4. Add a custom request header for Wavix MCP authentication:
* **Header name**: `Authorization`
* **Header value**: `Bearer YOUR_WAVIX_API_KEY`
5. Select the `sms_and_mms_messages_send` MCP tool.
6. Configure the tool input:
* `from`: Your registered Sender ID.
* `to`: `{{follow_up_number}}`.
* `message_body.text`: The follow-up text the caller requested.
7. Save the MCP node and publish the updated agent version.
Retell AI documents MCP setup through conversation flow MCP nodes. After you add the Wavix MCP server to your flow, you can verify the available tools with the Retell AI [Get MCP Tools](https://docs.retellai.com/api-references/get-mcp-tools) endpoint:
```bash theme={null}
curl -X GET "https://api.retellai.com/get-mcp-tools/YOUR_AGENT_ID?mcp_id=YOUR_WAVIX_MCP_ID" \
-H "Authorization: Bearer YOUR_RETELLAI_KEY"
```
* Replace `YOUR_AGENT_ID` with your Retell AI agent ID.
* Replace `YOUR_WAVIX_MCP_ID` with the MCP server ID from the conversation flow.
* Replace `YOUR_RETELLAI_KEY` with your Retell AI API key.
The response should include `sms_and_mms_messages_send`. Use the dashboard flow editor to map the tool inputs and publish the agent version.
### Capture the caller number
Retell AI stores the customer phone number differently depending on call direction:
* For inbound calls, the caller number is `from_number`.
* For outbound calls, the customer number is `to_number`.
Use a single dynamic variable, such as `follow_up_number`, for the SMS recipient:
* For inbound calls, set `follow_up_number` to the inbound `from_number`.
* For outbound calls, set `follow_up_number` to the outbound `to_number`.
You can set dynamic variables from an inbound call webhook, an outbound call request, or earlier nodes in the conversation flow. Then use `{{follow_up_number}}` as the `to` value in the Wavix MCP tool.
For example, update the agent prompt or flow instructions:
```text theme={null}
If the caller asks for a written follow-up and confirms consent, use the Wavix SMS tool to send one message to {{follow_up_number}} from SENDER_ID. Keep the message under 160 characters when possible. Do not send sensitive personal, payment, authentication, or health information by SMS.
```
### Security requirements
* Use a Wavix API key scoped only to messaging. Don't use a full-access account key.
* Store API keys only in Retell AI MCP server headers or another protected secret store. Don't put keys in prompts, dynamic variables, or public URLs.
* Require caller consent before sending an SMS. The agent should not send follow-ups automatically for every call.
* Use API key scopes to limit the Wavix MCP tools available to the agent.
* Don't send one-time passwords, payment details, health information, or other sensitive data in a follow-up SMS.
* Follow destination-country SMS rules, including Sender ID registration, opt-out language, and message content restrictions.
* Review Retell AI data storage settings if you redact Caller IDs or dynamic variables. If `phone_number` is redacted, Retell AI removes the customer number from the call record.
* Monitor Wavix message delivery reports and Retell AI function or MCP node logs during rollout.
## Call transfer
Wavix supports cold transfers using the `SIP REFER` command.
To transfer a call, you need two Wavix numbers, one for an active call and one to receive the transferred call. Make sure inbound call routing is set up on the second number.
To enable call transfers with Retell AI:
1. In your Retell AI dashboard, select the agent you want to enable this functionality for.
2. Under **Functions**, click **Add** and choose **Call Transfer**.
3. Set the **Transfer to** to **Static Destination** and enter a SIP URI to transfer the call to in the following format: `sip:[YOUR_WAVIX_NUMBER]@us.wavix.net`. Example: `sip:14062260605@us.wavix.net`.
4. Make sure to select **Keep raw input**.
5. Select **Cold Transfer** under **How should the AI handle the transfer?**.
6. Select **SIP REFER** as the **SIP Transfer Method**.
7. Select **Save**.
If you need to use **Dynamic Routing** for call transfer, make sure the transfer destination(s) are provided in the `sip:[YOUR_WAVIX_NUMBER]@us.wavix.net` format .
Update the agent's prompt to include the transfer call conditions.
## Troubleshooting
If your call doesn't go through, check the following:
**Outbound calls fail to connect**
1. Validate that the destination number is in E.164 format (e.g., `+14155552671`).
2. Confirm the destination country is listed under **Allowed Outbound Countries** in Retell AI's phone number settings.
3. Verify your Wavix account has sufficient balance for the outbound call.
4. Check that your Wavix CPS (calls per second) limit is not exceeded. By default, Wavix allows 3 CPS. Contact [support@wavix.com](mailto:support@wavix.com) to increase this limit.
**Inbound calls not reaching the Retell AI agent**
1. In the Wavix portal, verify that the inbound call destination for your number is correctly set to `[did]@sip.retellai.com;transport=tcp`.
2. Confirm that an **Inbound Call Agent** is assigned to the number in Retell AI's phone number settings.
3. Check that your Retell AI agent is in **Published** status, not in draft mode.
**SIP trunk authentication errors**
1. In the Wavix portal, navigate to **Numbers & trunks → Trunks** and verify the SIP trunk credentials.
2. Confirm the **SIP trunk ID** and **password** match exactly what you entered in Retell AI's phone number configuration. Credentials are case-sensitive.
**Agent not responding to calls**
1. In your Retell AI dashboard, verify the agent is assigned to the imported phone number.
2. Check that your agent's **LLM** (language model) is properly configured and has the correct prompt.
3. Test your agent directly from the Retell AI dashboard to ensure it responds correctly.
4. Review Retell AI logs for any errors related to the agent's LLM or TTS service.
**Unable to import a Wavix number into Retell AI**
1. Verify the **SIP Trunk User Name** is your actual **SIP trunk ID** (not your Wavix account ID).
2. Double-check the **SIP Trunk Password** has no extra spaces or special characters that might have been mistyped.
For additional support, email [support@wavix.com](mailto:support@wavix.com).
# SIP Trunking setup guides
Source: https://docs.wavix.com/sip-trunking/guides/setup-guides
Connect 3CX, Asterisk, FreePBX, FreeSWITCH, Zoiper, or any other IP-PBX to Wavix SIP trunks, with generic settings for platforms not listed here.
These guides provide step-by-step instructions to connect your IP-PBX or communications platform to Wavix.
## Select your platform
Connect your traditional or cloud-hosted PBX system to Wavix SIP trunks.
| Platform | Description |
| :- | :- |
| [3CX](/sip-trunking/guides/3cx) | Configure Wavix SIP trunks for 3CX Phone System. |
| [Asterisk](/sip-trunking/guides/asterisk) | Set up Asterisk PBX with Wavix using chan\_pjsip or chan\_sip. |
| [FreePBX](/sip-trunking/guides/freepbx) | A graphical interface guide for configuring FreePBX with Wavix. |
| [FreeSWITCH](/sip-trunking/guides/freeswitch) | Connect FreeSWITCH or FusionPBX to the Wavix network. |
| [Zoiper](/sip-trunking/guides/zoiper) | Configure Zoiper softphone for Wavix SIP trunking. |
## Generic configuration
If your platform is not listed above, you can usually connect it using these generic settings. Before you begin, ensure you have created a SIP trunk in the [Customer portal](https://app.wavix.com) to obtain your credentials.
| Setting | Value |
| :- | :- |
| **Registrar / Proxy** | `[region].wavix.net` (e.g., `us.wavix.net`) |
| **Outbound Proxy** | `[region].wavix.net` (e.g., `us.wavix.net`) |
| **Port** | `5060` |
| **Transport** | `UDP` (recommended) or `TCP` |
| **Authentication** | Digest (Username & Password) |
| **Supported codecs** | `G.711u` (PCMU), `G.722` |
For a complete list of regional gateways (US, EU, AU, SG), see [Wavix IP addresses](/sip-trunking/ip-allowlisting).
# How to connect Vapi voice AI agents with Wavix
Source: https://docs.wavix.com/sip-trunking/guides/vapi
This guide explains how to connect Vapi AI agents with Wavix voice infrastructure to place and receive calls.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Receive calls with Wavix and Vapi
### Create SIP trunk credentials in Vapi
1. **Sign in** to your Vapi account.
2. Go to **API Keys**.
3. Copy your **Private Key**.
4. Run the POST request below using your favorite tool, such as Postman or terminal.
```bash theme={null}
curl -L 'https://api.vapi.ai/credential' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_VAPI_PRIVATE_KEY' \
-d '{
"provider": "byo-sip-trunk",
"name": "Wavix",
"gateways": [
{
"ip": "95.211.82.14"
},
{
"ip": "209.58.144.243"
},
{
"ip": "173.234.106.26"
},
{
"ip": "23.108.101.90"
}
],
"outboundLeadingPlusEnabled": true,
"outboundAuthenticationPlan": {
"authUsername": "YOUR_SIP_TRUNK_ID",
"authPassword": "YOUR_SIP_TRUNK_PASSWORD"
}
}'
```
* Replace `YOUR_SIP_TRUNK_ID` and `YOUR_SIP_TRUNK_PASSWORD` with the SIP trunk credentials configured in the Wavix portal.
* Replace `YOUR_VAPI_PRIVATE_KEY` with your Vapi Private Key.
Make sure you list all Wavix regional gateway IP addresses in the 'gateways' array. Failing to do so may result in your calls being rejected with 401 Unauthorized error. A full list of regional gateways is shown at the bottom of the Trunks page in the [Wavix portal](https://app.wavix.com/trunks).
If successful, the response will contain the SIP trunk credentials `id`. Copy it for later use.
```bash highlight={2} theme={null}
{
"id": "00000000-c5c6-4f68-bb6d-000000000000",
"orgId": "00000000-b275-4b33-9dd2-000000000000",
"provider": "byo-sip-trunk",
"createdAt": "2025-10-13T10:56:17.439Z",
"updatedAt": "2025-10-13T10:56:17.439Z",
"gateways": [
],
"name": "Wavix",
"outboundLeadingPlusEnabled": true
}
```
Learn more about Vapi SIP trunks in the [Vapi SIP trunk documentation](https://docs.vapi.ai/advanced/sip/sip-trunk).
### Associate a phone number with the SIP trunk
To link your Wavix phone number to the SIP trunk credential in Vapi, you need to create a Phone Number resource. Run the POST request below using your favorite tool, such as Postman or terminal.
```bash theme={null}
curl -X POST "https://api.vapi.ai/phone-number" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "Wavix Number",
"number": "YOUR_WAVIX_PHONE_NUMBER",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_VAPI_CREDENTIAL_ID"
}'
```
* Replace `YOUR_WAVIX_PHONE_NUMBER` with a number on your Wavix account and `YOUR_VAPI_CREDENTIAL_ID` with your Vapi SIP trunk credentials created earlier.
* Replace `YOUR_VAPI_PRIVATE_KEY` with your Vapi Private Key.
Make sure `YOUR_WAVIX_PHONE_NUMBER` contains the leading '+' sign, i.e., `+61290597521`.
If successful, the phone number will appear in your Vapi account.
To assign an AI assistant to the phone number:
1. **Sign in** to your Vapi account.
2. Go to **Phone Numbers**.
3. Scroll down to **Inbound Settings** and associate an assistant with the number.
### Setup inbound call routing on Wavix
Wavix can route inbound calls to a SIP trunk on the platform, SIP URI, or forward them to a phone number. Vapi requires calls to be routed to a SIP URI.
To route calls to your Wavix number to the Vapi SIP URI:
1. In Wavix, open **Numbers & trunks → My numbers**.
2. Select your number by clicking the **⋯** menu → **Edit number**.
3. Set the **inbound call destination type** to **SIP URI**, and enter the destination in the format of:
```bash theme={null}
[did]@YOUR_VAPI_CREDENTIAL_ID.sip.vapi.ai
```
In the example above, it would be:
```bash theme={null}
[did]@00000000-c5c6-4f68-bb6d-000000000000.sip.vapi.ai
```
4. **Save** your changes.
Now, all calls to your Wavix number are routed to your Vapi AI assistant.
## Place calls with Wavix and Vapi
To place an outbound call, you'll need a Vapi **Assistant ID** and Vapi **Phone Number ID**.
1. In Vapi, open **Assistants**.
2. Select an assistant you want to use and copy the assistant ID.
1. In Vapi, open **Phone Numbers**.
2. Select a number you want to use as Caller ID and copy the number ID.
You can place outbound calls with Vapi using the API. Run the POST request below using your favorite tool, such as Postman or terminal.
```bash theme={null}
curl -L 'https://api.vapi.ai/call/phone' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_VAPI_PRIVATE_KEY' \
-d '{
"assistantId": "YOUR_VAPI_ASSISTANT_ID",
"customer": {
"number": "DESTINATION_NUMBER",
"numberE164CheckEnabled": true
},
"phoneNumberId": "YOUR_VAPI_NUMBER_ID"
}
'
```
* Replace `YOUR_VAPI_ASSISTANT_ID` with your **Vapi Assistant ID** and `YOUR_VAPI_NUMBER_ID` with your Vapi **Phone Number ID**.
* Replace `YOUR_VAPI_PRIVATE_KEY` with your Vapi **Private Key**.
* Replace the `DESTINATION_NUMBER` with a phone number you want to call. Make sure the phone number is provided in the international E.164 format with or without the leading `+` sign.
If successful, the Vapi places a call to the destination number.
Learn more about Vapi outbound calls in the [Vapi outbound calling documentation](https://docs.vapi.ai/calls/outbound-calling).
## Send a call follow-up SMS
You can let a Vapi assistant send an SMS after or during a call when the caller asks for a written follow-up. For example, after an appointment scheduling call, the assistant can send the appointment time, location, or support reference number to the same phone number that joined the call.
Before you enable SMS follow-ups:
* Register the SMS Sender ID you want to use. For setup instructions, see [Sender ID registration](/messaging/send-sms#sender-id-registration).
* Create a dedicated Wavix API key with only the scopes required to send SMS.
* Confirm that the caller has agreed to receive the follow-up SMS.
* Keep the SMS content short and include opt-out text when required by your destination country or messaging use case.
### Connect the Wavix MCP server to Vapi
The Wavix MCP server exposes Wavix messaging tools, including `sms_and_mms_messages_send`, to your Vapi assistant.
1. In your Vapi account, select **Tools**.
2. Select **+ Create Tool** and choose **MCP**.
3. Enter the tool name and description:
* **Name**: `Wavix`
* **Description**: `Wavix MCP server`
4. In the MCP server configuration, enter the server URL:
```bash theme={null}
https://mcp.wavix.com/mcp
```
5. Add new **Custom credentials**:
* Choose **Server Configuration** under Integrations.
* **Authentication Type**: `Bearer Token`
* **Credential Name**: `Wavix API`
* **Token**: `YOUR_WAVIX_API_KEY`
* **Header Name**: `Authorization`
* **Include Bearer Prefix**: Set to `Yes`
* Select **Save**
6. Use the default Streamable HTTP protocol.
7. Save the tool.
8. Open **Assistants**, select the assistant that handles calls, and add the Wavix MCP tool to the assistant.
9. Publish the assistant.
Vapi supports MCP tools in the assistant model configuration. Add the Wavix MCP server as a tool and pass the Wavix API key in the `Authorization` header:
```bash theme={null}
curl -X PATCH "https://api.vapi.ai/assistant/YOUR_VAPI_ASSISTANT_ID" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a voice assistant. If the caller asks for a written follow-up and confirms consent, use the Wavix SMS tool to send one message to {{customer.number}} from SENDER_ID. Keep the message under 160 characters when possible. Do not send sensitive personal, payment, authentication, or health information by SMS."
}
],
"tools": [
{
"type": "mcp",
"function": {
"name": "wavixMcp"
},
"server": {
"url": "https://mcp.wavix.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_WAVIX_API_KEY"
}
},
"metadata": {
"protocol": "shttp"
}
}
]
}
}'
```
* Replace `YOUR_VAPI_ASSISTANT_ID` with your Vapi assistant ID.
* Replace `YOUR_VAPI_PRIVATE_KEY` with your Vapi Private Key.
* Replace `YOUR_WAVIX_API_KEY` with a restricted Wavix API key.
* Replace `SENDER_ID` with a registered Sender ID on your Wavix account.
If your assistant already has a model configuration or other tools, merge the Wavix MCP tool into the existing `model.tools` array instead of replacing the full model configuration.
### Capture the caller number
Vapi provides `{{customer.number}}` as a default dynamic variable. For inbound calls, it contains the caller ID. For outbound calls, it contains the destination number.
Use `{{customer.number}}` as the SMS recipient when the assistant calls the Wavix `sms_and_mms_messages_send` tool:
* `from`: Your registered Sender ID.
* `to`: `{{customer.number}}`.
* `message_body.text`: The follow-up text the caller requested.
### Security requirements
* Use a Wavix API key scoped only to messaging. Don't use a full-access account key.
* Store API keys only in Vapi tool headers or another protected secret store. Don't put keys in assistant prompts, first messages, or public URLs.
* Require caller consent before sending an SMS. The assistant should not send follow-ups automatically for every call.
* Use API key scopes to limit the Wavix MCP tools available to the assistant.
* Don't send payment details, health information, or other sensitive data in a follow-up SMS.
* Follow destination-country SMS rules, including Sender ID registration, opt-out language, and message content restrictions.
* Monitor Wavix message delivery reports and Vapi tool-call logs during rollout.
## Transfer calls between Vapi and Wavix
Wavix supports cold transfers using the `SIP REFER` command. To transfer a call, you need two Wavix numbers, one for an active call and one to receive the transferred call. Make sure inbound call routing is set up on the second number.
To enable call transfers with Vapi, you'll need:
1. Create and configure a **Transfer Call** tool.
2. Associate the tool with your Vapi assistant.
### Configure Transfer Call
To configure the Transfer Call tool:
1. In your Vapi account, select **Tools**.
2. Select **+ Create Tool**, choose **Transfer Call**, and enter a name for the tool.
3. Under **Destinations**, select **+ Add Destination**, then choose **SIP**.
4. In the SIP URI field, enter the address in this format:`[YOUR_WAVIX_NUMBER]@[WAVIX_SIP_GATEWAY]`. Example: `sip:14067704205@us.wavix.net`.
5. In the **Message to Customer** field, enter the message to speak to the customer before the transfer.
6. Provide additional details to help the AI decide when to use this destination.
7. In **Transfer Mode**, make sure **Blind Transfer** is selected.
8. Select **Save**.
Replace `YOUR_WAVIX_NUMBER` with your Wavix number and `WAVIX_SIP_GATEWAY` with one of Wavix's SIP gateways.
Choose the primary Wavix gateway with the lowest ping from your location. A full list of regional gateways is shown at the bottom of the Trunks page in the [Wavix Customer portal](https://app.wavix.com/trunks).
Learn more about Vapi call transfer in the [Vapi call forwarding documentation](https://docs.vapi.ai/call-forwarding).
## Troubleshooting
* **603 Declined** can occur if the destination's per‑minute rate is higher than your account's Max call rate (check the value on the Trunks page). Contact [**support@wavix.com**](mailto:support@wavix.com) to request a change if needed.
* **Wrong number format**. Dial the full international E.164 number, e.g. `19085594899` (US) or `4408001218915` (UK). Do not dial local formats like `9085594899`. Strip prefixes like `0`, `00`, or `011` before the dialed number.
# How to configure Zoiper using Wavix SIP trunks
Source: https://docs.wavix.com/sip-trunking/guides/zoiper
Connect the Zoiper softphone to a Wavix SIP trunk. Install Zoiper, enter your SIP credentials, and place and receive your first call in minutes.
## Prerequisites
Before you begin, ensure you have:
1. An active phone number on your Wavix account. If you need to purchase one, see our guide on [how to buy a phone number](/numbers/buy-number).
2. A [SIP trunk](https://wavix.com/sip-trunk) ([How to create a SIP trunk](/sip-trunking/create-sip-trunk)).
## Configure Zoiper
Go to [zoiper.com](https://zoiper.com), download, and install the latest version.
Enter your Wavix SIP trunk ID and password. Select **Login**.
Enter the address of one of Wavix’s regional SIP proxies. Select **Next**.
Choose the gateway with the lowest ping from your location. See [Wavix IP addresses](/sip-trunking/ip-allowlisting) for the full list of regional gateways.
Wavix doesn't require an authentication username. Select **Skip**.
Wait while Zoiper validates your configuration and tests the connection to Wavix. Select **Next**.
Close the Account settings, open a dialpad, and place a test call.
All destination phone numbers must be in the E.164 international format. This format can handle numbers with up to 15 digits and is usually written as `[+][country code][subscriber number including area code]`. For example, a US number in E.164 format would be `+16561223344`. Wavix will reject calls to numbers without a country code or carrying national access codes.
| Country | Number | Reason | Number in E.164 format |
| :- | :- | :- | :- |
| US | `6561223344` | No country code | `+16561223344` |
| UK | `020 1122 3344` | No country code, national access code with leading 0 | `+442011223344` |
| Switzerland | `0041797000777` | Leading 00 international prefix | `+41797000777` |
## Configure inbound calls
For calls to be routed to your Zoiper instance, follow these steps in your Wavix account:
1. **Sign in** to your Wavix account
2. Navigate to **My numbers** under **Numbers & trunks** in the top menu
3. Click on the three dots next to the number you want to edit (right-hand side) and select **Edit number**
4. Select the destination trunk in the **Destination** section
5. Click **Add** to add the destination for the phone number
6. Click **Save** to apply the settings
You can also edit multiple numbers simultaneously. To do this, select the multiple numbers you want to modify, then click the **Bulk actions** button. The changes will apply to all selected numbers.
# Wavix IP addresses
Source: https://docs.wavix.com/sip-trunking/ip-allowlisting
Allowlist the Wavix IP addresses and ports for SIP signaling, RTP media, webhooks, and call streaming so calls and callbacks reach your network.
## SIP connectivity
| Location | DNS name | IP address |
| - | :- | :- |
| Amsterdam, NL | nl.wavix.net | 95.211.82.14 |
| Dallas, USA | us.wavix.net | 209.58.144.243 |
| Singapore, SG | sg.wavix.net | 23.108.101.90 |
| Sydney, AU | au.wavix.net | 173.234.106.26 |
**Ports**: 5060 (UDP, TCP), 5061 (TLS/TCP)
Unlike static SIP signaling IPs, media IPs are dynamic and can change frequently. To ensure proper audio flow, allow RTP traffic on ports **10000-20000** from **any IP address** in your firewall settings.
Use domain names whenever possible. They remain stable if underlying IPs change. If your system requires IP addresses, use the IP addresses listed above.
## Webhooks
Webhook server IP address:
| Service | IP address | Protocol | Port |
| - | :- | :- | :- |
| Webhooks | 62.212.73.112 | HTTPS | 443 |
## Call streaming
Call media streaming server IP address:
| Service | IP address | Protocol | Port |
| - | :- | :- | :- |
| Call streaming | 5.79.64.122 | TCP | 443 |
# SIP Trunks API overview
Source: https://docs.wavix.com/sip-trunking/sip-trunks
Create, list, configure, and delete SIP trunks and assign phone numbers to them with the Wavix SIP Trunking API, with examples for each endpoint.
Session Initiation Protocol (SIP) is a signaling protocol for starting, ending, and changing user sessions over an IP network. The Wavix platform provides scalable, enterprise-level features for inbound and outbound calls. This guide shows you how to create and configure [SIP trunks](https://wavix.com/sip-trunk) on your Wavix account using the Wavix API.
## Prerequisites
Before you create your first SIP trunk, sign up for a Wavix account.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## List SIP trunks on your Wavix account
To [list SIP trunks](/api-reference/sip-trunks/list-sip-trunks) and view their statuses on your Wavix account, use the following method:
```http theme={null}
GET https://api.wavix.com/v1/trunks
Authorization: Bearer your_api_key
Content-Type: application/json
```
## Create and configure SIP trunks
The Wavix platform supports these authentication methods for SIP trunks:
* **Digest** - SIP devices authenticate with a login and password.
* **IP Authentication** - The SIP trunk authenticates `SIP INVITE` messages sent from specified IP addresses. IP Authentication requires manual approval by Wavix administrators.
For outbound calls, Wavix supports one Caller ID per SIP trunk by default. To use more than one Caller ID, enable Caller ID Passthrough. Caller ID Passthrough requires manual approval by Wavix administrators.
To [create a SIP trunk](/api-reference/sip-trunks/create-a-sip-trunk) on your account, use this API method:
```http theme={null}
POST https://api.wavix.com/v1/trunks
Authorization: Bearer your_api_key
Content-Type: application/json
```
Response:
```json theme={null}
{
"label": "My SIP trunk",
"password": "YOUR_SIP_TRUNK_PASSWORD",
"callerid": "12121234567",
"ip_restrict": false,
"didinfo_enabled": true,
"call_restrict": true,
"call_limit": 60,
"cost_limit": true,
"max_call_cost": 0.18,
"channels_restrict": true,
"max_channels": 10,
"rewrite_enabled": true,
"rewrite_prefix": "00",
"rewrite_cond": "1",
"passthrough": false
}
```
After you create the SIP trunk, you receive a response with the SIP trunk ID and its configuration parameters.
To [update a SIP trunk](/api-reference/sip-trunks/update-a-sip-trunk) configuration, use this API method:
```http theme={null}
PUT https://api.wavix.com/v1/trunks/trunk_id
Authorization: Bearer your_api_key
Content-Type: application/json
```
Paste the following JSON in the request body.
```json theme={null}
{
"label": "SIP trunk label",
"password": "YOUR_SIP_TRUNK_PASSWORD",
"callerid": "12121234567",
"ip_restrict": true,
"didinfo_enabled": true,
"call_restrict": false,
"call_limit": 60,
"cost_limit": true,
"max_call_cost": 0.18,
"channels_restrict": true,
"max_channels": 10,
"rewrite_enabled": true,
"rewrite_prefix": "00",
"rewrite_cond": "1",
"passthrough": false
}
```
## Delete a SIP trunk
To [delete a SIP trunk](/api-reference/sip-trunks/delete-a-sip-trunk) from your account, use this API method:
```http theme={null}
DELETE https://api.wavix.com/v1/trunks/trunk_id
Authorization: Bearer your_api_key
Content-Type: application/json
```
# Send an SMS broadcast
Source: https://docs.wavix.com/tutorials/sms-broadcast
Run a bulk SMS campaign with Wavix SMS Broadcast: create a personalized template, upload a CSV contact list, launch it, and track delivery and clicks.
## Overview
Wavix SMS Broadcast is a no-code tool for running bulk SMS campaigns at scale with personalization, scheduling, and engagement tracking (for example, link clicks).
In this tutorial, you will:
* Create an approved SMS template with variables (personalization).
* Upload a CSV contact list and map variables to columns.
* Launch a broadcast and monitor delivery and click performance.
## Prerequisites
To get started, you'll need:
* An active [Wavix account](/getting-started/create-account)
* A Sender ID activated for a destination country
* Recipient phone numbers in E.164 format (e.g., +12345678900)
## Step 1: Create an SMS template
Templates help you save time and stay consistent. Here's how to create one:
1. In the top menu, go to **Solutions** → [**SMS broadcast**](https://app.wavix.com/sms-broadcast/campaigns)
2. Select the [Templates](https://app.wavix.com/sms-broadcast/templates) tab.
3. Select **Create new**, and follow the guided wizard.
Enter the template name and choose the country where you plan to send messages.
Select **Next**.
To create your message:
1. Enter the message text. Use double curly brackets (for example, `{{name}}`) to insert dynamic fields. These fields are personalized automatically when the message is sent.
2. If your message includes links, turn the URL shortener on or off. The Wavix URL shortener helps save characters and lets you track link clicks.
3. Choose the Sender ID that will be used when sending this template.
Select **Next**.
Check the estimated number of SMS segments in the top-right corner, above the message field.
Review your template details. To make changes, select **Back**. To finish, select **Create**.
Your template will be reviewed by Wavix. You'll get an email once it's approved.
## Step 2: Prepare your recipient list
Use a CSV file to upload your recipients. Make sure the file:
* Is smaller than 10 MB
* Contains no more than 100,000 rows
* Lists phone numbers in the first column, formatted in E.164 (for example, +12345678900)
Include a header row and any columns you want to use as template variables (for example, `name` for `{{name}}`).
```csv theme={null}
phone,name,offerCode
+12345678900,John,2026CHR25
+12345678911,Jane,2026CHR25
+12345678922,Bob,2026CHR25
+12345678933,Marie,2026CHR25
+12345678944,Sarah,2026CHR25
```
## Step 3: Launch your broadcast
To send an SMS broadcast:
1. In the top menu, go to **Solutions** → [**SMS broadcast**](https://app.wavix.com/sms-broadcast/campaigns)
2. Select the [Campaigns](https://app.wavix.com/sms-broadcast/campaigns) tab.
3. Select **Create new**, and follow the guided wizard.
Enter a broadcast name and upload your contact list. Wavix uses built-in validation to make sure all numbers are correctly formatted and belong to the same country. You can download any invalid or duplicate numbers, fix them in your original file, and upload it again.
After Wavix processes the file, select a template and the Sender ID you want to use.
Select **Next**
If your template includes variables (for example, `{{name}}`), map each one to the appropriate column in your uploaded CSV (for example, `name`).
Select **Next**.
Choose whether to send the broadcast immediately or schedule it for later. You can also set a sending rate to control delivery speed.
Select **Next**.
Review all campaign details. To make changes, select **Back**. To start the broadcast, select **Create**.
## Step 4: Monitor your results
Track the performance of your SMS broadcast in the Campaigns dashboard. You can view:
1. Delivery and failure rates
2. Engagement metrics (e.g., link clicks and CTR)
Use the Wavix [Link Shortener API](/api-reference/link-shortener/list-short-link-metrics) to access detailed engagement metrics
That's it. You created a template, uploaded contacts, launched a broadcast, and confirmed results in analytics. If you used tracked links, review clicks and CTR to understand engagement.
## Tips for better campaign performance
* Keep messages short and relevant.
* Use dynamic fields to personalize content and boost engagement.
* Avoid ALL CAPS and excessive punctuation, which can trigger spam filters.
* Always include an opt-out option if required by local regulations (for example, "Reply STOP").
# Answering Machine Detection (AMD)
Source: https://docs.wavix.com/voice/answering-machine-detection
Use Wavix Answering Machine Detection (AMD) to end outbound calls answered by voicemail, so your agents spend time only on live conversations.
[Answering Machine Detection](https://wavix.com/amd) (AMD) is a Wavix intelligence feature that analyzes the initial audio of an outbound call to determine if it was answered by a human or a machine. When an answering machine or voicemail greeting is detected, the Wavix platform automatically disconnects the call, saving your agents time and improving scale and efficiency.
## How AMD works
Wavix AMD analyzes the initial audio of a call to distinguish between a human response and a pre-recorded voicemail message. By identifying frequency patterns and audio characteristics, the platform can detect a machine even during **Early Media** playback (before the final answer signal).
Wavix AMD also screens for automated network announcements played during **Early Media**—the period before a call is technically answered. By identifying these pre-answer signals and terminating the call immediately, the Wavix platform ensures that your resources are only dedicated to successful human connections.
```mermaid actions={false} theme={null}
sequenceDiagram
participant App as Your Application
participant Wavix as Wavix Platform
participant Rec as Recipient
App->>Wavix: Initiate call (voicemail_detection: true)
Wavix->>Rec: Ringing...
Rec->>Wavix: Call Answered
Wavix->>Wavix: Analyze Audio (AMD)
alt Human Detected
Wavix->>App: Callback: machine_detected: false
Wavix-->>Rec: Bridged to Agent/Application
else Machine Detected
Wavix->>App: Callback: machine_detected: true
Wavix->>Rec: Disconnect Call
end
```
### Detection window and call signalling
Analysis starts as soon as Wavix has audio to evaluate — either from **Early Media** played by the called party's carrier before the call is formally answered, or from the live audio right after the called party picks up. A verdict is normally reached within about four seconds of whichever starting point applies. Until the verdict is in, the call is not yet bridged:
* Your application or PBX keeps receiving the ringing indication, with no media.
* If the called party has already answered, they may say "Hello" and wait for a reply during this window.
* If a machine is detected **during Early Media**, before the call is answered, Wavix disconnects it and the SIP caller receives a busy indication — the call is reported as `Busy` in both your logs and Wavix logs, and is not billed as answered.
* If a machine is detected **after the call is answered**, Wavix still disconnects it, but the call has already been answered by definition: it appears as `Answered` in Wavix call logs, with a talk time of roughly the detection window (three to four seconds), and is billed as an answered call plus the AMD fee (see [Billing](#billing)). Your dialer or PBX may show a busy/failed disposition of its own if it interprets the disconnect that way, so reconcile against the **Answered by** field rather than your dialer's disposition alone.
* If a human is detected, the call is bridged immediately.
Because the called party may already be waiting when the verdict lands, connect calls that pass AMD straight through to an agent or application that is ready to talk. Any extra queueing, ringing, or second detection stage after AMD adds to that silence and increases the chance the called party hangs up.
### Detection outcomes
| Verdict | What happens to the call | How it is reported |
| - | - | - |
| **Human** | Bridged immediately. | `machine_detected: false`; **Answered by** shows `human`. |
| **Machine** | Disconnected by Wavix. A SIP caller receives a busy indication. Reported and billed as `Busy` if detected during Early Media (before answer), or as `Answered` (call + AMD fee) if detected after answer — see [Detection window and call signalling](#detection-window-and-call-signalling). | `machine_detected: true`; **Answered by** shows `machine`. |
| **Undetermined** | Bridged, exactly as if a human had answered. | Not flagged as a machine; **Answered by** shows neither `human` nor `machine`. |
Wavix does not return an `AMDSTATUS` parameter or a `NOTSURE` signalling result. If your dialer logs values such as `HUMAN`, `MACHINE`, or `NOTSURE` per call, they come from a detection layer inside the dialer, not from Wavix. Running two detection layers on the same call lengthens the silence after answer and can drop calls that Wavix already classified as human. See [Using AMD with an outbound dialer](#using-amd-with-an-outbound-dialer).
### When AMD cannot reach a verdict
Some calls cannot be classified confidently — heavy background noise, a very delayed or silent answer, or a network announcement in an unexpected format. In those cases Wavix connects the call rather than dropping it, so a real person is never cut off because of an inconclusive verdict, and no AMD fee is applied to that call.
## Activation levels
You can enable AMD at two different levels depending on your integration needs:
### 1. Trunk level (Wavix portal & Wavix Embeddable)
Recommended for calls manually placed from your PBX or third-party systems connected via SIP, as well as features built using **Wavix Embeddable**.
For these methods, AMD is controlled globally for the specific SIP trunk:
1. **Sign in** to your [Wavix account](https://app.wavix.com).
2. In the top menu, click on **Numbers & Trunks → Trunks**.
3. Select an existing SIP trunk to edit (or create a new one).
Wavix Embeddable uses the SIP trunk configured during your application setup.
4. Scroll down to the **Trunk features** section.
5. Toggle **Voicemail detection** to **ON**.
6. Click **Save and close**.
Once enabled, any outbound call made through this trunk—whether via a hardware phone or a Wavix Embeddable instance—that is answered by a machine will be automatically dropped.
### 2. Call level (API only)
Recommended for programmable voice applications where you want granular control over which specific calls use AMD. This is currently supported exclusively by the **Calls API**.
#### Via Calls API
To enable AMD for a specific call, set the `voicemail_detection` property to `true` in your `POST /v1/calls` request.
```bash cURL theme={null}
curl -X POST "https://api.wavix.com/v1/calls" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"from": "13614157006",
"to": "1234567890",
"voicemail_detection": true
}'
```
```javascript Node.js theme={null}
const axios = require('axios');
axios.post('https://api.wavix.com/v1/calls', {
from: '13614157006',
to: '1234567890',
voicemail_detection: true
}, {
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json'
}
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://api.wavix.com/v1/calls"
payload := map[string]interface{}{
"from": "13614157006",
"to": "1234567890",
"voicemail_detection": true,
}
jsonPayload, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
req.Header.Set("Authorization", "Bearer ")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
defer resp.Body.Close()
fmt.Printf("Status: %s\n", resp.Status)
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.wavix.com/v1/calls")
header = {
'Content-Type' => 'application/json',
'Authorization' => 'Bearer '
}
body = {
from: '13614157006',
to: '1234567890',
voicemail_detection: true
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = body.to_json
response = http.request(request)
puts response.body
```
## AMD events and webhooks
To receive real-time notifications about AMD results, you can configure an **on-call** webhook. Wavix sends a POST callback to your designated URL whenever a call event occurs, such as when a call is answered and the AMD analysis is complete.
### Subscribe to call events
You can create a webhook using the [Create a webhook](/api-reference/call-webhooks/create-a-call-webhook) endpoint:
```bash theme={null}
curl -X POST "https://api.wavix.com/v1/calls/webhooks" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/calls",
"event_type": "on-call"
}'
```
### The machine\_detected event
When a call is answered and subsequently ends, Wavix triggers a `completed` event callback. The JSON payload includes a `machine_detected` boolean field that indicates whether the call was screened by the AMD system.
**Sample completed event payload:**
```json theme={null}
{
"uuid": "5dccb6b0-f35c-488c-867b-86fb012c4415",
"direction" : "outbound",
"event_type": "completed",
"event_time": "2025-09-22T12:56:45.000Z",
"event_payload": null,
"call_started": "2025-09-22T12:56:38.000Z",
"call_answered": "2025-09-22T12:56:40.000Z",
"call_completed": "2025-09-22T12:56:45.000Z",
"from": "+18045961058",
"to": "17653889567",
"machine_detected": true,
"tag": "marketing-campaign"
}
```
* `machine_detected: true`: An answering machine or voicemail was detected.
* `machine_detected: false`: A human was detected.
By listening for the `completed` event, your application can accurately log the outcome of the call, including whether it was dismissed by AMD or successfully answered by a human.
## Auditing AMD results on your own traffic
Detection accuracy depends on the destination, on local answering habits, and on how voicemail systems in that market present their greeting. Rather than relying on a single global figure, measure AMD on your own traffic. The per-call verdict is available in three places:
* **Webhooks** — the `machine_detected` field on the `completed` event described above. Persist it against your own campaign records to build a view of false machine and false human detections over time.
* **CDR API** — [List CDRs](/api-reference/cdrs/list-cdrs) returns the verdict for historical calls, so you can audit retrospectively even if you did not store the webhook payload.
* **Portal export** — in [app.wavix.com](https://app.wavix.com), export your call history as CSV and read the **Answered by** column. Filtering on `human` and `machine` isolates classified calls; excluding both leaves the undetermined ones.
To review suspected misclassifications, filter for answered calls with a very short duration and cross-reference the AMD verdict. If call recording is enabled on the same trunk, the recording makes the review conclusive.
## Billing
The AMD fee is charged per screened call, in addition to the call charge itself. Calls where the verdict was undetermined do not carry the AMD fee, but the call is still billed normally. A call ending in a `machine` verdict after answer is billed as any other answered call (for its few seconds of talk time) plus the AMD fee; if the machine is detected during Early Media, before answer, the call is not billed as answered at all. Check your rate sheet or contact your account manager for the rate that applies to your account.
To reconcile a period, export call history as CSV, select `Answered` in the **Disposition** column, and exclude `human` and `machine` in **Answered by**. The remaining calls are the undetermined ones, which are billed for the call itself but not for AMD.
## Limitations
Wavix AMD is a single centrally tuned model rather than a configurable engine. In practice this means:
* **No tuning parameters.** Total analysis time, initial-silence and greeting thresholds, and word-count limits are not exposed. The model is tuned on live traffic, including noisy lines and delayed answers.
* **No beep detection.** Wavix does not detect or wait for the end-of-greeting beep. Detected machines are disconnected rather than held open, so AMD is not suitable for flows that leave a message in a voicemail box.
* **No self-service asynchronous mode.** By default, the call is not bridged until the verdict is in, so the detection window is always visible to the called party. Wavix can run detection in parallel after the call connects instead — useful for automated flows (for example, an AI agent or a prerecorded message) that would rather start talking immediately and accept that a small fraction of calls disconnect a few seconds in. This mode is not exposed in the Wavix portal; contact your account manager to enable it on a trunk.
* **Outbound only.** AMD applies to outbound calls.
## Using AMD with an outbound dialer
Predictive and queue-mode dialers are the most common AMD integration, and also the easiest to misconfigure. A few rules keep live customers from being dropped:
* **Run detection in one place only.** If Wavix AMD is enabled on the trunk, disable voicemail detection in your dialer. Two layers on the same call stack their analysis windows and the second layer will discard calls Wavix already passed as human.
* **Do not treat the busy indication as a busy line.** On an AMD-enabled trunk, a busy response to an outbound attempt usually means AMD detected a machine and dropped the call. Classify it as screened in your retry logic rather than requeuing it as an unreachable number.
* **Bridge passing calls straight to a waiting agent.** Any queueing or ringing stage after AMD is added to the silence the called party already experienced.
* **Persist the verdict per call.** Without it you cannot distinguish an AMD drop from a network failure when auditing a campaign.
Check whether a second detection layer is active in your dialer, since its own machine or inconclusive verdict will end the call after Wavix has already passed it as human. Then export the affected calls and compare your dialer's verdict against the **Answered by** column to establish which layer made the decision.
This is the detection window and is expected. Reduce total silence by removing any queueing, ringing, or second detection stage between the AMD verdict and the agent.
Wavix does not emit those statuses. A connected call means Wavix classified it as human or could not reach a verdict; the status your dialer logged came from its own detection layer.
In your Wavix account, go to **Numbers & Trunks → Trunks**, open each trunk you created, and check **Voicemail detection** under **Trunk features**.
# Stream calls with WebSocket
Source: https://docs.wavix.com/voice/call-streaming
Stream live call audio to your application over a WebSocket, with unidirectional and bidirectional modes, pcm16 audio, and support for AI voice agents.
Call media streaming lets Wavix customers send live call audio to another application using a WebSocket connection. You can stream inbound and outbound audio in real time for seamless integration with AI voice assistants, large language models (LLMs), and other applications.
Wavix supports **unidirectional** and **bidirectional** call media streaming.
## Streaming types
### Unidirectional streaming
Your application receives call audio but can't send audio back to Wavix. You can stream:
* Inbound audio (to Wavix)
* Outbound audio (from Wavix)
* Both channels
### Bidirectional streaming
Your application can both receive and send audio over the same WebSocket connection. Wavix plays the audio you send directly into the call, which is useful for real-time AI conversations.
With bidirectional media streaming, your application can only receive the inbound audio stream.
## Audio format
### Output audio format
When streaming audio from an inbound or outbound channel, your application receives audio in the following format:
* Format: **pcm16**
* Sample rate: **24 kHz**
* Bit depth: **16-bit**
* Frame size: **20ms**
* Channels: **Mono**
* Endianness: **Little-endian**
### Input audio format
To ensure compatibility, send audio to Wavix in the following format:
* Format: **pcm16**
* Sample rate: **24 kHz**
* Bit depth: **16-bit**
* Frame size: **20ms**
* Channels: **Mono**
* Endianness: **Little-endian**
## Prerequisites
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Get your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## Call media streaming flow
To stream raw call audio, follow these steps:
1. Subscribe to call events.
2. Initiate or answer a call programmatically.
3. Start the call media streaming.
4. Stop the call media streaming.
### 1. Subscribe to call events
To receive all call-related events, subscribe to both inbound and outbound call events.
To subscribe to **outbound** call events, include your webhook URL in the `status_callback` parameter of the Initiate outbound call request. To receive **inbound** call events, assign a call status callback URL to your phone number using the Wavix Phone numbers API or GUI.
### 2. Initiate or answer a call programmatically
To start an **outbound** call, use the following method.
```bash Initiate an outbound call theme={null}
curl -L -X POST https://api.wavix.com/v1/call
-H 'Authorization: Bearer your_api_key'
-H 'Content-Type: application/json'
-d '{
"from": "Caller ID",
"to": "Destination number",
"status_callback": "Call status endpoint URL"
}'
```
* `your_api_key`: Your Wavix API key.
* `from`: Caller ID that will be used. Must be an active or verified number in your Wavix account.
* `to`: Destination phone number. The number must be present in international E.164 format.
* `status_callback`: The webhook URL where Wavix posts call events.
If successful, the method returns `HTTP 200 OK` and a unique call identifier.
To answer an **inbound** call, use the following method.
```bash Answer an inbound call theme={null}
curl -L -X POST https://api.wavix.com/v1/call/{{call_id}}/answer
-H 'Authorization: Bearer your_api_key'
-H 'Content-Type: application/json'
```
* `your_api_key`: Your Wavix API key.
* `call_id`: Unique identifier of the call which you received on your webhook assigned to a phone number.
Optionally, paste the following JSON into the request body to start streaming immediately.
```json theme={null}
{
"stream_channel": "The channel you want to stream",
"stream_type": "oneway or twoway streaming",
"stream_url": "WebSocket URL"
}
```
* `stream_channel`: Indicates what call channel should be streamed. Can be `inbound`, `outbound`, or `both`.
* `stream_type`: Can be 'oneway' for unidirectional or 'twoway' for bidirectional call media streaming.
* `stream_url`: WebSocket URL where the inbound call media is streamed (must start with `ws` or `wss`).
If successful, the method returns `HTTP 200 OK` and a success indicator. Streaming starts right away.
### 3. Start call media streaming
Wait until the call is answered before starting media streaming. To start the streaming, use the following method.
```bash Start call streaming theme={null}
curl -L -X POST https://api.wavix.com/v1/call/{{id}}/streams
-H 'Authorization: Bearer your_api_key'
-H 'Content-Type: application/json'
-d '{
"stream_channel": "The channel you want to stream",
"stream_type": "oneway or twoway streaming",
"stream_url": "WebSocket URL"
}'
```
* `your_api_key`: Your Wavix API key.
* `stream_channel`: Indicates what call channel should be streamed. Can be `inbound`, `outbound`, or `both`.
* `stream_type`: Can be 'oneway' for unidirectional or 'twoway' for bidirectional call media streaming.
* `stream_url`: WebSocket URL where the inbound call media is streamed (must start with `ws` or `wss`).
All parameters are mandatory.
With bidirectional media streaming, your application can only receive the inbound audio stream.
If successful, the method returns `HTTP 200 OK`. The response contains a unique stream identifier.
You can only have a single bidirectional and up to 5 unidirectional streams for a single call.
### 4. Stop call media streaming
Call media streaming stops automatically when the call is completed. To stop it programmatically, use the following method.
```bash Stop call streaming theme={null}
curl -L -g -X DELETE https://api.wavix.com/v1/call/answer/{{call_id}}/streams/{{stream_id}}
-H 'Authorization: Bearer your_api_key'
-H 'Content-Type: application/json'
```
* `your_api_key`: Your Wavix API key.
* `call_id`: Unique identifier of the call.
* `stream_id`: Unique identifier of the stream.
If successful, the method returns `HTTP 200 OK` and a success indicator.
## Call media streaming events
While streaming a call, Wavix sends messages to your WebSocket server. For bidirectional streaming, your server can also send messages back to Wavix.
## WebSocket messages from Wavix
Wavix sends the following message to your WebSocket server while streaming a call.
### `connected`
Sent once the connection is established.
```json theme={null}
{
"event": "connected",
"event_time": "Date and time of the event"
}
```
### `start`
Sent before media streaming begins. Contains stream metadata.
```json theme={null}
{
"event": "start",
"event_time": "Date and time of the event",
"call_id": "Unique identifier of the call",
"stream_id": "Unique identifier of the stream",
"stream_type": "oneway/twoway",
"channel": "inbound/outbound",
"sequence_number": "Message order number"
}
```
### `media`
Contains audio chunks streamed to your WebSocket server.
```json theme={null}
{
"event": "media",
"event_time": "Date and time of the event",
"call_id": "Unique identifier of the call",
"stream_id": "Unique identifier of the stream",
"sequence_number": "Message order number",
"media": {
"payload": "base64 encoded audio payload",
"track": "inbound/outbound",
"timestamp": "Milliseconds from stream start",
"chunk": "Chunk number"
}
}
```
### `stop`
Sent when streaming is stopped or the call ends.
```json theme={null}
{
"event": "stop",
"event_time": "Date and time of the event",
"call_id": "Unique identifier of the call",
"stream_id": "Unique identifier of the stream",
"sequence_number": "Message order number"
}
```
### `mark`
Acknowledges that the previous media message finished playing. Only used in bidirectional call streaming.
```json theme={null}
{
"event": "mark",
"event_time": "Date and time of the event",
"call_id": "Unique identifier of the call",
"stream_id": "Unique identifier of the stream",
"sequence_number": "Message order number",
"mark": {
"name": "Name of the mark message"
}
}
```
## WebSocket messages to Wavix
When using bidirectional streaming, your server can send these messages to Wavix to play audio back into the call and control the stream flow.
### `media`
Send audio chunks from your server to Wavix.
```json theme={null}
{
"event": "media",
"stream_id": "Unique identifier of the stream",
"media": {
"payload": "base64 encoded audio payload"
}
}
```
### `mark`
You can send the `mark` message after sending `media` to request notification when the audio chunk has been played. Wavix responds with the `mark` message with a matching name when the audio ends (or if there is no audio buffered).
```json theme={null}
{
"event": "mark",
"stream_id": "Unique identifier of the stream",
"mark": {
"name": "Name of the mark message"
}
}
```
### `clear`
You can send the `clear` message to interrupt previously sent audio and empty all buffered audio. This causes any queued `mark` message to be sent back to your WebSocket server.
```json theme={null}
{
"event": "clear",
"stream_id": "Unique identifier of the stream"
}
```
# Call transcription with Speech Analytics API
Source: https://docs.wavix.com/voice/call-transcription
Transcribe calls you make or receive on the Wavix platform, then search those transcriptions for keywords and phrases with the Speech Analytics API.
The Wavix Speech Analytics API supports two ways to transcribe phone calls:
1. Transcribe an active phone call that was initiated or received through Wavix.
2. Transcribe a phone call recorded outside Wavix by uploading an audio file.
For instructions on uploading and transcribing external recordings, see [Call transcription (file upload)](/voice/file-transcription).
This guide describes how to transcribe calls that went through Wavix and how to search those transcriptions for keywords and phrases.
To search call transcriptions for keywords or phrases, first enable Call recording and [Call transcription](https://wavix.com/speech-analytics) services on your SIP trunks and phone numbers. You can do this in the Wavix app or by using the [SIP trunks](/api-reference/sip-trunks/update-a-sip-trunk) and [DIDs](/api-reference/my-numbers/list-phone-numbers) endpoints.
## Prerequisites
Before you can access the Wavix Speech Analytics API, sign up for Wavix.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## How Wavix call transcription works
When you activate transcription on a SIP trunk or phone number, Wavix automatically converts recorded calls into plain text. Most calls are transcribed within 10 minutes, depending on call length and queue size.
After transcription, Wavix detects the call language and labels speakers as `agent` or `client` based on call direction.
## Request transcription for a specific call
To request a transcription for a specific call:
1. Use the [CDR API](/api-reference/cdrs/search-transcriptions) to find the call's unique identifier (`uuid`).
2. Request the transcription:
```http theme={null}
GET https://api.wavix.com/v1/cdr/uuid/transcription
Authorization: Bearer your_api_key
Content-Type: application/json
```
If successful, you receive an `HTTP 200 OK` response with the full transcription. The transcription is divided into blocks by speaker, with start and end times in milliseconds from call answer.
**Sample response:**
```json theme={null}
{
"transcript": {
"19293741161": "Hello",
"19293741160": "Hi"
},
"turns": [
{
"phone_number": "19293741161",
"s": 600,
"e": 700,
"text": "Hi"
}
],
"uuid": "1234",
"language": "en",
"duration": 10,
"charge": "0.003",
"status": "completed",
"transcription_date": "2023-01-09T10:04:39.734Z"
}
```
## Search for calls containing keywords or phrases
To [search for calls with transcription](/api-reference/cdrs/search-transcriptions) containing specific keywords or phrases, use the following method.
```http theme={null}
POST https://api.wavix.com/v1/cdr
```
Response sample:
```json theme={null}
{
"type": "placed",
"from": "2023-01-01",
"to": "2023-01-31",
"transcription": {
"status": "completed",
"language": "en",
"agent": {
"must": [
"Hello",
"Thank you"
],
"match": [
"Nope",
"Maybe"
],
"exclude": [
"Richard",
"Issue resolved"
]
},
"client": {
"must": [
"Hello",
"Bye, Larry"
],
"match": [
"Nope",
"Maybe"
],
"exclude": [
"Richard",
"Issue resolved"
]
},
"any": {
"must": [
"Hello",
"Bye, Larry"
],
"match": [
"Nope",
"Maybe"
],
"exclude": [
"Richard",
"Issue resolved"
]
}
}
}
```
* `type` - use `placed` for outbound calls or `received` for inbound calls
* `from` - filter results by the lower limit on the date the call was placed or received
* `to` - filter results by the upper limit on the date the call was placed or received
* `transcription` - filter results by the call transcription parameters:
* `status` - filter results by transcription status
* `language` - filter results by the language of the call
* `agent` - filter results based on keywords and phrases said by a speaker labeled as `agent`
* `must` - find calls with transcription that includes all specified keywords and phrases. The keywords and phrases are combined using logical AND.
* `match` - find calls with transcription that includes any specified keyword and phrase. The keywords and phrases are combined using logical OR.
* `exclude` - find calls with transcription that do not include any specified keyword and phrase. The keywords and phrases are combined using logical OR.
* `client` - filter results based on keywords and phrases said by a speaker labeled as `client`
* `must` - find calls with transcription that includes all specified keywords and phrases. The keywords and phrases are combined using logical AND.
* `match` - find calls with transcription that includes any specified keyword and phrase. The keywords and phrases are combined using logical OR.
* `exclude` - find calls with transcription that do not include any specified keyword and phrase. The keywords and phrases are combined using logical OR.
* `any` - filter results based on keywords and phrases said by any speaker
* `must` - find calls with transcription that includes all specified keywords and phrases. The keywords and phrases are combined using logical AND.
* `match` - find calls with transcription that includes any specified keyword and phrase. The keywords and phrases are combined using logical OR.
* `exclude` - find calls with transcription that do not include any specified keyword and phrase. The keywords and phrases are combined using logical OR.
The `type`, `from`, and `to` are mandatory parameters and cannot be blank. All other parameters are optional.
If successful, the method returns the `HTTP 200 OK` status code. The response will contain a list of call detail records that match the search criteria. Every call detail record contains the unique identifier of the call and a link to the full call transcription.
**Sample response:**
```json theme={null}
{
"items": [
{
"uuid": "8891",
"date": "2022-03-03T13:53:59.000Z",
"from": "12212123123",
"to": "18001231233",
"duration": 72,
"charge": "0.01",
"disposition": "ANSWERED",
"transcription": {
"uuid": "1234",
"url": "https://api.wavix.com/v1/cdr/8891/transcription"
},
"destination": "United States",
"sip_trunk": "36465",
"per_minute": "0.0059"
}
],
"pagination": {
"total": 100,
"total_pages": 10,
"current_page": 2,
"per_page": 0
}
}
```
## Transcribe a single call
To transcribe a specific call:
1. Use the [CDR API](/api-reference/cdrs/search-transcriptions) to find the call's unique identifier (`uuid`).
2. Send a PUT request:
```http theme={null}
PUT https://api.wavix.com/v1/cdr/uuid/retranscribe
```
3. Include the following JSON in the request body:
```json theme={null}
{
"language": "en",
"webhook_url": "https://your-webhook.url"
}
```
**Parameters:**
* `language`: (Optional) Force the language for transcription. Wavix uses this instead of auto-detection.
* `webhook_url`: (Optional) Webhook URL for transcription status updates.
If successful, you receive an empty `HTTP 200 OK` response. When transcription is complete, you receive a POST callback to your webhook:
```json theme={null}
{
"uuid": "123",
"status": "completed"
}
```
* `uuid`: Unique identifier of the recorded call
* `status`: `completed` (success) or `failed` (error)
# Voice Campaigns with Campaign Builder API
Source: https://docs.wavix.com/voice/campaign-builder
Trigger and manage automated outbound voice campaigns with the Wavix Campaign Builder API, using call scenarios you design in the Wavix portal.
Wavix [Campaign Builder](https://wavix.com/campaign-builder) lets you create custom flows for outbound calls using an intuitive, drag-and-drop interface. With the Wavix Campaign Builder API, you can trigger automatic calls programmed to follow a specific scenario.
## Prerequisites
Before you can access the Wavix Campaign Builder API, you need to sign up for Wavix.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## How to launch a campaign
Before placing an automatic call, sign in to your Wavix account and create a Call Flow using the app at [https://app.wavix.com/calling/flows](https://app.wavix.com/calling/flows). Once the Call Flow is approved, you can use it with the Wavix Campaign Builder API.
To launch a call, get the Call Flow's unique identifier:
1. Go to [https://app.wavix.com/calling/flows](https://app.wavix.com/calling/flows).
2. Find the approved Call Flow you want to launch.
3. The Call Flow ID appears in the ID column.
To [trigger a call](/api-reference/voice-campaigns/trigger-a-scenario), use the following method:
```http theme={null}
POST https://api.wavix.com/v1/voice-campaigns
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request body example:
```json theme={null}
{
"voice_campaign": {
"callflow_id": callflow_id,
"contact": "contact",
"caller_id": "caller_id"
}
}
```
* `callflow_id` - the unique identifier of the Call Flow to launch
* `contact` - a phone number in E.164 format, with or without the leading “+”
* `caller_id` - an active phone number on your Wavix account. This number will be used as the Caller ID
All parameters are required.
If successful, the service returns `HTTP 201 Created`. The response body contains the placed call details.
```json theme={null}
{
"voice_campaign": {
"id": 1,
"caller_id": "4420xxxxxxxx",
"contact": "4477xxxxxxxx",
"status": "in_progress",
"timestamp": "2021-12-09T09:47:18Z"
}
}
```
After the call is completed, you can query its details using the [Wavix CDR API](/api-reference/cdrs/list-cdrs).
# Retrieve call logs (CDRs)
Source: https://docs.wavix.com/voice/cdr
Query and export Call Detail Records (CDRs) with the Wavix API in CSV or JSON, including call duration, numbers, price, and summary metrics.
You can use the Wavix API to query and export call detail records (CDRs) from your account with various parameters. CDRs include attributes such as time, duration, origination and destination numbers, and call price.
CDRs have no retention period on the Wavix platform.
This section shows you how to search for CDRs and get call metrics using the Wavix API.
## Prerequisites
To get started, sign up for a Wavix account and find your API key.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## Retrieve CDRs from your account
You can request CDRs in either CSV or JSON format. The response format is defined in the request header. The Wavix platform also supports JSON streaming for CDRs.
With the Wavix API, you can get near real-time:
* Detailed records of every inbound, outbound, and missed call
* Summary information about all inbound or outbound calls, including total duration, total price, and the number of calls received or placed (JSON format only)
You can use CDRs to:
* Monitor service disruptions
* Analyze usage patterns and trends
The following example shows how to [query CDRs](/api-reference/cdrs/list-cdrs) on your Wavix account.
Request example:
```http theme={null}
GET https://api.wavix.com/v1/cdr?type=placed&from=2021-02-10&to=2021-02-20&per_page=100
Authorization: Bearer your_api_key
Content-Type: application/json
```
Response example:
```json theme={null}
{
"items": [
{
"date": "2021-02-10T10:07:06.376Z",
"from": 12212123123,
"to": 18001231233,
"duration": 72,
"charge": 0.01,
"destination": "sip:36465@sip.example.com",
"sip_trunk": "36465",
"per_minute": 0.0059,
"forward_fee": 0.0059
}
],
"pagination": {
"total": 100,
"total_pages": 10,
"current_page": 2,
"per_page": 10
}
}
```
To query CDRs in CSV format, use the following example:
```http theme={null}
GET https://api.wavix.com/v1/cdr.csv?type=placed&from=2021-02-10&to=2021-02-20&per_page=100
Authorization: Bearer your_api_key
Content-Type: application/json
```
# Call transcription with Speech Analytics API (file upload)
Source: https://docs.wavix.com/voice/file-transcription
How to use the Wavix Speech Analytics API to transcribe uploaded call recordings and search transcriptions for keywords.
The Wavix Speech Analytics API allows you to upload and transcribe recorded phone calls, even if they were not placed or received through the Wavix platform.
Wavix only supports the transcription of stereo audio files.
## Prerequisites
Before you can access the Wavix Speech Analytics API, sign up for Wavix.
### Create a Wavix account
1. [Sign up](https://app.wavix.com/) for a Wavix account using your business email address.
2. Confirm your email address and phone number during the sign-up process.
3. Wait for your account to be approved by the Wavix team.
4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.
### Find your API key
[Get your API key](/api-reference/authentication#get-your-api-key)
## Submit a file for transcription
To submit a file for transcription, use the method described below:
```http theme={null}
POST https://api.wavix.com/v1/speech-analytics
Authorization: Bearer your_api_key
Content-Type: application/json
```
The method takes two parameters:
* `file` - binary file content
* `callback_url` - a webhook URL to send the transcription status updates to
All parameters are mandatory and cannot be left blank.
If successful, the method returns the HTTP 201 status code. The response will include the details of the created transcription request, such as a unique request identifier and the uploaded file name.
```json theme={null}
{
"file" : "call.mp3",
"request_id" : "e865ea07-25af-4fdd-876e-04b0d41d5ebd",
"success" : true
}
```
* `file` - the name of the file uploaded
* `request_id` - unique identifier of the transcription request
* `success` - indicates the file was successfully uploaded and submitted for transcription
The time required for transcription completion varies based on the file's duration and the number of recordings in the queue. Typically, most files are transcribed within 10 minutes.
Once the transcription request's status changes, you'll receive a POST callback to the webhook address specified in the request. Your webhook must respond to the callback with an HTTP 2XX status code. Otherwise, Wavix will make a maximum of 5 attempts to resubmit the status update with 5-second intervals.
```json theme={null}
{
"request_id" : "e865ea07-25af-4fdd-876e-04b0d41d5ebd",
"status" : "completed",
"error" : null
}
```
* `request_id` - unique identifier of the transcription request.
* `status` - status of the file transcription.
* `error` - a human-readable error message, or ‘null’ if no errors occurred.
## Query a specific file transcription
You can request a specific file transcription using the method below.
```http theme={null}
GET https://api.wavix.com/v1/speech-analytics/{uuid}
Authorization: Bearer your_api_key
Content-Type: application/json
```
`uuid` - unique identifier of the transcription request
If successful, the method returns the `HTTP 200 OK` status code. The response will contain the full transcription of the submitted file. The transcription will be divided into blocks of text attributed to one of the speakers. Every block includes the start and end time when it was said. The time is provided in milliseconds and calculated from the beginning of the file.
```json theme={null}
{
"transcript" :
{
"channel_1" : "Hi there",
"channel_2" : "Hello"
},
"turns" : [
{
"speaker" : "channel_1",
"s" : 600,
"e" : 700,
"text" : "Hi there",
"sentiment" : "positive"
}
],
"request_id" : "e865ea07-25af-4fdd-876e-04b0d41d5ebd",
"language" : "en",
"duration" : 102,
"charge" : "0.01",
"status" : "completed",
"transcription_date" : "2023-01-09T10:04:39.734Z",
"transcription_score": "3.8",
"transcription_summary": "The agent and client discussed call recording and call transcription",
"original_file" : "https://api.wavix.com/v1/files/uuid"
}
```
* `transcript` - complete file transcription, with text attributed to each channel.
* `turns` - an array of `turn` objects. Each `turn` object contains text attributed to an identified speaker along with the start and end times for that text and identified sentiment.
* `request_id` - unique identifier of the transcription request.
* `language` - a language used in the transcription.
* `duration` - duration of the uploaded file, in seconds.
* `charge` - total charge for the transcription, in USD.
* `status` - transcription status, which can be either ‘completed’ or ‘failed’.
* `transcription_date` - the date and time of the transcription.
* `transcription_score` - indicates whether the conversation was positive, negative, or neutral. Scores ranging from 1.0 to 3.0 indicate negative conversation and 4.0 to 5.0 indicate positive.
* `transcription_summary` - a concise summary of the transcribed conversation.
* `original_file` - URL to the uploaded file.
## How to submit a file for re-transcription
In cases when you need to resubmit a previously submitted file for transcription, use the method below.
```http theme={null}
PATCH https://api.wavix.com/v1/speech-analytics/{uuid}
Authorization: Bearer your_api_key
Content-Type: application/json
```
* `uuid` - unique identifier of the transcription request.
Request sample:
```
{
"callback_url" : "https://webhook.url"
}
```
* `callback_url` - a webhook URL to send the transcription status updates to.
If successful, the method returns the `HTTP 200 OK` status code.
```json theme={null}
{
"success" : true
}
```
Once the transcription status changes, you'll receive a POST callback to the webhook address specified in the request. Your webhook must respond to the callback with an HTTP 2XX status code. Otherwise, Wavix will make a maximum of 3 attempts to resubmit the status update with 5-second intervals.
```json theme={null}
{
"request_id" : "e865ea07-25af-4fdd-876e-04b0d41d5ebd",
"status" : "completed",
"error" : null
}
```
* `request_id` - unique identifier of transcription request.
* `status` - status of file transcription.
* `error` - a human-readable error message, ‘null’ if no errors.
# Getting started with Voice AI
Source: https://docs.wavix.com/voice/voice-ai
Add artificial intelligence to your voice communications with real-time speech processing, natural conversation, and intelligent call handling.
## What is Voice AI?
Voice AI lets your applications understand and respond to spoken language automatically. It powers features like interactive voice menus, virtual assistants, and voice-to-text conversion, so you can create apps that talk with customers naturally without needing a person on the line.
## Common use cases
Handle inbound and outbound calls with AI agents that understand what callers say and respond naturally in real-time. Use them for customer support, scheduling appointments, or collecting information.
Convert speech into text during or after calls. Analyze conversations to understand sentiment, check compliance, or improve quality.
Replace traditional touch-tone menus with natural language understanding. Let callers simply say what they need instead of pressing numbered options.
Use AI to understand what callers want and why they're calling, then route them to the right place with full context.
## How it works
Voice AI integrations connect to Wavix in two ways, depending on your provider and use case.
### SIP trunk integration (Bring your own bot)
Connect a Wavix SIP trunk to your AI provider, then configure the provider's voice agent to handle calls. Wavix routes calls through the SIP trunk, and the AI agent processes speech and responds in real-time, enabling natural conversations with callers.
**Best for:** Pre-built AI voice platforms with native telephony support
**Flow:** Create a SIP trunk between Wavix and your AI provider. Set up the provider's voice agent to manage calls. Wavix sends inbound and outbound calls over SIP, and the AI agent listens, understands, and replies to callers in real time.
### WebSocket integration (Media streams)
Stream audio in real-time to an AI service through WebSockets. You control the AI processing while Wavix handles the voice infrastructure.
**Best for:** Custom AI implementations or services without native telephony
**Flow:** Initiate calls through the Calls API, receive real-time audio streams via WebSocket connection, process audio with your AI service, and send audio responses back through the WebSocket. See the [call streaming guide](./call-streaming) for implementation details.
Both methods support inbound and outbound calls. Choose based on whether you want a managed AI solution (SIP trunk) or custom AI processing (WebSocket).
## Next steps
Explore available AI features for your voice workflows. Add [transcription](./call-transcription), conversational agents, or intelligent call routing to automate tasks and improve customer interactions.
See the [API reference](/api-reference/getting-started) and the [Calls API](/api-reference/call-control/start-a-call) for more detailed information.