탐색으로 건너뛰기
배포전화Twilio

SMS OTP 인증

Twilio Verify를 사용하여 에이전트 대화 중 SMS로 일회용 패스코드를 전송하고 인증하세요.
전화번호, OTP 코드, 인증 성공을 수집하는 에이전트 대화

개요

이 가이드에서는 Twilio Verify를 ElevenLabs 에이전트와 통합하여 발신자의 전화번호로 OTP를 전송하고, 실시간 음성 대화 중 발신자가 다시 읽어 주는 코드를 인증하는 방법을 설명합니다.

다음 방법을 알아봅니다.

  • Twilio Verify 서비스를 만들고 인증을 위해 자격 증명을 Base64로 인코딩합니다.
  • 대시보드, Agents CLI 또는 ElevenLabs API를 사용하여 두 webhook 도구(send_SMS_verification 및 check_SMS_verification)를 구성합니다.
  • 비밀 값이 포함된 Authorization 헤더를 사용하여 두 webhook 호출을 모두 인증합니다.
  • 발신자가 아직 코드를 받지 못했을 때 에이전트가 대기하도록 skip_turn 시스템 도구를 활성화합니다.

사전 요구 사항

  • Twilio Verify가 활성화된 Twilio 계정. Twilio Console에서 Verify를 사용할 수 없는 경우 Twilio 지원팀 또는 Twilio 계정 팀을 통해 액세스를 요청하세요.
  • Twilio 계정이 평가판 모드인 경우 대상 전화번호는 Twilio에서 인증된 발신자 ID여야 합니다.
1

Twilio Console에 로그인

Twilio Console을 엽니다.

2

Authenticate(Verify) 서비스 생성

왼쪽 사이드바에서 Add + 를 선택하고 Authenticate(Verify) 서비스를 생성합니다.

3

서비스 이름 지정

알기 쉬운 이름을 지정합니다(예: ElevenLabs OTP).
4

Verify Service SID 복사

서비스 Settings 페이지를 열고 Verify Service SID를 복사합니다. VA로 시작하며 Account SID와는 다릅니다.

흔한 실수: 아래 도구 URL의 경로에는 Authenticate(Verify) 서비스의 Verify Service SID(VA...)를 사용하세요. 경로에 Account SID(AC...)를 넣지 마세요. Verify API는 URL에 서비스 SID를 기대하므로 Account SID를 사용하면 4xx 잘못된 매개변수 오류가 발생합니다.

에이전트에 연결하기 전에 Console의 Twilio API Explorer를 사용해 요청을 테스트할 수 있습니다.

자격 증명 인코딩 및 웹훅 도구 구성

1

Basic 인증용 Twilio 자격 증명 인코딩

Twilio Verify는 Account SID를 사용자 이름으로, Auth Token을 비밀번호로 사용하는 HTTP Basic 인증을 사용합니다. Twilio Console 홈 페이지의 Account Info에서 둘 다 확인할 수 있습니다.

셸에서 ACCOUNT_SID:AUTH_TOKEN을 Base64로 인코딩합니다(콜론으로 구분, 공백 없음).

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

출력을 복사합니다. 전체 Authorization 헤더 값은 Basic이라는 단어, 공백 하나, 그리고 해당 Base64 문자열로 구성됩니다. 다음 단계에서 도구 시크릿으로 저장하세요.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
2

send_SMS_verification 및 check_SMS_verification 도구 구성

send_SMS_verification은 Twilio Verify를 호출하여 SMS OTP를 전송합니다. check_SMS_verification은 발신자가 말한 숫자를 제출합니다. 두 도구 모두 동일한 Verify Service SID와 동일한 Authorization 시크릿이 필요합니다.

send_SMS_verification

전화번호, OTP 코드, 인증 성공을 수집하는 에이전트 대화

에이전트 설정의 Agent 섹션에서 Add Tool을 선택하고 Webhook을 선택합니다.

필드값
이름send_SMS_verification
설명제공된 전화번호로 SMS를 통해 OTP 인증 코드 전송
메서드POST
URLhttps://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications

YOUR_VERIFY_SERVICE_SID를 첫 번째 단계의 VA... SID로 바꿉니다.

인증 헤더: Headers에서 Authorization을 Secret 유형으로 추가하고 전체 값(Basic 뒤에 Base64)을 붙여넣습니다. 웹훅 도구를 참조하세요.

본문 매개변수: Content type을 URL-encoded(application/x-www-form-urlencoded)로 설정합니다. 값 유형으로 LLM Prompt를 사용해 매개변수를 추가합니다.

데이터 유형식별자설명
stringToE.164 형식의 발신자 전화번호(예: +14155552671)
stringChannel전송 채널, sms 사용

check_SMS_verification

두 번째 웹훅 도구를 추가합니다.

필드값
이름check_SMS_verification
설명발신자가 제공한 OTP 코드가 유효한지 확인
메서드POST
URLhttps://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 숫자)를 추가합니다.

대시보드에서 **Channel**을 LLM이 채우는 필드로 구성했다면, 모델이 항상 sms를 전달하도록 시스템 프롬프트에 지침을 추가하세요. 위 CLI 및 API 예시는 constant_value / constantValue로 sms를 고정하므로 모델이 채널을 선택하지 않습니다.

3

skip_turn 시스템 도구 활성화

발신자는 코드를 읽기 전에 SMS를 수신할 시간이 필요한 경우가 많습니다. skip_turn이 없으면 에이전트가 대기 시간에 말을 덮어쓰거나 프롬프트를 반복할 수 있습니다.

Tools에서 Add Tool을 선택하고 System tool을 선택한 다음 Skip turn을 활성화합니다. 추가 구성은 필요하지 않습니다.

모델이 언제 호출해야 하는지 알 수 있도록 시스템 프롬프트에 다음과 같은 지침을 추가합니다.

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을 참조하세요.

4

시스템 프롬프트에서 흐름 조율

다음과 같이 도구 순서를 명확히 지정하는 시스템 프롬프트를 사용합니다.

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가 다음과 같은 본문을 반환할 수 있습니다.

{
  "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 문서를 참조하세요.

Twilio 20003 — 인증 오류 — 자격 증명이 제공되지 않음(HTTP 401)

Authorization 헤더가 없거나, 형식이 잘못되었거나, 전송되지 않으면 Twilio는 다음과 같이 응답할 수 있습니다.

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

확인할 사항: 도구는 값이 전체 Basic <base64> 문자열인 Authorization 헤더를 전송해야 합니다(Basic이라는 단어와 Base64 출력 앞의 공백 하나 포함). Base64 입력은 추가 공백이나 줄바꿈 없이 정확히 ACCOUNT_SID:AUTH_TOKEN이어야 합니다. 두 웹훅 도구 모두에서 이 헤더에 시크릿이 연결되어 있는지 확인하세요. 20003을 참조하세요.

기타 문제

  • 평가판 모드에서 번호가 거부됨: Twilio Console에서 Verified phone numbers를 열고 테스트 전에 대상 번호가 목록에 있는지 확인하세요.
  • 에이전트가 발신자의 말을 덮어씀: Skip turn이 활성화되어 있고, 발신자에게 시간이 필요할 때 모델이 skip_turn을 사용하도록 시스템 프롬프트에서 지시하는지 확인하세요.