SMS-OTP-verificatie

Overzicht

Deze handleiding laat zien hoe je Twilio Verify met je ElevenLabs-agent integreert, zodat je een OTP naar het telefoonnummer van een beller kunt sturen en de code kunt verifiëren die deze tijdens een live spraakgesprek terugleest.

Je leert hoe je:

• Een Twilio Verify-service maakt en je gegevens Base64-codeert voor authenticatie.
• Twee webhook-tools (send_SMS_verification en check_SMS_verification) configureert in het dashboard, met de Agents CLI of via de ElevenLabs API.
• Beide webhook-calls authenticeert met een Authorization-header met een geheime waarde.
• De systeemtool skip_turn inschakelt, zodat de agent wacht wanneer de beller de code nog niet heeft ontvangen.

Vereisten

• Een Twilio-account met Twilio Verify ingeschakeld. Als Verify niet beschikbaar is in je Twilio Console, vraag dan toegang aan via Twilio support of je Twilio-accountteam.
• Als je Twilio-account zich in de proefmodus bevindt, moet het telefoonnummer van de ontvanger een geverifieerde caller ID in Twilio zijn.

Credentials coderen en webhooktools configureren

1

Codeer je Twilio-credentials voor Basic authentication

Twilio Verify gebruikt HTTP Basic authentication met je Account SID als gebruikersnaam en Auth Token als wachtwoord. Je vindt beide onder Account Info op de startpagina van de Twilio Console.

Codeer in je shell ACCOUNT_SID:AUTH_TOKEN met Base64 (gescheiden door een dubbele punt, zonder spaties):

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

Kopieer de uitvoer. De volledige waarde van de header Authorization bestaat uit het woord Basic, één spatie en die Base64-string. Sla deze in de volgende stappen op als tool secret.

Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

2

Configureer de tools send_SMS_verification en check_SMS_verification

send_SMS_verification roept Twilio Verify aan om een sms-OTP te verzenden. check_SMS_verification verstuurt de cijfers die de beller uitspreekt. Beide vereisen dezelfde Verify Service SID en hetzelfde Authorization-secret.

Toevoegen via het dashboard

Toevoegen via de CLI

Toevoegen via de API

send_SMS_verification

Kies in het gedeelte Agent van je agentinstellingen Add Tool en selecteer Webhook.

Veld	Waarde
Naam	send_SMS_verification
Beschrijving	Verstuurt via sms een OTP-verificatiecode naar het opgegeven telefoonnummer
Methode	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications

Vervang YOUR_VERIFY_SERVICE_SID door de VA...-SID uit de eerste stap.

Authentication header: Voeg onder Headers Authorization toe als type Secret en plak de volledige waarde (Basic plus Base64). Zie Webhooktools.

Body parameters: Stel Content type in op URL-encoded (application/x-www-form-urlencoded). Voeg parameters toe met LLM Prompt als waardetype:

Gegevenstype	ID	Beschrijving
string	To	Telefoonnummer van de beller in E.164-indeling (bijvoorbeeld +14155552671)
string	Channel	Bezorgkanaal; gebruik sms

check_SMS_verification

Voeg een tweede webhooktool toe:

Veld	Waarde
Naam	check_SMS_verification
Beschrijving	Controleert of de door de beller opgegeven OTP-code geldig is
Methode	POST
URL	https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck

Gebruik dezelfde Verify Service SID en hetzelfde Authorization-secret als voor send_SMS_verification.

Body parameters: URL-encoded. Voeg To (E.164) en Code (OTP-cijfers) toe met LLM Prompt.

Als je Channel in het dashboard als een door de LLM ingevuld veld configureert, voeg dan instructies toe aan je system prompt zodat het model altijd sms doorgeeft. In de bovenstaande CLI- en API-voorbeelden wordt sms vastgezet met constant_value / constantValue, zodat het model het kanaal niet kiest.

3

Schakel de system tool skip_turn in

Bellers hebben vaak even tijd nodig om de sms te ontvangen voordat ze de code kunnen voorlezen. Zonder skip_turn kan de agent door de stilte heen praten of prompts herhalen.

Toevoegen via het dashboard

Toevoegen via de CLI

Toevoegen via de API

Kies in Tools Add Tool, selecteer System tool en schakel Skip turn in. Verdere configuratie is niet nodig.

Voeg richtlijnen toe aan de system prompt zodat het model weet wanneer het deze moet aanroepen, bijvoorbeeld:

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.

Zie Skip turn voor meer informatie.

4

Orkestreer de flow in de system prompt

Gebruik een system prompt waarin de volgorde van de tools duidelijk is, bijvoorbeeld:

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.

Problemen oplossen

Twilio 60200 — Ongeldige parameter (HTTP 400)

Twilio kan een body zoals deze retourneren wanneer de request-URL of body niet overeenkomt met wat de Verify API verwacht:

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

Wat je moet controleren: Het pad moet je Verify Service SID (VA...) uit de instellingen van de Authenticate (Verify)-service gebruiken. Je Account SID (AC...) in .../Services/{Sid}/... zetten is een veelvoorkomende oorzaak van 60200. Bekijk de Twilio-documentatie over 60200 voor andere gevallen van ongeldige parameters.

Twilio 20003 — Authentication Error — No credentials provided (HTTP 401)

Wanneer de header Authorization ontbreekt, onjuist is opgebouwd of niet wordt verzonden, kan Twilio reageren met:

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

Wat je moet controleren: De tool moet een Authorization-header versturen waarvan de waarde de volledige tekenreeks Basic <base64> is (inclusief het woord Basic en één spatie vóór de Base64-uitvoer). De Base64-invoer moet exact ACCOUNT_SID:AUTH_TOKEN zijn, zonder extra spaties of regeleinden. Controleer of het secret aan deze header is gekoppeld voor beide webhooktools. Zie 20003.

Andere problemen

• Nummer afgewezen in de proefmodus: Open in de Twilio Console Verified phone numbers en controleer voordat je test of het nummer van de ontvanger in de lijst staat.
• Agent praat door de beller heen: Controleer of Skip turn is ingeschakeld en of de system prompt het model vertelt skip_turn te gebruiken wanneer de beller tijd nodig heeft.