FAQ API WhatsApp

Installa l'SDK, ottieni una chiave API e chiama l'endpoint di invio con un template pre-approvato. Bird fornisce numeri mittente gestiti, quindi non è necessario alcun passaggio di provisioning del numero prima del primo invio.

Un unico endpoint di invio che accetta un template o contenuto libero, un catalogo di template pre-approvati, eventi di consegna e conferma di lettura tramite API e webhook, una cronologia eventi per singolo messaggio, messaggi e media in entrata, metriche di consegna aggregate e numeri mittente gestiti da Bird per il primo invio. Stesse chiavi API e host regionali di Bird Email e SMS.

Significa che Bird ha accettato il messaggio e lo consegnerà in modo asincrono. La risposta 202 non è una conferma di consegna. Consegna, conferme di lettura ed errori arrivano successivamente come eventi che puoi interrogare o ricevere tramite webhook.

Entrambi. Un template raggiunge chiunque in qualsiasi momento, ed è per questo che è l'unico modo per avviare una conversazione. Il contenuto libero raggiunge un contatto all'interno della finestra di assistenza clienti di 24 ore aperta dal suo stesso messaggio, e solo da un numero di proprietà del tuo workspace. Bird non monitora quella finestra per te, quindi un invio in formato libero al di fuori di essa viene accettato e poi fallisce con service_window_expired.

Sì. Il messaggio di un contatto arriva sul webhook whatsapp.received, viene registrato nel log WhatsApp nella dashboard e viene conteggiato nella scheda In entrata della pagina Metriche. I messaggi in entrata ti raggiungono solo sui tuoi numeri: i numeri gestiti da Bird sono condivisi tra i workspace, quindi un messaggio inviato a uno di essi non viene registrato per il tuo.

Per messaggio, in base alla categoria del template (autenticazione, utility o marketing) e al Paese del destinatario. L'addebito avviene quando Bird accetta il messaggio, non quando il destinatario lo legge.

Una tariffa per messaggio più elevata che Meta applica quando la tua azienda si trova al di fuori del Paese del destinatario e invii template di autenticazione. L'idoneità inizia dopo l'invio di oltre 750.000 messaggi con template di autenticazione agli utenti di un singolo Paese in un periodo mobile di 30 giorni. La sede principale della tua azienda, impostata in Meta Business Manager, determina quali invii sono idonei.

I mittenti condivisi pagano sempre la tariffa internazionale per i template di autenticazione, indipendentemente dalla soglia di volume. Tutti i numeri WhatsApp sono attualmente gestiti da Bird, quindi questa tariffa si applica agli invii di autenticazione in cui la tua azienda si trova al di fuori del paese del destinatario.

Le pagine Utilizzo e Spesa nella dashboard mostrano i tuoi costi WhatsApp. Il registro messaggi mostra la categoria e il costo di ogni singolo messaggio una volta tariffato.

No. Ogni messaggio WhatsApp è una chiamata API separata a POST /v1/whatsapp/messages con un singolo destinatario. Per inviare a più destinatari, itera sull'endpoint di invio.

Il gruppo di frequenza whatsapp_send si applica all'endpoint di invio. Ogni risposta include un header IETF RateLimit con la quota residua e il tempo di reset: regolati su quello anziché su un numero fisso. I piani a pagamento aumentano la frequenza base.

Sì, come contenuto libero. L'endpoint di invio supporta immagini, video, audio, sticker, documenti e posizione oltre al testo. Come qualsiasi invio in formato libero, ciascuno richiede una finestra di assistenza clienti di 24 ore aperta e un numero di proprietà del tuo workspace. I parametri dei template restano basati su testo.

Una struttura di messaggio pre-approvata registrata presso WhatsApp tramite Meta. Ogni template ha un nome, una o più lingue, una categoria (autenticazione, utility o marketing) e variabili segnaposto che compili al momento dell'invio. Bird fornisce un catalogo gestito che puoi utilizzare subito, e puoi creare i tuoi template una volta collegato un WhatsApp Business Account.

Meta esamina e approva ogni template, che sia stato inviato da Bird o da te. Un template può essere attivo nel complesso ma avere singole lingue in stato rifiutato o sospeso, quindi verifica lo stato per lingua prima di inviare in quella lingua.

Autenticazione (codici monouso e flussi di login), utilità (aggiornamenti ordini, notifiche account) e marketing (promozioni e offerte). La categoria determina quale numero mittente Bird seleziona e come viene tariffato il messaggio.

Passa un array components con parametri body e button al momento dell'invio. I parametri possono essere nominali (associati tramite una chiave come 'name') o posizionali (associati tramite indice). I parametri nominali sono più sicuri quando l'ordine delle variabili di un template potrebbe cambiare.

Sì, nella pagina Template della dashboard, una volta che il tuo workspace ha collegato un proprio WhatsApp Business Account. Il builder attualmente supporta il testo del corpo in una singola lingua. La creazione tramite API pubblica non è disponibile, ma l'endpoint di invio accetta qualsiasi template che il tuo workspace può inviare, gestito o tuo.

No. Bird fornisce numeri mittente gestiti. I template di autenticazione vengono inviati da un numero dedicato, mentre i template utility e marketing condividono un numero per le notifiche. La pagina Numbers nella dashboard elenca i numeri disponibili per il tuo workspace.

Sì, e collegarne uno è ciò che sblocca l'invio con il tuo brand: i tuoi template, contenuto libero all'interno di una finestra di assistenza clienti aperta e messaggi in entrata. I numeri gestiti da Bird sono condivisi tra i workspace e supportano solo template gestiti, quindi considerali come il percorso a configurazione zero per un primo invio, non come la soluzione definitiva.

Per un template gestito, in base alla sua categoria: l'autenticazione utilizza un numero mittente dedicato, mentre utility e marketing condividono un numero per le notifiche. Tutto il resto specifica il proprio mittente nel campo from, che deve essere un numero di proprietà del tuo workspace, e un template da te creato deve risiedere sullo stesso WhatsApp Business Account di quel numero.

Invia una POST a /v1/whatsapp/messages con il numero di telefono del destinatario in formato E.164, uno slug del template e i valori per le variabili del template. Bird valida la richiesta, restituisce un 202 con un ID messaggio e consegna in modo asincrono.

Passa un header Idempotency-Key e una richiesta ripetuta restituirà il risultato originale anziché inviare due volte. Senza di esso, un nuovo tentativo viene trattato come un nuovo messaggio e il destinatario riceve un duplicato.

Sì. I tag sono fino a 20 etichette strutturate con cui puoi filtrare e raggruppare nel registro messaggi e nelle metriche. I metadati sono JSON arbitrari (fino a 2 KB) restituiti sul messaggio e sui relativi eventi, utili per correlare gli invii con i tuoi sistemi.

Ogni cambio di stato genera un evento webhook: accepted, sent, delivered, read, failed o rejected. Puoi anche interrogare la timeline degli eventi del messaggio tramite API. Lo stato delivered significa che WhatsApp ha confermato che il dispositivo del destinatario lo ha ricevuto.

Sei eventi del ciclo di vita: whatsapp.accepted (Bird lo ha messo in coda), whatsapp.sent (inviato a WhatsApp), whatsapp.delivered (il dispositivo del destinatario lo ha ricevuto), whatsapp.read (il destinatario lo ha aperto), whatsapp.failed (WhatsApp lo ha rifiutato dopo l'invio) e whatsapp.rejected (Bird lo ha rifiutato prima dell'invio, nessun addebito).

No. Un evento di lettura significa che il destinatario ha aperto il messaggio, ma lo stato del messaggio resta su "consegnato". La lettura viene segnalata separatamente come timestamp e come evento whatsapp.read, non come cambio di stato.

Rejected significa che Bird ha rifiutato il messaggio prima di inviarlo a WhatsApp, quindi non viene addebitato alcun costo. Failed significa che Bird lo ha inviato ma WhatsApp ha rifiutato la consegna. Entrambi includono un oggetto errore con codice, descrizione e codice errore Meta, quando applicabile.

In due modi: recuperare la cronologia di un messaggio specifico con GET /v1/whatsapp/messages/{id}/events, oppure sottoscrivere un endpoint webhook agli eventi di tipo whatsapp.* e riceverli in tempo reale. La pagina Messages nella dashboard mostra anche la cronologia degli eventi per ogni messaggio.

Nella pagina Metrics dell'app dashboard WhatsApp. Mostra tasso di consegna, tasso di errore, volume accettato e latenza di consegna (elaborazione ed end-to-end) su tutto ciò che il tuo workspace invia.

Per numero mittente, per template, per categoria di template e per tag. Un tasso di errore che sembra accettabile nel complesso spesso risulta essere un singolo template o un singolo tag a generare la maggior parte degli errori.

Due: latenza di elaborazione (lato Bird, dall'accettazione all'invio) e latenza totale (end-to-end, dall'accettazione alla conferma di consegna). Entrambe sono riportate a p50, p95 e p99.

Non ancora per le statistiche aggregate. È possibile creare aggregazioni personalizzate dagli eventi webhook o dall'API della lista messaggi, che include lo stato e la cronologia degli eventi per ogni messaggio.

WhatsApp fornisce la crittografia end-to-end per i messaggi tra il mittente e il dispositivo del destinatario. La tua chiamata API a Bird avviene tramite HTTPS e gli eventi webhook che Bird ti invia sono firmati con HMAC.

Ogni evento è firmato con HMAC. Verifica la firma con il secret del tuo endpoint prima di elaborare il payload e ruota il secret dalla dashboard quando necessario.

Nella regione in cui è ospitata la tua organizzazione, us1 o eu1. La tua chiave API lo indica nel prefisso (bk_us1_, bk_eu1_), ed è così che gli SDK e la CLI selezionano l'endpoint corretto senza che tu debba configurarne uno.

Solo ciò per cui la configuri. Una chiave ha una lista di scope, ciascuno in lettura o scrittura, quindi una chiave che invia messaggi WhatsApp non può gestire i tuoi numeri o leggere un altro canale. Le chiavi supportano anche allowlist di IP e rotazione sicura con un periodo di grazia configurabile.

Le certificazioni e la documentazione sulla sicurezza sono su trust.bird.com. L'accordo sul trattamento dei dati, l'informativa sulla privacy e la policy di utilizzo accettabile sono su bird.com/legal. Per un questionario fornitore, il tuo team Bird dedicato se ne occupa.