> 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. # SMS-OTP-Verifizierung ![Agentenkonversation zur Erfassung einer Telefonnummer, eines OTP-Codes und einer erfolgreichen Verifizierung](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp) ## Übersicht In diesem Leitfaden erfahren Sie, wie Sie [Twilio Verify](https://www.twilio.com/docs/verify/api) in Ihren ElevenLabs-Agenten integrieren, damit Sie ein OTP an die Telefonnummer eines Anrufers senden und den Code verifizieren können, den dieser während einer Live-Sprachkonversation nennt. Sie erfahren, wie Sie: * einen Twilio-Verify-Service erstellen und Ihre Anmeldedaten für die Authentifizierung Base64-kodieren. * zwei Webhook-Tools (`send_SMS_verification` und `check_SMS_verification`) im [Dashboard](https://elevenlabs.io/app/agents), mit der [Agents CLI](/docs/de/eleven-agents/operate/cli) oder über die [ElevenLabs API](/docs/de/api-reference/introduction) konfigurieren. * beide Webhook-Aufrufe mit einem `Authorization`-Header und einem geheimen Wert authentifizieren. * das System-Tool [`skip_turn`](/docs/de/eleven-agents/customization/tools/system-tools/skip-turn) aktivieren, damit der Agent wartet, wenn der Anrufer den Code noch nicht erhalten hat. ## Voraussetzungen * Ein Twilio-Konto mit aktiviertem [Twilio Verify](https://www.twilio.com/docs/verify/api). Falls Verify in Ihrer Twilio Console nicht verfügbar ist, beantragen Sie Zugriff über den [Twilio-Support](https://support.twilio.com/) oder Ihr Twilio-Kontoteam. * Befindet sich Ihr Twilio-Konto im [Testmodus](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), muss die Zieltelefonnummer eine verifizierte Anrufer-ID in Twilio sein. #### Bei der Twilio Console anmelden Öffnen Sie die [Twilio Console](https://console.twilio.com/). #### Authenticate-(Verify)-Service erstellen Wählen Sie in der linken Seitenleiste **Add +** und erstellen Sie einen **Authenticate**-Service (Verify). #### Service benennen Geben Sie ihm einen aussagekräftigen Namen, z. B. `ElevenLabs OTP`. #### Verify Service SID kopieren Öffnen Sie die Seite **Settings** des Service und kopieren Sie die **Verify Service SID**. Sie beginnt mit `VA` und unterscheidet sich von Ihrer Account SID. > **Warning** > > **Häufiger Fehler**: Verwenden Sie in den untenstehenden Tool-URLs die **Verify Service SID** (`VA...`) des Authenticate-(Verify)-Service. Tragen Sie nicht Ihre **Account SID** (`AC...`) in den Pfad ein. Die Verify API erwartet die Service SID in der URL; mit der Account SID entstehen ungültige Parameterfehler vom Typ `4xx`. Mit dem Twilio API Explorer in der Console können Sie Anfragen testen, bevor Sie sie mit Ihrem Agenten verknüpfen. ### Zugangsdaten codieren und Webhook-Tools konfigurieren #### Twilio-Zugangsdaten für die Basic-Authentifizierung codieren Twilio Verify verwendet HTTP-Basic-Authentifizierung mit Ihrer **Account SID** als Benutzername und Ihrem **Auth Token** als Passwort. Beide finden Sie unter **Account Info** auf der Startseite der [Twilio Console](https://console.twilio.com/). Codieren Sie in Ihrer Shell `ACCOUNT_SID:AUTH_TOKEN` mit Base64 (durch Doppelpunkt getrennt, ohne Leerzeichen): ```bash printf '%s' 'YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN' | base64 ``` Kopieren Sie die Ausgabe. Der vollständige Wert des Headers `Authorization` besteht aus dem Wort `Basic`, einem einzelnen Leerzeichen und diesem Base64-String. Speichern Sie ihn in den nächsten Schritten als Tool-Secret. ```text Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx== ``` #### Tools \`send_SMS_verification\` und \`check_SMS_verification\` konfigurieren `send_SMS_verification` ruft Twilio Verify auf, um ein SMS-OTP zu senden. `check_SMS_verification` übermittelt die Ziffern, die der Anrufer nennt. Beide benötigen dieselbe Verify Service SID und dasselbe `Authorization`-Secret. #### Über das Dashboard hinzufügen ### send_SMS_verification ![Agentengespräch zur Erfassung einer Telefonnummer, eines OTP-Codes und der erfolgreichen Verifizierung](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp) Wählen Sie im Bereich **Agent** Ihrer Agenteneinstellungen **Add Tool** und anschließend **Webhook**. | Feld | Wert | | ------------ | ----------------------------------------------------------------------------- | | Name | `send_SMS_verification` | | Beschreibung | Sendet einen OTP-Bestätigungscode per SMS an die angegebene Telefonnummer | | Methode | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications` | Ersetzen Sie `YOUR_VERIFY_SERVICE_SID` durch die `VA...`-SID aus dem ersten Schritt. **Authentifizierungs-Header:** Fügen Sie unter **Headers** `Authorization` als Typ **Secret** hinzu und fügen Sie den vollständigen Wert ein (`Basic ` plus Base64). Siehe [Webhook-Tools](/docs/de/eleven-agents/customization/tools/webhook-tools). **Body-Parameter:** Setzen Sie **Content type** auf **URL-encoded** (`application/x-www-form-urlencoded`). Fügen Sie Parameter mit **LLM Prompt** als Werttyp hinzu: | Datentyp | Bezeichner | Beschreibung | | -------- | ---------- | ----------------------------------------------------------------- | | `string` | `To` | Telefonnummer des Anrufers im E.164-Format (z. B. `+14155552671`) | | `string` | `Channel` | Zustellkanal; verwenden Sie `sms` | ### check_SMS_verification Fügen Sie ein zweites Webhook-Tool hinzu: | Feld | Wert | | ------------ | --------------------------------------------------------------------------------- | | Name | `check_SMS_verification` | | Beschreibung | Prüft, ob der vom Anrufer angegebene OTP-Code gültig ist | | Methode | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck` | Verwenden Sie dieselbe Verify Service SID und dasselbe `Authorization`-Secret wie für `send_SMS_verification`. **Body-Parameter:** **URL-encoded**. Fügen Sie `To` (E.164) und `Code` (OTP-Ziffern) mit **LLM Prompt** hinzu. #### Über die CLI hinzufügen > **Note** > > Erstellen Sie ein [Workspace-Secret](/docs/de/api-reference/workspace/secrets/create), dessen Wert der vollständige `Authorization`-Header ist (`Basic ` plus Base64). Tragen Sie die Secret-ID im folgenden JSON als `YOUR_SECRET_ID` ein. #### Tool-Konfigurationsdateien hinzufügen Speichern Sie das Sende-Tool als `tool_configs/send_SMS_verification.json` (ersetzen Sie `YOUR_VERIFY_SERVICE_SID` durch Ihre `VA...`-SID): ```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" } } } } } ``` Speichern Sie das Prüf-Tool als `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" } } } } } ``` #### Tools registrieren ```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 ``` #### Tools mit Ihrem Agenten verknüpfen Bearbeiten Sie `agent_configs/.json`. Setzen Sie unter `conversation_config.agent.prompt` `tool_ids` so, dass beide Tools enthalten sind (verwenden Sie die IDs aus `tools.json` oder aus `elevenlabs agents tools list`). Führen Sie dann den Push aus: ```bash elevenlabs agents push --agent "" ``` #### Über die API hinzufügen > **Note** > > Erstellen Sie ein [Workspace-Secret](/docs/de/api-reference/workspace/secrets/create), das den vollständigen Headerwert `Basic ...` enthält, und übergeben Sie dann seine ID als `secret_id` in `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** > > Wenn Sie **`Channel`** im Dashboard als vom LLM ausgefülltes Feld konfigurieren, fügen Sie Ihrem System-Prompt Anweisungen hinzu, damit das Modell immer `sms` übergibt. Die obigen CLI- und API-Beispiele setzen `sms` mit `constant_value` / `constantValue` fest, sodass das Modell den Kanal nicht auswählt. #### System-Tool \`skip_turn\` aktivieren Anrufer benötigen oft einen Moment, um die SMS zu erhalten, bevor sie den Code vorlesen können. Ohne `skip_turn` kann der Agent in die Pause hineinsprechen oder Aufforderungen wiederholen. #### Über das Dashboard hinzufügen Wählen Sie unter **Tools** **Add Tool**, dann **System tool**, und aktivieren Sie **Skip turn**. Weitere Konfiguration ist nicht erforderlich. #### Über die CLI hinzufügen Setzen Sie in `agent_configs/.json` unter `conversation_config.agent.prompt` `built_in_tools.skip_turn` auf `null` (Standardwerte), damit Skip turn aktiviert ist, und führen Sie dann Folgendes aus: ```bash elevenlabs agents push --agent "" ``` #### Über die API hinzufügen ```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, }, }, }, }, }); ``` Falls Sie beim Erstellen der Webhook-Tools bereits `tool_ids` gesetzt haben, fügen Sie `built_in_tools` in dasselbe `prompt`-Objekt ein, statt es zu ersetzen. Fügen Sie dem System-Prompt Hinweise hinzu, damit das Modell weiß, wann es das Tool aufrufen soll, zum Beispiel: ```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. ``` Weitere Informationen finden Sie unter [Skip turn](/docs/de/eleven-agents/customization/tools/system-tools/skip-turn). #### Ablauf im System-Prompt orchestrieren Verwenden Sie einen System-Prompt, der die Tools klar in Reihenfolge bringt, zum Beispiel: ```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. ``` ## Fehlerbehebung ### Twilio `60200` — Ungültiger Parameter (HTTP 400) Twilio gibt möglicherweise einen solchen Text zurück, wenn die Anfrage-URL oder der -Text nicht den Erwartungen der Verify API entspricht: ```json { "code": 60200, "message": "Invalid parameter", "more_info": "https://www.twilio.com/docs/errors/60200", "status": 400 } ``` **Prüfen Sie Folgendes:** Der Pfad muss Ihre **Verify Service SID** (`VA...`) aus den Einstellungen des Authenticate-(Verify-)Dienstes verwenden. Wenn Sie Ihre **Account SID** (`AC...`) in `.../Services/{Sid}/...` einfügen, ist das eine häufige Ursache für `60200`. Weitere Fälle ungültiger Parameter finden Sie in der Twilio-Dokumentation zu [60200](https://www.twilio.com/docs/errors/60200). ### Twilio `20003` — Authentifizierungsfehler — Keine Zugangsdaten angegeben (HTTP 401) Wenn der Header `Authorization` fehlt, fehlerhaft formatiert ist oder nicht gesendet wird, kann Twilio Folgendes zurückgeben: ```json { "code": 20003, "message": "Authentication Error - No credentials provided", "more_info": "https://www.twilio.com/docs/errors/20003", "status": 401 } ``` **Prüfen Sie Folgendes:** Das Tool muss einen `Authorization`-Header senden, dessen Wert der vollständige String `Basic ` ist (einschließlich des Worts `Basic` und eines einzelnen Leerzeichens vor der Base64-Ausgabe). Die Base64-Eingabe muss exakt `ACCOUNT_SID:AUTH_TOKEN` entsprechen, ohne zusätzliche Leerzeichen oder Zeilenumbrüche. Stellen Sie sicher, dass das Secret bei beiden Webhook-Tools diesem Header zugeordnet ist. Siehe [20003](https://www.twilio.com/docs/errors/20003). ### Weitere Probleme * **Nummer im Testmodus abgelehnt:** Öffnen Sie in der Twilio Console [Verified phone numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) und stellen Sie vor dem Test sicher, dass die Zielnummer aufgeführt ist. * **Der Agent spricht über den Anrufer hinweg:** Stellen Sie sicher, dass **Skip turn** aktiviert ist und der System-Prompt das Modell anweist, `skip_turn` zu verwenden, wenn der Anrufer Zeit braucht.