Buzzbip Guide — Casi d'uso invio WhatsApp v2

Panoramica

Ogni messaggio WhatsApp avviato dall'azienda deve usare un template approvato da Meta. L'API di invio v2 aggiunge pulsanti URL dinamici, media header per destinatario, pulsanti COPY_CODE e template AUTHENTICATION rispetto a v1. Tutti gli invii vanno a POST /api/v2/whatsapp/templates/{TEMPLATE_ID}/send (senza slash finale).

Variabili del corpo

I template usano placeholder numerati {{1}} {{2}} {{3}} nel corpo. body_params[0] riempie {{1}}, body_params[1] riempie {{2}}, e così via.

curl --request POST \
  'https://app.buzzbip.com/api/v2/whatsapp/templates/1289/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "to": "21696816277",
    "country_code": "TN",
    "body_params": ["Sam", "ORD-2026-00041"]
  }'

1. In Buzzbip, crea un template con corpo: "Hello {{1}}, your order {{2}} is confirmed."
2. Invia e attendi lo stato APPROVED.
3. Invia con body_params che corrisponde esattamente al numero di placeholder.

Pulsante URL dinamico

Invia un URL unico per destinatario in un pulsante call-to-action. L'URL del template è fisso all'approvazione tranne un suffisso {{1}}. buttons[].value sostituisce quel suffisso per destinatario. 💡 Suggerimento: usa uno slug o token breve univoco — ID ordine, hash o codice di tracciamento.

curl --request POST \
  'https://app.buzzbip.com/api/v2/whatsapp/templates/1296/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "to": "21696816277",
    "country_code": "TN",
    "body_params": ["Sam"],
    "buttons": [
      { "index": 0, "sub_type": "url", "value": "ord-2026-00041" }
    ]
  }'

1. Crea un template con pulsante URL: https://shop.example.com/track/{{1}}
2. Invia e attendi APPROVED.
3. Invia con buttons, index 0, sub_type "url", value è il suffisso univoco.

PDF, immagine o video per destinatario

Flusso in due passaggi per inviare un file diverso a ogni cliente. Per più PDF a un destinatario: A — unisci PDF lato server → un upload → un invio; B — invii multipli: ripeti upload+invio per file; C — documento principale come header + file extra come pulsanti URL firmati. ⚠️ Nota: WhatsApp consente un solo allegato header per invio.

curl --request POST \
  'https://app.buzzbip.com/api/v2/whatsapp/media' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --form 'file=@/path/to/invoice-sam-april.pdf'

1. Carica il file: POST /api/v2/whatsapp/media (multipart, campo: file) → la risposta contiene media_id
2. Invia il template con header_media_id uguale a quel media_id. Per DOCUMENT, imposta anche document_filename.
3. Ripeti i passaggi 1–2 per ogni destinatario con il suo file.

Pulsante COPY_CODE e OTP

Due sotto-pattern. D1: codice promo che il cliente copia — crea template con pulsante COPY_CODE, invia con buttons [{ index: 0, sub_type: "copy_code", value: "SAVE25" }], codice diverso per cliente. D2: OTP per template AUTHENTICATION — invia solo con otp_code; l'API inserisce il codice nel corpo e nel pulsante Copy Code.

curl --request POST \
  'https://app.buzzbip.com/api/v2/whatsapp/templates/1299/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "to": "21696816277",
    "country_code": "TN",
    "body_params": ["Sam"],
    "buttons": [{ "index": 0, "sub_type": "copy_code", "value": "SAVE25" }]
  }'

Combinare body params, media e pulsanti

Tutti i campi opzionali possono essere combinati in un unico invio quando il template ha i componenti corrispondenti.

curl --request POST \
  'https://app.buzzbip.com/api/v2/whatsapp/templates/1302/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "to": "21696816277",
    "country_code": "TN",
    "body_params": ["Sam", "2026-04", "99.00 TND"],
    "header_media_id": 1542,
    "document_filename": "invoice-sam-april-2026.pdf",
    "buttons": [
      { "index": 0, "sub_type": "url", "value": "r/sam-2026-04" }
    ]
  }'

Prossimi passi

Correlati: api/v2/whatsapp-templates/send-template api/v2/whatsapp-media guides/whatsapp-common-gotchas