SIP hostname documentation

fern/advanced/sip/troubleshoot-sip-trunk-credential-errors.mdx

@@ -13,6 +13,7 @@ This error occurs during the gateway creation step of SIP trunk provisioning. Va
 **In this guide, you'll learn to:**
 
 - Identify the three most common causes of SIP trunk credential validation failures
+- Understand when hostnames work (outbound) and when they don't (inbound)
 - Resolve hostname-vs-IP, inbound-flag, and IP-allowlist issues
 - Verify your gateway configuration against the full parameter reference
 
@@ -30,21 +31,26 @@ Before you start troubleshooting, ensure you have:
 - Your SIP provider's server address, username, and password
 - Access to your SIP provider's admin panel (to check IP whitelisting)
 
-## Using a hostname instead of an IP address
+## Using a hostname for an inbound gateway
 
 This is the most common cause of this error.
 
 ### What happens
 
-Vapi's API accepts both hostnames (for example, `sip.example.com`) and IPv4 addresses (for example, `203.0.113.10`) in the `gateways[].ip` field. However, the underlying SBC only accepts IPv4 addresses. When you provide a hostname, the SBC rejects the gateway configuration.
+The `gateways[].ip` field accepts both hostnames (for example, `sip.example.com`) and IPv4 addresses (for example, `203.0.113.10`). However, the behavior differs depending on the call direction:
+
+- **Outbound gateways** — Hostnames and IPv4 addresses both work. Vapi resolves the hostname when routing outbound calls to your SIP provider.
+- **Inbound gateways** — Only IPv4 addresses work. The SBC needs a numeric IP address to match incoming SIP requests to your trunk. When you provide a hostname with `inboundEnabled: true`, the SBC rejects the gateway configuration.
 
 ### How to check
 
-Look at the value you passed in `gateways[].ip`. If it contains letters (for example, `sip.example.com`), it is a hostname. The SBC needs a numeric IPv4 address instead.
+Look at your gateway configuration. If `inboundEnabled` is `true` (or omitted, since it defaults to `true`) and the `ip` field contains a hostname (for example, `sip.example.com`), this is the cause of the error.
 
 ### How to fix
 
-Resolve the hostname to its IPv4 address, then use that IP directly.
+You have two options depending on whether you need inbound calling:
+
+**If you need inbound calling**, resolve the hostname to its IPv4 address:
 
 <Steps>
 <Step title="Look up the IP address">
@@ -76,7 +82,7 @@ Replace the hostname with the numeric IPv4 address in your gateway configuration
       "ip": "203.0.113.10",
       "port": 5060,
       "outboundEnabled": true,
-      "inboundEnabled": false
+      "inboundEnabled": true
     }
   ]
 }
@@ -86,10 +92,27 @@ Replace the hostname with the numeric IPv4 address in your gateway configuration
 </Steps>
 
 <Note>
-  Always use the IPv4 address, not the hostname. If your provider's IP changes,
-  you need to update the gateway configuration.
+  If your provider's IP address changes, you need to update the gateway
+  configuration with the new address.
 </Note>
 
+**If you only need outbound calling**, you can keep the hostname and disable inbound:
+
+```json title="Gateway configuration"
+{
+  "provider": "byo-sip-trunk",
+  "name": "my sip trunk",
+  "gateways": [
+    {
+      "ip": "sip.example.com",
+      "port": 5060,
+      "outboundEnabled": true,
+      "inboundEnabled": false
+    }
+  ]
+}
+```
+
 ## Inbound enabled on an outbound-only trunk
 
 ### What happens
@@ -157,7 +180,7 @@ The table below lists all available options for each entry in the `gateways` arr
 
 | Option               | Type    | Default   | Description                                                                    |
 | -------------------- | ------- | --------- | ------------------------------------------------------------------------------ |
-| `ip`                 | string  | (required)| IPv4 address of your SIP gateway. Must be a numeric IP address, not a hostname.|
+| `ip`                 | string  | (required)| IPv4 address or hostname of your SIP gateway. Hostnames work for outbound-only gateways. Inbound gateways require a numeric IPv4 address.|
 | `port`               | number  | `5060`    | SIP signaling port.                                                            |
 | `netmask`            | number  | `32`      | Subnet mask for inbound IP matching. Valid range: 24 to 32.                    |
 | `inboundEnabled`     | boolean | `true`    | Whether this gateway accepts inbound calls. Set to `false` for outbound-only trunks. |