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
- Invio di messaggi WhatsApp: invia un template o un messaggio di servizio tramite l'API
- Collegare un proprio numero: configura un numero per inviare e ricevere messaggi con il tuo brand
- Template: sfoglia i template e trova le variabili necessarie per inviarli
- Ricezione di messaggi WhatsApp: leggi i messaggi in entrata e scarica i media
- Webhook: iscriviti ai messaggi in arrivo e agli aggiornamenti di consegna
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.