Primi passi

1. Account e chiave

Registrati, conferma l'email e crea una chiave sandbox in Dashboard → Chiavi API. La chiave si vede una volta sola: salvala in una variabile d'ambiente (DPL_API_KEY), mai nel codice.

2. Crea un cliente

curl -X POST https://api.depalmalabs.it/v1/customers \
  -H "Authorization: Bearer $DPL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Centro Estetico Luna", "external_ref": "CLI-042"}'

# Risposta
{ "object": "customer", "id": "cus_xxxxxxxxxxxx", "status": "pending_onboarding", ... }

3. Collega il numero del cliente

Con una chiave live genera il link di onboarding e mandalo al cliente. Il cliente accede con Facebook, sceglie o crea l'account WhatsApp Business, verifica il numero e aggiunge la carta su WhatsApp Manager.

Al collegamento ricevi il riepilogo con la fee di attivazione del numero (dashboard → Riepiloghi). Il cliente diventa active, e ricevi l'evento customer.status, quando ci sono tutte e tre le cose: numero collegato, metodo di pagamento Meta, attivazione pagata. Prima di allora l'invio risponde customer_not_active.

curl -X POST https://api.depalmalabs.it/v1/customers/cus_xxxxxxxxxxxx/onboarding-link \
  -H "Authorization: Bearer $DPL_API_KEY"

# Risposta: manda "url" al tuo cliente (vale 14 giorni)
{ "url": "https://developers.depalmalabs.it/onboarding/...", "expires_at": "..." }

In sandbox non serve: i clienti creati con chiave di test sono già utilizzabili per le prove.

4. Manda il primo messaggio

<?php
// Richiede PHP 7.4+ con estensione curl.
$apiKey = getenv('DPL_API_KEY'); // dpl_live_... oppure dpl_test_...

$payload = [
    'customer_id' => 'cus_xxxxxxxxxxxx',
    'to' => '+393331234567',
    'type' => 'template',
    'template' => [
        'name' => 'promemoria_appuntamento',
        'language' => 'it',
        // {{1}} = nome, {{2}} = data e ora
        'variables' => ['Maria', 'domani alle 10:00'],
    ],
];

// Idempotency-Key: un id univoco dell'evento nel tuo gestionale (es. appuntamento 123).
// Le chiavi non scadono: la stessa chiave restituisce sempre lo stesso messaggio, anche se fallito.
// Per un nuovo invio usa una chiave nuova.
$idempotencyKey = 'appuntamento-123-promemoria';

$ch = curl_init('https://api.depalmalabs.it/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . $idempotencyKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$netError = curl_errno($ch) ? curl_error($ch) : null;
curl_close($ch);

if ($netError !== null || $status === 0) {
    // Rete o timeout: il messaggio potrebbe essere partito. Riprova con la STESSA Idempotency-Key.
    echo "Esito incerto ($netError): riprova con la stessa chiave\n";
    exit;
}
$data = json_decode($response, true);
if ($status === 202) {
    echo "Esito da confermare: non rimandare, attendi il webhook\n";
} elseif (($status === 201 || $status === 200) && $data['status'] === 'failed') {
    // Con 200 è un replay: questa chiave appartiene a un invio già fallito. Correggi e usa una chiave nuova.
    echo "Invio fallito: " . json_encode($data['error']) . "\n";
} elseif ($status === 201 || $status === 200) {
    echo "Inviato: " . $data['id'] . "\n";            // salva l'id per seguire lo stato
} else {
    echo "Errore " . ($data['error']['code'] ?? $status) . ": " . ($data['error']['message'] ?? '') . "\n";
}

La risposta contiene l'id del messaggio (msg_…). Lo stato passa da accepted a sent, delivered e read: lo leggi con GET /v1/messages/{id} o lo ricevi sul webhook.

Regole da conoscere

Fuori dalle 24 ore dall'ultimo messaggio del destinatario puoi mandare solo template approvati.
Scrivi solo a chi ha dato al tuo cliente il consenso a ricevere messaggi WhatsApp (opt-in).
Usa sempre Idempotency-Key: se la rete cade puoi ripetere la richiesta senza mandare doppioni.
Limite: 600 richieste al minuto per chiave (header X-RateLimit-Remaining), più il limite giornaliero di invii del cliente.