Passa al contenuto principale

UC-025 — Gestire Numeri WhatsApp Business

CampoValore
IDUC-025
ObiettivoVerificare e gestire i numeri WhatsApp Business disponibili
CanaleWhatsApp
Complessità⭐ Base
Tempo stimato10 minuti
API coinvolteGET /api/message-server/whatsapp/phone-numbers, GET /api/message-server/whatsapp/phone-numbers/{phoneNumberId}

Scenari reali​

  • ShopItalia — Verificare numeri disponibili: Prima di lanciare una campagna, il team marketing verifica quali numeri WhatsApp Business sono attivi e pronti per l'invio.
  • MultiStore — Controllare onboarding: L'azienda ha richiesto l'attivazione di un nuovo numero per il brand "SportZone" e vuole verificare lo stato di onboarding.
  • AgenziaViaggi — Scegliere numero per campagna: Con 3 numeri attivi (uno per brand), il team seleziona il numero corretto da associare alla campagna estiva.

Flusso di gestione numeri​

Il diagramma mostra i tre stati possibili di un numero WhatsApp Business e le azioni conseguenti: usare per invio, attendere onboarding o contattare il supporto.

Prerequisiti​

  • API Key attiva con permessi WhatsApp
  • Almeno un numero WhatsApp Business registrato sulla piattaforma

Step 1 — Recupera la lista dei numeri disponibili​

Interroga l'endpoint per ottenere tutti i numeri WhatsApp Business associati al tuo account.

curl -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Lista numeri​

{
  "phoneNumbers": [
    {
      "phoneNumberId": "waba-num-001",
      "phoneNumber": "+390212345678",
      "displayName": "ShopItalia",
      "qualityRating": "GREEN",
      "status": "ACTIVE",
      "messagingLimit": "TIER_10K",
      "verifiedName": "ShopItalia S.r.l.",
      "platform": "CLOUD_API"
    },
    {
      "phoneNumberId": "waba-num-002",
      "phoneNumber": "+390287654321",
      "displayName": "SportZone",
      "qualityRating": "UNKNOWN",
      "status": "PENDING",
      "messagingLimit": "TIER_1K",
      "verifiedName": "SportZone by ShopItalia",
      "platform": "CLOUD_API"
    },
    {
      "phoneNumberId": "waba-num-003",
      "phoneNumber": "+390211223344",
      "displayName": "ShopItalia Support",
      "qualityRating": "GREEN",
      "status": "ACTIVE",
      "messagingLimit": "TIER_100K",
      "verifiedName": "ShopItalia S.r.l.",
      "platform": "CLOUD_API"
    }
  ],
  "total": 3
}
Dietro le quinte — Quality rating e messaging limit
  1. Quality rating: Meta assegna un punteggio di qualita basato sul feedback degli utenti. I valori possibili sono GREEN (buono), YELLOW (attenzione) e RED (critico). Un rating RED puo portare alla sospensione del numero.
  2. Messaging limit: Il tier determina quanti messaggi unici puoi inviare in 24 ore: TIER_1K (1.000), TIER_10K (10.000), TIER_100K (100.000), UNLIMITED. Il tier sale automaticamente con un buon quality rating.
  3. Status PENDING: Un numero in stato PENDING sta completando il processo di verifica con Meta. Il processo include la verifica OTP e la revisione del display name.
  4. Platform CLOUD_API: Indica che il numero usa la Cloud API di Meta (gestita da Meta). L'alternativa e ON_PREMISE per installazioni locali del Business API.
  5. Verified name: Il nome verificato da Meta che appare nell'intestazione della chat WhatsApp del destinatario. Non puo essere modificato senza una nuova richiesta di verifica.

Step 2 — Verifica il dettaglio di un numero specifico​

Per ottenere informazioni dettagliate su un singolo numero, usa l'ID restituito nello step precedente.

curl -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/waba-num-001 \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Dettaglio numero​

{
  "phoneNumberId": "waba-num-001",
  "phoneNumber": "+390212345678",
  "displayName": "ShopItalia",
  "qualityRating": "GREEN",
  "status": "ACTIVE",
  "messagingLimit": "TIER_10K",
  "verifiedName": "ShopItalia S.r.l.",
  "platform": "CLOUD_API",
  "nameStatus": "APPROVED",
  "accountMode": "LIVE",
  "lastOnboardedAt": "2025-11-15T10:00:00+01:00",
  "wabaId": "waba-acct-shopitalia-001"
}

:::tip Controlla quality rating e tier prima delle campagne Prima di lanciare campagne di grandi dimensioni, verifica che il qualityRating sia GREEN e che il messagingLimit sia sufficiente per il volume previsto. Un tier TIER_1K non puo gestire una campagna da 5.000 destinatari. :::

Risultato atteso​

StepAzioneRisultato
1GET /phone-numbersLista completa dei numeri con stato e tier
2GET /phone-numbers/{id}Dettaglio completo di un numero specifico

Esempio completo end-to-end​

# 1. Recupera tutti i numeri disponibili
echo "=== Numeri WhatsApp Business ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.phoneNumbers[] | {phoneNumberId, displayName, status, qualityRating, messagingLimit}'

# 2. Trova numeri attivi con tier sufficiente per la campagna
echo "=== Numeri pronti per campagna (ACTIVE + TIER >= 10K) ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '[.phoneNumbers[] | select(.status == "ACTIVE" and (.messagingLimit == "TIER_10K" or .messagingLimit == "TIER_100K" or .messagingLimit == "UNLIMITED"))]'

# 3. Dettaglio del numero scelto
PHONE_ID="waba-num-001"
echo "=== Dettaglio numero ${PHONE_ID} ==="
curl -s -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/${PHONE_ID}" \
  -H "X-Api-Key: YOUR_API_KEY" | jq .

Varianti​

Filtrare numeri per stato​

Per trovare rapidamente solo i numeri attivi lato client:

curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" \
  | jq '[.phoneNumbers[] | select(.status == "ACTIVE")]'

Monitorare lo stato di onboarding​

Per un numero in stato PENDING, esegui un polling periodico:

# Controlla ogni 30 secondi fino a quando lo stato cambia
PHONE_ID="waba-num-002"
while true; do
  STATUS=$(curl -s -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/${PHONE_ID}" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.status')
  echo "$(date): Status = $STATUS"
  if [ "$STATUS" != "PENDING" ]; then
    echo "Onboarding completato con stato: $STATUS"
    break
  fi
  sleep 30
done

Errori comuni​

404 Not Found — Numero non trovato​

{
  "status": "fail",
  "data": {
    "phoneNumberId": "Phone number not found: waba-num-999"
  }
}

Soluzione: Verifica l'ID del numero con una GET sulla lista completa. L'ID potrebbe essere cambiato dopo una riconfigurazione.

401 Unauthorized — API Key mancante o non valida​

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva nel pannello della piattaforma.

403 Forbidden — Permessi insufficienti​

{
  "status": "fail",
  "data": {
    "authorization": "API key does not have permission to access WhatsApp phone numbers"
  }
}

Soluzione: La tua API Key potrebbe non avere i permessi per il canale WhatsApp. Verifica i permessi nel pannello della piattaforma o contatta l'amministratore.

Prossimi passi​

Riferimenti​