Numeri inbox e webhook dei messaggi in arrivo

Nella pagina Numeri inbox scegli quali dei tuoi numeri WhatsApp si sincronizzano nell'inbox Unibox, dove il tuo team legge le loro chat e risponde. Se dai a un numero un URL webhook, WbizTool invia anche al tuo server ogni nuovo messaggio che il numero riceve o invia, come JSON firmato: registra le conversazioni in un CRM, avvisa il team o avvia una risposta automatica.

Stai creando il ricevitore? Vai a Come vengono consegnati i webhook, Verificare la firma e Payload.

Chi può farlo: Proprietari ed Editor aggiungono numeri, modificano i webhook e vedono il secret del webhook. Gli Analisti non vedono Numeri inbox nella barra laterale. Serve il componente aggiuntivo Unibox: $20 al mese o $200 all'anno ai prezzi di listino USA per ogni numero nell'inbox (il tuo prezzo compare in Fatturazione e piani), aggiunto a un piano a pagamento o a vita da un Proprietario in Fatturazione e piani (vedi Componenti aggiuntivi). La sua quantità indica quanti numeri possono stare nell'inbox contemporaneamente.

Apri Numeri inbox sotto Inbox nella barra laterale, oppure vai su /unibox/listeners/.

Prima di iniziare#

• Il componente aggiuntivo Unibox con un numero inbox libero: la riga sotto il titolo della pagina dice, ad esempio, "2 di 3 numeri inbox in uso (componente aggiuntivo Unibox)", oppure "Nessun componente aggiuntivo Unibox" (vedi Senza il componente aggiuntivo Unibox).
• Un numero WhatsApp collegato con un codice QR o un codice di abbinamento, che mostra Collegato in Numeri WhatsApp. I numeri collegati tramite l'estensione del browser non si possono aggiungere. Un account Telegram collegato si aggiunge come un numero.
• Per un webhook: un indirizzo https:// di al massimo 500 caratteri raggiungibile da Internet (non localhost né una rete privata) che accetti richieste POST con un corpo JSON e risponda 2xx entro 8 secondi.

Aggiungere un numero all'inbox#

1. Apri la finestra

   Fai clic su Aggiungi numero all’inbox in alto a destra nella pagina.

2. Scegli il numero

   Sceglilo in Numero WhatsApp. L'elenco mostra i tuoi numeri collegati che non sono ancora nell'inbox.

3. Aggiungi un webhook (facoltativo)

   Scrivi il tuo indirizzo in URL del webhook (facoltativo). Compare allora Messaggi da inviare: lascia spuntato Messaggi ricevuti, Messaggi inviati o entrambi. Puoi aggiungere o modificare il webhook in seguito.

   

4. Aggiungilo

   Fai clic su Aggiungi numero. Vedi "Numero aggiunto – le sue chat iniziano a sincronizzarsi entro pochi minuti." Se hai inserito un URL webhook, si apre Il tuo secret del webhook: fai clic su Copia e conserva il secret dove il tuo server può leggerlo. Puoi mostrarlo di nuovo in seguito in Impostazioni webhook.

• Solo i nuovi messaggi. Un numero si sincronizza dal momento in cui lo aggiungi: i messaggi precedenti non vengono importati né inviati.
• Tutti i numeri in uso? La finestra dice "Tutti i tuoi numeri inbox sono in uso. Fermane o rimuovine uno, oppure aggiungine altri al componente aggiuntivo Unibox." Ferma o rimuovi un numero, oppure chiedi a un Proprietario di aumentare la quantità del componente aggiuntivo (Vedi i componenti aggiuntivi).
• Aggiungere di nuovo un numero rimosso ne ripristina l'inbox ("Numero aggiunto di nuovo – le sue chat si sincronizzano di nuovo da adesso in poi."); i messaggi del periodo in cui era rimosso non vengono recuperati. Con un URL webhook mantiene il secret precedente, se ne aveva uno (usa Mostra in Impostazioni webhook); altrimenti si apre Il tuo secret del webhook con uno nuovo.

Cosa mostra la scheda di un numero#

Ogni scheda mostra il numero, quando WbizTool l'ha controllato l'ultima volta in cerca di messaggi ("Ultimo controllo 1 min fa", oppure Mai controllato), i suoi Messaggi e Contatti sincronizzati (tutte le chat sincronizzate da quel numero, comprese quelle senza messaggi nell'inbox), l'Ultimo messaggio e il Webhook: l'URL e cosa invia, ad esempio "Invia ogni messaggio ricevuto e inviato · firmato con un secret", oppure "Nessuno – i messaggi compaiono solo nell’inbox." Un badge Zapier significa che uno Zap riceve i messaggi (vedi Zapier e numeri inbox).

Il badge in alto a destra indica cosa sta facendo il numero:

Modificare l'URL del webhook o i messaggi inviati#

1. Apri le impostazioni del webhook

   Fai clic su Impostazioni webhook nella scheda del numero.

2. Modifica le impostazioni

   Modifica l'URL del webhook (facoltativo) e le spunte in Messaggi da inviare. Per disattivare il webhook, cancella l'URL.

3. Salva

   Fai clic su Salva. Vedi "Impostazioni webhook salvate."

   

• Modificare l'URL mantiene il secret. Cancellare l'URL lo elimina; un URL aggiunto in seguito riceve un nuovo secret, mostrato una volta in Il tuo secret del webhook.
• Se nessuna casella è spuntata, la scheda dice "Nessun evento selezionato – non viene inviato nulla".

Mostrare o rigenerare il secret#

Il secret è composto da 32 lettere e cifre. In Impostazioni webhook, sotto Secret del webhook, Mostra lo rivela con Copia accanto. Rigenera chiede "Generare un nuovo secret? Quello attuale smette subito di funzionare – aggiornalo ovunque verifichi le firme." Fai clic su Genera nuovo secret: viene salvato subito ("Nuovo secret generato."), senza Salva, e tutte le richieste da quel momento sono firmate con il nuovo secret, compresi i nuovi tentativi di messaggi precedenti.

Fermare, avviare o rimuovere un numero#

I webhook in attesa di un nuovo tentativo vengono scartati quando fermi o rimuovi il numero o ne modifichi l'URL.

Come vengono consegnati i webhook#

• Quando: ogni numero inbox viene controllato circa una volta al minuto mentre è collegato; i controlli vanno in pausa mentre invia messaggi, ad esempio una campagna. Un messaggio viene inviato dopo il controllo che lo trova, di solito entro un paio di minuti. Non c'è un pulsante di test: invia un messaggio al numero da un altro telefono.
• Una richiesta per messaggio: message_received per Messaggi ricevuti; message_sent per Messaggi inviati, inviati dal telefono, da WhatsApp Web o da WbizTool (campagne, API, promemoria). Le risposte inviate dall'inbox Unibox di solito non vengono inviate: l'inbox le ha già.
• Esito positivo: qualsiasi stato 2xx entro 8 secondi. I reindirizzamenti non vengono seguiti: un 3xx conta come errore.
• Nuovi tentativi: un timeout, un errore di connessione, 429 o un 5xx vengono ritentati 3 volte, dopo 30 secondi, 1 minuto e 2 minuti. Le altre risposte, come 400 o 404, e un certificato TLS non valido non vengono ritentati.
• 410 Gone: WbizTool disattiva il webhook del numero (URL e secret rimossi; per un hook di Zapier, torna il tuo webhook precedente). Il numero continua a sincronizzarsi nell'inbox.
• Ordine e duplicati: le richieste possono arrivare fuori ordine e, raramente, due volte. Ordina per message.whatsapp_timestamp e salta un message.id che hai già gestito per lo stesso whatsapp_client_id. Se due dei tuoi numeri sono nello stesso gruppo, ciascuno invia la propria copia.
• Messaggi in ritardo: un messaggio recuperato in ritardo, ad esempio dopo che il numero si riconnette o dopo una pausa dei controlli, viene comunque inviato, con replayed a true se ha più di 10 minuti. I messaggi arrivati mentre il numero era fermo non vengono inviati dopo Avvia (vedi Fermare, avviare o rimuovere un numero).
• Controllo dell'indirizzo: l'URL viene ricontrollato prima di ogni richiesta; a un host che ora punta a una rete privata, o che non si risolve, non viene inviato nulla, e quel messaggio non viene ritentato.

Intestazioni#

Verificare la firma#

Ogni richiesta è firmata con il secret del webhook del numero usando HMAC-SHA256 sul corpo grezzo della richiesta, esattamente come ricevuto. Il digest esadecimale in minuscolo viene inviato in X-Wbiztool-Signature come sha256=<digest>. Un webhook impostato nella pagina Numeri inbox ha sempre un secret, quindi l'intestazione è sempre presente.

Calcola la firma dai byte grezzi prima di analizzare il JSON. Analizzare e ricodificare il corpo lo modifica (spazi, caratteri con escape), e la firma non corrisponderà.

// Express: register this route before app.use(express.json()), or the raw body is lost
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // answer quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

Per provare il tuo ricevitore prima che arrivi un messaggio vero, firma tu stesso un corpo e invialo:

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

La firma copre il corpo, compreso il suo timestamp, che è nuovo a ogni tentativo. Per rifiutare le richieste ripetute, scarta un timestamp più vecchio di 5 minuti e salta un message.id che hai già gestito.

Payload#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

I numeri, gli ID e i nomi qui sopra sono esempi. Il corpo reale è una sola riga di JSON compatto, e ogni carattere non ASCII (lettere accentate, altri alfabeti, emoji) arriva come escape \uXXXX, ad esempio \ud83d\udcf8 per 📸. Potrebbero essere aggiunti altri campi; ignora quelli che non usi.

Campi di primo livello#

Campi di message#

Campi di contact#

Zapier e numeri inbox#

Il trigger Incoming WhatsApp Message di WbizTool in Zapier usa questi webhook. Attivare uno Zap aggiunge il numero all'inbox se serve (occupando uno dei tuoi numeri inbox) e punta il suo webhook a Zapier, solo per i messaggi ricevuti, con un secret proprio; la scheda mostra un badge Zapier. Il tuo URL webhook, il tuo secret e le tue spunte tornano quando lo Zap viene disattivato.

Impostazioni webhook avvisa allora: "Questo webhook appartiene a uno Zap di Zapier. Se modifichi o rimuovi l’URL, lo Zap smette di ricevere messaggi." Anche Ferma e Rimuovi avvisano: lo Zap resta attivo in Zapier ma non riceve nulla, quindi disattivalo invece in Zapier. Vedi Come funziona il trigger con i tuoi numeri inbox.

Senza il componente aggiuntivo Unibox#

La pagina dice "Nessun componente aggiuntivo Unibox" e "Il componente aggiuntivo Unibox non è attivo in questo spazio di lavoro.", e Aggiungi numero all’inbox apre Componente aggiuntivo Unibox richiesto: "Per aggiungere numeri WhatsApp all’inbox condivisa e ricevere i loro messaggi via webhook, abbonati al componente aggiuntivo Unibox." Un Proprietario fa clic su Vedi i componenti aggiuntivi e aggiunge il componente aggiuntivo Numero Unibox in Fatturazione e piani, su un piano a pagamento o a vita (non nella prova gratuita).

Quando il componente aggiuntivo termina o un numero si disconnette#

• Il componente aggiuntivo termina: tutti i numeri inbox vengono fermati, subito o entro circa un'ora. Le schede mostrano Fermato con "Fermato perché il componente aggiuntivo Unibox non è attivo in questo spazio di lavoro." Proprietari ed Editor vengono informati di quali inbox sono state fermate, nell'email di fatturazione o nell'avviso "Alcuni numeri o funzioni di … si sono fermati" (Problemi con numeri e invii in Notifiche). Conversazioni, URL webhook e secret vengono conservati: quando il componente aggiuntivo torna attivo, fai clic su Avvia su ogni numero. I messaggi del periodo in cui era fermo vengono poi aggiunti all'inbox, fino a 30 giorni prima, ma non inviati al tuo webhook.
• Il componente aggiuntivo copre meno numeri di quelli attivi: "Ci sono più numeri attivi di quanti ne consenta il tuo componente aggiuntivo. Quelli in eccesso più recenti vengono fermati automaticamente entro circa un’ora."
• Il numero si disconnette: la scheda mostra Numero disconnesso e non viene sincronizzato né inviato nulla. Dopo che lo riconnetti, anche i messaggi arrivati nel frattempo vengono recuperati e inviati; quelli con più di 10 minuti hanno replayed a true.
• Viene riconnesso con un altro telefono: il numero inbox e il suo webhook proseguono con il nuovo numero (stesso whatsapp_client_id, nuovo whatsapp_phone) da quel momento; le vecchie chat restano nell'inbox come cronologia.

Risoluzione dei problemi#

Pagine correlate#

• Inbox Unibox: leggi le chat dei tuoi numeri inbox e rispondi
• Integrazione con Zapier
• Collega il tuo numero WhatsApp
• Piani e fatturazione
• API Invia messaggio: il suo campo webhook indica se un messaggio che invii è partito (è un webhook diverso)