Creazione e gestione di modelli

I modelli vengono utilizzati durante l'invio dei modelli di messaggi con l'API Cloud, ospitata da Meta, o l'API On-Premises. L'API Cloud controlla i modelli e i parametri delle variabili utilizzando l'apprendimento automatico per proteggere la sicurezza e l'integrità dei servizi dell'API Cloud. Quando l'API Cloud controlla i modelli e il testo delle variabili, nessuna informazione viene condivisa con WhatsApp.

I modelli possono essere creati usando l'API Business Management o WhatsApp Business Manager. Il numero di modelli che un account WhatsApp Business può avere è determinato dall'azienda madre. Se un'azienda madre non è verificata, ciascuno dei suoi account WhatsApp Business è limitato a 250 modelli. Tuttavia, se l'azienda madre è verificata e almeno uno dei suoi account WhatsApp Business dispone di un numero di telefono aziendale con un nome visualizzato approvato, ciascuno dei suoi account WhatsApp Business può avere fino a 6000 modelli.

Prima di iniziare

Ecco cosa ti servirà:

• Un token d'accesso dell'utente di sistema collegato all'azienda
• L'autorizzazione whatsapp_business_management
• L'ID dell'account WhatsApp Business per l'azienda
• Il nome utente della risorsa multimediale per ogni documento, immagine o file video da utilizzare in un modello di contenuto multimediale. Per ottenere un nome utente della risorsa multimediale, devi caricare la risorsa multimediale utilizzando l'API Resumable Upload

Limitazioni

• Il campo name di un modello di messaggio prevede un limite di 512 caratteri.
• Il campo content di un modello di messaggio prevede un limite di 1024 caratteri.
• È possibile modificare un modello solo quando si trova in stato Approvato, Rifiutato oppure In pausa, una sola volta al giorno e per un massimo di 10 volte al mese.
• Gli account WhatsApp Business possono creare solo 100 modelli di messaggi all'ora.
• I modelli composti da 4 o più pulsanti, o da un pulsante di risposta rapida e uno o più pulsanti di un altro tipo, non possono essere visualizzati sui client desktop di WhatsApp. Agli utenti di WhatsApp che ricevono uno di questi modelli di messaggi verrà chiesto di visualizzare il messaggio su un telefono.

Localizzazione

Puoi aggiungere un modello di messaggio in una lingua specifica durante la creazione di un modello. Questi modelli vengono conteggiati ai fini del tuo limite. Sii coerente quando fornisci le traduzioni. Consulta l'articolo del Centro assistenza Perché visualizzo errori di "struttura non disponibile" nella callback? per ulteriori informazioni.

Creazione di modelli

Invia una richiesta POST all'endpoint WhatsApp Business Account > Modelli di messaggi per creare un modello.

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Corpo del post

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Proprietà del corpo

Categorie dei modelli

I modelli devono essere categorizzati usando una delle seguenti categorie: Le categorie sono un fattore tenuto in considerazione per i prezzi e la categoria che designi sarà validata al momento della creazione del modello.

• AUTHENTICATION
• MARKETING
• UTILITY

Consulta il nostro documento Categorizzazione dei modelli per determinare quale categoria usare quando crei modelli.

Componenti dei modelli

I modelli sono composti da vari componenti di testo, multimediali e interattivi, in base alle esigenze dell'azienda. Consulta il documento Componenti dei modelli per una lista di tutti i componenti possibili e dei rispettivi requisiti, oltre agli esempi e alle query di esempio.

Durante la creazione di un modello, definisci i suoi componenti assegnando un array di oggetti component alla proprietà components nel corpo della richiesta.

Ad esempio, qui è riportato un array contenente un componente text body con due variabili e valori di esempio, un componente phone number button e un componente URL button:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Fai riferimento al documento Componenti dei modelli per una lista di tutti i componenti possibili e dei rispettivi requisiti, oltre agli esempi e alle query di esempio.

I modelli categorizzati come AUTHENTICATION dispongono di requisiti unici per i componenti. Consulta Modelli di autenticazione.

Convalida della categoria

Quando invii una richiesta di creazione di un modello, ne convalidiamo immediatamente la categoria usando le nostre linee guida di categorizzazione dei modelli.

• Se siamo d'accordo con la categoria da te indicata, creiamo il modello e ne impostiamo lo status su PENDING. Quindi il modello viene sottoposto alla procedura di controllo.
• Se non siamo d'accordo con la tua indicazione, creiamo il modello, ma ne impostato lo status su REJECTED e attiviamo un webhook di aggiornamento dello stato del modello di messaggio con reason impostato su INCORRECT_CATEGORY. Ti consigliamo di metterti in ascolto per questo webhook per identificare i modelli rifiutati oppure di richiedere il campo rejected_reason sui modelli appena creati, che avrà il valore TAG_CONTENT_MISMATCH.

In entrambi i casi, lo stato iniziale del modello viene restituito come parte della risposta API.

Se lo stato del tuo modello è stato impostato su REJECTED come parte della validazione della categoria, hai diverse opzioni:

• modificare i componenti del modello in modo che rispettino le nostre linee guida;
• modificare la categoria del modello in modo che rispetti le nostre linee guida;
• creare un nuovo modello.

Categorizzazione automatica

Puoi includere la proprietà allow_category_change nella tua richiesta affinché venga assegnata automaticamente una categoria in base ai contenuti del tuo modello e alle nostre linee guida di categorizzazione dei modelli. Questo può impedire che lo stato del modello venga immediatamente impostato su REJECTED a causa di una categoria errata.

La categorizzazione automatica è possibile solo quando si crea un modello.

Controllo del modello

I modelli con stato PENDING vengono sottoposti alla procedura di controllo. Controlliamo i contenuti di ogni modello appena creato o modificato per assicurarci che rispettino le nostre linee guida e normative sui contenuti. In base all'esito del controllo, cambiamo automaticamente lo stato su APPROVED o REJECTED, attivando un webhook di aggiornamento dello stato del modello di messaggio.

Stato del modello

In base all'esito della convalida della categoria e del controllo del modello, impostiamo o modifichiamo lo status del tuo modello in uno dei seguenti valori:

• APPROVED: il modello ha superato il controllo ed è stato approvato e ora può essere inviato nei messaggi con modelli.
• PENDING: il modello ha superato la convalida della categoria ed è in fase di controllo.
• REJECTED: il modello non ha superato la convalida della categoria o il controllo del modello. Puoi richiedere il campo rejected_reason sul modello per sapere il motivo.

Con il riferimento all'endpoint Modello di messaggio WhatsApp per tutti i campi e gli stati possibili.

Risposta

In caso di azione eseguita correttamente, l'API risponde con ID, stato e categoria del modello appena creato. Ci sono tre esiti possibili:

• Siamo d'accordo con la categoria da te indicata e il modello è ora sottoposto alla procedura di controllo (lo status è PENDING).
• Non siamo d'accordo con la categoria indicata (lo status è REJECTED)
• Abbiamo approvato automaticamente il modello (lo status è APPROVED). Questo è possibile solo per modelli di autenticazione con pulsanti con password monouso.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Proprietà della risposta

Esempio di richiesta

Ecco un esempio di richiesta per la creazione di un modello di promozione stagionale composto dai seguenti componenti:

• Un'intestazione con testo
• Un corpo di testo
• Un piè di pagina
• Due pulsanti di risposta rapida

Per ulteriori esempi, consulta Esempi di richieste.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Esempio di risposta

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Invio di modelli

Utilizza l'API Cloud o l'API On-Premises per inviare un modello in un modello di messaggio.

Time-To-Live (TTL): personalizzazione, impostazioni predefinite, valori minimi/massimi e compatibilità

Qualora non riuscissimo a consegnare un messaggio a un utente WhatsApp, continueremo a tentare la consegna per un periodo di tempo noto come TTL (Time-To-Live) o periodo di validità dei messaggi.

Puoi personalizzare il TTL predefinito dei modelli di autenticazione, utility e marketing.

Ti invitiamo a impostare un TTL per tutti i tuoi modelli di autenticazione preferibilmente uguale o inferiore al tempo di scadenza del codice, per assicurarti che i tuoi clienti ricevano un messaggio solo quando un codice è ancora utilizzabile.

Tabella di impostazioni predefinite, valori minimi/massimi e compatibilità

Come personalizzare il TTL per il tuo modello

Per impostare un TTL personalizzato per un modello di autenticazione, utility o marketing includi e imposta il valore della proprietà message_send_ttl_seconds nella chiamata POST /<PHONE_NUMBER_ID>/messages.

Il TTL può essere personalizzato con incrementi di 1 secondo.

Valori proprietà message_send_ttl_seconds validi

• Modelli di autenticazione: da 30 a 900 secondi (da 30 secondi a 15 minuti)
• Modelli di utility: da 30 a 43200 secondi (da 30 secondi a 12 ore)
• Modelli di marketing: da 43200 a 2592000 (da 12 ore a 30 giorni)

Per i modelli di autenticazione e utility, puoi impostare il valore della proprietà message_send_ttl_seconds a -1, che imposterà un TTL personalizzato di 30 giorni.

Quando il TTL viene superato: messaggi ignorati

I messaggi che non vengono consegnati entro il TTL predefinito o personalizzato vengono annullati.

Se non ricevi un webhook di messaggio consegnato prima del superamento del TTL, puoi desumere che la consegna del messaggio sia stata annullata.

Se invii un messaggio che non si riesce a consegnare, potrebbe verificarsi un lieve ritardo prima della ricezione del webhook, quindi è consigliabile prevedere un breve tempo di attesa prima di dedurre che la consegna del messaggio sia stata annullata.

Best practice per i modelli di marketing

Pulsante di disattivazione marketing

Ti consigliamo di aggiungere un pulsante di risposta rapida ai modelli classificati come MARKETING che semplifichi per i clienti la disattivazione dei messaggi di marketing. Così facendo, dai ai clienti la possibilità di rifiutare esplicitamente il consenso alla ricezione di messaggi di marketing senza dover bloccare la tua azienda. In questo modo, potresti ampliare più rapidamente il volume dei messaggi. Consulta questo articolo per maggiori informazioni sui benefici dell'aggiunta di un pulsante di disattivazione ai modelli di marketing.

Acquisizione di modelli

Invia una richiesta GET all'endpoint WhatsApp Business Account > Message Templates per ottenere una lista dei modelli di proprietà di un account WhatsApp Business.

Sintassi della richiesta

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Parametri della stringa della query

Esempio di richiesta

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Esempio di richiesta (modelli rifiutati)

Puoi restituire solo i modelli con valori del campo specifici includendo il campo e il valore desiderato nella richiesta. Ad esempio, includi status=REJECTED per ottenere solo i modelli che sono stati rifiutati.

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Recupero dello spazio dei nomi di un modello

Lo spazio dei nomi di un modello di messaggio è necessario per inviare messaggi con quel modello.

Per ottenere lo spazio dei nomi di un modello, invia una richiesta GET all'endpoint /{whatsapp-business-account-ID} e includi il campo message_template_namespace.

Esempio di richiesta

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

In caso di azione eseguita correttamente, viene restituito un oggetto JSON con l'ID dell'account WhatsApp Business e lo spazio dei nomi:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Modifica di modelli

Invia una richiesta POST all'endpoint WhatsApp Message Template per modificare un modello. Puoi anche modificare un modello manualmente utilizzando la scheda WhatsApp Manager > Strumenti per l'account > Modelli di messaggi.

Limitazioni

• Possono essere modificati solo i modelli con uno stato APPROVED, REJECTED o PAUSED.
• Puoi modificare solo category o components di un modello.
• Non puoi modificare la category di un modello approvato.
• I modelli approvati possono essere modificati fino a 10 volte in una finestra di 30 giorni o 1 volta in una finestra di 24 ore. I modelli rifiutati o in pausa possono essere modificati un numero illimitato di volte.
• Dopo la modifica di un modello approvato o in pausa, il modello viene approvato automaticamente se supera la procedura di controllo.

Sintassi della richiesta

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Corpo del post

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Proprietà

Esempio di richiesta (modifica di componenti)

Esempio di richiesta al testo del corpo di un modello che conteneva contenuti di marketing e utility affinché contenga solo quelli di marketing.

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Esempio di richiesta (solo modifica della categoria)

Esempio di richiesta per modificare la categoria del modello da UTILITY a MARKETING.

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Esempio di risposta

Esempio di risposta in caso di azione eseguita correttamente.

{
  "success": true
}

Eliminazione di modelli

Usa l'endpoint WhatsApp Business Account > Message Templates per eliminare un modello in base al nome o all'ID.

Note

• Se elimini un modello che è stato inviato in un modello di messaggio ma che deve ancora essere consegnato (ad esempio perché il telefono del cliente è spento), lo stato del modello sarà impostato su PENDING_DELETION e cercheremo di consegnare il messaggio per 30 giorni. Trascorso questo periodo riceverai l'errore "Struttura non disponibile" e il cliente non riceverà il messaggio.
• I nomi di un modello approvato che è stato eliminato non possono essere riutilizzati per 30 giorni.

Eliminazione in base al nome

L'eliminazione di un modello in base al nome elimina tutti i modelli che corrispondono a quel nome, ovvero i modelli con lo stesso nome anche in lingue diverse.

Sintassi della richiesta

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Esempio di richiesta

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "success": true
}

Eliminazione in base all'ID

Per eliminare un modello in base all'ID, includi l'ID del modello insieme al suo nome nella richiesta; solo il modello con l'ID corrispondente sarà eliminato.

Sintassi della richiesta

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Esempio di richiesta

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "success": true
}

Per saperne di più

Passaggi successivi

• Primi passi con l'API Cloud per iniziare a inviare messaggi