> 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.

# Weryfikacja SMS OTP

![Rozmowa z agentem, podczas której zbierany jest numer telefonu, kod OTP i potwierdzenie weryfikacji](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp)

## Omówienie

Ten przewodnik pokazuje, jak zintegrować [Twilio Verify](https://www.twilio.com/docs/verify/api) z agentem ElevenLabs, aby wysyłać OTP na numer telefonu rozmówcy i weryfikować kod, który poda podczas rozmowy głosowej na żywo.

Dowiesz się, jak:

* Utworzyć usługę Twilio Verify i zakodować poświadczenia w Base64 na potrzeby uwierzytelniania.
* Skonfigurować dwa narzędzia webhook (`send_SMS_verification` i `check_SMS_verification`) w [panelu](https://elevenlabs.io/app/agents), za pomocą [Agents CLI](/docs/pl/eleven-agents/operate/cli) lub [API ElevenLabs](/docs/pl/api-reference/introduction).
* Uwierzytelniać oba wywołania webhooka nagłówkiem `Authorization` z tajną wartością.
* Włączyć narzędzie systemowe [`skip_turn`](/docs/pl/eleven-agents/customization/tools/system-tools/skip-turn), aby agent czekał, gdy rozmówca nie otrzymał jeszcze kodu.

## Wymagania wstępne

* Konto Twilio z włączoną usługą [Twilio Verify](https://www.twilio.com/docs/verify/api). Jeśli Verify nie jest dostępne w Twilio Console, poproś o dostęp przez [wsparcie Twilio](https://support.twilio.com/) lub zespół obsługi twojego konta Twilio.
* Jeśli twoje konto Twilio działa w [trybie próbnym](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), docelowy numer telefonu musi być zweryfikowanym caller ID w Twilio.

#### Zaloguj się do Twilio Console

Otwórz [Twilio Console](https://console.twilio.com/).

#### Utwórz usługę Authenticate (Verify)

Na lewym pasku bocznym wybierz **Add +** i utwórz usługę **Authenticate** (Verify).

#### Nazwij usługę

Nadaj jej opisową nazwę (na przykład `ElevenLabs OTP`).

#### Skopiuj Verify Service SID

Otwórz stronę **Settings** usługi i skopiuj **Verify Service SID**. Zaczyna się od `VA` i różni się od Account SID.

> **Warning**
>
> **Częsty błąd**: w adresach URL narzędzi poniżej użyj **Verify Service SID** (`VA...`) z usługi Authenticate (Verify). Nie umieszczaj w ścieżce **Account SID** (`AC...`). Verify API oczekuje SID usługi w adresie URL; użycie Account SID powoduje błędy `4xx` nieprawidłowego parametru.

Możesz użyć Twilio API Explorer w konsoli, aby przetestować żądania przed podpięciem ich do agenta.

### Zakoduj dane logowania i skonfiguruj narzędzia webhook

#### Zakoduj dane logowania Twilio do uwierzytelniania Basic

Twilio Verify używa uwierzytelniania HTTP Basic z **Account SID** jako nazwą użytkownika i **Auth Token** jako hasłem. Oba znajdziesz w sekcji **Account Info** na stronie głównej [Twilio Console](https://console.twilio.com/).

W terminalu zakoduj Base64 `ACCOUNT_SID:AUTH_TOKEN` (rozdzielone dwukropkiem, bez spacji):

```bash
printf '%s' 'YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN' | base64
```

Skopiuj wynik. Pełna wartość nagłówka `Authorization` to słowo `Basic`, pojedyncza spacja i ten ciąg Base64. Zapisz ją jako sekret narzędzia w kolejnych krokach.

```text
Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
```

#### Skonfiguruj narzędzia \`send_SMS_verification\` i \`check_SMS_verification\`

`send_SMS_verification` wywołuje Twilio Verify, aby wysłać SMS z OTP. `check_SMS_verification` przesyła cyfry podane przez rozmówcę. Oba wymagają tego samego Verify Service SID i sekretu `Authorization`.

#### Dodaj przez panel

### send_SMS_verification

![Rozmowa agenta zbierająca numer telefonu, kod OTP i potwierdzająca weryfikację](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp)

W sekcji **Agent** ustawień agenta wybierz **Add Tool**, a następnie **Webhook**.

| Pole   | Wartość                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| Nazwa  | `send_SMS_verification`                                                       |
| Opis   | Wysyła kod weryfikacyjny OTP przez SMS na podany numer telefonu               |
| Metoda | `POST`                                                                        |
| URL    | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications` |

Zastąp `YOUR_VERIFY_SERVICE_SID` identyfikatorem SID `VA...` z pierwszego kroku.

**Nagłówek uwierzytelniania:** w sekcji **Headers** dodaj `Authorization` jako typ **Secret** i wklej pełną wartość (`Basic ` oraz Base64). Zobacz [Narzędzia webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools).

**Parametry body:** ustaw **Content type** na **URL-encoded** (`application/x-www-form-urlencoded`). Dodaj parametry, ustawiając **LLM Prompt** jako typ wartości:

| Typ danych | Identyfikator | Opis                                                                  |
| ---------- | ------------- | --------------------------------------------------------------------- |
| `string`   | `To`          | Numer telefonu rozmówcy w formacie E.164 (na przykład `+14155552671`) |
| `string`   | `Channel`     | Kanał dostawy; użyj `sms`                                             |

### check_SMS_verification

Dodaj drugie narzędzie webhook:

| Pole   | Wartość                                                                           |
| ------ | --------------------------------------------------------------------------------- |
| Nazwa  | `check_SMS_verification`                                                          |
| Opis   | Sprawdza, czy kod OTP podany przez rozmówcę jest prawidłowy                       |
| Metoda | `POST`                                                                            |
| URL    | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck` |

Użyj tego samego Verify Service SID i sekretu `Authorization` co dla `send_SMS_verification`.

**Parametry body:** **URL-encoded**. Dodaj `To` (E.164) i `Code` (cyfry OTP), używając **LLM Prompt**.

#### Dodaj przez CLI

> **Note**
>
> Utwórz [sekret workspace](/docs/pl/api-reference/workspace/secrets/create), którego wartością będzie pełny nagłówek `Authorization` (`Basic ` oraz Base64). Wstaw identyfikator sekretu w JSON poniżej jako `YOUR_SECRET_ID`.

#### Dodaj pliki konfiguracji narzędzi

Zapisz narzędzie wysyłające jako `tool_configs/send_SMS_verification.json` (zastąp `YOUR_VERIFY_SERVICE_SID` swoim SID `VA...`):

```json
{
  "type": "webhook",
  "name": "send_SMS_verification",
  "description": "Sends an OTP verification code via SMS to the provided phone number",
  "api_schema": {
    "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications",
    "method": "POST",
    "content_type": "application/x-www-form-urlencoded",
    "request_headers": {
      "Authorization": { "secret_id": "YOUR_SECRET_ID" }
    },
    "request_body_schema": {
      "type": "object",
      "description": "Twilio Verify start verification parameters",
      "required": ["To", "Channel"],
      "properties": {
        "To": {
          "type": "string",
          "description": "Caller phone number in E.164 format (for example +14155552671)"
        },
        "Channel": {
          "type": "string",
          "constant_value": "sms"
        }
      }
    }
  }
}
```

Zapisz narzędzie sprawdzające jako `tool_configs/check_SMS_verification.json`:

```json
{
  "type": "webhook",
  "name": "check_SMS_verification",
  "description": "Checks whether the OTP code provided by the caller is valid",
  "api_schema": {
    "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck",
    "method": "POST",
    "content_type": "application/x-www-form-urlencoded",
    "request_headers": {
      "Authorization": { "secret_id": "YOUR_SECRET_ID" }
    },
    "request_body_schema": {
      "type": "object",
      "description": "Twilio Verify verification check parameters",
      "required": ["To", "Code"],
      "properties": {
        "To": {
          "type": "string",
          "description": "Same caller number in E.164 format"
        },
        "Code": {
          "type": "string",
          "description": "The OTP digits the caller provided"
        }
      }
    }
  }
}
```

#### Zarejestruj narzędzia

```bash
elevenlabs tools add "send_SMS_verification" --type "webhook" --config-path ./tool_configs/send_SMS_verification.json
elevenlabs tools add "check_SMS_verification" --type "webhook" --config-path ./tool_configs/check_SMS_verification.json
```

#### Podepnij narzędzia do agenta

Edytuj `agent_configs/<agent-name>.json`. W sekcji `conversation_config.agent.prompt` ustaw `tool_ids`, aby obejmowało oba narzędzia (użyj identyfikatorów z `tools.json` lub z `elevenlabs agents tools list`). Następnie wyślij zmiany:

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Dodaj przez API

> **Note**
>
> Utwórz [sekret workspace](/docs/pl/api-reference/workspace/secrets/create) zawierający pełną wartość nagłówka `Basic ...`, a potem przekaż jego identyfikator jako `secret_id` w `request_headers`.

```python
from elevenlabs import ElevenLabs, ToolRequestModel

elevenlabs = ElevenLabs()

send_sms = elevenlabs.conversational_ai.tools.create(
    request=ToolRequestModel(
        tool_config={
            "type": "webhook",
            "name": "send_SMS_verification",
            "description": "Sends an OTP verification code via SMS to the provided phone number",
            "api_schema": {
                "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications",
                "method": "POST",
                "content_type": "application/x-www-form-urlencoded",
                "request_headers": {
                    "Authorization": {"secret_id": "YOUR_SECRET_ID"},
                },
                "request_body_schema": {
                    "type": "object",
                    "description": "Twilio Verify start verification parameters",
                    "required": ["To", "Channel"],
                    "properties": {
                        "To": {
                            "type": "string",
                            "description": "Caller phone number in E.164 format (for example +14155552671)",
                        },
                        "Channel": {
                            "type": "string",
                            "constant_value": "sms",
                        },
                    },
                },
            },
        }
    )
)

check_sms = elevenlabs.conversational_ai.tools.create(
    request=ToolRequestModel(
        tool_config={
            "type": "webhook",
            "name": "check_SMS_verification",
            "description": "Checks whether the OTP code provided by the caller is valid",
            "api_schema": {
                "url": "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck",
                "method": "POST",
                "content_type": "application/x-www-form-urlencoded",
                "request_headers": {
                    "Authorization": {"secret_id": "YOUR_SECRET_ID"},
                },
                "request_body_schema": {
                    "type": "object",
                    "description": "Twilio Verify verification check parameters",
                    "required": ["To", "Code"],
                    "properties": {
                        "To": {
                            "type": "string",
                            "description": "Same caller number in E.164 format",
                        },
                        "Code": {
                            "type": "string",
                            "description": "The OTP digits the caller provided",
                        },
                    },
                },
            },
        }
    )
)

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "prompt": {
                "tool_ids": [send_sms.id, check_sms.id],
            },
        },
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

const sendSms = await elevenlabs.conversationalAi.tools.create({
  toolConfig: {
    type: "webhook",
    name: "send_SMS_verification",
    description: "Sends an OTP verification code via SMS to the provided phone number",
    apiSchema: {
      url: "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications",
      method: "POST",
      contentType: "application/x-www-form-urlencoded",
      requestHeaders: {
        Authorization: { secretId: "YOUR_SECRET_ID" },
      },
      requestBodySchema: {
        type: "object",
        description: "Twilio Verify start verification parameters",
        required: ["To", "Channel"],
        properties: {
          To: {
            type: "string",
            description: "Caller phone number in E.164 format (for example +14155552671)",
          },
          Channel: {
            type: "string",
            constantValue: "sms",
          },
        },
      },
    },
  },
});

const checkSms = await elevenlabs.conversationalAi.tools.create({
  toolConfig: {
    type: "webhook",
    name: "check_SMS_verification",
    description: "Checks whether the OTP code provided by the caller is valid",
    apiSchema: {
      url: "https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck",
      method: "POST",
      contentType: "application/x-www-form-urlencoded",
      requestHeaders: {
        Authorization: { secretId: "YOUR_SECRET_ID" },
      },
      requestBodySchema: {
        type: "object",
        description: "Twilio Verify verification check parameters",
        required: ["To", "Code"],
        properties: {
          To: {
            type: "string",
            description: "Same caller number in E.164 format",
          },
          Code: {
            type: "string",
            description: "The OTP digits the caller provided",
          },
        },
      },
    },
  },
});

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      prompt: {
        toolIds: [sendSms.id, checkSms.id],
      },
    },
  },
});
```

> **Note**
>
> Jeśli skonfigurujesz **`Channel`** jako pole wypełniane przez LLM w panelu, dodaj instrukcje w system prompt, aby model zawsze przekazywał `sms`. Przykłady CLI i API powyżej ustawiają `sms` na stałe przez `constant_value` / `constantValue`, więc model nie wybiera kanału.

#### Włącz narzędzie systemowe \`skip_turn\`

Rozmówcy często potrzebują chwili, aby otrzymać SMS, zanim odczytają kod. Bez `skip_turn` agent może mówić podczas pauzy lub powtarzać komunikaty.

#### Dodaj przez panel

W sekcji **Tools** wybierz **Add Tool**, zaznacz **System tool** i włącz **Skip turn**. Nie wymaga to dalszej konfiguracji.

#### Dodaj przez CLI

W pliku `agent_configs/<agent-name>.json`, w sekcji `conversation_config.agent.prompt`, ustaw `built_in_tools.skip_turn` na `null` (ustawienia domyślne), aby włączyć Skip turn, a następnie uruchom:

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Dodaj przez API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "prompt": {
                "built_in_tools": {
                    "skip_turn": None,
                },
            },
        },
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      prompt: {
        builtInTools: {
          skipTurn: null,
        },
      },
    },
  },
});
```

Jeśli podczas tworzenia narzędzi webhook ustawiłeś już `tool_ids`, dodaj `built_in_tools` do tego samego obiektu `prompt`, zamiast go zastępować.

Dodaj wskazówki do system prompt, aby model wiedział, kiedy wywołać to narzędzie, na przykład:

```text
When the caller indicates they are still waiting to receive the OTP code — for example,
"hold on", "I haven't received it yet", or "give me a second" — use the skip_turn tool
to wait silently rather than speaking. Do not repeat the prompt or ask for the code again
until the caller indicates they are ready.
```

Szczegóły znajdziesz w artykule [Skip turn](/docs/pl/eleven-agents/customization/tools/system-tools/skip-turn).

#### Zarządzaj przebiegiem w system prompt

Użyj system prompt, który jasno określa kolejność użycia narzędzi, na przykład:

```text
You are a secure verification agent. When you need to verify a caller's identity:

1. Ask for their phone number if you do not already have it.
2. Standardize the number to E.164 for tool calls: a leading plus, country code, then digits only, no spaces (for example +14155552671).
3. Call send_SMS_verification with their number and Channel set to "sms".
4. Tell the caller: "I've sent a verification code to your phone. Please read it out when you're ready."
5. If the caller says they haven't received the code yet or asks for a moment, use skip_turn to wait silently.
6. Once the caller provides the code, call check_SMS_verification with their number and the code.
7. If the response status is "approved", proceed with the verified flow.
8. If the code is invalid, let the caller know and offer to resend.
```

## Rozwiązywanie problemów

### Twilio `60200` — Nieprawidłowy parametr (HTTP 400)

Twilio może zwrócić taką odpowiedź, gdy URL żądania lub jego treść nie odpowiadają temu, czego oczekuje Verify API:

```json
{
  "code": 60200,
  "message": "Invalid parameter",
  "more_info": "https://www.twilio.com/docs/errors/60200",
  "status": 400
}
```

**Co sprawdzić:** Ścieżka musi używać **Verify Service SID** (`VA...`) z ustawień usługi Authenticate (Verify). Umieszczenie **Account SID** (`AC...`) w `.../Services/{Sid}/...` to częsta przyczyna błędu `60200`. Inne przypadki nieprawidłowych parametrów znajdziesz w dokumentacji Twilio dotyczącej [60200](https://www.twilio.com/docs/errors/60200).

### Twilio `20003` — Błąd uwierzytelniania — Nie podano danych logowania (HTTP 401)

Gdy nagłówek `Authorization` jest nieobecny, nieprawidłowy lub nie został wysłany, Twilio może odpowiedzieć:

```json
{
  "code": 20003,
  "message": "Authentication Error - No credentials provided",
  "more_info": "https://www.twilio.com/docs/errors/20003",
  "status": 401
}
```

**Co sprawdzić:** Narzędzie musi wysyłać nagłówek `Authorization`, którego wartością jest pełny ciąg `Basic <base64>` (w tym słowo `Basic` i pojedyncza spacja przed wynikiem Base64). Dane wejściowe Base64 muszą mieć dokładnie format `ACCOUNT_SID:AUTH_TOKEN`, bez dodatkowych spacji ani nowych linii. Upewnij się, że sekret jest przypisany do tego nagłówka w obu narzędziach webhook. Zobacz [20003](https://www.twilio.com/docs/errors/20003).

### Inne problemy

* **Numer odrzucony w trybie próbnym:** W konsoli Twilio otwórz [Verified phone numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) i przed testem upewnij się, że numer docelowy jest na liście.
* **Agent mówi jednocześnie z rozmówcą:** Upewnij się, że **Skip turn** jest włączone, a prompt systemowy mówi modelowi, by używał `skip_turn`, gdy rozmówca potrzebuje czasu.