WhatsApp Template API

API per sviluppatori

Invia template WhatsApp approvati dai tuoi sistemi con una sola chiamata API; la conversazione poi prosegue in MonoChat.

• WhatsApp
• API REST
• Solo API

Installa da MonoStoreScopri su monochat.ai

Panoramica

WhatsApp Template API permette al tuo CRM, ERP, sito e-commerce o a qualsiasi backend di inviare tramite MonoChat un messaggio template WhatsApp approvato a un cliente. Una sola richiesta indica il numero WhatsApp da cui inviare, il numero di telefono del cliente, il template e le sue variabili.

Quando il cliente risponde, la conversazione arriva nella tua inbox MonoChat come tutte le altre. L’app non ha schermate proprie: tutto avviene tramite tre endpoint API.

Punti di forza

• Una sola chiamata API. Invia un template per nome e lingua, con le variabili di intestazione, corpo, pulsanti e carosello compilate con i tuoi dati.
• Direttamente in chat. Ogni invio restituisce l’id della conversazione e un link diretto ad essa in MonoChat.
• Nuovi clienti benvenuti. Se il numero di telefono non è ancora un cliente, il cliente viene creato con il nome che invii.

Installazione e configurazione

1. Collega il tuo numero WhatsApp Business a MonoChat e assicurati che sia verificato e abbia template approvati da Meta.
2. Installa WhatsApp Template API da Impostazioni › MonoStore › App, oppure apri il link di installazione app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Se non hai un account MonoChat, il link ti permette di registrarti prima e installa l’app per te.
3. Crea un token API in Profilo › Token API. Il token viene mostrato una sola volta, quindi copialo subito.
4. Chiama template/list.js per vedere i tuoi template approvati e le loro variabili.
5. Chiama template/send.js con il numero del cliente e i valori delle variabili per inviare il tuo primo template.

nota

• Ogni messaggio è fatturato come qualsiasi messaggio template inviato da MonoChat.
• Gli URL dei file multimediali devono restare raggiungibili finché WhatsApp non ha scaricato il file.
• Invia ai clienti che hanno accettato di ricevere tue comunicazioni: WhatsApp può limitare i numeri i cui messaggi vengono bloccati o segnalati.

Funzionalità

Elenca i template

I template approvati di un numero WhatsApp, con lingua, categoria, stato e variabili, così il tuo sistema sa cosa può inviare.

Invia un template

Per nome e lingua del template, con le variabili di intestazione, corpo, pulsanti e carosello. Un valore mancante blocca l’invio, così al cliente non arriva nulla di compilato a metà.

Assegna a un operatore

Indica l’email di un operatore e la conversazione viene aperta a suo nome.

Intestazioni multimediali

Ottieni credenziali di caricamento a breve durata, carica un’immagine, un video o un documento sullo storage di MonoChat e usane l’URL come intestazione del template.

Link alla conversazione

Ogni invio restituisce l’id della sessione, l’id del messaggio e un link che apre la conversazione in MonoChat.

Errori chiari

Una chiamata non riuscita dice cosa è andato storto, per esempio “Channel not found” o “Variable missing”.

Prima di iniziare

• Il tuo numero WhatsApp Business è collegato a MonoChat e verificato. Vedi Canali.
• I template che vuoi inviare sono approvati da Meta. I template sono il modo per scrivere per primi, o per raggiungere un cliente fuori dalla finestra di 24 ore. Vedi Messaggi template.
• Hai un token API da Profilo › Token API. Vedi Token API.
• Conosci il tuo tenant slug: la parte dopo /tenants/ nel tuo indirizzo MonoChat. In https://app.monochat.ai/tenants/mybusiness lo slug è mybusiness.

Riferimento API

L’app non ha schermate proprie. Tutto avviene tramite tre endpoint, ciascuno una POST con un corpo JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Cosa fa
template/list.js	Elenca i template di uno dei tuoi numeri WhatsApp, con le loro variabili.
template/send.js	Invia un template a un cliente e restituisce un link alla conversazione.
upload/get-token.js	Fornisce credenziali di caricamento a breve durata per un’immagine, un video o un documento di intestazione.

I numeri di telefono si scrivono sempre con il prefisso internazionale e senza +, ad esempio 905334445566. Una chiamata riuscita risponde 200 con i dati dell’endpoint in result.

1. Elencare i template

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Elenca tutti i template del numero WhatsApp Business indicato: nome, codice lingua, categoria, componenti (intestazione, corpo, piè di pagina, pulsanti), tipi di variabili e stato di approvazione.

Campo	Obbligatorio	Descrizione
phoneNumber	sì	Il tuo numero WhatsApp Business in MonoChat, con prefisso internazionale, senza +.
options	no	Paginazione e filtri, ad esempio { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Risposta (abbreviata):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Come leggerla:

• name: il nome di sistema con cui invii il template.
• languageCode: la lingua in cui inviarlo.
• category: la categoria WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: le parti da cui è composto il template.

Componente	Contenuto	Descrizione
HEADER	IMAGE, VIDEO, DOCUMENT o testo	Per i contenuti multimediali è indicato il format; le variabili compaiono in variables.
BODY	Testo con variabili	Il corpo del messaggio, con segnaposto come {{1}}, {{2}}.
FOOTER	Testo	Di solito non ha variabili.
BUTTONS	URL, risposta rapida…	I testi dei pulsanti e le loro variabili, se presenti.

Il template di esempio qui sopra richiede un’immagine per l’intestazione e due testi per il corpo (nome del cliente e nome del prodotto). Il piè di pagina è fisso ("Teşekkürler") e non ci sono pulsanti.

2. Inviare un template

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Invia un template approvato a un cliente. Se il numero di telefono non è ancora un cliente, il cliente viene creato; la conversazione viene aperta (o riutilizzata) e il template viene inviato al suo interno.

Campo	Obbligatorio	Descrizione
phoneNumber	sì	Il numero WhatsApp Business da cui inviare. Deve essere collegato a MonoChat e verificato.
templateMessageName	sì	Il name del template, esattamente come lo restituisce l’elenco.
languageCode	sì	La lingua del template, come la restituisce l’elenco (ad esempio tr-TR).
customerPhoneNumber	sì	Il numero WhatsApp del cliente.
variables	se il template ne ha	I valori delle variabili del template (vedi sotto).
customerFirstName, customerLastName	no	Usati quando il cliente è nuovo per MonoChat.
agentEmailAddress	no	Assegna la conversazione all’operatore con questa email.

Variabili. Ogni elemento dell’array variables ha un type e un elenco di parameters, indicati nell’ordine dei segnaposto del template:

type	parameters
HEADER	La variabile di testo dell’intestazione, oppure l’URL pubblico dell’immagine, del video o del documento di intestazione.
BODY	I {{1}}, {{2}}, … del corpo, in ordine.
BUTTONS	Un valore per ogni pulsante che ha una variabile (ad esempio la parte dinamica di un pulsante URL o un codice coupon), nell’ordine dei pulsanti.
CAROUSEL	Al posto di parameters, un array cards con una voce per ogni scheda del carosello, ciascuna con i propri components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Un valore mancante blocca l’invio con Variable missing, così al cliente non arriva nulla di compilato a metà. FOOTER ha raramente variabili.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Risposta:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: apre la conversazione in MonoChat, per le persone che hanno effettuato l’accesso e sono autorizzate a vederla.
• sessionId: l’id della conversazione.
• messageId: l’id del messaggio in MonoChat. Il suo stato di consegna e di lettura compare in chat come per qualsiasi altro messaggio.

Contenuti multimediali nei template. WhatsApp scarica i contenuti multimediali dell’intestazione dall’URL che indichi, quindi l’URL deve essere valido e raggiungibile pubblicamente. I link che richiedono un accesso non funzionano. Se hai caricato il file con upload/get-token.js, usa l’URL del file costruito a partire da quella risposta.

3. Caricare un file multimediale per un’intestazione

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Quando l’intestazione di un template è un’immagine, un video o un documento, il file ha bisogno di un indirizzo pubblico da cui WhatsApp possa scaricarlo. Questo endpoint ti dà un permesso a breve durata per caricare il file sullo storage di MonoChat.

Campo	Obbligatorio	Descrizione
fileName	sì	Il nome del file con la sua estensione, ad esempio product.jpg o promo.pdf.

I file vengono sempre salvati nella cartella chat-assets del tuo workspace; gli esempi più vecchi che inviano un campo key continuano a funzionare, il valore non è necessario.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

La risposta indica dove caricare il file e fornisce le credenziali per farlo:

Campo	Descrizione
bucket, region, path	Dove va il file.
temporaryCredentials	Credenziali solo per il caricamento, valide per quel solo percorso e per 15 minuti.
baseUrl	L’indirizzo pubblico dello storage. L’URL del file è baseUrl + / + path.

Carica subito il file con qualsiasi client S3 usando queste credenziali, poi passa il suo URL come parametro HEADER quando invii il template. I file molto grandi o i formati che WhatsApp non supporta (accetta i più comuni formati di immagine, video e PDF) non funzionano.

Esempio: un template con un’intestazione immagine

Supponi di avere un template approvato new_product_announcement con un’intestazione immagine e due variabili nel corpo (nome del cliente e nome del prodotto), e di volerlo inviare a un cliente.

1. Elenca i template. Chiama template/list.js con il tuo numero WhatsApp e trova new_product_announcement. I suoi componenti mostrano una variabile IMAGE nell’intestazione e due variabili TEXT nel corpo.
2. Carica l’immagine. Chiama upload/get-token.js con { "fileName": "urun.jpg" }, carica il file con le credenziali restituite e costruisci il suo URL a partire da baseUrl e path.
3. Invia il template. Chiama template/send.js con l’URL del file come parametro HEADER e ["Ayşe", "XYZ Telefon"] come parametri BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Se il template avesse variabili nei pulsanti, aggiungeresti un elemento BUTTONS allo stesso modo.
4. Apri la chat. L’url della risposta apre la conversazione; quando il cliente risponde, la conversazione prosegue nella tua inbox MonoChat.

Errori

Una chiamata non riuscita risponde con uno stato di errore e un messaggio che dice cosa è andato storto. Registra questi messaggi nel tuo sistema e, dove serve, mostra un messaggio comprensibile ai tuoi utenti.

Messaggio	Causa
phoneNumber field is required	template/list.js è stato chiamato senza phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Manca un campo obbligatorio di template/send.js.
Channel not found	Il phoneNumber non è un numero WhatsApp del tuo workspace.
Channel is not verified	Il numero WhatsApp è collegato ma non verificato.
Template message not found	Nessun template approvato con quel nome e quella lingua sul numero. Controlla l’ortografia e languageCode.
Template message is not approved	Il template esiste ma non è approvato da Meta.
Variable missing: …	variables non corrisponde al template, ad esempio il template richiede due valori nel corpo e ne hai inviato uno.
Agent user not found	Nessun operatore con l’email in agentEmailAddress.
Customer Channel not found	Non è stato possibile creare o trovare l’identità WhatsApp del cliente.

Codici di stato HTTP che potresti vedere:

• 401 Unauthorized: l’header Authorization: Bearer <API_TOKEN> manca, oppure il token è errato o scaduto. Usa un token valido del tuo account.
• 403 Forbidden: il token non ha accesso a questo workspace o a questa app, ad esempio per un tenant slug errato.
• 404 Not Found: l’indirizzo dell’endpoint è sbagliato. Controlla il percorso completo /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: un problema imprevisto in MonoChat o presso il provider WhatsApp, oppure un rifiuto lato WhatsApp (il numero non è su WhatsApp, il cliente ti ha bloccato, limiti di qualità o di frequenza). Riprova più tardi e contatta l’assistenza MonoChat se il problema persiste.

Schermate

Invio di un template WhatsApp approvato da un sistema CRM, ERP o e-commerce con una sola chiamata API tramite MonoChatL’elenco dei template WhatsApp approvati con le loro variabiliInviare un template a un nuovo numero crea automaticamente il clienteUn template inviato in più lingueTemplate con intestazioni di immagine, video, documento e PDF

FAQ

WhatsApp Template API ha un’interfaccia utente?

No. È un’app solo API con tre endpoint: elencare i template, inviare un template e ottenere le credenziali di caricamento per le intestazioni multimediali.

Di cosa ho bisogno prima di poterla usare?

Un numero WhatsApp Business collegato a MonoChat e verificato, template approvati da Meta e un token API da Profilo › Token API.

Cosa succede quando il cliente risponde?

La conversazione arriva nella tua inbox MonoChat come tutte le altre. Ogni invio restituisce anche un link diretto alla conversazione, e puoi assegnarla a un operatore tramite email.

Posso inviare a un numero che non è ancora un cliente?

Sì. Se il numero di telefono non è ancora un cliente, il cliente viene creato con il nome che invii.

Quanto costano i messaggi template?

Ogni messaggio è fatturato come qualsiasi messaggio template inviato da MonoChat. Meta stabilisce i prezzi dei template in base alla categoria e al paese del destinatario; usa il calcolatore dei costi dei messaggi in blocco di WhatsApp per stimare un invio.

Correlati

• Session Link
• Bulk Template Message API
• Messaggi template
• App MonoStore