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

# Vérification OTP par SMS

![Conversation avec un agent recueillant un numéro de téléphone, un code OTP et la confirmation de vérification](/docs/_fern-img/97201c6fdad0c63900236b52726c867d3ff9405fdbd30725858f384653c95803.webp)

## Vue d’ensemble

Ce guide explique comment intégrer [Twilio Verify](https://www.twilio.com/docs/verify/api) à votre agent ElevenLabs afin d’envoyer un OTP au numéro de téléphone d’un appelant et de vérifier le code qu’il vous communique lors d’une conversation vocale en direct.

Vous apprendrez à :

* Créer un service Twilio Verify et encoder vos identifiants en Base64 pour l’authentification.
* Configurer deux outils webhook, `send_SMS_verification` et `check_SMS_verification`, dans le [dashboard](https://elevenlabs.io/app/agents), avec l’[Agents CLI](/docs/fr/eleven-agents/operate/cli) ou à l’aide de l’[API ElevenLabs](/docs/fr/api-reference/introduction).
* Authentifier les deux appels webhook à l’aide d’un en-tête `Authorization` contenant une valeur secrète.
* Activer l’outil système [`skip_turn`](/docs/fr/eleven-agents/customization/tools/system-tools/skip-turn) afin que l’agent attende lorsque l’appelant n’a pas encore reçu le code.

## Prérequis

* Un compte Twilio avec [Twilio Verify](https://www.twilio.com/docs/verify/api) activé. Si Verify n’est pas disponible dans votre console Twilio, demandez l’accès via [l’assistance Twilio](https://support.twilio.com/) ou votre équipe de compte Twilio.
* Si votre compte Twilio est en [mode d’essai](https://www.twilio.com/docs/guides/how-to-use-your-free-trial-account), le numéro de téléphone de destination doit être un ID appelant vérifié dans Twilio.

#### Connectez-vous à la console Twilio

Ouvrez la [console Twilio](https://console.twilio.com/).

#### Créez un service Authenticate (Verify)

Dans la barre latérale gauche, sélectionnez **Add +** et créez un service **Authenticate** (Verify).

#### Nommez le service

Donnez-lui un nom descriptif, par exemple `ElevenLabs OTP`.

#### Copiez le SID du service Verify

Ouvrez la page **Settings** du service et copiez le **Verify Service SID**. Il commence par `VA` et diffère de votre Account SID.

> **Warning**
>
> **Erreur fréquente** : utilisez votre **Verify Service SID** (`VA...`) du service Authenticate (Verify) dans les URL des outils ci-dessous. N’insérez pas votre **Account SID** (`AC...`) dans le chemin. L’API Verify attend le SID du service dans l’URL ; utiliser l’Account SID génère des erreurs `4xx` de paramètre non valide.

Vous pouvez utiliser l’API Explorer de Twilio dans la console pour tester les requêtes avant de les associer à votre agent.

### Encoder les identifiants et configurer les outils webhook

#### Encodez vos identifiants Twilio pour l’authentification Basic

Twilio Verify utilise l’authentification HTTP Basic avec votre **Account SID** comme nom d’utilisateur et votre **Auth Token** comme mot de passe. Vous les trouverez tous deux dans **Account Info**, sur la page d’accueil de la [console Twilio](https://console.twilio.com/).

Dans votre terminal, encodez `ACCOUNT_SID:AUTH_TOKEN` en Base64, séparés par deux-points et sans espaces :

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

Copiez la sortie. La valeur complète de l’en-tête `Authorization` se compose du mot `Basic`, d’un espace, puis de cette chaîne Base64. Enregistrez-la comme secret d’outil lors des prochaines étapes.

```text
Basic dkFDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
```

#### Configurez les outils \`send_SMS_verification\` et \`check_SMS_verification\`

`send_SMS_verification` appelle Twilio Verify pour envoyer un OTP par SMS. `check_SMS_verification` transmet les chiffres énoncés par l’appelant. Les deux requièrent le même Verify Service SID et le même secret `Authorization`.

#### Ajouter via le Dashboard

### send_SMS_verification

![Conversation avec un agent recueillant un numéro de téléphone, un code OTP et la confirmation de vérification](/docs/_fern-img/9d72a753674c17481e99ea871b1b178cd7791f2da1ec3491ad4786c3fbc9a84e.webp)

Dans la section **Agent** des paramètres de votre agent, sélectionnez **Add Tool**, puis **Webhook**.

| Champ       | Valeur                                                                        |
| ----------- | ----------------------------------------------------------------------------- |
| Nom         | `send_SMS_verification`                                                       |
| Description | Envoie un code de vérification OTP par SMS au numéro de téléphone fourni      |
| Méthode     | `POST`                                                                        |
| URL         | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/Verifications` |

Remplacez `YOUR_VERIFY_SERVICE_SID` par le SID `VA...` de la première étape.

**En-tête d’authentification :** sous **Headers**, ajoutez `Authorization` en tant que type **Secret** et collez la valeur complète (`Basic ` suivi de Base64). Consultez [Outils webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools).

**Paramètres du corps :** définissez **Content type** sur **URL-encoded** (`application/x-www-form-urlencoded`). Ajoutez les paramètres avec **LLM Prompt** comme type de valeur :

| Type de données | Identifiant | Description                                                                   |
| --------------- | ----------- | ----------------------------------------------------------------------------- |
| `string`        | `To`        | Numéro de téléphone de l’appelant au format E.164, par exemple `+14155552671` |
| `string`        | `Channel`   | Canal de livraison ; utilisez `sms`                                           |

### check_SMS_verification

Ajoutez un deuxième outil webhook :

| Champ       | Valeur                                                                            |
| ----------- | --------------------------------------------------------------------------------- |
| Nom         | `check_SMS_verification`                                                          |
| Description | Vérifie si le code OTP fourni par l’appelant est valide                           |
| Méthode     | `POST`                                                                            |
| URL         | `https://verify.twilio.com/v2/Services/YOUR_VERIFY_SERVICE_SID/VerificationCheck` |

Utilisez le même Verify Service SID et le même secret `Authorization` que pour `send_SMS_verification`.

**Paramètres du corps :** **URL-encoded**. Ajoutez `To` (E.164) et `Code` (chiffres OTP) avec **LLM Prompt**.

#### Ajouter via la CLI

> **Note**
>
> Créez un [secret de Workspace](/docs/fr/api-reference/workspace/secrets/create) dont la valeur est l’en-tête `Authorization` complet (`Basic ` suivi de Base64). Indiquez l’ID du secret dans le JSON ci-dessous sous `YOUR_SECRET_ID`.

#### Ajoutez les fichiers de configuration des outils

Enregistrez l’outil d’envoi sous `tool_configs/send_SMS_verification.json` (remplacez `YOUR_VERIFY_SERVICE_SID` par votre SID `VA...`) :

```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"
        }
      }
    }
  }
}
```

Enregistrez l’outil de vérification sous `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"
        }
      }
    }
  }
}
```

#### Enregistrez les outils

```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
```

#### Associez les outils à votre agent

Modifiez `agent_configs/<agent-name>.json`. Sous `conversation_config.agent.prompt`, définissez `tool_ids` pour inclure les deux outils, en utilisant les ID de `tools.json` ou de `elevenlabs agents tools list`. Envoyez ensuite les modifications :

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Ajouter via l’API

> **Note**
>
> Créez un [secret de Workspace](/docs/fr/api-reference/workspace/secrets/create) contenant la valeur complète de l’en-tête `Basic ...`, puis transmettez son ID comme `secret_id` dans `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**
>
> Si vous configurez **`Channel`** comme champ renseigné par le LLM dans le Dashboard, ajoutez des instructions à votre prompt système afin que le modèle transmette toujours `sms`. Les exemples CLI et API ci-dessus définissent `sms` avec `constant_value` / `constantValue`, le modèle ne choisit donc pas le canal.

#### Activez l’outil système \`skip_turn\`

Les appelants ont souvent besoin d’un moment pour recevoir le SMS avant de pouvoir lire le code. Sans `skip_turn`, l’agent peut parler pendant ce silence ou répéter les invites.

#### Ajouter via le Dashboard

Dans **Tools**, sélectionnez **Add Tool**, puis **System tool**, et activez **Skip turn**. Aucune autre configuration n’est requise.

#### Ajouter via la CLI

Dans `agent_configs/<agent-name>.json`, sous `conversation_config.agent.prompt`, définissez `built_in_tools.skip_turn` sur `null` (valeurs par défaut) pour activer Skip turn, puis exécutez :

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Ajouter via l’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,
        },
      },
    },
  },
});
```

Si vous avez déjà défini `tool_ids` lors de la création des outils webhook, fusionnez `built_in_tools` dans le même objet `prompt` au lieu de le remplacer.

Ajoutez des consignes au prompt système afin que le modèle sache quand l’appeler, par exemple :

```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.
```

Consultez [Skip turn](/docs/fr/eleven-agents/customization/tools/system-tools/skip-turn) pour plus de détails.

#### Orchestrez le flux dans le prompt système

Utilisez un prompt système qui séquence clairement les outils, par exemple :

```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.
```

## Résolution des problèmes

### Twilio `60200` : paramètre non valide (HTTP 400)

Twilio peut renvoyer un corps de réponse comme celui-ci lorsque l’URL ou le corps de la requête ne correspond pas aux attentes de l’API Verify :

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

**À vérifier :** le chemin doit utiliser votre **Verify Service SID** (`VA...`) issu des paramètres du service Authenticate (Verify). Insérer votre **Account SID** (`AC...`) dans `.../Services/{Sid}/...` est une cause fréquente de l’erreur `60200`. Consultez la documentation Twilio sur [60200](https://www.twilio.com/docs/errors/60200) pour les autres cas de paramètre non valide.

### Twilio `20003` : erreur d’authentification : aucun identifiant fourni (HTTP 401)

Lorsque l’en-tête `Authorization` est absent, mal formé ou non envoyé, Twilio peut répondre par :

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

**À vérifier :** l’outil doit envoyer un en-tête `Authorization` dont la valeur est la chaîne complète `Basic <base64>`, y compris le mot `Basic` et un seul espace avant la sortie Base64. L’entrée Base64 doit être exactement `ACCOUNT_SID:AUTH_TOKEN`, sans espaces ni sauts de ligne supplémentaires. Vérifiez que le secret est associé à cet en-tête sur les deux outils webhook. Consultez [20003](https://www.twilio.com/docs/errors/20003).

### Autres problèmes

* **Numéro refusé en mode d’essai :** dans la console Twilio, ouvrez [Verified phone numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/verified) et assurez-vous que le numéro de destination est répertorié avant de tester.
* **L’agent parle en même temps que l’appelant :** vérifiez que **Skip turn** est activé et que le prompt système indique au modèle d’utiliser `skip_turn` lorsque l’appelant a besoin de temps.