Numeri di telefono WhatsApp
Un messaggio WhatsApp parte da uno di due tipi di numero: uno che Bird gestisce per conto tuo oppure uno di proprietà del tuo spazio di lavoro. Il tipo che possiedi determina cosa puoi inviare e se l'invio indica il mittente.
La pagina Numbers li elenca entrambi. Il campo from nella risposta di invio e nel log dei messaggi identifica il numero utilizzato da un dato messaggio.
Numeri gestiti da Bird
I numeri di Bird non richiedono configurazione e includono i template pre-approvati il cui slug inizia con bird_. Bird ne seleziona uno in base alla categoria del template e alla tua area geografica: i template authentication usano un numero dedicato per l'autenticazione, i template utility un numero per le notifiche. Un invio con template gestito quindi non ha il campo from, e impostarne uno viene rifiutato.
Questi numeri usano l'infrastruttura di invio gestita da Bird, quindi il mittente che il destinatario vede è quello di Bird e non il tuo, e i contenuti liberi non possono essere inviati tramite essi. Sono contrassegnati come Bird-managed nella colonna WABA.
Il tuo numero
Collegare un numero proprio è ciò che sblocca l'invio con il tuo brand: i tuoi template e contenuti liberi all'interno di una finestra di assistenza clienti aperta. Ogni invio da quel numero lo riporta in from.
Lo colleghi dalla pagina Numbers, nel popup Embedded Signup di Meta. Ci sono due modalità, e differiscono per chi legge il codice di verifica che Meta invia al numero:
- Ho un mio numero. Ricevi il codice di Meta via SMS o chiamata vocale e lo digiti nella finestra Embedded Signup. Scegli il percorso di migrazione supportato o, se ne hai i requisiti, quello di coesistenza con Business app prima di modificare una registrazione esistente, e imposta un Phone registration PIN solo se il numero ne ha già uno su WhatsApp.
- Un numero che il tuo spazio di lavoro possiede presso Bird. Selezionalo dalla lista Number. Bird riceve il codice e completa la verifica di Meta per te, quindi il numero arriva pre-verificato e tu devi solo selezionarlo nella finestra Embedded Signup.
Verifica su un numero del tuo spazio di lavoro presso Bird
Scegliere un numero posseduto avvia la verifica prima dell'apertura del popup Embedded Signup. Bird chiede a Meta di inviare un SMS al numero, poi legge il codice per conto tuo.
Di solito ci vuole meno di un minuto. Non devi attendere nella finestra: Continue in background la chiude e la riga nella pagina Numbers mostra lo stesso avanzamento.
Una volta letto il codice, il numero è verificato con Meta e in attesa che tu completi l'Embedded Signup. Finish setting up apre il popup di Meta, dove selezioni il numero e l'account business a cui deve essere associato.
Cosa indica lo stato di un numero
Un numero attraversa diversi stati prima di poter inviare, e la colonna Status indica quello in cui si trova:
| Stato | Significato |
|---|---|
| Preparing | Bird sta completando la verifica di Meta per un numero posseduto dal tuo spazio di lavoro. |
| Pre-verified | Bird ha completato la verifica di Meta. Completa il numero in Embedded Signup. |
| Pending | L'Embedded Signup è terminato e Bird sta registrando il numero presso Meta. |
| Connected | Il numero può inviare. |
| Failed | La configurazione si è interrotta. La riga riporta il motivo. |
Entrambi i percorsi possono fallire a metà, durante la verifica di Meta o nel popup. Il modo in cui recuperi dipende dal motivo riportato nella riga.
Se la riga riporta verification_code_not_received o verification_rate_limited, apri il numero e seleziona Try again anziché disconnetterlo. Perché la pre-verifica fallisce e quando riprovare spiega quando il pulsante diventa disponibile e cosa fare se anche il nuovo tentativo fallisce.
Per qualsiasi altro motivo, disconnetti il numero dalle azioni della riga e collegalo di nuovo: la riga in errore mantiene il numero riservato, quindi un secondo tentativo senza rimuoverlo viene rifiutato.
Posso inviare WhatsApp senza acquistare un numero di telefono? illustra la scelta.
Cosa mostra un numero collegato
La pagina di un numero mostra cosa WhatsApp gli consente di fare, più una sezione Activity che copre la sua attività di invio.
Quality rating, Messaging limit e Send rate sono valori di WhatsApp, non di Bird. Il messaging limit è il numero di conversazioni avviate dal business che WhatsApp consente in 24 ore, e aumenta man mano che il numero invia bene. Quality rating riporta Not rated finché WhatsApp non ha abbastanza storico di consegna per assegnare un punteggio.
La scheda Business profile contiene ciò che i destinatari vedono di te in WhatsApp: nome visualizzato, descrizione, indirizzo e immagine del profilo.
L'account business dietro un numero
Ogni numero collegato appartiene a un WhatsApp Business Account, e la colonna WABA rimanda a esso. La sua scheda riporta le revisioni di Meta sul business stesso, non sul numero.
Questi stati determinano cosa può fare l'account. Business verification in particolare è prerequisito per i template di autenticazione: un business non verificato non può crearne uno. Marketing Messages API riporta Onboarded una volta che Meta ha accettato l'account. Gli invii marketing non lo attendono. L'onboarding abilita le ottimizzazioni di consegna di Meta e un header gif, che fallisce con WhatsApp su un account che non ha completato l'onboarding. Uno spazio di lavoro può contenere più account business, ciascuno con più numeri. Consulta i verdetti dell'account che possiede il mittente desiderato; un account collegato ha uno spazio di lavoro e un proprietario regionale specifici.
Bird legge questi dati da Meta a intervalli e non in modo continuo, quindi Last read from WhatsApp indica la data dei verdetti sopra riportati.
Leggere i tuoi numeri dall'API
Tutto ciò che la dashboard mostra sopra è leggibile tramite l'API e dagli SDK. Le letture richiedono una chiave API con accesso in lettura a whatsapp_management.
GET /v1/whatsapp/numbers restituisce i tuoi mittenti come pagina a cursore. Ciascuno riporta lo stato che WhatsApp gli attribuisce, quindi è la chiamata che ti dice quali valori from un invio può usare.
GET /v1/whatsapp/numbers/{id} legge un singolo numero, con lo stesso quality rating, messaging limit e livello di throughput mostrati nella pagina di dettaglio. GET /v1/whatsapp/numbers/{id}/profile legge il profilo business dietro la scheda Business profile, inclusi description, address e websites.
GET /v1/whatsapp/numbers/{id}/events restituisce come un numero ha raggiunto il suo stato attuale, dal più recente: quando è stato aggiunto, ogni cambio di stato e ogni decisione su messaging limit, quality rating e display name. Ogni evento contiene type, summary e created_at. type è un enum aperto, quindi tratta un valore che non riconosci come un tipo di evento futuro anziché come un errore.
GET /v1/whatsapp/business-accounts e GET /v1/whatsapp/business-accounts/{id} leggono gli stati dell'account descritti sopra in questa pagina: account_review_status, business_verification_status e marketing_messages_onboarding_status. Un numero riporta il suo account nel proprio campo waba, che contiene l'account ID di Meta anziché un ID Bird.
Due dettagli utili prima di costruire su queste letture. meta_synced_at data i campi riportati da WhatsApp, corrispondente a Last read from WhatsApp nella dashboard, ed è assente su un numero che Bird gestisce per conto tuo. Un numero a metà registrazione è leggibile: status riporta preparing e awaiting_signup, next indica cosa fare riguardo a quello stato e finish_setup_url contiene il link per completarlo, così puoi monitorare la configurazione e passare a una persona l'ultimo passaggio. L'unico campo non esposto è meta_preverified_id, l'id interno di WhatsApp per un numero in preparazione, che resta nella dashboard.
Collegare, rinominare e disconnettere un numero non fanno parte dell'API pubblica né degli SDK. Sono disponibili nella dashboard e sulla CLI (bird whatsapp numbers create|update|delete e bird whatsapp numbers profile update). Un solo passaggio richiede il browser: una nuova connessione si completa nella schermata di consenso di Meta, motivo per cui create ti fornisce un finish_setup_url anziché completare autonomamente.
Messaggi in entrata
I messaggi in entrata raggiungono il tuo spazio di lavoro solo sui tuoi numeri. Bird li registra nel log WhatsApp e la scheda Inbound nella pagina Metrics riporta il volume ricevuto per numero. Ogni messaggio apre anche la finestra di 24 ore necessaria per i contenuti liberi. I numeri gestiti da Bird non ricevono messaggi per il tuo spazio di lavoro.
Prossimi passi
- Inviare messaggi WhatsApp: la chiamata di invio di questi numeri e quando from è obbligatorio
- Template WhatsApp: il catalogo gestito e i tuoi template
- La finestra di assistenza clienti WhatsApp: quando i contenuti liberi sono recapitabili
- Log WhatsApp: vedere quale numero ha inviato un messaggio
- Collegare WhatsApp a Bird: dall'acquisto di un numero a un canale attivo: un video che percorre lo stesso iter nella dashboard
for await (const number of bird.whatsapp.numbers.list({ limit: 25 })) {
console.log(number.id, number.phone_number, number.status);
}for number in client.whatsapp.numbers.list(limit=25):
print(number.id, number.phone_number, number.status)for number, err := range client.Whatsapp.Numbers.List(ctx, bird.WhatsappNumbersListParams{Limit: 25}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(number.Id, number.PhoneNumber, number.Status)
}foreach ($bird->whatsapp->numbers->list() as $number) {
echo $number->getId(), ' ', $number->getPhoneNumber(), ' ', $number->getStatus(), PHP_EOL;
}curl -sS "https://us1.platform.bird.com/v1/whatsapp/numbers?limit=25" \
-H "Authorization: Bearer $BIRD_API_KEY"Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Esplora la funzionalitàConnect WhatsAppSegui il percorso di apprendimentoBuild your first integration
Prova l'esercitazione e ottieni un brief di implementazione