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. Puoi inviarne uno dal catalogo gestito di Bird, che non richiede un numero tuo e invia da un mittente gestito da Bird, oppure collegare un numero tuo e inviare i tuoi template da quello. I contatti possono scrivere a un numero tuo 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. Validiamo la richiesta e restituiamo 202 Accepted con un ID messaggio. Addebito e consegna avvengono in modo asincrono. L'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 numeri propri collegati |
| Gruppi | Gruppi WhatsApp amministrati dai tuoi numeri aziendali, con partecipanti e link di invito |
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 Messaggi ricevuti e un dettaglio Per numero di telefono. Per agire su ogni messaggio in arrivo nel momento in cui viene ricevuto, iscriviti invece all'evento webhook whatsapp.received; vedi Webhook per messaggi in arrivo.
Alcuni destinatari chiedono di non ricevere più messaggi, e una risposta con STOP è il modo più comune per farlo: Bird include la lista di parole chiave, quindi funziona sui tuoi numeri senza configurazione. Puoi anche registrare una soppressione limitata a un singolo account business, oppure un opt-out che copre l'intero spazio di lavoro. Bird blocca gli invii successivi a quell'indirizzo in entrambi i casi. Vedi Opt-out e parole chiave.
Passi successivi
| Pagina | Cosa copre |
|---|---|
| Invio di messaggi WhatsApp | L'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 cronologia delle reazioni tramite API |
| Webhooks | Webhook di consegna, messaggi in entrata, reazioni, soppressione e gruppi |
| Groups | Chat condivise con più clienti, link di invito e limiti dei gruppi |
| Invio a un gruppo | Indirizzare un gruppo, requisiti e ricevute per partecipante |
| Ricezione messaggi di gruppo | Quale partecipante ha scritto un messaggio di gruppo e come rispondere |
| Opt-out | Regole per parole chiave, preferenze dei destinatari e lista di soppressione |
| Metriche WhatsApp | Prestazioni di consegna in uscita e volume dei messaggi in entrata |
| Limiti di frequenza | Capacità della policy dell'organizzazione, header di risposta e gestione del codice 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