Piattaforma WhatsApp Business

Numeri di telefono pre-verificati

Questo documento spiega come offrire ai tuoi clienti finali numeri di telefono aziendali pre-verificati nel nuovo flusso di iscrizione integrata. I numeri di telefono aziendali pre-verificati sono numeri di telefono aziendali che sono già stati verificati da te, pertanto i clienti finali non dovranno contattarti per richiedere una password monouso.

Screenshot of pre-verifed phone numbers in Embedded Signup flow

Tieni presente che i numeri di telefono aziendali pre-verificati sono rappresentati dagli oggetti WhatsApp Business Pre-Verified Phone Number, che sono temporanei. Quando un cliente finale seleziona uno di questi numeri e completa il nuovo flusso di iscrizione integrata, l'oggetto temporaneo sarà sostituito da un oggetto WhatsApp Business Phone Number e tu dovrai ottenere il nuovo ID per registrare il numero.

Requisiti

Limitazioni

  • Disponibili solo con il nuovo flusso di iscrizione integrata. Consulta il documento Integrare il flusso di iscrizione per scoprire come abilitare il nuovo flusso.
  • Dovrai tenere traccia degli utenti che reclamano un numero di telefono aziendale pre-verificato.
  • Se un cliente finale non reclama un numero aziendale pre-verificato nel flusso di iscrizione integrata entro 90 giorni dalla verifica, il numero tornerà allo stato non verificato e sarà necessario ripetere la procedura di verifica perché lo stato venga ripristinato per altri 90 giorni.
  • I numeri di telefono aziendali pre-verificati non reclamati non possono essere nuovamente verificati fino a 45 giorni prima che sia programmato il loro ripristino allo stato non verificato. Questo periodo di tempo è indicato nel campo verification_expiry_time.
  • Se aggiungi un numero di telefono al tuo gruppo di numeri di telefono aziendali pre-verificati (Passaggio 1), ma non lo verifichi entro 90 giorni (Passaggio 3), il numero verrà rimosso dal gruppo e dovrai aggiungerlo di nuovo.

Creazione di numeri pre-verificati

Segui questi passaggi per creare un numero di telefono aziendale pre-verificato, mostrarlo nell'iscrizione integrata e registrarlo dopo che è stato reclamato da un cliente finale.

Passaggio 1: crea un numero di telefono aziendale pre-verificato

Usa l'endpoint Business Account > Add Phone Numbers per creare un numero di telefono aziendale pre-verificato nel tuo account business. Mediante questa operazione, il numero viene aggiunto al tuo gruppo.

Sintassi della richiesta

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Risposta

In caso di azione eseguita correttamente, l'API restituirà un ID per il numero di telefono pre-verificato di WhatsApp Business. Prendi nota di questo valore, ti servirà per la richiesta successiva.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

Esempio di richiesta

curl -X POST 'https://graph.facebook.com/v20.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "id": "106540352242922"
}

Consulta il riferimento relativo all'endpoint Business Account > Add Phone Numbers per i formati dei numeri di telefono e i parametri per le query supportati.

Passaggio 2: richiedi un codice di verifica

Usa l'endpoint WhatsApp Business Pre-Verified Phone Number > Request Code per richiedere una password monouso tramite SMS o messaggio vocale per il numero di telefono aziendale pre-verificato appena creato.

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Risposta

In caso di azione eseguita correttamente, l'API restituirà il valore true.

{
  "success": <SUCCESS>
}

In aggiunta, invieremo un SMS o un messaggio vocale contenente una password monouso al numero di telefono. Prendi nota della password monouso, ti servirà per la richiesta successiva.

Sintassi dell'SMS contenente la password monouso

WhatsApp code <CODE>

Sintassi del messaggio vocale contenente la password monouso

Ripetuta tre volte.

Verification code is <CODE>

Esempio di richiesta

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "success": true
}

Esempio di SMS contenente una password monouso

WhatsApp code 123-456

Esempio di messaggio vocale contenente una password monouso

Ripetuto tre volte.

Verification code is 123456

Consulta il riferimento relativo all'endpoint WhatsApp Business Pre-Verified Phone Number > Request Code per i metodi di codice, le lingue e i parametri per le query supportati.

Passaggio 3: verificare il numero

Usa l'endpoint WhatsApp Business Pre-Verified Phone Number > Verify Code per verificare il numero di telefono aziendale usando la password monouso corrispondente.

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Risposta

In caso di azione eseguita correttamente, l'API restituirà il valore true e il parametro code_verification_status del numero di telefono aziendale sarà impostato su VERIFIED per 90 giorni.

{
  "success": <SUCCESS>
}

Esempio di richiesta

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "success": true
}

Consulta il riferimento relativo all'endpoint WhatsApp Business Pre-Verified Phone Number > Verify Code per i parametri delle query supportati.

Una volta ottenuti uno o più numeri di telefono aziendali pre-verificati con stato verificato, mostrali nel nuovo flusso di iscrizione integrata.

Visualizzazione dei numeri pre-verificati nell'iscrizione integrata

Puoi mostrare i numeri di telefono aziendali pre-verificati nel nuovo flusso di iscrizione integrata attraverso un modulo dati precompilato. Per farlo, aggiungi un oggetto preVerifiedPhone con una proprietà ids all'oggetto setup e assegna gli ID dei tuoi numeri di telefono aziendali pre-verificati come array di stringhe alla proprietà ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

Ad esempio:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

Tieni presente che, se un numero di telefono aziendale pre-verificato con stato VERIFIED non viene reclamato entro 90 giorni dalla verifica, il suo stato passerà a UNVERIFIED ma continuerà a essere visibile nel nuovo flusso di iscrizione integrata. Se un cliente finale tenta di reclamare un numero non verificato, dovrà provvedere a completarne la verifica, ovvero dovrà richiederti una password monouso.

Per evitare uno scenario di questo tipo che implicherebbe un'esperienza utente negativa, ti consigliamo di monitorare le tempistiche, in modo da eseguire nuovamente la procedura di verifica prima che un numero torni nello stato non verificato.

Se non sei sicuro di quando hai verificato l'ultima volta un dato numero di telefono aziendale pre-verificato, interroga l'endpoint WhatsApp Business Pre-Verified Phone Number e leggi i campi code_verification_time e verification_expiry_time, che indicano quando è stata effettuata la verifica più recente e la scadenza di tale verifica.

Come determinare se un numero è stato reclamato tramite l'iscrizione integrata

Consulta Ottenere gli ID dei numeri di telefono reclamati.

Ottenere gli ID dei numeri di telefono reclamati

Esegui un GET sull'endpoint WhatsApp Business Account > Phone Numbers, che restituisce tutti i numeri di telefono di WhatsApp Business in un account WhatsApp Business.

Esegui un'analisi per la proprietà display_phone_number in ciascun oggetto restituito nell'insieme di risultati. Se un oggetto ha come valore display_phone_number il numero di telefono visualizzato (ad es. 16505551234), significa che è stato reclamato. Copia il valore della proprietà id dell'oggetto, questo è l'ID del nuovo oggetto WhatsApp Business Phone Number che ora rappresenta questo numero (l'ID precedente smetterà di funzionare).

In alternativa, puoi usare lo stesso endpoint con l'espansione field per richiedere il campo display_phone_number e specificare il numero di telefono visualizzato. Ad esempio:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Se viene restituito un oggetto WhatsApp Business Phone Number con quel numero di telefono visualizzato, significa che il numero è stato reclamato, quindi copia l'id dell'oggetto.

Ottenere i numeri di telefono aziendali pre-verificati

Usa l'endpoint Business Account > Preverified Numbers per ottenere una lista di tutti gli oggetti WhatsApp Business Pre-Verified Phone Number, indipendentemente dal loro stato di verifica, presenti nel gruppo di numeri di telefono aziendali pre-verificati del tuo account business:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

I risultati vengono ordinati automaticamente secondo la data di creazione. Puoi anche usare l'espansione dei campi per richiedere il campo code_verification_status e fare in modo che l'API restituisca solo numeri di telefono aziendali pre-verificati con lo stato di verifica indicato:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

Condividere e annullare la condivisione di numeri pre-verificati

Invia una richiesta POST all'endpoint Business > Share Preverified Numbers per condividere numeri di telefono aziendali pre-verificati con partner commerciali, oppure una richiesta DELETE allo stesso endpoint per annullare la condivisione.

I numeri di telefono aziendali pre-verificati condivisi possono essere mostrati nel flusso di iscrizione integrata dai partner commerciali.

Se condividi numeri con più partner commerciali, ti consigliamo di indicare ai tuoi partner di ottenere una lista di numeri pre-verificati condivisi prima di mostrarli nell'iscrizione integrata. Questo riduce la probabilità che un partner cerchi di mostrare un numero già reclamato (i numeri reclamati non compaiono nel flusso, ma il partner potrebbe non saperlo e chiedersi perché non compaia).

Sintassi della richiesta di condivisione

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Sintassi della richiesta di annullamento della condivisione

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Risposta

In caso di azione eseguita correttamente, l'API restituirà il valore true. Se effettui una condivisione, informa il tuo partner commerciale non appena avrai condiviso il numero pre-verificato e forniscigli l'ID del numero. Se annulli la condivisione, il numero non comparirà più nell'implementazione dell'iscrizione integrata del partner.

{
  "success": <SUCCESS>
}

Esempio di richiesta di condivisione

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Esempio di richiesta di annullamento della condivisione

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Esempio di risposta

{
  "success": true
}

Registrare i numeri pre-verificati in modo programmatico

Puoi bypassare la selezione dei numeri di telefono dell'iscrizione integrata interamente e registrare numeri di telefono aziendali pre-verificati sull'account WhatsApp Business di un cliente finale registrato in modo programmatico. Per farlo, segui i passaggi riportati nel documento Registrare i numeri di telefono, ma usa l'ID di un numero di telefono aziendale pre-verificato nel Passaggio 1, quindi vai al Passaggio 4.

Sintassi della richiesta

Usa questa richiesta per creare un numero di telefono WhatsApp Business su un account WhatsApp Business usando l'ID di un numero di telefono aziendale pre-verificato. Questa operazione sostituisce il Passaggio 1.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Corpo del post

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Proprietà

SegnapostoDescrizioneEsempio di valore

<PREVERIFIED_ID>

Stringa

Obbligatorio.


L'ID del numero di telefono aziendale pre-verificato.

6635066806614622

<COUNTRY_DIAL_CODE>

Stringa

Obbligatorio.


Il prefisso internazionale del numero di telefono aziendale pre-verificato.

1

<DISPLAY_PHONE_NUMBER>

Stringa

Obbligatorio.


Il numero di telefono visualizzato del numero di telefono aziendale pre-verificato.

5550783881

<VERIFIED_NAME>

Stringa

Obbligatorio.


Il nome visualizzato del numero di telefono aziendale pre-verificato.

Lucky Shrub

Sintassi della risposta

Se l'operazione viene eseguita correttamente, l'API risponde con l'ID di un numero di telefono WhatsApp Business. Usa questo ID per registrare il numero (Passaggio 4 nel documento Registrare i numeri di telefono).

{
  "id": "<ID>"
}

Proprietà della risposta

SegnapostoDescrizioneEsempio di valore

<ID>

ID di un numero di telefono WhatsApp Business.


Questo oggetto ha sostituito l'oggetto WhatsApp Business Pre-Verified Phone Number.

108692048990658

Esempio di richiesta

curl 'https://graph.facebook.com/v20.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

Esempio di risposta

{
  "id": "108692048990658"
}