import { CodeBlock } from '../views/docs/CodeBlock';
import { CodeTabs } from '../views/docs/CodeTabs';
import { Callout, NextLink, Prose, PropTable } from '../views/docs/prose';


## SIP Integrations

Guava agents can receive inbound calls over the SIP protocol. You can use this feature to directly dial Guava agents from an SBC, PBX, or softphone without going out to the PSTN.

<Callout>
<strong>Using Twilio?</strong> See the [Twilio Programmable Voice guide](/docs/twilio-programmable-voice) or the [Twilio Elastic SIP guide](/docs/twilio-elastic-sip) for step-by-step walkthroughs.
</Callout>

### Contact us for peer whitelisting

Currently, we are whitelisting SIP peers at our firewall level. Contact us at [hi@goguava.ai](mailto:hi@goguava.ai) to get your source IPs whitelisted.

### Check connectivity

Once whitelisted, try to make an `OPTIONS` ping to our SIP trunk at `sip.goguava.ai`. If the check fails, see our guide below on firewall configuration.

### Create a SIP code

Every SIP integration requires a `guavasip` code, which you can create in the Guava dashboard. `guavasip` codes work just like registered phone numbers — agents can listen to them and peers can dial them.

1. Open the [SIP page in the dashboard](https://app.goguava.ai/dashboard/sip).
2. Click **Create SIP Code**.
3. Take note of both the SIP code and the termination URI.

<CodeBlock
  language="bash"
  code={`# You will see a SIP code like this.
guavasip-xxx

# Your termination URI will look like this.
sip:guavasip-xxx@sip.goguava.ai`}
/>

### Attach your agent to the SIP code

Next, start an agent using `agent.listen_sip("guavasip-xxx")`. This is the SIP equivalent of `agent.listen_phone(...)` — Guava forwards every call addressed to that code to your agent.

<CodeBlock
  filename="main.py"
  language="python"
  code={`import os
import guava

agent = guava.Agent(
    name="Nova",
    organization="Acme Corp",
    purpose="Handle inbound calls from the corporate PBX.",
)

# Register handlers — on_call_received, on_call_start, etc.

# Replace with your SIP code from the dashboard.
agent.listen_sip("guavasip-xxx")`}
/>

<Callout>To connect an agent to both a phone number and a SIP code simultaneously, see the documentation for [guava.Runner](./runner).</Callout>

### Dial your agent

The last step is to dial your agent using the termination URI (e.g. `sip:guavasip-xxx@sip.goguava.ai`). If you're having trouble connecting to your agent, please contact us at [hi@goguava.ai](mailto:hi@goguava.ai).

### Firewall configuration

To dial our SIP trunk from your network, you may need to whitelist us in your firewall.

|     |  |
| -------- | ------- |
| **FQDN**  | The FQDN for the Guava SIP trunk is `sip.goguava.ai`.    |
| **Trunk IP** | The IP address for the Guava SIP trunk is `136.118.29.109`. This IP is used for both media and signaling.     |
| **TCP Ports**    | `5060`, `5061` (TLS)   |
| **UDP Ports** | `5060`, `10000-65535` (Media) |
| **ICMP** | Whitelist ICMP to allow connectivity checks (e.g. `ping`). |
| **Supported Codecs** | `PCMU` (G.711 μ-law), `PCMA` (G.711 a-law) |