> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Rejestrowanie połączeń Twilio

> **Zaawansowane**
>
> Ten przewodnik opisuje zaawansowany schemat integracji dla deweloperów, którzy potrzebują pełnej kontroli nad
> infrastrukturą Twilio. Aby uprościć konfigurację, rozważ użycie [natywnej integracji z Twilio](/docs/pl/eleven-agents/phone-numbers/twilio-integration/native-integration),
> która automatycznie obsługuje konfigurację.

## Kiedy użyć każdego podejścia

Zanim zaczniesz, poznaj różnice między natywną integracją a metodą rejestrowania połączeń:

| Funkcja                | Natywna integracja | Rejestrowanie połączeń |
| ---------------------- | ------------------ | ---------------------- |
| Łatwość konfiguracji   | Łatwiejsza         | Bardziej złożona       |
| Przekazywanie połączeń | Obsługiwane        | Nieobsługiwane         |
| Własna logika Twilio   | Ograniczona        | Pełna kontrola         |
| Zarządzanie numerami   | Przez ElevenLabs   | Przez Twilio           |

## Omówienie

Endpoint rejestrowania połączeń pozwala używać własnej infrastruktury Twilio, jednocześnie korzystając z agentów ElevenLabs do prowadzenia rozmowy. Zamiast importować numer Twilio do ElevenLabs, zachowujesz pełną kontrolę nad konfiguracją Twilio i używasz API ElevenLabs do rejestrowania połączeń oraz odbierania [TwiML](https://www.twilio.com/docs/voice/twiml), który łączy je z twoimi agentami.

To podejście jest idealne, gdy:

* Musisz zachować istniejącą infrastrukturę i workflow Twilio
* Chcesz programowo kontrolować routing i obsługę połączeń
* Masz złożone przepływy połączeń, które wymagają własnej logiki Twilio przed połączeniem z agentem
* Musisz zintegrować agentów ElevenLabs z istniejącym systemem telefonicznym

## Jak to działa

1. Twój serwer odbiera połączenie przychodzące lub inicjuje połączenie wychodzące przez Twilio
2. Twój serwer wywołuje endpoint rejestrowania połączeń ElevenLabs z danymi agenta i połączenia
3. ElevenLabs zwraca TwiML, który łączy połączenie z agentem przez WebSocket
4. Zwracasz ten TwiML do Twilio, aby ustanowić połączenie

> **Note**
>
> Podczas korzystania z endpointu rejestrowania połączeń funkcja przekazywania połączeń nie jest dostępna, ponieważ ElevenLabs
> nie ma bezpośredniego dostępu do poświadczeń twojego konta Twilio.

## Wymagania wstępne

* [Konto ElevenLabs](https://elevenlabs.io)
* Skonfigurowany Agent konwersacyjny ElevenLabs ([utwórz go tutaj](/docs/pl/eleven-agents/quickstart))
* [Konto Twilio](https://www.twilio.com/try-twilio) z aktywnym numerem telefonu
* Agent skonfigurowany z formatem audio μ-law 8000 Hz (zobacz [konfigurację agenta](#agent-configuration))

## Konfiguracja agenta

Przed użyciem endpointu rejestrowania połączeń skonfiguruj agenta tak, aby używał właściwego formatu audio obsługiwanego przez Twilio.

#### Skonfiguruj wyjście TTS

1. Przejdź do ustawień agenta
2. Przejdź do sekcji Voice
3. Z listy rozwijanej wybierz „μ-law 8000 Hz”

![](/docs/_fern-img/b37196c36051755fb0b10a99b393501ec11573f963c83b6b092e1b5926c6617f.webp)

#### Ustaw format wejściowy

1. Przejdź do ustawień agenta
2. Przejdź do sekcji Advanced
3. Wybierz „μ-law 8000 Hz” jako format wejściowy

![](/docs/_fern-img/ec87531c38e26f2293b90126f1b91ee9acb4cc677c6f3e83a6e1b6029743d3f7.webp)

## Dokumentacja API

Endpoint rejestrowania połączeń przyjmuje następujące parametry:

| Parametr                              | Typ    | Wymagany | Opis                                                      |
| ------------------------------------- | ------ | -------- | --------------------------------------------------------- |
| `agent_id`                            | string | Tak      | ID agenta obsługującego połączenie                        |
| `from_number`                         | string | Tak      | Numer telefonu osoby dzwoniącej                           |
| `to_number`                           | string | Tak      | Docelowy numer telefonu                                   |
| `direction`                           | string | Nie      | Kierunek połączenia: `inbound` (domyślnie) lub `outbound` |
| `conversation_initiation_client_data` | object | Nie      | Zmienne dynamiczne i nadpisania konfiguracji              |

Endpoint zwraca TwiML, który należy przekazać bezpośrednio do Twilio.

## Implementacja

```python
import os
from fastapi import FastAPI, Request
from fastapi.responses import Response
from elevenlabs import ElevenLabs

app = FastAPI()

elevenlabs = ElevenLabs()
AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")

@app.post("/twilio/inbound")
async def handle_inbound_call(request: Request):
    form_data = await request.form()
    from_number = form_data.get("From")
    to_number = form_data.get("To")

    # Register the call with ElevenLabs
    twiml = elevenlabs.conversational_ai.twilio.register_call(
        agent_id=AGENT_ID,
        from_number=from_number,
        to_number=to_number,
        direction="inbound",
        conversation_initiation_client_data={
            "dynamic_variables": {
                "caller_number": from_number,
            }
        }
    )

    # Return the TwiML directly to Twilio
    return Response(content=twiml, media_type="application/xml")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import express from "express";

const app = express();
app.use(express.urlencoded({ extended: true }));

const elevenlabs = new ElevenLabsClient();
const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

// Handle incoming Twilio calls
app.post("/twilio/inbound", async (req, res) => {
  const { From: fromNumber, To: toNumber } = req.body;

  // Register the call with ElevenLabs
  const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
    agentId: AGENT_ID,
    fromNumber,
    toNumber,
    direction: "inbound",
    conversationInitiationClientData: {
      dynamicVariables: {
        caller_number: fromNumber,
      },
    },
  });

  // Return the TwiML directly to Twilio
  res.type("application/xml").send(twiml);
});

app.listen(8000, () => {
  console.log("Server running on port 8000");
});
```

## Połączenia wychodzące

W przypadku połączeń wychodzących zainicjuj połączenie przez Twilio i skieruj adres URL webhooka na swój serwer, który następnie rejestruje je w ElevenLabs:

```python
from twilio.rest import Client
import os
from fastapi import Request
from fastapi.responses import Response
from elevenlabs import ElevenLabs

# Initialize clients
twilio_client = Client(
    os.getenv("TWILIO_ACCOUNT_SID"),
    os.getenv("TWILIO_AUTH_TOKEN")
)
elevenlabs = ElevenLabs()
AGENT_ID = os.getenv("ELEVENLABS_AGENT_ID")

def initiate_outbound_call(to_number: str):
    call = twilio_client.calls.create(
        from_=os.getenv("TWILIO_PHONE_NUMBER"),
        to=to_number,
        url="https://your-server.com/twilio/outbound"
    )
    return call.sid

@app.post("/twilio/outbound")
async def handle_outbound_webhook(request: Request):
    form_data = await request.form()
    from_number = form_data.get("From")
    to_number = form_data.get("To")

    twiml = elevenlabs.conversational_ai.twilio.register_call(
        agent_id=AGENT_ID,
        from_number=from_number,
        to_number=to_number,
        direction="outbound",
    )

    return Response(content=twiml, media_type="application/xml")
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import Twilio from "twilio";

// Initialize clients
const twilioClient = new Twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const elevenlabs = new ElevenLabsClient();
const AGENT_ID = process.env.ELEVENLABS_AGENT_ID;

// Initiate an outbound call
async function initiateOutboundCall(toNumber: string) {
  const call = await twilioClient.calls.create({
    from: process.env.TWILIO_PHONE_NUMBER,
    to: toNumber,
    url: "https://your-server.com/twilio/outbound",
  });
  return call.sid;
}

// Handle the Twilio webhook for outbound calls
app.post("/twilio/outbound", async (req, res) => {
  const { From: fromNumber, To: toNumber } = req.body;

  const twiml = await elevenlabs.conversationalAi.twilio.registerCall({
    agentId: AGENT_ID,
    fromNumber,
    toNumber,
    direction: "outbound",
  });

  res.type("application/xml").send(twiml);
});
```

## Personalizacja rozmów

Użyj parametru `conversation_initiation_client_data`, aby przekazać zmienne dynamiczne i nadpisać konfigurację agenta:

```json
{
  "agent_id": "your-agent-id",
  "from_number": "+1234567890",
  "to_number": "+0987654321",
  "direction": "inbound",
  "conversation_initiation_client_data": {
    "dynamic_variables": {
      "customer_name": "John Doe",
      "account_type": "premium",
      "order_id": "ORD-12345"
    }
  }
}
```

> **Info**
>
> Więcej informacji o zmiennych dynamicznych i nadpisaniach znajdziesz w dokumentacji dotyczącej [zmiennych dynamicznych](/docs/pl/eleven-agents/customization/personalization/dynamic-variables) oraz
> [nadpisań](/docs/pl/eleven-agents/customization/personalization/overrides).

## Konfiguracja Twilio

Skonfiguruj numer telefonu Twilio, aby wskazywał na twój serwer:

#### Utwórz publiczny URL

W lokalnym środowisku deweloperskim użyj [ngrok](https://ngrok.com), aby udostępnić serwer:

```bash
ngrok http 8000
```

#### Skonfiguruj numer Twilio

1. Przejdź do [konsoli Twilio](https://console.twilio.com)
2. Przejdź do Phone Numbers > Manage > Active numbers
3. Wybierz swój numer telefonu
4. W sekcji „Voice Configuration” ustaw adres URL webhooka na endpoint serwera (np. `https://your-ngrok-url.ngrok.app/twilio/inbound`)
5. Ustaw metodę HTTP na POST

![](/docs/_fern-img/510d09d492b0c6ac9966f8fe39a9da685df79e8108f6fbc55fe502f48f650084.webp)

## Ograniczenia

Podczas używania endpointu rejestrowania połączeń zamiast natywnej integracji:

* **Brak przekazywania połączeń**: Funkcja przekazywania nie jest dostępna, ponieważ ElevenLabs nie ma dostępu do twoich poświadczeń Twilio
* **Ręczna konfiguracja**: Musisz samodzielnie skonfigurować formaty audio i obsłużyć routing TwiML
* **Brak importu w panelu**: Numery telefonów zarejestrowane w ten sposób nie pojawiają się w panelu numerów telefonów ElevenLabs