> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API di verifica telefonica: OTP, SMS e WhatsApp

> Verifica numeri con Didit tramite OTP via SMS, WhatsApp, Telegram, RCS e voce. $0.02 per chiamata + operatore, rilevamento operatore e rischio.

La Verifica telefonica di Didit offre un metodo affidabile per verificare i numeri di telefono degli utenti tramite codici monouso (OTP). Questa funzionalità aggiunge un livello essenziale di sicurezza al tuo processo di verifica dell'identità, garantendo informazioni di contatto legittime degli utenti.

Prompt di integrazione della verifica telefonica
        Copia il prompt negli appunti



      
      

\<pre>

\````# Goal
Integrate Didit Phone Verification (OTP send + check + carrier/risk lookup) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow — the SDK collects the number and OTP for you.

1\. Add the PHONE feature to the workflow (Business Console or POST /v3/workflows/). Configure risk actions: duplicated_phone_number_action, disposable_number_action, voip_number_action.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `phone_verifications[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server, OTP pair)
Two endpoints, paired by phone_number.

Step 1 — send the code:
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/send/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"options": {
  "code_size": 6,
  "preferred_channel": "whatsapp",
  "locale": "en-US"
},
"vendor_data": "user-1234"
}'
\```
Channels: `whatsapp` (default), `sms`, `telegram`, `voice` — delivery falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.
Branding: SMS codes carry your app's SMS sender name ("123456 is your verification code for Acme Bank") on every send, at no extra cost; set it in the Business Console. Pass `options.sms_sender_name` to sign one code with another name (1 to 30 characters). WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console to send them under your business name.

Step 2 — check the code (user types it into your UI):
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/check/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"code": "123456",
"voip_number_action": "DECLINE"
}'
\```
Each session accepts **up to 3** code-entry attempts. The check response includes the full phone metadata (carrier, line_type, disposable, voip, ported).

\# Status enum (per phone_verifications[].status / phone.status)
"Not Started" | "In Progress" | "Approved" | "Declined" | "Failed" | "Expired or Not Found" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.PHONE)
warnings[] risk codes include:
DUPLICATED_PHONE_NUMBER, DISPOSABLE_NUMBER, VOIP_NUMBER, INVALID_PHONE_NUMBER, OTP_DELIVERY_FAILED, OTP_MAX_ATTEMPTS_REACHED, OTP_EXPIRED, PHONE_NUMBER_BLOCKED.
Full catalogue: /core-technology/phone-verification/warnings-phone-verification.

\# Failure modes to handle
\- HTTP 400 — non-E.164 phone_number on /send/.
\- send response status="Blocked" with reason="spam" — anti-abuse block; no code sent, no charge.
\- check response status="Failed" — wrong code, attempts remaining; re-prompt.
\- check response status="Declined" — third failed attempt; restart with /v3/phone/send/.
\- check response status="Expired or Not Found" — outside the 5-minute window or no pending session for that number; restart.

\# See also
\- Canonical schema: /reference/data-models#phone-verification
\- Per-feature report: /core-technology/phone-verification/report-phone-verification
\- Risk catalogue: /core-technology/phone-verification/warnings-phone-verification
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Incolla in

Nella lezione dell'Academy sulla lettura dell'esito di una verifica, il capitolo al minuto 8:08 illustra la verifica telefonica e il rilevamento dei duplicati.[Verifica telefonica e duplicati — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![Diagramma di flusso della verifica telefonica](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=6c12863ce97e5ad6a11757b598918932)## Come funzionaLa nostra soluzione di Verifica telefonica offre una convalida completa dei numeri di telefono attraverso una procedura semplice e intuitiva per l'utente. Il sistema combina la verifica tramite OTP con una valutazione avanzata del rischio per fornire una verifica telefonica affidabile su larga scala.**1. Raccolta del numero di telefono**Il sistema raccoglie in modo sicuro le seguenti informazioni:| Dati raccolti | Dettagli |
| - | - |
| **Numero di Telefono** | Se non fornito durante la creazione della sessione, l'utente inserisce il proprio numero di telefono in formato internazionale. Se già fornito, l'utente deve verificare il numero precompilato. |
| **Prefisso internazionale** | Suggerito automaticamente in base alla geolocalizzazione IP o alla selezione dell'utente. |
| **Tipo di operatore** | Rileva se il numero è cellulare o di rete fissa. |**2. Generazione e consegna dell'OTP**Il nostro sistema di verifica:- Genera un codice monouso sicuro con scadenza temporale
- Consegna il codice tramite SMS al numero fornito
- Garantisce una consegna ottimizzata grazie all'integrazione con più operatori
- Offre opzioni alternative in caso di difficoltà nella consegna**3. Convalida del codice**L'utente completa la verifica:- Inserendo il codice ricevuto nell'interfaccia di verifica
- Inviandolo entro il limite di tempo configurato (di norma 5–10 minuti)
- Richiedendo un nuovo codice se necessario (con apposito limite di frequenza)**4. Valutazione del rischio**Il nostro sistema esegue controlli avanzati:| Controllo | Descrizione |
| - | - |
| **Formato e operatore** | Verifica il formato del numero di telefono e le informazioni sull'operatore. |
| **Numeri usa e getta** | Verifica il numero nei database noti di numeri usa e getta o virtuali. |
| **Rilevamento del SIM swap** | Individua potenziali rischi legati al SIM swap. |
| **Schemi di attività** | Rileva schemi di attività sospetti. |
| **Dati storici** | Esegue controlli incrociati con lo storico dei dati di verifica. |**5. Consegna dei risultati**Accedi ai risultati di verifica attraverso molteplici canali:| Canale | Descrizione |
| - | - |
| **Dashboard** | Aggiornamenti in tempo reale nella dashboard. |
| **Webhook** | Notifiche webhook istantanee. |
| **API** | Integrazione tramite API RESTful. |
| **Report** | Report completi con informazioni dettagliate sulla verifica. |## Funzionalità di verificaIl nostro servizio di Verifica telefonica offre diverse funzionalità chiave per migliorare il tuo processo di verifica:#### Verifica OTP- **Generazione sicura dei codici**: codici monouso generati casualmente
- **Consegna via SMS**: consegna rapida e affidabile ai dispositivi mobili
- **Timeout configurabili**: imposta i tempi di scadenza in base ai tuoi requisiti di sicurezza
- **Opzioni di nuovo tentativo**: consenti agli utenti di richiedere nuovi codici con adeguati limiti di frequenza
- **Codici con il tuo brand**: i codici SMS riportano il nome del tuo brand invece di inviare un messaggio generico, senza costi aggiuntivi. Vedi [Messaggi di verifica personalizzati con il brand](#messaggi-di-verifica-personalizzati-con-il-brand).
- **Il tuo numero WhatsApp**: i codici WhatsApp possono provenire dal tuo numero WhatsApp Business. Vedi [Inviare codici WhatsApp dal proprio numero](#inviare-codici-whatsapp-dal-proprio-numero).#### Messaggi di verifica personalizzati con il brandI codici di verifica SMS possono mostrare il nome del tuo brand, consentendo agli utenti di riconoscere il messaggio come tuo:> 123456 è il tuo codice di verifica per **Acme Bank**Solo il nome è personalizzabile.
Il resto del testo è una formula standard registrata presso gli operatori telefonici di ogni paese, che impedisce che i codici vengano filtrati come spam, ed è tradotta nella lingua del destinatario.
Il branding è gratuito: un codice con brand ha lo stesso costo di uno senza brand.**Imposta il nome del mittente SMS** nella Business Console, in **Phone Verification → Settings** di un workflow o sotto **White Label → SMS**.
Appartiene alla tua applicazione, non a un singolo workflow: firma ogni codice SMS inviato dall'applicazione, in ogni workflow e tramite l'API autonoma, con o senza personalizzazione white label.**Quale nome riporta un codice**: vale la prima corrispondenza:1) `options.sms_sender_name` su [`POST /v3/phone/send/`](https://docs.didit.me/it/standalone-apis/phone-send), per quel singolo codice.
2) Il nome del mittente SMS della tua applicazione.
3) Solo per gli invii white label (un workflow con personalizzazione white label o `options.use_white_label_customization: true` sull'API), il tuo nome pubblico white label.
4) In caso contrario, il codice viene inviato senza nome.Un nome del mittente utilizza da 1 a 30 caratteri: solo lettere, cifre, spazi e ' & - !, non solo cifre, con spazi singoli tra le parole.
L'API rifiuta un nome che non rispetta queste regole con un errore `400` prima dell'invio del codice.- **Canali**: il nome viene aggiunto ai messaggi SMS, compresi gli SMS inviati come alternativa a un altro canale. I codici WhatsApp vengono inviati con un messaggio fisso e non lo includono; per mostrare su di essi il nome della tua azienda, [inviali dal tuo numero](#inviare-codici-whatsapp-dal-proprio-numero).
- **Modifiche giornaliere**: ogni applicazione può iniziare a utilizzare fino a due nuovi nomi al giorno (UTC), conteggiando sia i nuovi nomi mittente sia i nuovi valori di `sms_sender_name`. Successivamente, i codici mantengono il nome attuale dell'applicazione fino al giorno successivo e un nuovo nome specificato per richiesta viene inviato con il nome dell'applicazione. Un nome già utilizzato in precedenza non viene riconteggiato.
- **Priorità alla consegna**: un problema di branding non blocca mai un codice. Se un nome non può essere applicato, il codice viene inviato con il nome dell'applicazione o senza nome.#### Scrivi il tuo testo SMS e l'ID mittentePuoi sostituire il testo dei tuoi codici SMS e il mittente visualizzato dagli utenti.
Imposta entrambi nella Business Console sotto **White Label → SMS**.
Appartengono alla tua applicazione, come il nome del mittente SMS, e si applicano a ogni codice SMS inviato da essa, in ogni workflow e tramite l'API autonoma.**Il tuo testo personalizzato** va definito per ogni lingua.
Un codice viene inviato con il tuo testo quando ne hai scritto uno per la lingua in cui viene inviato il codice; tutte le altre lingue mantengono il testo tradotto di Didit.
Usa `{code}` per il codice e, facoltativamente, `{brand}` per il tuo nome del mittente SMS, ad esempio `Acme: {code} is your login code for {brand}.`Un testo deve:- contenere `{code}` esattamente una volta, e nessun altro segnaposto oltre a `{code}` e `{brand}`;
- non contenere link: gli operatori telefonici bloccano i codici di verifica che li contengono;
- rientrare in un unico SMS con un codice a 8 cifre e un nome di 30 caratteri: fino a 160 caratteri, oppure 70 quando utilizza caratteri non appartenenti all'alfabeto latino di base (ad esempio cirillico, arabo o emoji).**Il tuo ID mittente** utilizza da 3 a 11 lettere, cifre e spazi, non solo cifre, ad esempio `AcmeBank`.
Viene utilizzato nei paesi in cui Didit abilita gli ID mittente personalizzati, ovvero i paesi i cui operatori accettano un nome del mittente senza previa registrazione; in tutti gli altri casi, i codici partono con il mittente di Didit.
Contatta l'assistenza per richiedere l'abilitazione di un paese in cui è necessaria la registrazione del mittente.- **Priorità alla consegna**: quando un codice viene reinviato su una rotta che non può trasmettere il tuo testo o il tuo ID mittente, viene inviato con il testo di Didit, firmato con il tuo nome del mittente SMS e il mittente di Didit, in modo che il codice arrivi sempre.#### Inviare codici WhatsApp dal proprio numeroPer impostazione predefinita, i codici WhatsApp provengono dal numero WhatsApp Business di Didit.
Puoi invece collegare il tuo numero WhatsApp Business, in modo che gli utenti ricevano i codici dal nome e dal numero della tua azienda.**Collega un numero** nella Business Console, in **Phone Verification → Settings → WhatsApp number** di un workflow, e seleziona **Connect WhatsApp number**.
Si apre una finestra di accesso: accedi all'account aziendale che gestisce il tuo numero WhatsApp Business, quindi scegli l'account WhatsApp Business e il numero da cui inviare.
Didit registra quindi il numero per l'invio e crea il relativo messaggio di verifica.
Per modificarlo è necessaria l'autorizzazione a modificare le personalizzazioni, come per il nome del mittente SMS.Il numero appartiene alla tua applicazione, non a un singolo workflow: una volta collegato, invia ogni codice WhatsApp che l'applicazione trasmette, in ogni workflow e tramite l'API autonoma.- **Approvazione**: il nuovo messaggio di verifica richiede l'approvazione prima che il numero possa inviare codici, solitamente entro pochi minuti. Fino ad allora, la scheda mostra il numero come in attesa di approvazione e nel frattempo i codici continuano a partire dal numero di Didit.
- **Testo del messaggio**: i messaggi di verifica su WhatsApp utilizzano un testo standard nella lingua dell'utente: il codice, una nota di sicurezza e un pulsante di copia. Il testo non può essere modificato, ma il mittente è la tua azienda.
- **Consegna**: se non è possibile recapitare un codice su WhatsApp, questo viene inviato tramite SMS, firmato con il tuo nome del mittente SMS.
- **Fatturazione**: i messaggi inviati dal tuo numero vengono fatturati al tuo account WhatsApp Business, pertanto Didit addebita solo la tariffa di verifica (\$0.02) per tali codici. I codici inviati tramite SMS vengono fatturati come di consueto.
- **Richiede attenzione**: se il numero non è più in grado di inviare messaggi (ad esempio, l'accesso è stato rimosso dal tuo account aziendale), i codici partono nuovamente dal numero di Didit e la scheda ti invita a collegare nuovamente il numero.
- **Disconnetti** in qualsiasi momento dalla stessa scheda. I codici partiranno nuovamente dal numero di Didit; il numero e il relativo messaggio di verifica rimangono nel tuo account WhatsApp Business.#### Analisi del numero di telefono- **Validazione del formato**: Assicura che il numero di telefono segua il formato internazionale corretto
- **Rilevamento dell'operatore**: Identifica l'operatore di telecomunicazioni associato al numero
- **Tipo di numero**: Distingue tra numeri mobili, fissi e VoIP
- **Validazione del paese**: Verifica che il numero di telefono corrisponda al formato previsto per il paese#### Valutazione del rischio- **Rilevamento dei numeri usa e getta**: Identifica i numeri temporanei utilizzati per eludere la tracciabilità
- **Identificazione di numeri virtuali**: Segnala i numeri che potrebbero essere virtuali o basati su VoIP
- **Monitoraggio delle attività**: Rileva pattern sospetti tra i vari tentativi di verifica
- **Controllo delle blocklist**: Effettua controlli incrociati con liste interne di numeri precedentemente utilizzati in modo illecito## PrezziLa verifica telefonica viene addebitata **per messaggio inviato** con tariffe trasparenti a consumo:| Componente | Costo |
| - | - |
| **Tariffa Didit** | \$0.02 per verifica |
| **Tariffa operatore** | Varia in base al paese e al canale |
| **Totale** | \$0.02 + tariffa operatore |Lo sconto del tuo piano si applica solo alla tariffa Didit di \$0.02; la tariffa dell'operatore viene riaddebitata al costo e non è mai scontata. Consulta [Sconti](https://docs.didit.me/it/getting-started/pricing.md#sconti).Supportiamo molteplici canali di consegna con tariffe differenti (la disponibilità varia in base al paese):| Canale | Descrizione |
| - | - |
| **SMS** | Consegna tramite messaggio di testo tradizionale |
| **WhatsApp** | Consegna tramite messaggistica WhatsApp |
| **Telegram** | Consegna tramite messaggistica Telegram |
| **RCS** | Messaggistica Rich Communication Services |
| **Viber** | Consegna tramite messaggistica Viber |
| **Zalo** | Consegna tramite messaggistica Zalo (Vietnam) |> [!NOTE]
>
> Paghi solo quando viene inviato un messaggio. Se l'utente abbandona prima della consegna dell'OTP, non ti viene addebitato alcun costo.→ [Prezzi della verifica telefonica](https://docs.didit.me/it/getting-started/phone-verification-pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.