Numeri di telefono

Questa guida specifica come puoi verificare il tuo numero di telefono e la relativa formattazione richiesta per l'API Cloud.

Esiste un criterio per il tipo di numeri di telefono che puoi aggiungere al tuo account WhatsApp Business (WABA). Per maggiori informazioni, consulta Numeri di telefono.

Per alcune chiamate API elencate è necessario che tu conosca l'ID del numero di telefono. Consulta Acquisizione di tutti i numeri di telefono per saperne di più sulla modalità di acquisizione dei numeri di telefono associati al tuo WABA. La risposta della chiamata API include gli ID per ciascuno dei numeri di telefono collegati all'account WhatsApp Business. Salva l'ID per il telefono che desideri utilizzare con qualsiasi chiamata /PHONE_NUMBER_ID.

Verifica dei numeri di telefono

Devi verificare il numero di telefono che desideri utilizzare per inviare i messaggi ai tuoi clienti. I numeri di telefono devono essere verificati utilizzando un codice inviato tramite SMS/chiamata. La procedura di verifica può essere eseguita tramite le chiamate API Graph specificate di seguito.

Per verificare un numero di telefono utilizzando l'API Graph, effettua una richiesta POST a PHONE_NUMBER_ID/request_code. Nella chiamata, includi il metodo di verifica e la lingua scelti.

Parametri

Esempio

Esempio di richiesta:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

Dopo la chiamata API, riceverai il codice di verifica tramite il metodo selezionato. Per completare la procedura di verifica, includi il codice in una richiesta POST a PHONE_NUMBER_ID/verify_code.

Parametri

Esempio

Esempio di richiesta:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

Una risposta corretta è simile a questa:

{
  "success": true
}

Controllo della modifica dell'identità

Se vuoi che verifichiamo l'identità di un cliente prima di procedere alla consegna del messaggio, abilita l'impostazione del controllo della modifica dell'identità sul tuo numero di telefono aziendale.

Se un cliente esegue un'azione su WhatsApp che consideriamo una modifica dell'identità, generiamo un nuovo hash di identità per l'utente. Puoi acquisire questo hash ogni volta che invii un messaggio al cliente, abilitando l'impostazione del controllo della modifica dell'identità sul tuo numero di telefono aziendale. Dopo l'abilitazione, ogni volta che il cliente ti invia un messaggio o che invii un messaggio al cliente senza un hash di identità, includeremo l'hash del cliente in qualsiasi webhook dei messaggi in arrivo o dello stato di ricezione. Quindi puoi acquisire e memorizzare questo hash per usarlo in futuro.

Per utilizzare l'hash, includilo in una richiesta di invio di messaggi. Confronteremo l'hash presente nella richiesta con quello corrente del cliente. In caso di corrispondenza dell'hash, il messaggio verrà consegnato. In caso di mancata corrispondenza, significa che il cliente ha modificato la propria identità dall'ultimo messaggio che hai inviato, quindi non consegneremo il nuovo messaggio. Invece, ti invieremo un webhook dello stato dei messaggi contenente il codice di errore 137000, informandoti dell'errore e della mancata corrispondenza.

Quando ricevi un webhook dell'hash non corrispondente, presumi che il numero di telefono del cliente non sia più affidabile. Per ristabilire l'affidabilità, verifica di nuovo l'identità del cliente usando altri canali diversi da WhatsApp. Dopo aver ristabilito l'affidabilità, ripeti l'invio del messaggio non riuscito alla nuova identità (se presente), senza hash. Quindi memorizza il nuovo hash del cliente incluso nel webhook dello stato di ricezione del messaggio.

Sintassi della richiesta

Invia una richiesta POST all'endpoint WhatsApp Business Phone Number > Settings per abilitare o disabilitare l'impostazione di controllo della modifica dell'identità.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Corpo del post

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

Imposta <ENABLE_IDENTITY_KEY_CHECK> su true per abilitare il controllo dell'identità o su false per disabilitarlo.

Esempio di richiesta di abilitazione

curl 'https://graph.facebook.com/v19.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

Esempio di risposta di abilitazione

{
  "success": true
}

Esempio di invio del messaggio con il controllo

Questo messaggio di esempio verrebbe consegnato solo in caso di corrispondenza del valore dell'hash recipient_identity_key_hash con quello attuale del cliente.

curl 'https://graph.facebook.com/v19.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

Esempio di webhook dei messaggi in arrivo

Nei webhook dei messaggi in arrivo, l'hash del cliente viene assegnato alla proprietà identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Esempio di webhook dello stato di ricezione

Nei webhook dello stato di ricezione, l'hash del cliente viene assegnato alla proprietà recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Esempio di webhook dello stato di ricezione non riuscito

Nei webhook dello stato di ricezione, l'hash del cliente viene assegnato alla proprietà recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Acquisizione del livello di throughput

Usa l'endpoint WhatsApp Business Phone Number per ottenere l'attuale livello di throughput di un numero di telefono:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput