> 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認証 ![電話番号、OTPコード、認証成功を確認するエージェントとの会話](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp) ## 概要 このガイドでは、[Twilio Verify](https://www.twilio.com/docs/verify/api)をElevenLabsエージェントと統合し、発信者の電話番号にOTPを送信して、ライブ音声会話中に読み上げられたコードを認証する方法を説明します。 以下の方法を学べます。 * Twilio Verifyサービスを作成し、認証用に認証情報をBase64エンコードする。 * [ダッシュボード](https://elevenlabs.io/app/agents)、[Agents CLI](/docs/ja/eleven-agents/operate/cli)、または[ElevenLabs API](/docs/ja/api-reference/introduction)で、2つのWebhookツール（`send_SMS_verification`と`check_SMS_verification`）を設定する。 * シークレット値を含む`Authorization`ヘッダーを使用して、両方のWebhook呼び出しを認証する。 * 発信者がまだコードを受け取っていない場合にエージェントが待機するよう、[`skip_turn`](/docs/ja/eleven-agents/customization/tools/system-tools/skip-turn)システムツールを有効にする。 ## 前提条件 * [Twilio Verify](https://www.twilio.com/docs/verify/api)が有効になっているTwilioアカウント。Twilio ConsoleでVerifyを利用できない場合は、[Twilioサポート](https://support.twilio.com/)またはTwilioのアカウントチームにアクセスをリクエストしてください。 * Twilioアカウントが[トライアルモード](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account)の場合、宛先電話番号はTwilioで確認済みの発信者IDである必要があります。 #### Twilio Consoleにログイン [Twilio Console](https://console.twilio.com/)を開きます。 #### Authenticate（Verify）サービスを作成 左側のサイドバーで\*\*Add +\*\*を選択し、**Authenticate**（Verify）サービスを作成します。 #### サービスに名前を付ける わかりやすい名前を付けます（例：`ElevenLabs OTP`）。 #### Verify Service SIDをコピー サービスの**Settings**ページを開き、**Verify Service SID**をコピーします。`VA`で始まり、Account SIDとは異なります。 > **Warning** > > **よくある間違い**：以下のツールURLでは、Authenticate（Verify）サービスの**Verify Service SID**（`VA...`）を使用してください。パスに**Account SID**（`AC...`）を入力しないでください。Verify APIはURL内のサービスSIDを想定しているため、Account SIDを使用すると`4xx`の無効なパラメーターエラーが発生します。 エージェントにリクエストを接続する前に、ConsoleのTwilio API Explorerでテストできます。 ### 認証情報をエンコードしてWebhookツールを設定 #### Basic認証用にTwilio認証情報をエンコード Twilio Verifyでは、**Account SID**をユーザー名、**Auth Token**をパスワードとしてHTTP Basic認証を使用します。どちらも[Twilio Console](https://console.twilio.com/)のホームページにある**Account Info**で確認できます。 シェルで、`ACCOUNT_SID:AUTH_TOKEN`をBase64エンコードします（コロン区切り、スペースなし）。 ```bash printf '%s' 'YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN' | base64 ``` 出力をコピーします。`Authorization`ヘッダーの完全な値は、`Basic`という単語、半角スペース1つ、およびそのBase64文字列です。次の手順でツールシークレットとして保存します。 ```text Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx== ``` #### \`send_SMS_verification\`ツールと\`check_SMS_verification\`ツールを設定 `send_SMS_verification`はTwilio Verifyを呼び出してSMS OTPを送信します。`check_SMS_verification`は発信者が口頭で伝えた数字を送信します。どちらも同じVerify Service SIDと同じ`Authorization`シークレットが必要です。 #### ダッシュボードから追加 ### send_SMS_verification ![電話番号、OTPコード、認証成功を収集するエージェントとの会話](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp) エージェント設定の**Agent**セクションで、**Add Tool**を選択し、**Webhook**を選択します。 | フィールド | 値 | | ----- | ----------------------------------------------------------------------------- | | 名前 | `send_SMS_verification` | | 説明 | 指定された電話番号にSMSでOTP認証コードを送信 | | メソッド | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications` | `YOUR_VERIFY_SERVICE_SID`を、最初の手順で取得した`VA...` SIDに置き換えます。 **認証ヘッダー：** **Headers**で、タイプを**Secret**として`Authorization`を追加し、完全な値（`Basic `とBase64）を貼り付けます。[Webhookツール](/docs/ja/eleven-agents/customization/tools/webhook-tools)を参照してください。 **本文パラメーター：** **Content type**を**URL-encoded**（`application/x-www-form-urlencoded`）に設定します。値のタイプとして**LLM Prompt**を指定し、パラメーターを追加します。 | データ型 | 識別子 | 説明 | | -------- | --------- | --------------------------------- | | `string` | `To` | E.164形式の発信者電話番号（例：`+14155552671`） | | `string` | `Channel` | 配信チャネル。`sms`を使用 | ### check_SMS_verification 2つ目のWebhookツールを追加します。 | フィールド | 値 | | ----- | --------------------------------------------------------------------------------- | | 名前 | `check_SMS_verification` | | 説明 | 発信者が指定したOTPコードが有効かどうかを確認 | | メソッド | `POST` | | URL | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck` | `send_SMS_verification`と同じVerify Service SIDおよび同じ`Authorization`シークレットを使用します。 **本文パラメーター：** **URL-encoded**。**LLM Prompt**を使用して、`To`（E.164）と`Code`（OTPの数字）を追加します。 #### CLIから追加 > **Note** > > 完全な`Authorization`ヘッダー（`Basic `とBase64）を値とする[ワークスペースシークレット](/docs/ja/api-reference/workspace/secrets/create)を作成します。以下のJSONでは、シークレットIDを`YOUR_SECRET_ID`として指定してください。 #### ツール設定ファイルを追加 送信用ツールを`tool_configs/send_SMS_verification.json`として保存します（`YOUR_VERIFY_SERVICE_SID`を`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" } } } } } ``` 確認用ツールを`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" } } } } } ``` #### ツールを登録 ```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 ``` #### ツールをエージェントに接続 `agent_configs/.json`を編集します。`conversation_config.agent.prompt`の`tool_ids`に両方のツールを含めます（`tools.json`または`elevenlabs agents tools list`のIDを使用してください）。その後、プッシュします。 ```bash elevenlabs agents push --agent "" ``` #### APIから追加 > **Note** > > 完全な`Basic ...`ヘッダー値を含む[ワークスペースシークレット](/docs/ja/api-reference/workspace/secrets/create)を作成し、そのIDを`request_headers`内の`secret_id`として渡します。 ```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** > > ダッシュボードで\*\*`Channel`\*\*をLLM入力フィールドとして設定する場合は、モデルが常に`sms`を渡すよう、システムプロンプトに指示を追加してください。上記のCLIおよびAPIの例では、`constant_value`／`constantValue`で`sms`を固定しているため、モデルがチャネルを選択することはありません。 #### \`skip_turn\`システムツールを有効化 発信者がSMSを受信してコードを確認するまでには、少し時間がかかることがあります。`skip_turn`がないと、エージェントが間を埋めて話したり、プロンプトを繰り返したりする可能性があります。 #### ダッシュボードから追加 **Tools**で**Add Tool**を選択し、**System tool**を選んで**Skip turn**を有効にします。追加の設定は不要です。 #### CLIから追加 `agent_configs/.json`の`conversation_config.agent.prompt`で、Skip turnを有効にするために`built_in_tools.skip_turn`を`null`（デフォルト）に設定し、次を実行します。 ```bash elevenlabs agents push --agent "" ``` #### 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, }, }, }, }, }); ``` Webhookツールの作成時にすでに`tool_ids`を設定している場合は、置き換えるのではなく、同じ`prompt`オブジェクトに`built_in_tools`を統合してください。 モデルが呼び出すタイミングを認識できるよう、次のようなガイダンスをシステムプロンプトに追加します。 ```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. ``` 詳しくは[Skip turn](/docs/ja/eleven-agents/customization/tools/system-tools/skip-turn)を参照してください。 #### システムプロンプトでフローをオーケストレーション 次の例のように、ツールの順序を明確にしたシステムプロンプトを使用します。 ```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. ``` ## トラブルシューティング ### Twilio `60200` — 無効なパラメーター（HTTP 400） リクエストURLまたは本文がVerify APIの想定と一致しない場合、Twilioから次のような本文が返されることがあります： ```json { "code": 60200, "message": "Invalid parameter", "more_info": "https://www.twilio.com/docs/errors/60200", "status": 400 } ``` **確認すること：** パスには、Authenticate（Verify）サービス設定の**Verify Service SID**（`VA...`）を使用する必要があります。`.../Services/{Sid}/...`に**Account SID**（`AC...`）を指定すると、`60200`が発生することがよくあります。その他の無効なパラメーターのケースについては、Twilioの[60200](https://www.twilio.com/docs/errors/60200)ドキュメントを参照してください。 ### Twilio `20003` — 認証エラー — 認証情報が提供されていません（HTTP 401） `Authorization`ヘッダーがない、形式が正しくない、または送信されていない場合、Twilioは次のように応答することがあります： ```json { "code": 20003, "message": "Authentication Error - No credentials provided", "more_info": "https://www.twilio.com/docs/errors/20003", "status": 401 } ``` **確認すること：** ツールは、完全な`Basic `文字列（`Basic`という語と、その後にBase64出力の前の半角スペース1つを含む）を値とする`Authorization`ヘッダーを送信する必要があります。Base64入力は、余分なスペースや改行なしで、正確に`ACCOUNT_SID:AUTH_TOKEN`でなければなりません。両方のWebhookツールで、このヘッダーにシークレットが設定されていることを確認してください。[20003](https://www.twilio.com/docs/errors/20003)も参照してください。 ### その他の問題 * **トライアルモードで番号が拒否される：** Twilio Consoleで[Verified phone numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/verified)を開き、テスト前に宛先番号が一覧に登録されていることを確認してください。 * **エージェントが発信者にかぶせて話す：** **Skip turn**が有効になっていること、および発信者に時間が必要な場合はモデルが`skip_turn`を使用するようシステムプロンプトで指示されていることを確認してください。