Weryfikacja SMS OTP

Omówienie

Ten przewodnik pokazuje, jak zintegrować Twilio Verify 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, za pomocą Agents CLI lub API ElevenLabs.
• Uwierzytelniać oba wywołania webhooka nagłówkiem Authorization z tajną wartością.
• Włączyć narzędzie systemowe skip_turn, aby agent czekał, gdy rozmówca nie otrzymał jeszcze kodu.

Wymagania wstępne

• Konto Twilio z włączoną usługą Twilio Verify. Jeśli Verify nie jest dostępne w Twilio Console, poproś o dostęp przez wsparcie Twilio lub zespół obsługi twojego konta Twilio.
• Jeśli twoje konto Twilio działa w trybie próbnym, docelowy numer telefonu musi być zweryfikowanym caller ID w Twilio.

Zakoduj dane logowania i skonfiguruj narzędzia webhook

1

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.

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

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.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

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

Dodaj przez CLI

Dodaj przez API

send_SMS_verification

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.

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.

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.

3

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

Dodaj przez CLI

Dodaj przez API

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

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

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.

4

Zarządzaj przebiegiem w system prompt

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

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:

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

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ć:

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

Inne problemy

• Numer odrzucony w trybie próbnym: W konsoli Twilio otwórz Verified phone numbers 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.