Panoramica di WhatsApp
Bird WhatsApp usa la stessa piattaforma e le stesse chiavi API di Bird Email e Bird SMS. Chiama l'host regionale per la chiave API (https://us1.platform.bird.com o https://eu1.platform.bird.com). Gli endpoint WhatsApp si trovano sotto /v1/whatsapp/….
Gli invii avviati dall'azienda utilizzano un template di messaggio pre-approvato. Inviane uno dal catalogo gestito di Bird, che non richiede un tuo numero e invia da un mittente gestito da Bird, oppure collega un tuo numero e invia i tuoi template da quello. I contatti possono scrivere a un tuo numero e Bird registra quei messaggi in entrata insieme a quelli in uscita.
Come funziona l'invio
Invia un messaggio WhatsApp con POST /v1/whatsapp/messages: un destinatario, un template, tag e metadati opzionali. La richiesta viene validata e restituita con 202 Accepted e un ID messaggio. Addebito e consegna avvengono in modo asincrono. La API non ha un endpoint batch, quindi invia una richiesta per messaggio.
Tre concetti definiscono l'intera API:
- Invio e consegna sono fasi separate. Un 202 significa che Bird ha accettato il messaggio. Il dispositivo del destinatario lo riceve solo dopo che il messaggio avanza attraverso WhatsApp fino a un risultato di consegna terminale. Una conferma di lettura appare come timestamp read_at ed evento whatsapp.read; non modifica lo stato del messaggio.
- Ogni invio avviato dall'azienda usa un template. Fornisci il template slug, un language opzionale e i valori per le sue variabili. Un messaggio di servizio, ovvero testo libero o media, raggiunge un contatto solo all'interno della finestra di 24 ore aperta dal suo stesso messaggio, e solo da un numero di proprietà del tuo spazio di lavoro. Vedi Invio di messaggi WhatsApp.
- Categoria e destinazione determinano mittente e prezzo. Ogni template ha una categoria authentication, utility o marketing. Un template gestito invia dal numero Bird per la sua categoria, quindi non ha un campo from; ogni altro invio specifica il proprio mittente. Il prezzo dipende anche dal paese del destinatario e il messaggio viene addebitato in due passaggi: la commissione di Bird mentre Bird elabora l'invio e la quota di Meta quando il messaggio viene consegnato. Vedi Costi e fatturazione.
L'app WhatsApp nella dashboard
Nella dashboard, WhatsApp è una delle app canale dello spazio di lavoro. Le sue pagine:
| Pagina | A cosa serve |
|---|---|
| Messages | Messaggi in entrata e in uscita, con contenuto, eventi e dettagli di consegna per messaggio |
| Metrics | Metriche di consegna in uscita e volume dei messaggi in entrata |
| Templates | I template che puoi inviare, gestiti e tuoi: nome, lingua, categoria e anteprima renderizzata |
| Numbers | Numeri mittente gestiti da Bird e, quando il rollout ti raggiunge, i tuoi numeri |
Visibilità
Bird registra una timeline per ogni messaggio. Le timeline in uscita includono eventi di accettazione, invio, consegna, lettura e fallimento. Una timeline in entrata registra quando Bird ha ricevuto il messaggio.
- Leggere una timeline: GET /v1/whatsapp/messages/{message_id}/events restituisce gli eventi del messaggio. La pagina Messages mostra la stessa timeline. Vedi Eventi WhatsApp.
- Iscriversi agli eventi di consegna in uscita: invia gli eventi pubblici whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed e whatsapp.rejected a un endpoint webhook.
- Consultare le metriche aggregate: la pagina Metrics ha schede separate Outbound e Inbound.
Ricezione
Bird archivia i messaggi in entrata inviati a un numero di proprietà del tuo spazio di lavoro, con stato received. I numeri gestiti da Bird non ricevono messaggi per il tuo spazio di lavoro. Trova i messaggi nella pagina Messages o con GET /v1/whatsapp/messages?direction=inbound. Il dettaglio del messaggio mostra testo, media supportati, documenti, posizioni e tipi di contenuto che Bird non può renderizzare. I media ricevuti sono disponibili per 30 giorni.
La scheda Inbound nella pagina Metrics mostra una serie temporale Messages received e una suddivisione By phone number. Per agire su ogni messaggio in entrata appena arriva, iscriviti invece all'evento webhook whatsapp.received; vedi Eventi WhatsApp.
Alcuni destinatari chiedono di interrompere l'invio. Registra la richiesta come soppressione legata a un account aziendale o come opt-out a livello di persona che copre l'intero spazio di lavoro: in entrambi i casi Bird blocca gli invii successivi a quell'indirizzo. Vedi Opt-out.
Passi successivi
| Pagina | Cosa copre |
|---|---|
| Invio di messaggi WhatsApp | La API di invio: destinatario, template, componenti, tag, modello asincrono |
| Messaggi di servizio | I nove tipi di contenuto, la finestra di servizio e l'invio di media tramite URL |
| Ricezione | Messaggi in entrata, recupero dei media e webhook whatsapp.received |
| Template | Il catalogo dei template, categorie e variabili, e invio tramite slug |
| Log WhatsApp | Messaggi in entrata e in uscita, contenuto, stato e timeline degli eventi |
| Eventi | Timeline dei messaggi e webhook pubblici di consegna in uscita |
| Opt-out | Soppressioni a livello di account, opt-out a livello di spazio di lavoro e come terminarli |
| Metriche WhatsApp | Prestazioni di consegna in uscita e volume dei messaggi in entrata |
| Limiti di frequenza | La frequenza base di ogni gruppo, whatsapp_send incluso, e gestione del 429 |
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione