API dei modelli WhatsApp #

I modelli di messaggio WhatsApp sono messaggi predefiniti approvati per l’invio al di fuori della normale finestra di conversazione di 24 ore, come ad esempio un messaggio di benvenuto, un promemoria per un appuntamento o un sollecito di riattivazione. Questa API ti consente di elencare, creare, modificare, inviare, verificare, eliminare e spedire modelli a livello programmatico.

Tutti i percorsi seguenti sono relativi all’URL di base dell’API:

https://api.youraiconnector.com/v1

Ogni richiesta deve essere autenticata. Consulta Autenticazione per i quattro metodi accettati. Gli esempi in questa pagina utilizzano l’intestazione X-API-Key (e una forma di parametro di query per cURL).

Utilizzo dei sotto-account (agenzie) #

Stati di approvazione #

Poiché i messaggi inviati al di fuori di una conversazione aperta devono essere prima revisionati da WhatsApp, ogni modello ha uno status di approvazione:

Solo i modelli draft e rejected possono essere modificati o (ri)inviati. Una volta che un modello è approved, viene bloccato: creane uno nuovo se hai bisogno di apportare modifiche.

Approvazione automatica: Alcuni canali non richiedono una fase di revisione esterna. I modelli creati o inviati per una campagna su tali canali vengono archiviati immediatamente come approved, senza un ID contenuto (sid).

Template su account connessi a Meta #

Questi endpoint funzionano allo stesso modo indipendentemente dalla connessione WhatsApp utilizzata dal tuo account, ma ciò che accade dietro le quinte differisce:

• Su una connessione WhatsApp gestita, i template vengono registrati presso il provider di messaggistica e sid è l’ID contenuto del provider (HXXXXXXXX…).
• Su un account il cui numero è eseguito sul proprio WhatsApp Business Account (una delle due opzioni di connessione Meta), i template vengono creati e revisionati in quel WhatsApp Business Account e sid è l’ID template di Meta — una stringa numerica come "3394843740694756". status utilizza ancora i valori nella tabella sopra, e rejection_reason riporta ancora la spiegazione di Meta.

Esistono due endpoint aggiuntivi per questo: uno per chiedere su quale connessione ti trovi e uno per riconciliare il tuo elenco di template con il tuo WhatsApp Business Account. I template già esistenti nel WhatsApp Business Account vengono importati nella tua libreria tramite la sincronizzazione, quindi una GET /whatsapp-templates successiva li elenca come qualsiasi altro template.

Controlla su quale connessione vengono eseguiti i template #

GET /whatsapp-templates/provider

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

Sincronizza i template da Meta #

Aggiorna lo stato di approvazione di ogni template che risiede nel tuo WhatsApp Business Account e importa qualsiasi template che esiste lì ma non è ancora nella tua libreria. È sicuro chiamarlo tutte le volte che vuoi. Su una connessione gestita non c’è nulla da sincronizzare, quindi la chiamata non esegue alcuna azione e riporta semplicemente quanti template hai.

POST /whatsapp-templates/meta-sync

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

Comunicare direttamente con Meta (avanzato) #

Se hai bisogno di qualcosa che gli endpoint sopra non espongono — intestazioni, piè di pagina, pulsanti o un template creato interamente a mano — /v1/meta-templates inoltra la tua richiesta direttamente all’API dei template di Meta, senza memorizzare nulla nella tua libreria di template. Funziona solo su account il cui numero è eseguito sul proprio WhatsApp Business Account; su una connessione gestita, ogni chiamata restituisce 400 chiedendoti di collegare prima un’app Meta.

Un template rifiutato da Meta restituisce 400 con la spiegazione di Meta in error.

Elenca modelli #

Restituisce tutti i modelli presenti nel tuo account, con un riepilogo leggero per ciascuno.

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

Ottieni un modello #

Restituisce i dettagli completi di un singolo modello, incluse le sue variabili, lo stato e i timestamp.

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

Un modello che non esiste nel tuo account restituisce 404 con { "success": false, "error": "Template not found" }.

Crea un modello #

Crea un modello per il messaggio di apertura di una campagna e lo invia per l’approvazione in un unico passaggio.

POST /whatsapp-templates

I segnaposto delle variabili possono essere scritti come {{first_name}}, {first_name} o [first_name]: vengono tutti normalizzati nella forma a doppia parentesi graffa.

Il risultato dipende dai canali della campagna:

• Campagna WhatsApp Business API: il contenuto viene inviato per la revisione di WhatsApp. La risposta contiene campaign_status (received o pending) e un template_sid.
• Un canale senza una fase di revisione esterna: il modello viene salvato e approvato automaticamente (campaign_status: "approved", template_sid: null).
• Nessun canale WhatsApp nella campagna: non viene creato nulla e campaign_status è not_applicable.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Risposta (inviato per la revisione)

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Creare un modello autonomo #

Crea un modello nella tua libreria di modelli senza collegarlo al messaggio di apertura di una campagna. Questo è il passaggio di creazione del ciclo di vita che il resto di questa pagina segue: crealo qui, modificalo, invialo per la revisione, controllane lo stato ed eliminalo quando non ti serve più.

POST /whatsapp-templates/docs

Modelli di autenticazione (codice monouso). WhatsApp non accetta modelli di autenticazione a testo libero: il corpo del messaggio è preimpostato da WhatsApp e il modello deve contenere un pulsante “copia codice”. Quando crei un modello con category: "authentication", lo inviamo in quel formato fisso per te. Il tuo body viene mantenuto come anteprima mostrata nell’app, ma il testo che il tuo contatto riceve è la formulazione propria di WhatsApp (il codice, un promemoria di sicurezza e una nota di scadenza di 10 minuti). Dichiara esattamente una variabile, ad esempio ["code"], e passa il codice quando invii (vedi il campo variables su Invia un modello a un contatto). Il codice deve essere più breve di 15 caratteri.

Quale creazione dovrei usare? Usa questa quando vuoi un modello che puoi modificare e inviare tu stesso. Usa POST /whatsapp-templates (sopra) quando vuoi impostare il messaggio di apertura di una campagna: quella richiede campaign_id e scrive direttamente nella campagna.

Un modello creato come submitted viene inviato per la revisione di WhatsApp in background, quindi controlla l’endpoint di stato per il risultato invece di aspettartelo nella risposta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

Un name, language o body mancante, una lingua non supportata, un status diverso da draft o submitted, un type o category sconosciuto, o un corpo superiore a 1024 caratteri restituisce 400 con una error esplicativa. Un campaign_id che non è una delle tue campagne restituisce 404.

Aggiorna un modello #

Modifica un modello che non è ancora stato approvato. È possibile modificare solo i modelli con stato draft o rejected. Fornisci una qualsiasi combinazione di name, body, language e variables: verranno modificati solo i campi inviati.

PUT /whatsapp-templates/{templateId}

La modifica non invia nuovamente il modello per la revisione. Utilizzare l’endpoint di invio in seguito.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

Risposta

{
  "success": true,
  "template_id": "template_abc123"
}

Il tentativo di modificare un modello che è già approved (o comunque non modificabile), l’invio di campi vuoti o l’invio di un valore non valido restituisce 400 con un error esplicativo.

Inviare un modello per l’approvazione #

Invia un modello draft o rejected per la revisione. I modelli su un canale che non richiede una revisione esterna vengono approvati immediatamente; tutti gli altri vengono inviati a WhatsApp e il status restituito (solitamente received o pending) viene memorizzato nel modello.

POST /whatsapp-templates/{templateId}/submit

I modelli di follow-up devono dichiarare e utilizzare le variabili richieste prima di poter essere inviati: un segnaposto per il nome e un segnaposto per il contesto personale per i follow-up intelligenti.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Controllare lo stato di approvazione #

Un endpoint leggero per il polling dello stato attuale di un modello. Lo stato viene letto dal record memorizzato, che viene aggiornato periodicamente in background, quindi un’approvazione o un rifiuto molto recenti potrebbero richiedere un breve lasso di tempo prima di apparire.

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

Eliminare un modello #

Rimuove il record del modello dal tuo account.

DELETE /whatsapp-templates/{templateId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

Inviare un modello a un contatto #

Invia un modello approvato a un contatto, anche quando non c’è una conversazione aperta: questo riapre la sessione di chat. Puoi indirizzare il contatto tramite contactId o tramite phoneNumber e scegliere il modello tramite whatsappTemplateId o tramite templateName.

POST /whatsapp-templates/send

Il corpo del modello supporta la sostituzione avanzata delle variabili:

• Variabili di base: {{first_name}}, {{email}}, {{company}}
• Valori predefiniti: {{first_name|there}} mostra there se il campo è vuoto
• Trasformazioni: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
• Combinate: {{company|Your Company|uppercase}}

Crediti: L’invio di un modello consuma crediti. Il costo esatto dipende dal paese del destinatario e dalla categoria del modello.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Una richiesta a cui mancano sia un identificatore di contatto che entrambi gli identificatori di modello restituisce 400. Se al tuo account mancano le credenziali di messaggistica necessarie per l’invio, la risposta è 403.

Crea o aggiorna il template live di una campagna #

Una seconda coppia di endpoint per il template di apertura di una campagna, definiti tramite percorso invece che tramite un campaign_id nel corpo della richiesta. Questi sono quelli da utilizzare per una campagna già attiva: a differenza di Crea un template sopra, l’aggiornamento qui comporta anche il reinvio delle bozze di follow-up della campagna per la revisione, in modo che il template di apertura e i relativi follow-up rimangano sincronizzati.

POST /whatsapp-templates/campaign/{campaignId} crea il template di apertura della campagna. PUT /whatsapp-templates/campaign/{campaignId} lo modifica: la campagna deve già avere un template, altrimenti verrà restituito 400.

cURL (creazione)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

Per modificare, cambiare il metodo in PUT e utilizzare gli stessi campi: questo invia nuovamente il template di apertura (e le bozze di follow-up della campagna, su una campagna WhatsApp API) per la revisione.

Una campagna che non appartiene al proprio account restituisce 404; una campagna appartenente a un altro account per il quale non si è autorizzati restituisce 403. La modifica di una campagna senza un template esistente restituisce 400.

Invia un template a un contatto esistente #

Un’alternativa più semplice, basata sul percorso, rispetto a Invia un template a un contatto sopra: sia il template che il contatto devono già esistere; nulla viene cercato per nome o creato al volo.

POST /whatsapp-templates/{templateId}/send-to-contact

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

Risposta

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Crediti: L’invio consuma crediti, con lo stesso tariffario dell’endpoint precedente. Un contactId mancante o non presente nel proprio account restituisce 403; un templateId inesistente restituisce 404.

Invio massivo di un template #

Invia un template a molti contatti in un’unica chiamata, con un’anteprima dei costi che è possibile mostrare prima di confermare.

Stima prima il costo #

Restituisce il costo dell’invio, suddiviso per paese di destinazione, senza inviare nulla o scalare crediti. Il prezzo del modello è per paese di destinazione, quindi deve essere calcolato lato server in base ai contatti reali anziché stimato lato client.

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Risposta

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts conta gli ID mancanti, non tuoi o privi di numero di telefono: la stima copre solo i restanti, quindi un valore diverso da zero significa che l’invio reale raggiungerà meno contatti di quelli selezionati.

Invia il batch #

Invia il modello a ogni contatto nell’elenco, risolvendo eventuali variabili intelligenti per contatto e addebitando i crediti per ogni invio.

POST /whatsapp-templates/{templateId}/bulk-send

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Risposta

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

Un contatto che fallisce (non trovato, non presente nel tuo account o errore di invio) viene ignorato e conteggiato in failed invece di interrompere il batch. Un contactIds vuoto, più di 5000 ID su un invio (500 su una stima) o un templateId mancante restituiscono 400.

Riprova un messaggio fallito #

Due endpoint per rispedire un messaggio fallito, senza creare un nuovo record di messaggio o spendere nuovamente crediti.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template riprova specificamente un messaggio modello fallito: risolve nuovamente il contenuto del modello dalla campagna se il messaggio fallito non lo contiene già. Solo i messaggi con stato failed e tipo template possono essere riprovati in questo modo.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry è indipendente dal canale e funziona per qualsiasi messaggio non basato su modello fallito (ad esempio WhatsApp Web), inviandolo al percorso di spedizione corretto in base al canale del messaggio. Accetta lo stato failed, failed_connection, limit_exceeded o queued_retry.

Nessuno dei due endpoint richiede un corpo della richiesta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "data": "Message retry initiated successfully"
}

Per la versione indipendente dal canale, sostituisci il percorso con .../msg_abc789/retry. Un messaggio il cui stato non è idoneo per il riinvio, o (sull’endpoint del modello) che non è un messaggio modello, restituisce 400. Un contatto o un messaggio mancante restituisce 404.

Profilo WhatsApp Business #

Gestisci il profilo WhatsApp Business (informazioni, indirizzo, descrizione, email, siti web, categoria aziendale e logo) mostrato ai contatti su WhatsApp. Funziona sia su una connessione gestita che su un account che esegue il proprio WhatsApp Business Account.

Salva il profilo #

PUT /whatsapp-templates/profile

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

Risposta

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

Un phoneNumber mancante, un URL di sito web non valido o un phoneNumber non connesso al tuo account restituisce 400 o 404.

Carica un’immagine del profilo #

Scarica un’immagine da un URL fornito e la carica su WhatsApp, restituendo un handle. Passa quell’handle come profilePictureHandle nella chiamata di salvataggio del profilo sopra per impostarla come foto: questo endpoint carica solo l’immagine, non la imposta autonomamente.

POST /whatsapp-templates/profile/picture

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "data": "1234567890123456"
}

data è l’handle dell’immagine caricata. Un phoneNumber o fileUrl mancante, o un phoneNumber senza token di accesso WhatsApp archiviato, restituisce 400; un fileUrl non raggiungibile o non valido restituisce un errore che descrive il motivo per cui il download non è riuscito.

Controlla lo stato di un mittente #

Esegue il polling (e aggiorna) lo stato di invio in tempo reale di un numero WhatsApp connesso con il provider di messaggistica. Utile per confermare che un numero sia effettivamente in grado di inviare messaggi prima di farvi affidamento.

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "data": "ONLINE"
}

data è uno tra ONLINE (invio normale), PENDING (ancora in fase di verifica) o DELETED (il provider non riconosce più questo mittente: riconnetti il numero). Un phoneNumber senza informazioni aziendali WhatsApp archiviate restituisce 404.

Genera modelli di follow-up con l’IA #

La piattaforma può scrivere per te i modelli di follow-up WhatsApp di una campagna — i solleciti inviati quando una conversazione si interrompe — basandosi sulle istruzioni e sull’obiettivo della campagna stessa. Esiste un endpoint di lavoro che viene eseguito in background, oltre a tre endpoint più datati mantenuti per le integrazioni esistenti. Tutti utilizzano crediti IA.

Avvia un lavoro di generazione #

POST /campaigns/{campaignId}/template-generation

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

Risposta (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

La chiamata restituisce una risposta non appena il lavoro viene messo in coda. Leggi la campagna (GET /campaigns/{campaignId}, vedi l’API Campagne) e monitora il suo oggetto template_generation_status finché non termina:

I modelli generati vengono salvati nella campagna come qualsiasi altro, quindi appaiono in Elenco modelli e devono comunque passare attraverso l’approvazione di WhatsApp prima di poter essere inviati. Un 400 significa che type era diverso da all o cold_only; un 404 significa che la campagna non esiste o appartiene a un altro account.

Gli Agenti hanno una versione gemella di questa chiamata, POST /agents/{agentId}/template-generation, che scrive i follow-up per un Agente e termina durante la chiamata nel caso tipico — vedi Genera messaggi di follow-up nell’API Agenti IA.

Gli endpoint di generazione precedenti #

Tre endpoint precedenti svolgono lo stesso lavoro e sono mantenuti affinché le integrazioni esistenti continuino a funzionare. Il nuovo codice dovrebbe utilizzare l’endpoint di lavoro sopra indicato.

Tutti e tre richiedono i follow-up automatici sull’account e crediti sufficienti — un 400 indica quale manca — e la coppia indirizzata alla campagna restituisce 403 quando la campagna appartiene a un altro account.

Errori dell’API dei template #

Gli endpoint dei template restituiscono il formato di errore standard:

{
  "success": false,
  "error": "Template not found"
}

Un 404 su questi endpoint solitamente significa che la risorsa non è stata trovata: o non esiste o appartiene a un altro account. Alcuni endpoint (la creazione/aggiornamento con ambito campagna e gli invii a un contatto esistente) restituiscono invece 403 quando la campagna o il contatto appartengono a qualcun altro anziché non esistere affatto. Alcuni endpoint includono anche un campo error_code che rispecchia lo stato HTTP. I codici condivisi che ogni endpoint può restituire — 400, 401, 403 (il tuo piano non include l’accesso API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e impaginazione.

Passaggi successivi #

• Autenticazione — i quattro modi per autenticare una richiesta.
• Errori e limiti di frequenza — codici di stato e il limite di 300 richieste/min.
• API Campagne — gestisci le campagne a cui sono allegati i modelli.