Invia messaggi WhatsApp
dal tuo codice

Primi passi

L'API Besked ti permette di inviare messaggi WhatsApp da qualsiasi linguaggio di programmazione. In tre passaggi sei pronto a integrare:

1. Registrati gratuitamente su app.besked.it.
2. Collega il tuo numero WhatsApp scansionando il QR code dalla dashboard (esattamente come WhatsApp Web).
3. Genera una API key dalla sezione Profilo › API Keys. La chiave inizia con wcp_.

Base URL: https://app.besked.it/api/v1

Tutte le risposte sono in JSON e seguono convenzioni REST standard.

Autenticazione

Ogni richiesta deve includere la tua API key nell'header HTTP X-API-Key (supportato anche il classico Authorization: Bearer):

X-API-Key: wcp_abc123...

Le API key sono collegate a una whitelist opzionale di IP e domini configurabile dalla dashboard. Puoi emettere più chiavi e revocarle singolarmente.

Invio singolo

Invia un messaggio con una singola chiamata. Il messaggio viene accodato (risposta 202 Accepted) e inviato rispettando i limiti anti-ban.

Endpoint: POST /api/v1/send

Payload:

• sessionId (string, richiesto) — ID della sessione WhatsApp da usare.
• to (string, richiesto) — numero destinatario in formato E.164 senza il + (es. 393331234567).
• message (string, opzionale se mediaUrl presente) — testo del messaggio (max 65.536 caratteri).
• mediaUrl (string, opzionale) — URL pubblico del file da allegare.
• mediaType (string, opzionale) — image, video, audio, document (dedotto dall'estensione se omesso).
• fileName (string, opzionale) — nome del file per i documenti.

curl -X POST https://app.besked.it/api/v1/send \
  -H "X-API-Key: wcp_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "my-session-id",
    "to": "393331234567",
    "message": "Ciao! Il tuo ordine #1042 è stato spedito."
  }'

const res = await fetch('https://app.besked.it/api/v1/send', {
  method: 'POST',
  headers: {
    'X-API-Key': 'wcp_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: 'my-session-id',
    to: '393331234567',
    message: 'Ciao! Il tuo ordine #1042 è stato spedito.'
  })
});

const data = await res.json();
console.log(data.data.messageId);

<?php
$payload = [
    'sessionId' => 'my-session-id',
    'to'        => '393331234567',
    'message'   => 'Ciao! Il tuo ordine #1042 è stato spedito.'
];

$ch = curl_init('https://app.besked.it/api/v1/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: wcp_abc123...',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
echo $response['data']['messageId'];

Risposta

L'API risponde con 202 Accepted:

{
  "success": true,
  "message": "Message queued for delivery",
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "position": 5,
    "sessionId": "my-session-id",
    "to": "393331234567",
    "queuedAt": "2026-04-17T10:00:00.000Z",
    "statusUrl": "/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/status"
  }
}

Codici di errore comuni: 400 input non valido, 401 API key mancante o errata, 402 piano scaduto, 403 IP/dominio non autorizzato o destinatario in blacklist, 404 sessione non trovata.

Stato messaggio

Verifica lo stato di un messaggio accodato:

Endpoint: GET /api/v1/messages/:id/status

curl https://app.besked.it/api/v1/messages/550e8400.../status \
  -H "X-API-Key: wcp_abc123..."

const res = await fetch(
  `https://app.besked.it/api/v1/messages/${messageId}/status`,
  { headers: { 'X-API-Key': 'wcp_abc123...' } }
);
const data = await res.json();
console.log(data.data.status); // queued | sent | delivered | read | failed

<?php
$ch = curl_init("https://app.besked.it/api/v1/messages/$messageId/status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: wcp_abc123...']
]);
$data = json_decode(curl_exec($ch), true);
echo $data['data']['status'];

Stati possibili: queued in coda, sent inviato a WhatsApp, delivered consegnato al destinatario, read letto, failed fallito.

Endpoint disponibili

Panoramica dei principali endpoint. Il riferimento completo con tutti i parametri, esempi e schemi di risposta è disponibile nella dashboard dopo la registrazione.

Limiti e anti-ban

Per proteggere i tuoi numeri WhatsApp, Besked applica limiti intelligenti per sessione:

• 15 messaggi al minuto per sessione
• 150 messaggi all'ora per sessione
• 1.000 messaggi al giorno per sessione
• Cooldown randomizzato tra messaggi (2–5 secondi), pausa lunga ogni 10 e ogni 50 messaggi
• Rilevamento pattern sospetti (spam, messaggi ripetuti, attività notturna anomala)
• Pausa automatica della sessione e blacklist temporanea dei numeri che generano errori ripetuti

Le code interne gestiscono tutto automaticamente: tu invii tutte le richieste che vuoi, Besked distribuisce nel tempo.

Best practice: invia sempre a utenti che hanno dato consenso esplicito a ricevere comunicazioni via WhatsApp. L'anti-ban tecnico è efficace, ma il consenso è la migliore protezione.

Sicurezza

• Tutte le richieste avvengono via HTTPS / TLS.
• Le API key sono hash-ate con bcrypt lato server e non sono recuperabili dopo la creazione: in caso di smarrimento, generane una nuova e revoca la precedente.
• Supporto whitelist CIDR di IP e whitelist di domini chiamanti.
• Non esporre la API key in codice client-side o frontend pubblico: usala solo da server trusted.
• Rotazione consigliata ogni 6 mesi.

Documentazione completa

Questa pagina è un riassunto. Il riferimento completo con tutti i parametri, i codici di errore dettagliati, gli esempi per ogni endpoint e un API playground interattivo è disponibile nell'area cliente:

app.besked.it/dashboard/api-docs

La registrazione è gratuita e include 1 sessione WhatsApp e un quota di prova per testare le integrazioni.