> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringee.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telnyx

> Set up Telnyx as your telephony provider

[Telnyx](https://telnyx.com) is Ringee's default and recommended telephony provider. It provides WebRTC-based calling, phone number management, and call recording through a powerful API.

## Setup

**1. Create a Telnyx account**

Go to [telnyx.com](https://telnyx.com) and sign up for an account.

**2. Get your API key**

1. In the Telnyx portal, go to **API Keys**
2. Copy your **API Key** (starts with `KEY...`)

**3. Create a Credential Connection (WebRTC)**

Ringee uses Telnyx's **Credential Connections** for WebRTC calling:

1. Go to **Voice** → **Connections** → **Credential Connections**
2. Click **Add Credential Connection**
3. Configure the connection:
   * **Connection Name**: `ringee-webrtc`
   * **Username**: Choose a SIP username
   * **Password**: Choose a SIP password
4. Copy the **Connection ID**, **Username**, and **Password**

**4. Buy a phone number**

1. Go to **Numbers** → **Search & Buy**
2. Search for a number in your desired country
3. Purchase the number
4. Assign the number to your credential connection

**5. Configure webhooks**

Set up webhooks to receive call events:

1. Go to your credential connection settings
2. Set the **Webhook URL** to: `https://your-backend-url/api/telnyx/webhook`
3. Events will be sent for: call initiated, answered, ended, recording completed, etc.

**6. Configure environment variables**

Add the following to your `.env` file:

```env theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
TELNYX_API_KEY="KEYyour_api_key_here"
TELNYX_CONNECTION_ID="your_connection_id"
TELNYX_SIP_USER="your_sip_username"
TELNYX_SIP_PASSWORD="your_sip_password"
NEXT_PUBLIC_TELNYX_LOGIN="your_sip_username"
NEXT_PUBLIC_TELNYX_PASSWORD="your_sip_password"
```

## Environment Variables

| Variable | Required | Description |
| - | - | - |
| `TELNYX_API_KEY` | Yes | Your Telnyx API key |
| `TELNYX_CONNECTION_ID` | Yes | Credential connection ID for WebRTC |
| `TELNYX_SIP_USER` | Yes | SIP username for the credential connection |
| `TELNYX_SIP_PASSWORD` | Yes | SIP password for the credential connection |
| `NEXT_PUBLIC_TELNYX_LOGIN` | Yes | SIP login exposed to the frontend (same as `TELNYX_SIP_USER`) |
| `NEXT_PUBLIC_TELNYX_PASSWORD` | Yes | SIP password exposed to the frontend (same as `TELNYX_SIP_PASSWORD`) |

> [!NOTE]
>
> The `NEXT_PUBLIC_` variables are needed by the frontend to establish WebRTC connections directly from the browser to Telnyx. These are the same values as the SIP credentials.

## How it works

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sequenceDiagram
    participant Browser
    participant Ringee Backend
    participant Telnyx
    participant Phone

    Browser->>Telnyx: WebRTC connect (SIP credentials)
    Browser->>Telnyx: Initiate call
    Telnyx->>Phone: Ring phone via PSTN
    Phone-->>Telnyx: Answer
    Telnyx-->>Browser: Call connected
    Telnyx->>Ringee Backend: Webhook: call.answered
    Note over Browser,Phone: Voice call in progress
    Browser->>Telnyx: Hang up
    Telnyx->>Ringee Backend: Webhook: call.hangup
```

## Features

| Feature | Supported |
| - | - |
| Outbound calls | ✅ |
| Inbound calls | ✅ |
| Call recording | ✅ |
| Phone number purchase | ✅ |
| Number search by country | ✅ |
| WebRTC (browser calling) | ✅ |
| Call transfer | ✅ |

## Troubleshooting

> [accordion] Calls not connecting
>
> Verify that your SIP credentials match between `TELNYX_SIP_USER` / `TELNYX_SIP_PASSWORD` and `NEXT_PUBLIC_TELNYX_LOGIN` / `NEXT_PUBLIC_TELNYX_PASSWORD`. Also ensure your credential connection is active in the Telnyx portal.

> [accordion] Webhooks not received
>
> Make sure your webhook URL is publicly accessible. For local development, use a tunneling service like [ngrok](https://ngrok.com) to expose your backend: `ngrok http 3000`

> [accordion] No phone numbers available
>
> Phone number availability varies by country. Try searching for different area codes or number types (local vs. toll-free).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.