Condividi tramite

Inviare messaggi di modello WhatsApp con i messaggi avanzati

  • Articolo

Questo articolo descrive come inviare messaggi di modello WhatsApp usando Advanced Communication Messages SDK.

Prerequisiti

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Messages SDK per .NET.

Nome della classe Descrizione
NotificationMessagesClient Si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Definisce il "chi" e il "what" del messaggio del modello che si intende inviare.

Nota

Per altre informazioni, vedere informazioni di riferimento su Azure SDK per .NET. Spazio dei nomi Azure.Communication.Messages.

Tipi di modello WhatsApp supportati

Tipo di modello Descrizione
Modelli di messaggio basati su testo I modelli di messaggio WhatsApp sono formati di messaggio specifici con o senza parametri.
Modelli di messaggio basati su supporti Modelli di messaggi WhatsApp con parametri multimediali per i componenti di intestazione.
Modelli di messaggio interattivi I modelli di messaggio interattivi espandono il contenuto che è possibile inviare ai destinatari, includendo pulsanti interattivi usando l'oggetto componenti. Sono supportati sia call-to-action che risposta rapida.
Modelli di messaggio basati sulla posizione Modelli di messaggio WhatsApp con parametri di posizione in termini longitudine e latitudine per i componenti di intestazione.

Configurazione comune

Seguire questa procedura per aggiungere i frammenti di codice necessari alla funzione Main del Program.cs file.

Creare e gestire il messaggio del modello WhatsApp

I modelli di messaggio WhatsApp sono formati di messaggi specifici che le aziende usano per inviare notifiche o messaggi di assistenza clienti a persone che hanno accodato esplicitamente alle notifiche. I messaggi possono includere promemoria per gli appuntamenti, informazioni sulla spedizione, risoluzione dei problemi o aggiornamenti dei pagamenti. Prima di iniziare a usare Advanced messaging SDK per inviare messaggi modello, l'utente deve creare modelli necessari nella piattaforma WhatsApp Business.

Per altre informazioni sui requisiti di WhatsApp per i modelli, vedi i riferimenti all'API WhatsApp Business Platform:

Autenticare il client

Messages SDK usa per NotificationMessagesClient inviare messaggi. Il NotificationMessagesClient metodo esegue l'autenticazione usando il stringa di connessione acquisito dalla risorsa Servizi di comunicazione di Azure nella portale di Azure. Per altre informazioni sulle stringa di connessione, vedere access-your-connection-strings-and-service-endpoints.

Per semplicità, questa guida introduttiva usa una stringa di connessione per l'autenticazione. Negli ambienti di produzione è consigliabile usare entità servizio.

Ottenere la stringa di connessione dalla risorsa Servizi di comunicazione di Azure nel portale di Azure. A sinistra passare alla scheda Keys. Copiare il campo Connection string per la chiave primaria. La stringa di connessione è nel formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando il campo

Impostare la variabile di ambiente COMMUNICATION_SERVICES_CONNECTION_STRING sul valore della stringa di connessione.
Aprire una finestra della console e immettere il comando seguente:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Dopo l'aggiunta della variabile di ambiente potrebbe essere necessario riavviare eventuali programmi in esecuzione che necessitano di leggere la variabile di ambiente, inclusa la finestra della console. Se ad esempio si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Per altre informazioni su come impostare una variabile di ambiente per il sistema, seguire la procedura descritta in Archiviare la stringa di connessione in una variabile di ambiente.

Per creare un'istanza NotificationMessagesClient, aggiungere il codice seguente al metodo Main:

// Retrieve connection string from environment variable
string connectionString = 
    Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");

// Instantiate the client
var notificationMessagesClient = new NotificationMessagesClient(connectionString);

Configurare l’ID di registrazione del canale

È stato creato il GUID dell'ID registrazione canale durante la registrazione del canale. Trovarlo nel portale nella scheda Canali della risorsa Servizi di comunicazione di Azure.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando la scheda ‘Canali’. L'attenzione viene posta sull'azione di copia del campo

Assegnarlo a una variabile denominata channelRegistrationId.

var channelRegistrationId = new Guid("<your channel registration ID GUID>");

Configurare l’elenco dei destinatari

Devi fornire un numero di telefono attivo associato a un account WhatsApp. Questo account WhatsApp riceve il modello, il testo e i messaggi multimediali inviati in questa guida introduttiva.

Per questo esempio, è possibile usare il numero di telefono personale.

Il numero di telefono del destinatario non può essere il numero di telefono commerciale (ID mittente) associato alla registrazione del canale WhatsApp. L'ID mittente viene visualizzato come mittente del testo e dei messaggi multimediali inviati al destinatario.

Il numero di telefono deve includere il codice paese. Per altre informazioni sulla formattazione dei numeri di telefono, vedi la documentazione di WhatsApp per formati di numeri di telefono.

Nota

Nell'elenco dei destinatari è attualmente supportato un solo numero di telefono.

Creare l'elenco dei destinatari nel seguente modo:

var recipientList = new List<string> { "<to WhatsApp phone number>" };

Esempio:

// Example only
var recipientList = new List<string> { "+14255550199" };

Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp

Le conversazioni tra un account WhatsApp Business e un utente WhatsApp possono essere avviate in uno dei due modi seguenti:

  • L'azienda invia un messaggio modello all'utente WhatsApp.
  • L'utente WhatsApp invia qualsiasi messaggio al numero di ufficio.

Un'azienda non può avviare una conversazione interattiva. Un'azienda può inviare un messaggio interattivo solo dopo aver ricevuto un messaggio dall'utente. L'azienda può inviare messaggi interattivi solo all'utente durante la conversazione attiva. Una volta scaduta la finestra di conversazione di 24 ore, solo l'utente può riavviare la conversazione interattiva. Per altre informazioni sulle conversazioni, vedi la definizione in WhatsApp Business Platform.

Per avviare una conversazione interattiva dal tuo account WhatsApp personale, invia un messaggio al tuo numero di azienda (ID mittente).

Una conversazione WhatsApp visualizzata sul Web che mostra un messaggio utente inviato al numero di account WhatsApp Business.

Set up environment (Configurare l'ambiente)

Creazione di un progetto .NET

Per creare il progetto, seguire l'esercitazione in Creare un'applicazione console .NET usando Visual Studio.

Per compilare il codice, premere CTRL+F7.

Installare il pacchetto

Installare il pacchetto NuGet Azure.Communication.Messages nel progetto C#.

  1. Aprire Gestione pacchetti NuGet in Project>Manage NuGet Packages....
  2. Cercare il pacchetto Azure.Communication.Messages.
  3. Installa la versione più recente.

Configurare il framework dell'app

Aprire il file Program.cs in un editor di testo.

Sostituire il contenuto del file Program.cs con il codice seguente:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure;
using Azure.Communication.Messages;

namespace AdvancedMessagingQuickstart
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Advanced Messages quickstart samples.");

            // Quickstart code goes here
        }
    }
}

Per usare le funzionalità di messaggistica avanzata, aggiungere una using direttiva per includere lo spazio dei Azure.Communication.Messages nomi.

using Azure.Communication.Messages;

Esempi di codice

Seguire questa procedura per aggiungere frammenti di codice necessari alla funzione Main del Program.cs file.

Elencare i modelli di WhatsApp in portale di Azure

È possibile visualizzare i modelli nella portale di Azure passando alla risorsa >del Servizio di comunicazione di Azure Modelli di messaggistica>avanzata.

Screenshot che mostra una risorsa Servizi di comunicazione di Azure nella portale di Azure, visualizzando la scheda Modelli di messaggistica > avanzata.

Selezionare un modello per visualizzare i dettagli.

Il content campo dei dettagli del modello può includere associazioni di parametri. Le associazioni di parametri possono essere indicate come:

  • Campo format con un valore, IMAGEad esempio .
  • Parentesi doppie che circondano un numero, ad esempio {{1}}. Il numero, indicizzato in corrispondenza di 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio.

Screenshot che mostra i dettagli del modello.

In alternativa, puoi visualizzare e modificare tutti i modelli di account WhatsApp Business nei modelli di messaggio strumenti> account WhatsApp Manager>.

Per elencare i modelli a livello di codice, è possibile recuperare tutti i modelli per l'ID canale come indicato di seguito:

MessageTemplateClient messageTemplateClient = new MessageTemplateClient(connectionString);
Pageable<MessageTemplateItem> templates = messageTemplateClient.GetTemplates(channelRegistrationId);

Inviare un messaggio modello senza parametri

Se il modello non richiede parametri, non è necessario specificare valori o associazioni durante la creazione di MessageTemplate.

var messageTemplate = new MessageTemplate(templateName, templateLanguage);

Esempio

non sample_template accetta parametri.

Screenshot che mostra i dettagli del modello per il modello denominato sample_template.

Assemblare l'oggetto MessageTemplate facendo riferimento al nome e alla lingua del modello di destinazione.

string templateName = "sample_template"; 
string templateLanguage = "en_us"; 

var sampleTemplate = new MessageTemplate(templateName, templateLanguage);

Inviare un messaggio modello con parametri di testo nel corpo

Usare MessageTemplateText per definire i parametri nel corpo indicato con parentesi quadre doppie che circondano un numero, ad esempio {{1}}. Il numero, indice avviato da 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio. L'inclusione di parametri non presenti nel modello non è valida.

Definizione del modello con due parametri:

{
  "type": "BODY",
  "text": "Message with two parameters: {{1}} and {{2}}"
}

Esempi

sample_shipping_confirmation sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_shipping_confirmation.

In questo esempio il corpo del modello ha un parametro:

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

I parametri vengono definiti con i MessageTemplateValue valori e MessageTemplateWhatsAppBindings le associazioni. Usare i valori e le associazioni per assemblare .MessageTemplate

string templateName = "sample_shipping_confirmation"; 
string templateLanguage = "en_us"; 

var threeDays = new MessageTemplateText("threeDays", "3");

WhatsAppMessageTemplateBindings bindings = new();
bindings.Body.Add(new(threeDays.Name));

MessageTemplate shippingConfirmationTemplate  = new(templateName, templateLanguage);
shippingConfirmationTemplate.Bindings = bindings;
shippingConfirmationTemplate.Values.Add(threeDays);

Inviare un messaggio modello con il parametro multimediale nell'intestazione

Usare MessageTemplateImage, MessageTemplateVideoo MessageTemplateDocument per definire il parametro multimediale in un'intestazione.

Definizione del modello con il parametro image media nell'intestazione:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Può format avere diversi tipi di supporti supportati da WhatsApp. In .NET SDK ogni tipo di supporto usa un tipo MessageTemplateValue corrispondente.

Formato Tipo MessageTemplateValue Tipo di file
IMAGE MessageTemplateImage png, jpg
VIDEO MessageTemplateVideo mp4
DOCUMENT MessageTemplateDocument pdf

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Assembly del modello di messaggio per i supporti di immagine:

var url = new Uri("< Your media URL >");

var media = new MessageTemplateImage("image", url);
WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(media.Name));

var messageTemplate = new MessageTemplate(templateName, templateLanguage);
template.Bindings = bindings;
template.Values.Add(media);

Esempi

sample_movie_ticket_confirmation sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_movie_ticket_confirmation.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede quattro parametri di testo:

{
  "type": "BODY",
  "text": "Your ticket for *{{1}}*\n*Time* - {{2}}\n*Venue* - {{3}}\n*Seats* - {{4}}"
},

Creare una MessageTemplateImage e quattro MessageTemplateText variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello.

string templateName = "sample_movie_ticket_confirmation"; 
string templateLanguage = "en_us"; 
var imageUrl = new Uri("https://aka.ms/acsicon1");

var image = new MessageTemplateImage("image", imageUrl);
var title = new MessageTemplateText("title", "Contoso");
var time = new MessageTemplateText("time", "July 1st, 2023 12:30PM");
var venue = new MessageTemplateText("venue", "Southridge Video");
var seats = new MessageTemplateText("seats", "Seat 1A");

WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(image.Name));
bindings.Body.Add(new(title.Name));
bindings.Body.Add(new(time.Name));
bindings.Body.Add(new(venue.Name));
bindings.Body.Add(new(seats.Name));

MessageTemplate movieTicketConfirmationTemplate = new(templateName, templateLanguage);
movieTicketConfirmationTemplate.Values.Add(image);
movieTicketConfirmationTemplate.Values.Add(title);
movieTicketConfirmationTemplate.Values.Add(time);
movieTicketConfirmationTemplate.Values.Add(venue);
movieTicketConfirmationTemplate.Values.Add(seats);
movieTicketConfirmationTemplate.Bindings = bindings;

Altri esempi

Inviare un messaggio modello con la posizione nell'intestazione

Usare MessageTemplateLocation per definire il parametro location in un'intestazione.

Definizione del modello per il componente di intestazione che richiede la posizione come:

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

può format richiedere tipi di supporti diversi. In .NET SDK ogni tipo di supporto usa un tipo MessageTemplateValue corrispondente.

Proprietà Descrizione Tipo
ADDRESS Indirizzo visualizzato dopo il NAME valore, sotto la mappa generica nella parte superiore del messaggio. string
LATITUDE Latitudine della posizione. double
LONGITUDE Longitudine della posizione. double
LOCATIONNAME Testo visualizzato immediatamente sotto la mappa generica nella parte superiore del messaggio. string

Per altre informazioni sui modelli basati sulla posizione, vedi la documentazione di WhatsApp per i supporti di messaggio.

Esempio

sample_movie_location sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_location_template.

Assembly modello di messaggio basato sul percorso:

 var location = new MessageTemplateLocation("location");
 location.LocationName = "Pablo Morales";
 location.Address = "1 Hacker Way, Menlo Park, CA 94025";
 location.Position = new Azure.Core.GeoJson.GeoPosition(longitude: 122.148981, latitude: 37.483307);

 WhatsAppMessageTemplateBindings location_bindings = new();
 location_bindings.Header.Add(new(location.Name));

 var messageTemplateWithLocation = new MessageTemplate(templateNameWithLocation, templateLanguage);
 messageTemplateWithLocation.Values.Add(location);
 messageTemplateWithLocation.Bindings = location_bindings;

Inviare un messaggio modello con pulsanti di risposta rapida

Usare MessageTemplateQuickAction per definire il payload per i pulsanti di risposta rapida e MessageTemplateQuickAction gli oggetti con i tre attributi seguenti.

Proprietà Descrizione Type
Nome Oggetto name utilizzato per cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Azione rapida textfacoltativa. string
Payload L'oggetto payload assegnato a un pulsante disponibile in una risposta di messaggio se l'utente seleziona il pulsante. string

Definizione del modello con pulsanti di risposta rapida:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Per altre informazioni sul payload nelle risposte di risposta rapida dell'utente, vedi la documentazione di WhatsApp per il callback ricevuto da un pulsante di risposta rapida.

Esempio

sample_issue_resolution sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_issue_resolution.

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
},

Il modello include due pulsanti di risposta precompilato e YesNo.

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

Creare una MessageTemplateText e due MessageTemplateQuickAction variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

string templateName = "sample_issue_resolution";
string templateLanguage = "en_us";

var name = new MessageTemplateText(name: "name", text: "Kat");
var yes = new MessageTemplateQuickAction(name: "Yes"){ Payload =  "Kat said yes" };
var no = new MessageTemplateQuickAction(name: "No") { Payload = "Kat said no" };

WhatsAppMessageTemplateBindings bindings = new();
bindings.Body.Add(new(name.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), yes.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), no.Name));

MessageTemplate issueResolutionTemplate = new(templateName, templateLanguage);
issueResolutionTemplate.Values.Add(name);
issueResolutionTemplate.Values.Add(yes);
issueResolutionTemplate.Values.Add(no);
issueResolutionTemplate.Bindings = bindings;

Usare MessageTemplateQuickAction per definire il suffisso URL per i pulsanti di chiamata all'azione e MessageTemplateQuickAction l'oggetto hanno i due attributi seguenti.

Proprietà Descrizione Type
Nome Viene name utilizzato per cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Oggetto text aggiunto all'URL. string

Pulsanti di definizione del modello:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Esempio

sample_purchase_feedback sagoma:

Questo modello di esempio aggiunge un pulsante con un collegamento URL dinamico al messaggio. Usa anche un'immagine nell'intestazione e un parametro di testo nel corpo.

Acquisizione dello schermo dell'editor pulsanti di Gestione WhatsApp Pannello di azione Call to action che mostra il pulsante Tipo DI URL che puoi usare per scegliere tra Statico e Dinamico.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

Il modello include un pulsante URL dinamico con un parametro:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

Creare un MessageTemplateImageoggetto , uno MessageTemplateTexte una MessageTemplateQuickAction variabile. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

string templateName = "sample_purchase_feedback";
string templateLanguage = "en_us";
var imageUrl = new Uri("https://aka.ms/acsicon1");

var image = new MessageTemplateImage(name: "image", uri: imageUrl);
var product = new MessageTemplateText(name: "product", text: "coffee");
var urlSuffix = new MessageTemplateQuickAction(name: "text") { Text = "survey-code" };

WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(image.Name));
bindings.Body.Add(new(product.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.Url.ToString(), urlSuffix.Name));

MessageTemplate purchaseFeedbackTemplate = new("sample_purchase_feedback", "en_us");
purchaseFeedbackTemplate.Values.Add(image);
purchaseFeedbackTemplate.Values.Add(product);
purchaseFeedbackTemplate.Values.Add(urlSuffix);
purchaseFeedbackTemplate.Bindings = bindings;

Per i collegamenti statici, non è necessario includere MessageTemplateQuickAction il modello perché il modello WhatsApp ha un collegamento statico CallToAction senza input richiesto dall'utente.

Pulsanti di definizione del modello:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

Esempio

purchase_feedback_static sagoma:

Questo modello di esempio aggiunge un pulsante con un collegamento URL statico al messaggio. Usa anche un'immagine nell'intestazione e un parametro di testo nel corpo.

Acquisizione dello schermo che mostra i dettagli per il modello purchase-feedback-static-.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Hello {{1}}, \nHope you are great day!.\n Please click on given link to explore about our program.."
},

Il modello include un pulsante URL dinamico con un parametro:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/"
    }
  ]
}

Creare un MessageTemplateImageoggetto , uno MessageTemplateText. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

// Send sample template sample_template
string templateNameWithcta = "purchase_feedback_static";
var bodyParam1 = new MessageTemplateText(name: "customer", text: "Joe");
var image = new MessageTemplateImage("image", new Uri("https://aka.ms/acsicon1"));

WhatsAppMessageTemplateBindings cta_bindings = new();
cta_bindings.Body.Add(new(bodyParam1.Name));
cta_bindings.Header.Add(new(image.Name));

var messageTemplateWithcta = new MessageTemplate(templateNameWithcta, templateLanguage);
messageTemplateWithcta.Values.Add(bodyParam1);
messageTemplateWithcta.Values.Add(image);
messageTemplateWithcta.Bindings = cta_bindings;

TemplateNotificationContent templateContent4 =
    new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplateWithcta);
Response<SendMessageResult> sendTemplateMessageResult4 =
    notificationMessagesClient.Send(templateContent4);

Eseguire il codice

Compilare ed eseguire il programma.

Per inviare un SMS o un messaggio multimediale a un utente WhatsApp, deve esserci una conversazione attiva tra l'account WhatsApp Business e l'utente WhatsApp.

Se non si dispone di una conversazione attiva, ai fini di questo esempio è possibile aggiungere un'attesa tra l'invio del messaggio modello e l'invio del messaggio di testo. Questo ritardo aggiunto concede abbastanza tempo per rispondere all'azienda sull’account WhatsApp dell'utente. Per riferimento, l'esempio specificato richiede l'input manuale dell'utente prima di inviare il messaggio successivo. Per altre informazioni, vedere l'esempio completo in Codice di esempio. Se ha esito positivo, ricevi tre messaggi sull'account WhatsApp dell'utente.

Compilare ed eseguire il programma.

dotnet build
dotnet run

Esempio di codice completo

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Threading.Tasks;
using Azure;
using Azure.Communication.Messages;
using Azure.Communication.Messages.Models.Channels;

namespace SendTemplateMessages
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Send WhatsApp Template Messages\n");

            string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");

            NotificationMessagesClient notificationMessagesClient = new NotificationMessagesClient(connectionString);

            var channelRegistrationId = new Guid("<Your Channel ID>");
            var recipientList = new List<string> { "<Recipient's WhatsApp Phone Number>" };

            // List out available templates for a channel ID
            MessageTemplateClient messageTemplateClient = new MessageTemplateClient(connectionString);
            Pageable<MessageTemplateItem> templates = messageTemplateClient.GetTemplates(channelRegistrationId);
            foreach (WhatsAppMessageTemplateItem template in templates)
            {
                Console.WriteLine("Name: {0}\tLanguage: {1}\tStatus: {2}\tContent: {3}\n",
                    template.Name, template.Language, template.Status, template.Content);
            }

            // Send Sample Template sample_template
            MessageTemplate sampleTemplate = AssembleSampleTemplate();
            var sampleTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, sampleTemplate);
            var result = await notificationMessagesClient.SendAsync(sampleTemplateContent);
            PrintResponse(result);
           
            // Send sample template sample_shipping_confirmation
            MessageTemplate shippingConfirmationTemplate = AssembleSampleShippingConfirmation();
            var shippingConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, shippingConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(shippingConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_movie_ticket_confirmation
            MessageTemplate movieTicketConfirmationTemplate = AssembleSampleMovieTicketConfirmation();
            var movieTicketConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, movieTicketConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(movieTicketConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_happy_hour_announcement
            MessageTemplate happyHourTemplate = AssembleSampleHappyHourAnnouncement();
            var happyHourTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, happyHourTemplate);
            result = await notificationMessagesClient.SendAsync(happyHourTemplateContent);
            PrintResponse(result);

            // Send sample template sample_flight_confirmation
            MessageTemplate flightConfirmationTemplate = AssembleSampleFlightConfirmation();
            var flightConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, flightConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(flightConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_issue_resolution
            MessageTemplate issueResolutionTemplate = AssembleSampleIssueResolution();
            var issueResolutionTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, issueResolutionTemplate);
            result = await notificationMessagesClient.SendAsync(issueResolutionTemplateContent);
            PrintResponse(result);

            // Send sample template sample_purchase_feedback
            MessageTemplate purchaseFeedbackTemplate = AssembleSamplePurchaseFeedback();
            var purchaseFeedbackTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, purchaseFeedbackTemplate);
            result = await notificationMessagesClient.SendAsync(purchaseFeedbackTemplateContent);
            PrintResponse(result);

            Console.WriteLine("Press any key to exit.");
            Console.ReadKey(true);
        }

        public static MessageTemplate AssembleSampleTemplate()
        {
            string templateName = "sample_template";
            string templateLanguage = "en_us";

            return new MessageTemplate(templateName, templateLanguage);
        }

        public static MessageTemplate AssembleSampleShippingConfirmation()
        {
            string templateName = "sample_shipping_confirmation";
            string templateLanguage = "en_us";

            var threeDays = new MessageTemplateText("threeDays", "3");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Body.Add(new(threeDays.Name));

            MessageTemplate shippingConfirmationTemplate = new(templateName, templateLanguage);
            shippingConfirmationTemplate.Bindings = bindings;
            shippingConfirmationTemplate.Values.Add(threeDays);

            return shippingConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleMovieTicketConfirmation()
        {
            string templateName = "sample_movie_ticket_confirmation"; 
            string templateLanguage = "en_us"; 
            var imageUrl = new Uri("https://aka.ms/acsicon1");

            var image = new MessageTemplateImage("image", imageUrl);
            var title = new MessageTemplateText("title", "Contoso");
            var time = new MessageTemplateText("time", "July 1st, 2023 12:30PM");
            var venue = new MessageTemplateText("venue", "Southridge Video");
            var seats = new MessageTemplateText("seats", "Seat 1A");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(image.Name));
            bindings.Body.Add(new(title.Name));
            bindings.Body.Add(new(time.Name));
            bindings.Body.Add(new(venue.Name));
            bindings.Body.Add(new(seats.Name));

            MessageTemplate movieTicketConfirmationTemplate = new(templateName, templateLanguage);
            movieTicketConfirmationTemplate.Values.Add(image);
            movieTicketConfirmationTemplate.Values.Add(title);
            movieTicketConfirmationTemplate.Values.Add(time);
            movieTicketConfirmationTemplate.Values.Add(venue);
            movieTicketConfirmationTemplate.Values.Add(seats);
            movieTicketConfirmationTemplate.Bindings = bindings;

            return movieTicketConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleHappyHourAnnouncement()
        {
            string templateName = "sample_happy_hour_announcement";
            string templateLanguage = "en_us";
            var videoUrl = new Uri("< Your .mp4 Video URL >");

            var video = new MessageTemplateVideo("video", videoUrl);
            var venue = new MessageTemplateText("venue", "Fourth Coffee");
            var time = new MessageTemplateText("time", "Today 2-4PM");
            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(video.Name));
            bindings.Body.Add(new(venue.Name));
            bindings.Body.Add(new(time.Name));

            MessageTemplate happyHourAnnouncementTemplate = new(templateName, templateLanguage);
            happyHourAnnouncementTemplate.Values.Add(venue);
            happyHourAnnouncementTemplate.Values.Add(time);
            happyHourAnnouncementTemplate.Values.Add(video);
            happyHourAnnouncementTemplate.Bindings = bindings;

            return happyHourAnnouncementTemplate;
        }

        public static MessageTemplate AssembleSampleFlightConfirmation()
        {
            string templateName = "sample_flight_confirmation";
            string templateLanguage = "en_us";
            var documentUrl = new Uri("< Your .pdf document URL >");

            var document = new MessageTemplateDocument("document", documentUrl);
            var firstName = new MessageTemplateText("firstName", "Kat");
            var lastName = new MessageTemplateText("lastName", "Larssen");
            var date = new MessageTemplateText("date", "July 1st, 2023");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(document.Name));
            bindings.Body.Add(new(firstName.Name));
            bindings.Body.Add(new(lastName.Name));
            bindings.Body.Add(new(date.Name));

            MessageTemplate flightConfirmationTemplate = new(templateName, templateLanguage);
            flightConfirmationTemplate.Values.Add(document);
            flightConfirmationTemplate.Values.Add(firstName);
            flightConfirmationTemplate.Values.Add(lastName);
            flightConfirmationTemplate.Values.Add(date);
            flightConfirmationTemplate.Bindings = bindings;

            return flightConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleIssueResolution()
        {
            string templateName = "sample_issue_resolution";
            string templateLanguage = "en_us";

            var name = new MessageTemplateText(name: "name", text: "Kat");
            var yes = new MessageTemplateQuickAction(name: "Yes"){ Payload =  "Kat said yes" };
            var no = new MessageTemplateQuickAction(name: "No") { Payload = "Kat said no" };

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Body.Add(new(name.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), yes.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), no.Name));

            MessageTemplate issueResolutionTemplate = new(templateName, templateLanguage);
            issueResolutionTemplate.Values.Add(name);
            issueResolutionTemplate.Values.Add(yes);
            issueResolutionTemplate.Values.Add(no);
            issueResolutionTemplate.Bindings = bindings;

            return issueResolutionTemplate;
        }

        public static MessageTemplate AssembleSamplePurchaseFeedback()
        {
            
            string templateName = "sample_purchase_feedback";
            string templateLanguage = "en_us";
            var imageUrl = new Uri("https://aka.ms/acsicon1");

            var image = new MessageTemplateImage(name: "image", uri: imageUrl);
            var product = new MessageTemplateText(name: "product", text: "coffee");
            var urlSuffix = new MessageTemplateQuickAction(name: "text") { Text = "survey-code"};
            
            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(image.Name));
            bindings.Body.Add(new(product.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.Url.ToString(), urlSuffix.Name));

            MessageTemplate purchaseFeedbackTemplate = new(templateName, templateLanguage);
            purchaseFeedbackTemplate.Values.Add(image);
            purchaseFeedbackTemplate.Values.Add(product);
            purchaseFeedbackTemplate.Values.Add(urlSuffix);
            purchaseFeedbackTemplate.Bindings = bindings;

            return purchaseFeedbackTemplate;
        }

        public static void PrintResponse(Response<SendMessageResult> response)
        {
            Console.WriteLine($"Response: {response.GetRawResponse().Status} " +
                $"({response.GetRawResponse().ReasonPhrase})");
            Console.WriteLine($"Date: " +
                $"{response.GetRawResponse().Headers.First(header => header.Name == "Date").Value}");
            Console.WriteLine($"ClientRequestId: {response.GetRawResponse().ClientRequestId}");
            Console.WriteLine($"MS-CV: " +
                $"{response.GetRawResponse().Headers.First(header => header.Name == "MS-CV").Value}");
            foreach (var receipts in response.Value.Receipts)
            {
                Console.WriteLine($"MessageId: {receipts.MessageId}");
            }
            Console.WriteLine($"\n");
        }
    }
}

Altri esempi

Questi esempi usano modelli di esempio disponibili per gli account WhatsApp Business creati tramite il portale di Azure iscrizione incorporata.

Usare sample_happy_hour_announcement modello di esempio

Questo modello di esempio usa un video nell'intestazione e due parametri di testo nel corpo.

Screenshot che mostra i dettagli del modello per il modello denominato sample_happy_hour_announcement.

L'intestazione del modello richiede un video:

{
  "type": "HEADER",
  "format": "VIDEO"
},

Il video deve essere un URL per ospitare il video mp4.

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Il corpo del modello richiede due parametri di testo:

{
  "type": "BODY",
  "text": "Happy hour is here! 🍺😀🍸\nPlease be merry and enjoy the day. 🎉\nVenue: {{1}}\nTime: {{2}}"
},

Creare una MessageTemplateVideo e due MessageTemplateText variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello.

string templateName = "sample_happy_hour_announcement";
string templateLanguage = "en_us";
var videoUrl = new Uri("< Your .mp4 Video URL >");

var video = new MessageTemplateVideo("video", videoUrl);
var venue = new MessageTemplateText("venue", "Fourth Coffee");
var time = new MessageTemplateText("time", "Today 2-4PM");
WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(video.Name));
bindings.Body.Add(new(venue.Name));
bindings.Body.Add(new(time.Name));

MessageTemplate happyHourAnnouncementTemplate = new(templateName, templateLanguage);
happyHourAnnouncementTemplate.Values.Add(venue);
happyHourAnnouncementTemplate.Values.Add(time);
happyHourAnnouncementTemplate.Values.Add(video);
happyHourAnnouncementTemplate.Bindings = bindings;

Usare un modello di esempio sample_flight_confirmation

Questo modello di esempio usa un documento nell'intestazione e tre parametri di testo nel corpo.

Screenshot che mostra i dettagli del modello per il modello denominato sample_flight_confirmation.

L'intestazione del modello richiede un documento:

{
  "type": "HEADER",
  "format": "DOCUMENT"
},

Il documento deve essere un URL per il documento PDF ospitato.

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Il corpo del modello richiede tre parametri di testo:

{
  "type": "BODY",
  "text": "This is your flight confirmation for {{1}}-{{2}} on {{3}}."
},

Creare una MessageTemplateDocument e tre MessageTemplateText variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello.

string templateName = "sample_flight_confirmation";
string templateLanguage = "en_us";
var documentUrl = new Uri("< Your .pdf document URL >");

var document = new MessageTemplateDocument("document", documentUrl);
var firstName = new MessageTemplateText("firstName", "Kat");
var lastName = new MessageTemplateText("lastName", "Larssen");
var date = new MessageTemplateText("date", "July 1st, 2023");

WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(document.Name));
bindings.Body.Add(new(firstName.Name));
bindings.Body.Add(new(lastName.Name));
bindings.Body.Add(new(date.Name));

MessageTemplate flightConfirmationTemplate = new(templateName, templateLanguage);
flightConfirmationTemplate.Values.Add(document);
flightConfirmationTemplate.Values.Add(firstName);
flightConfirmationTemplate.Values.Add(lastName);
flightConfirmationTemplate.Values.Add(date);
flightConfirmationTemplate.Bindings = bindings;

Prerequisiti

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Messages SDK per Java Servizi di comunicazione di Azure.

Nome della classe Descrizione
NotificationMessagesClient Si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Definisce il "chi" e il "what" del messaggio del modello che si intende inviare.

Nota

Per altre informazioni, vedere Le informazioni di riferimento su Azure SDK per Java sono disponibili nel pacchetto com.azure.communication.messages.

Tipi di modello WhatsApp supportati

Tipo di modello Descrizione
Modelli di messaggio basati su testo I modelli di messaggio WhatsApp sono formati di messaggio specifici con o senza parametri.
Modelli di messaggio basati su supporti Modelli di messaggi WhatsApp con parametri multimediali per i componenti di intestazione.
Modelli di messaggio interattivi I modelli di messaggio interattivi espandono il contenuto che è possibile inviare ai destinatari, includendo pulsanti interattivi usando l'oggetto componenti. Sono supportati sia call-to-action che risposta rapida.
Modelli di messaggio basati sulla posizione Modelli di messaggio WhatsApp con parametri di posizione in termini longitudine e latitudine per i componenti di intestazione.

Configurazione comune

Seguire questa procedura per aggiungere i frammenti di codice necessari alla funzione principale del App.java file.

Creare e gestire il messaggio del modello WhatsApp

I modelli di messaggio WhatsApp sono formati di messaggi specifici che le aziende usano per inviare notifiche o messaggi di assistenza clienti a persone che hanno accodato esplicitamente alle notifiche. I messaggi possono includere promemoria per gli appuntamenti, informazioni sulla spedizione, risoluzione dei problemi o aggiornamenti dei pagamenti. Prima di iniziare a usare Advanced messaging SDK per inviare messaggi modello, l'utente deve creare modelli necessari nella piattaforma WhatsApp Business.

Per altre informazioni sui requisiti di WhatsApp per i modelli, vedi i riferimenti all'API WhatsApp Business Platform:

Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp

Le conversazioni tra un account WhatsApp Business e un utente WhatsApp possono essere avviate in uno dei due modi seguenti:

  • L'azienda invia un messaggio modello all'utente WhatsApp.
  • L'utente WhatsApp invia qualsiasi messaggio al numero di ufficio.

Indipendentemente dalla modalità di avvio della conversazione, un'azienda può inviare messaggi modello solo fino a quando l'utente non invia un messaggio all'azienda. Solo dopo che l'utente invia un messaggio all'azienda, l'azienda può inviare sms o messaggi multimediali all'utente durante la conversazione attiva. Una volta scaduta la finestra di conversazione di 24 ore, è necessario reinizializzare la conversazione. Per altre informazioni sulle conversazioni, vedi la definizione all'indirizzo Piattaforma WhatsApp Business.

Autenticare il client

Sono disponibili alcune opzioni diverse per l'autenticazione di un client di Messaggi:

Per autenticare un client, creare un'istanza di NotificationMessagesClient o MessageTemplateClient con la stringa di connessione. Inoltre, è possibile inizializzare il client con qualsiasi client HTTP personalizzato che implementi l'interfaccia com.azure.core.http.HttpClient.

Per semplicità, questa guida introduttiva usa una stringa di connessione per l'autenticazione. Negli ambienti di produzione è consigliabile usare entità servizio.

Ottenere la stringa di connessione dalla risorsa Servizi di comunicazione di Azure nel portale di Azure. A sinistra passare alla scheda Keys. Copiare il campo Connection string per il Primary key. La stringa di connessione è nel formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando il campo

Impostare la variabile di ambiente COMMUNICATION_SERVICES_CONNECTION_STRING sul valore della stringa di connessione.
Aprire una finestra della console e immettere il comando seguente:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Per altre informazioni su come impostare una variabile di ambiente per il sistema, seguire la procedura descritta in Archiviare la stringa di connessione in una variabile di ambiente.

Per creare un'istanza di NotificationMessagesClient, aggiungere il codice seguente al metodo main:

// You can get your connection string from your resource in the Azure portal.
String connectionString = System.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING");

NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Configurare l’ID di registrazione del canale

Il GUID dell'ID di registrazione del canale è stato creato durante la registrazione del canale. È possibile cercarlo nel portale nella scheda Canali della risorsa di Servizi di comunicazione di Azure.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando la scheda ‘Canali’. L'attenzione viene posta sull'azione di copia del campo

Assegnarlo a una variabile denominata channelRegistrationId.

String channelRegistrationId = "<your channel registration id GUID>";

Configurare l’elenco dei destinatari

È necessario fornire un numero di telefono reale che ha un account WhatsApp associato. Questo account WhatsApp riceve il testo e i messaggi multimediali inviati in questa guida introduttiva. Per questa guida introduttiva, questo numero di telefono potrebbe essere il numero di telefono personale.

Il numero di telefono del destinatario non può essere il numero di telefono commerciale (ID mittente) associato alla registrazione del canale WhatsApp. L'ID mittente viene visualizzato come mittente del testo e dei messaggi multimediali inviati al destinatario.

Il numero di telefono deve includere il prefisso internazionale. Per altre informazioni sulla formattazione dei numeri di telefono, vedi la documentazione di WhatsApp sui Formati di numeri di telefono.

Nota

Nell'elenco dei destinatari è attualmente supportato un solo numero di telefono.

Creare l'elenco dei destinatari nel seguente modo:

List<String> recipientList = new ArrayList<>();
recipientList.add("<to WhatsApp phone number>");

Esempio:

// Example only
List<String> recipientList = new ArrayList<>();
recipientList.add("+14255550199");

Set up environment (Configurare l'ambiente)

Per configurare un ambiente per l'invio di messaggi, completare la procedura descritta nelle sezioni seguenti.

Prerequisito

Creare una nuova applicazione Java

Aprire un terminale o una finestra di comando e passare alla directory in cui si vuole creare l'applicazione Java. Eseguire il comando seguente per generare il progetto Java dal maven-archetype-quickstart modello.

mvn archetype:generate -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart" -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeVersion="1.4" -DinteractiveMode="false"

L'obiettivo generate crea una directory con lo stesso nome del valore artifactId. In questa directory la src/main/java directory contiene il codice sorgente del progetto, la src/test/java directory contiene l'origine di test e il pom.xml file è il project Object Model (POM).

Installare il pacchetto

Aprire il file pom.xml nell'editor di testo. Aggiungere l'elemento di dipendenza seguente al gruppo di dipendenze.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-messages</artifactId>
</dependency>

Configurare il framework dell'app

Aprire /src/main/java/com/communication/quickstart/App.java in un editor di testo, aggiungere direttive import e rimuovere l'istruzione System.out.println("Hello world!"); :

package com.communication.quickstart;

import com.azure.communication.messages.*;
import com.azure.communication.messages.models.*;

import java.util.ArrayList;
import java.util.List;
public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

Esempi di codice

Seguire questa procedura per aggiungere frammenti di codice necessari alla funzione principale del App.java file.

Elencare i modelli WhatsApp nel portale di Azure

Per visualizzare i modelli nella portale di Azure, passare alla risorsa >Servizi di comunicazione di Azure Modelli di messaggistica>avanzata.

Screenshot che mostra una risorsa Servizi di comunicazione di Azure nella portale di Azure, visualizzando la scheda Modelli di messaggistica avanzati.

Selezione di un modello per visualizzare i dettagli del modello.

Il campo Contenuto dei dettagli del modello può includere associazioni di parametri. Le associazioni di parametri possono essere indicate come:

  • Campo "format" con un valore, IMAGEad esempio .
  • Parentesi doppie che circondano un numero, ad esempio {{1}}. Il numero, indice avviato da 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio.

Screenshot che mostra i dettagli del modello.

In alternativa, puoi visualizzare e modificare tutti i modelli di account WhatsApp Business nei modelli di messaggio strumenti> account WhatsApp Manager>.

Per elencare i modelli a livello di codice, è possibile recuperare tutti i modelli per l'ID canale usando il codice seguente:

public static void getMessageTemplateWithConnectionString() {
    MessageTemplateClient templateClient =
        new MessageTemplateClientBuilder()
            .connectionString(connectionString)
            .buildClient();

    PagedIterable<MessageTemplateItem> response = templateClient.listTemplates(channelRegistrationId);

    response.stream().forEach(t -> {
        WhatsAppMessageTemplateItem template = (WhatsAppMessageTemplateItem) t ;
        System.out.println("===============================");
        System.out.println("Template Name :: "+template.getName());
        System.out.println("Template Language :: "+template.getLanguage());
        System.out.println("Template Status :: "+template.getStatus());
        System.out.println("Template Content :: "+template.getContent());
        System.out.println("===============================");
    });
    }

Inviare un messaggio modello con parametri di testo nel corpo

Se il modello non accetta parametri, non è necessario specificare valori o associazioni durante la creazione di MessageTemplate.

 /*
    * This sample shows how to send template message with below details
    * Name: sample_shipping_confirmation, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Your package has been shipped. It will be delivered in {{1}} business days."
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
private static void sendTemplateMessage() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_shipping_confirmation", "en_US");

    //Update template parameter type and value
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateText("Days", "5"));
    template.setValues(messageTemplateValues);

    //Update template parameter binding
    List<WhatsAppMessageTemplateBindingsComponent> components = new ArrayList<>();
    components.add(new WhatsAppMessageTemplateBindingsComponent("Days"));
    MessageTemplateBindings bindings =new WhatsAppMessageTemplateBindings()
        .setBody(components);
    template.setBindings(bindings);

    NotificationMessagesClient client = createClientWithTokenCredential();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
    }

Inviare un messaggio modello con il parametro media nell'intestazione

Usare MessageTemplateImage, MessageTemplateVideoo MessageTemplateDocument per definire il parametro multimediale in un'intestazione.

Definizione del modello con il parametro image media nell'intestazione:

{
  "type": "HEADER",
  "format": "VIDEO"
},

Può "format" essere su di quattro diversi tipi di supporti supportati da WhatsApp. In .NET SDK ogni tipo di supporto usa un tipo corrispondente MessageTemplateValue .

Formato Tipo MessageTemplateValue Tipo di file
IMMAGINE MessageTemplateImage png, jpg
VIDEO MessageTemplateVideo mp4
DOCUMENT MessageTemplateDocument pdf

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Esempio

sample_happy_hour_announcement sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_happy_hour_announcement.

In questo caso, l'intestazione del modello richiede un video:

{
  "type": "HEADER",
  "format": "VIDEO"
},

Il video deve essere un URL di un video mp4 ospitato.

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Il corpo del modello richiede due parametri di testo:

{
  "type": "BODY",
  "text": "Happy hour is here! 🍺😀🍸\nPlease be merry and enjoy the day. 🎉\nVenue: {{1}}\nTime: {{2}}"
},

Creare una MessageTemplateVideo e quattro MessageTemplateText variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello.

 /*
    * This sample shows how to send template message with below details
    * Name: sample_happy_hour_announcement, Language: en_US
    *  [
          {
            "type": "HEADER",
            "format": "VIDEO"
          },
          {
            "type": "BODY",
            "text": "Happy hour is here! 🍺😀🍸\nPlease be merry and enjoy the day. 🎉\nVenue: {{1}}\nTime: {{2}}"
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
private static void sendTemplateMessageWithVideo() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_happy_hour_announcement", "en_US");

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateVideo("HeaderVideo", "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"));
    messageTemplateValues.add(new MessageTemplateText("VenueInfoInBody", "Starbucks"));
    messageTemplateValues.add(new MessageTemplateText("TimeInfoInBody", "Today 2-4PM"));

    // Add parameter binding for template header in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateHeaderBindings = new ArrayList<>();
    templateHeaderBindings.add(new WhatsAppMessageTemplateBindingsComponent("HeaderVideo"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("VenueInfoInBody"));
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("TimeInfoInBody"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setHeaderProperty(templateHeaderBindings) // Set the parameter binding for template header
        .setBody(templateBodyBindings); // Set the parameter binding for template body

    template
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

Inviare un messaggio modello con pulsanti di risposta rapida

Usare MessageTemplateQuickAction per definire il payload per i pulsanti di risposta rapida e MessageTemplateQuickAction gli oggetti con i tre attributi seguenti.

Proprietà Descrizione Type
Nome Oggetto name utilizzato per cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Azione rapida textdell'opzione . string
Payload L'oggetto payload assegnato a un pulsante disponibile in una risposta di messaggio se l'utente seleziona il pulsante. string

Definizione del modello con pulsanti di risposta rapida:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Per altre informazioni sul payload nelle risposte di risposta rapida dell'utente, vedi la documentazione di WhatsApp per il callback ricevuto da un pulsante di risposta rapida.

Esempio

sample_issue_resolution sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_issue_resolution.

Il corpo del modello richiede un parametro di testo:

/*
    * This sample shows how to send template message with below details
    * Name: sample_issue_resolution, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "QUICK_REPLY",
                "text": "Yes"
              },
              {
                "type": "QUICK_REPLY",
                "text": "No"
              }
            ]
          }
        ]
* */
private static void sendTextTemplateMessageWithQuickReply() {

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateText("Name", "Arif"));
    messageTemplateValues.add(new MessageTemplateQuickAction("Yes").setPayload("Yes"));
    messageTemplateValues.add(new MessageTemplateQuickAction("No").setPayload("No"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("Name"));

    // Add parameter binding for template buttons in a list
    List<WhatsAppMessageTemplateBindingsButton> templateButtonBindings = new ArrayList<>();
    templateButtonBindings.add( new WhatsAppMessageTemplateBindingsButton(WhatsAppMessageButtonSubType.QUICK_REPLY, "Yes"));
    templateButtonBindings.add( new WhatsAppMessageTemplateBindingsButton(WhatsAppMessageButtonSubType.QUICK_REPLY, "No"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setBody(templateBodyBindings) // Set the parameter binding for template body
        .setButtons(templateButtonBindings); // Set the parameter binding for template buttons

    MessageTemplate messageTemplate = new MessageTemplate("sample_issue_resolution", "en_US")
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, messageTemplate));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

Usare MessageTemplateQuickAction per definire il suffisso URL per i pulsanti di chiamata all'azione e MessageTemplateQuickAction l'oggetto hanno i due attributi seguenti.

Proprietà Descrizione Type
Nome Oggetto name utilizzato per cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Oggetto text aggiunto all'URL. string

Pulsanti di definizione del modello:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Esempio

sample_purchase_feedback sagoma:

Questo modello di esempio aggiunge un pulsante con un collegamento URL dinamico al messaggio. Usa anche un'immagine nell'intestazione e un parametro di testo nel corpo.

Screenshot che mostra la modifica del tipo di URL nel gestore WhatsApp.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

Il modello include un pulsante URL dinamico con un parametro:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

Creare un MessageTemplateImageoggetto , uno MessageTemplateTexte una MessageTemplateQuickAction variabile. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

/*
* This sample shows how to send template message with below details
* Name: sample_purchase_feedback, Language: en_US
*  [
        {
        "type": "HEADER",
        "format": "IMAGE"
        },
        {
        "type": "BODY",
        "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
        },
        {
        "type": "FOOTER",
        "text": "This message is from an unverified business."
        },
        {
        "type": "BUTTONS",
        "buttons": [
            {
            "type": "URL",
            "text": "Take Survey",
            "url": "https://www.example.com/"
            }
        ]
        }
    ]
* */
private static void sendTemplateMessageWithImage() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_purchase_feedback", "en_US");

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateImage("HeaderImage", "https://upload.wikimedia.org/wikipedia/commons/3/30/Building92microsoft.jpg"));
    messageTemplateValues.add(new MessageTemplateText("ProductInfoInBody", "Microsoft Office"));

    // Add parameter binding for template header in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateHeaderBindings = new ArrayList<>();
    templateHeaderBindings.add(new WhatsAppMessageTemplateBindingsComponent("HeaderImage"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("ProductInfoInBody"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setHeaderProperty(templateHeaderBindings) // Set the parameter binding for template header
        .setBody(templateBodyBindings); // Set the parameter binding for template body

    template
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

Eseguire il codice

  1. Aprire la directory contenente il pom.xml file e compilare il progetto usando il mvn comando .

    mvn compile

  2. Eseguire l'app usando il comando seguente mvn:

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

Codice di esempio completo

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

  • Registrare l'account WhatsApp Business con la risorsa Servizi di comunicazione di Azure.
  • Creare un messaggio di modello WhatsApp.
  • Numero di telefono WhatsApp attivo per ricevere messaggi.
  • Node.js versioni di Active LTS e Maintenance LTS (è consigliabile 8.11.1 e 10.14.1).
  • Node.js versioni di Active LTS e Maintenance LTS (sono consigliate le versioni 8.11.1 e 10.14.1)
    • In un terminale o una finestra di comando eseguire node --version per verificare che Node.js sia installato

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Messages SDK per Javascript.

Nome della classe Descrizione
NotificationMessagesClient Si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Definisce il "chi" e il "what" del messaggio del modello che si intende inviare.

Nota

Per altre informazioni, vedere il pacchetto azure SDK per JavaScript @azure-rest/communication-messages

Tipi di modello WhatsApp supportati

Tipo di modello Descrizione
Modelli di messaggio basati su testo I modelli di messaggio WhatsApp sono formati di messaggio specifici con o senza parametri.
Modelli di messaggio basati su supporti Modelli di messaggi WhatsApp con parametri multimediali per i componenti di intestazione.
Modelli di messaggio interattivi I modelli di messaggio interattivi espandono il contenuto che è possibile inviare ai destinatari, includendo pulsanti interattivi usando l'oggetto componenti. Sono supportati sia call-to-action che risposta rapida.
Modelli di messaggio basati sulla posizione Modelli di messaggio WhatsApp con parametri di posizione in termini longitudine e latitudine per i componenti di intestazione.

Configurazione comune

Seguire questa procedura per aggiungere i frammenti di codice necessari alla funzione principale del send-messages.js file.

Creare e gestire il messaggio del modello WhatsApp

I modelli di messaggio WhatsApp sono formati di messaggi specifici che le aziende usano per inviare notifiche o messaggi di assistenza clienti a persone che hanno accodato esplicitamente alle notifiche. I messaggi possono includere promemoria per gli appuntamenti, informazioni sulla spedizione, risoluzione dei problemi o aggiornamenti dei pagamenti. Prima di iniziare a usare Advanced messaging SDK per inviare messaggi modello, l'utente deve creare modelli necessari nella piattaforma WhatsApp Business.

Per altre informazioni sui requisiti di WhatsApp per i modelli, vedi i riferimenti all'API WhatsApp Business Platform:

Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp

Le conversazioni tra un account WhatsApp Business e un utente WhatsApp possono essere avviate in uno dei due modi seguenti:

  • L'azienda invia un messaggio modello all'utente WhatsApp.
  • L'utente WhatsApp invia qualsiasi messaggio al numero di ufficio.

Indipendentemente dalla modalità di avvio della conversazione, un'azienda può inviare messaggi modello solo fino a quando l'utente non invia un messaggio all'azienda. Solo dopo che l'utente invia un messaggio all'azienda, l'azienda può inviare sms o messaggi multimediali all'utente durante la conversazione attiva. Una volta scaduta la finestra di conversazione di 24 ore, è necessario reinizializzare la conversazione. Per altre informazioni sulle conversazioni, vedi la definizione all'indirizzo Piattaforma WhatsApp Business.

Autenticare il client

Il codice seguente recupera la stringa di connessione per la risorsa da una variabile di ambiente denominata COMMUNICATION_SERVICES_CONNECTION_STRING usando il pacchetto dotenv.

Per semplicità, questa guida introduttiva usa una stringa di connessione per l'autenticazione. Negli ambienti di produzione è consigliabile usare entità servizio.

Ottenere la stringa di connessione dalla risorsa Servizi di comunicazione di Azure nel portale di Azure. A sinistra passare alla scheda Keys. Copiare il campo Connection string per il Primary key. La stringa di connessione è nel formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando il campo

Impostare la variabile di ambiente COMMUNICATION_SERVICES_CONNECTION_STRING sul valore della stringa di connessione.
Aprire una finestra della console e immettere il comando seguente:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Per altre informazioni su come impostare una variabile di ambiente per il sistema, seguire la procedura descritta in Archiviare la stringa di connessione in una variabile di ambiente.

Per creare un'istanza di NotificationClient, aggiungere il codice seguente al Main metodo :

const NotificationClient = require("@azure-rest/communication-messages").default;

// Set Connection string
const connectionString = process.env["COMMUNICATION_SERVICES_CONNECTION_STRING"];

// Instantiate the client
const client = NotificationClient(connectionString);

Configurare l’ID di registrazione del canale

Il GUID DELL'ID di registrazione del canale è stato creato durante la registrazione del canale. È possibile cercarlo nel portale nella scheda Canali della risorsa di Servizi di comunicazione di Azure.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando la scheda ‘Canali’. L'attenzione viene posta sull'azione di copia del campo

Assegnarlo a una variabile denominata channelRegistrationId.

const channelRegistrationId = "<your channel registration id GUID>";

Configurare l’elenco dei destinatari

È necessario fornire un numero di telefono reale che ha un account WhatsApp associato. Questo account WhatsApp riceve il modello, il testo e i messaggi multimediali inviati in questa guida introduttiva. Per questa guida introduttiva, questo numero di telefono potrebbe essere il numero di telefono personale.

Il numero di telefono del destinatario non può essere il numero di telefono commerciale (ID mittente) associato alla registrazione del canale WhatsApp. L'ID mittente viene visualizzato come mittente del testo e dei messaggi multimediali inviati al destinatario.

Il numero di telefono deve includere il prefisso internazionale. Per altre informazioni sulla formattazione dei numeri di telefono, vedi la documentazione di WhatsApp sui Formati di numeri di telefono.

Nota

Nell'elenco dei destinatari è attualmente supportato un solo numero di telefono.

Creare l'elenco dei destinatari nel seguente modo:

const recipientList = ["<to WhatsApp phone number>"];

Esempio:

// Example only
const recipientList = ["+14255550199"];

Configurazione

Per configurare un ambiente per l'invio di messaggi, completare la procedura descritta nelle sezioni seguenti.

Creare una nuova applicazione Node.js

  1. Creare una nuova directory per l'app e aprirla in un terminale o in una finestra di comando.

  2. Esegui il comando seguente:

    mkdir advance-messages-quickstart && cd advance-messages-quickstart

  3. Eseguire il comando seguente per creare un package.json file con le impostazioni predefinite.

    npm init -y

  4. Usare un editor di testo per creare un file denominato send-messages.js nella directory radice del progetto.

  5. Aggiungere il frammento di codice seguente al file send-messages.js.

    async function main() {
    // Quickstart code goes here.
}

main().catch((error) => {
    console.error("Encountered an error while sending message: ", error);
    process.exit(1);
});

Completare la sezione seguente per aggiungere il codice sorgente per questo esempio al send-messages.js file creato.

Installare il pacchetto

Usare il comando npm install per installare SDK di Messaggistica avanzata di Servizi di comunicazione di Azure per JavaScript.

npm install @azure-rest/communication-messages --save

L'opzione --save elenca la libreria come dipendenza nel file package.json.

Esempi di codice

Seguire questa procedura per aggiungere frammenti di codice necessari alla funzione principale del send-messages.js file.

Elencare i modelli WhatsApp nel portale di Azure

Per visualizzare i modelli nella portale di Azure, passare alla risorsa >Servizi di comunicazione di Azure Modelli di messaggistica>avanzata.

Screenshot che mostra una risorsa Servizi di comunicazione di Azure nella portale di Azure, visualizzando la scheda Modelli di messaggistica avanzati.

Selezione di un modello per visualizzare i dettagli del modello.

Il campo Contenuto dei dettagli del modello può includere associazioni di parametri. Le associazioni di parametri possono essere indicate come:

  • Campo "format" con un valore, IMAGEad esempio .
  • Parentesi doppie che circondano un numero, ad esempio {{1}}. Il numero, indice avviato da 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio.

Screenshot che mostra i dettagli del modello.

In alternativa, puoi visualizzare e modificare tutti i modelli di account WhatsApp Business nei modelli di messaggio strumenti> account WhatsApp Manager>.

Per elencare i modelli a livello di codice, è possibile recuperare tutti i modelli per l'ID canale usando il codice seguente:

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

/**
 * @summary Get Template list for a channel
 */

const MessageTemplateClient = require("@azure-rest/communication-messages").default,
  { isUnexpected } = require("@azure-rest/communication-messages");

// Load the .env file if it exists
require("dotenv").config();

async function main() {
  const connectionString = process.env.COMMUNICATION_LIVETEST_STATIC_CONNECTION_STRING || "";
  const client = MessageTemplateClient(connectionString);
  console.log("Fetch Templates...");
  const response = await client
    .path("/messages/channels/{channelId}/templates", process.env.CHANNEl_ID || "")
    .get({
      queryParameters: { maxPageSize: 2 },
    });

  if (isUnexpected(response)) {
    throw new Error("Failed to get template for the channel.");
  }

  // The paginate helper creates a paged async iterator using metadata from the first page.
  const items = paginate(client, response);

  // We get an PageableAsyncIterator so we need to do `for await`.
  for await (const item of items) {
    console.log(JSON.stringify(item, null, 2));
  }
}

main().catch((error) => {
  console.error("Encountered an error while sending message: ", error);
  throw error;
});

Inviare un messaggio modello con parametri di testo nel corpo

sample_shipping_confirmation sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_shipping_confirmation.

In questo esempio il corpo del modello ha un parametro:

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

I parametri vengono definiti con i values valori e bindings le associazioni. Utilizzare i valori e i binding per assemblare l'oggetto template .

 /*
    * This sample shows how to send template message with below details
    * Name: sample_shipping_confirmation, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Your package has been shipped. It will be delivered in {{1}} business days."
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

/**
 * @summary Use AAD token credentials when sending a whatsapp template message.
 */

const { isNode } = require("@azure/core-util");
const { ClientSecretCredential, DefaultAzureCredential } = require("@azure/identity");
const NotificationClient = require("@azure-rest/communication-messages").default,
  { isUnexpected } = require("@azure-rest/communication-messages");

// Load the .env file if it exists
require("dotenv").config();

async function main() {
  // You will need to set this environment variable or edit the following values
  const endpoint = process.env.ACS_URL || "";

  // Azure AD Credential information is required to run this sample:
  if (
    !process.env.AZURE_TENANT_ID ||
    !process.env.AZURE_CLIENT_ID ||
    !process.env.AZURE_CLIENT_SECRET
  ) {
    console.error(
      "Azure AD authentication information not provided, but it is required to run this sample. Exiting.",
    );
    return;
  }

  // get credentials
  const credential = isNode
    ? new DefaultAzureCredential()
    : new ClientSecretCredential(
        process.env.AZURE_TENANT_ID,
        process.env.AZURE_CLIENT_ID,
        process.env.AZURE_CLIENT_SECRET,
      );

  const client = NotificationClient(endpoint, credential);

  const DaysTemplateValue = {
    kind: "text",
    name: "Days",
    text: "5",
  };

  const templateBindings = {
    kind: "whatsApp",
    body: [
      {
        refValue: "Days",
      },
    ],
  };

  const template = {
    name: "sample_shipping_confirmation",
    language: "en_US",
    bindings: templateBindings,
    values: [DaysTemplateValue],
  };

  const result = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
      channelRegistrationId: process.env.CHANNEL_ID || "",
      to: [process.env.RECIPIENT_PHONE_NUMBER || ""],
      kind: "template",
      template: template,
    },
  });

  console.log("Response: " + JSON.stringify(result, null, 2));

  if (isUnexpected(result)) {
    throw new Error("Failed to send message");
  }

  const response = result;
  response.body.receipts.forEach((receipt) => {
    console.log("Message sent to:" + receipt.to + " with message id:" + receipt.messageId);
  });
}

main().catch((error) => {
  console.error("Encountered an error while sending message: ", error);
  throw error;
});

module.exports = { main };

Eseguire il codice

Usare il comando node per eseguire il codice aggiunto al file send-messages.js.

node ./send-messages.js

Codice di esempio completo

Trovare il codice finalizzato per questo esempio in GitHub.

Prerequisiti

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità dell’SDK Messages di Servizi di comunicazione di Azure per Python.

Nome della classe Descrizione
NotificationMessagesClient Si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Definisce il "chi" e il "what" del messaggio del modello che si intende inviare.

Nota

Per altre informazioni, impostare i messaggi di riferimento di Azure SDK per Python Package.

Tipi di modello WhatsApp supportati

Tipo di modello Descrizione
Modelli di messaggio basati su testo I modelli di messaggio WhatsApp sono formati di messaggio specifici con o senza parametri.
Modelli di messaggio basati su supporti Modelli di messaggi WhatsApp con parametri multimediali per i componenti di intestazione.
Modelli di messaggio interattivi I modelli di messaggio interattivi espandono il contenuto che è possibile inviare ai destinatari, includendo pulsanti interattivi usando l'oggetto componenti. Sono supportati sia call-to-action che risposta rapida.
Modelli di messaggio basati sulla posizione Modelli di messaggio WhatsApp con parametri di posizione in termini longitudine e latitudine per i componenti di intestazione.

Configurazione comune

Seguire questa procedura per aggiungere i frammenti di codice necessari al messages-quickstart.py programma Python.

Creare e gestire il messaggio del modello WhatsApp

I modelli di messaggio WhatsApp sono formati di messaggi specifici che le aziende usano per inviare notifiche o messaggi di assistenza clienti a persone che hanno accodato esplicitamente alle notifiche. I messaggi possono includere promemoria per gli appuntamenti, informazioni sulla spedizione, risoluzione dei problemi o aggiornamenti dei pagamenti. Prima di iniziare a usare Advanced messaging SDK per inviare messaggi modello, l'utente deve creare modelli necessari nella piattaforma WhatsApp Business.

Per altre informazioni sui requisiti di WhatsApp per i modelli, vedi i riferimenti all'API WhatsApp Business Platform:

Autenticare il client

L'invio dei messaggi viene eseguito tramite NotificationMessagesClient. NotificationMessagesClient viene autenticato usando la stringa di connessione acquisita dalla risorsa di Servizi di comunicazione di Azure nel portale di Azure. Per altre informazioni sulle stringhe di connessione, vedere access-your-connection-strings-and-service-endpoints.

Ottenere l'stringa di connessione delle risorse di comunicazione di Azure da portale di Azure come indicato nello screenshot. A sinistra passare alla scheda Keys. Copiare il campo Connection string per la chiave primaria. La stringa di connessione è nel formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando il campo

Impostare la variabile di ambiente COMMUNICATION_SERVICES_CONNECTION_STRING sul valore della stringa di connessione.
Aprire una finestra della console e immettere il comando seguente:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Dopo l'aggiunta della variabile di ambiente potrebbe essere necessario riavviare eventuali programmi in esecuzione che necessitano di leggere la variabile di ambiente, inclusa la finestra della console. Se ad esempio si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Per altre informazioni su come impostare una variabile di ambiente per il sistema, seguire la procedura descritta in Archiviare la stringa di connessione in una variabile di ambiente.

    # Get a connection string to our Azure Communication Services resource.
    connection_string = os.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING")
    
    def send_template_message(self):
        from azure.communication.messages import NotificationMessagesClient

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

Configurare l’ID di registrazione del canale

È stato creato il GUID dell'ID registrazione canale durante la registrazione del canale. Trovarlo nel portale nella scheda Canali della risorsa Servizi di comunicazione di Azure.

Screenshot che mostra una risorsa di Servizi di comunicazione di Azure nel portale di Azure, visualizzando la scheda ‘Canali’. L'attenzione viene posta sull'azione di copia del campo

Assegnarlo a una variabile denominata channelRegistrationId.

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

Configurare l’elenco dei destinatari

Devi fornire un numero di telefono attivo associato a un account WhatsApp. Questo account WhatsApp riceve il modello, il testo e i messaggi multimediali inviati in questa guida introduttiva.

Per questo esempio, è possibile usare il numero di telefono personale.

Il numero di telefono del destinatario non può essere il numero di telefono commerciale (ID mittente) associato alla registrazione del canale WhatsApp. L'ID mittente viene visualizzato come mittente del testo e dei messaggi multimediali inviati al destinatario.

Il numero di telefono deve includere il codice paese. Per altre informazioni sulla formattazione dei numeri di telefono, vedi la documentazione di WhatsApp per formati di numeri di telefono.

Nota

Nell'elenco dei destinatari è attualmente supportato un solo numero di telefono.

Configurare l'elenco dei destinatari nel seguente modo:

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

Esempio di utilizzo:

    # Example only
    to=[self.phone_number],

Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp

Le conversazioni tra un account WhatsApp Business e un utente WhatsApp possono essere avviate in uno dei due modi seguenti:

  • L'azienda invia un messaggio modello all'utente WhatsApp.
  • L'utente WhatsApp invia qualsiasi messaggio al numero di ufficio.

Un'azienda non può avviare una conversazione interattiva. Un'azienda può inviare un messaggio interattivo solo dopo aver ricevuto un messaggio dall'utente. L'azienda può inviare messaggi interattivi solo all'utente durante la conversazione attiva. Una volta scaduta la finestra di conversazione di 24 ore, solo l'utente può riavviare la conversazione interattiva. Per altre informazioni sulle conversazioni, vedi la definizione in WhatsApp Business Platform.

Per avviare una conversazione interattiva dal tuo account WhatsApp personale, invia un messaggio al tuo numero di azienda (ID mittente).

Una conversazione WhatsApp visualizzata sul Web che mostra un messaggio utente inviato al numero di account WhatsApp Business.

Set up environment (Configurare l'ambiente)

Creare una nuova applicazione Python

In una finestra del terminale o della console creare una nuova cartella per l'applicazione e aprirla.

mkdir messages-quickstart && cd messages-quickstart

Installare il pacchetto

Usare la libreria client messaggi di comunicazione di Azure per Python 1.1.0 o versione successiva.

Da un prompt della console eseguire il comando seguente:

pip install azure-communication-messages

Per InteractiveMessages, Reazioni e Adesivi, usare la versione beta seguente:

pip install azure-communication-messages==1.2.0b1

Configurare il framework dell'app

Creare un nuovo file denominato messages-quickstart.py e aggiungere la struttura del programma di base.

type nul > messages-quickstart.py

Struttura dei programmi di base

import os

class MessagesQuickstart(object):
    print("Azure Communication Services - Advanced Messages SDK Quickstart")

if __name__ == '__main__':
    messages = MessagesQuickstart()

Struttura dei programmi di base

import os

class MessagesQuickstart(object):
    print("Azure Communication Services - Advanced Messages SDK Quickstart")

if __name__ == '__main__':
    messages = MessagesQuickstart()

Esempi di codice

Seguire questa procedura per aggiungere i frammenti di codice necessari al messages-quickstart.py programma Python.

Elencare i modelli di WhatsApp in portale di Azure

È possibile visualizzare i modelli nella portale di Azure passando alla risorsa >del Servizio di comunicazione di Azure Modelli di messaggistica>avanzata.

Screenshot che mostra una risorsa Servizi di comunicazione di Azure nella portale di Azure, visualizzando la scheda

Selezionare un modello per visualizzare i dettagli del modello.

Il content campo dei dettagli del modello può includere associazioni di parametri. Le associazioni di parametri possono essere indicate come:

  • Campo format con un valore, IMAGEad esempio .
  • Parentesi doppie che circondano un numero, ad esempio {{1}}. Il numero, indice avviato da 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio.

Screenshot che mostra i dettagli del modello.

In alternativa, puoi visualizzare e modificare tutti i modelli del tuo account WhatsApp Business nei modelli di messaggio strumenti> account WhatsApp Manager>.

Per elencare i modelli a livello di codice, è possibile recuperare tutti i modelli per l'ID canale come indicato di seguito:

def get_templates_list(self):

    from azure.communication.messages import MessageTemplateClient
    message_template_client = MessageTemplateClient.from_connection_string(self.connection_string)
    # calling send() with whatsapp message details
    template_list = message_template_client.list_templates(self.channel_id)
    count_templates = len(list(template_list))
    print("Successfully retrieved {} templates from channel_id {}.".format(count_templates, self.channel_id))

Inviare un messaggio modello senza parametri

Se il modello non richiede parametri, non è necessario specificare i valori o le associazioni durante la creazione di MessageTemplate.

Esempio

l'oggetto sample_template non ha parametri.

Screenshot che mostra i dettagli del modello per il modello denominato sample_template.

Assemblare l'oggetto MessageTemplate facendo riferimento al nome e alla lingua del modello di destinazione.

input_template: MessageTemplate = MessageTemplate(name="gathering_invitation", language="ca")  # Name of the WhatsApp Template

Inviare un messaggio modello con parametri di testo nel corpo

Usare MessageTemplateText per definire i parametri nel corpo indicato con parentesi quadre doppie che circondano un numero, ad esempio {{1}}. Il numero, indice avviato da 1, indica l'ordine in cui devono essere specificati i valori di associazione per creare il modello di messaggio. Il tentativo di includere parametri non nel modello non è valido.

Definizione del modello con due parametri:

{
  "type": "BODY",
  "text": "Message with two parameters: {{1}} and {{2}}"
}

Esempi

sample_shipping_confirmation sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_shipping_confirmation.

In questo esempio il corpo del modello ha un parametro:

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

Definire i parametri usando i MessageTemplateValue valori e MessageTemplateWhatsAppBindings le associazioni. Usare i valori e le associazioni per assemblare .MessageTemplate

# Setting template options
templateName = "sample_shipping_confirmation"
templateLanguage = "en_us" 
shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
threeDays = MessageTemplateText(name="threeDays", text="3")
bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=threeDays.name)])
shippingConfirmationTemplate.bindings = bindings
shippingConfirmationTemplate.template_values=[threeDays]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
)

Inviare un messaggio modello con il parametro media nell'intestazione

Usare MessageTemplateImage, MessageTemplateVideoo MessageTemplateDocument per definire il parametro multimediale in un'intestazione.

Definizione del modello con il parametro image media nell'intestazione:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Può format avere diversi tipi di supporti supportati da WhatsApp. In .NET SDK ogni tipo di supporto usa un tipo corrispondente MessageTemplateValue .

Formato Tipo MessageTemplateValue Tipo di file
IMMAGINE MessageTemplateImage png, jpg
VIDEO MessageTemplateVideo mp4
DOCUMENT MessageTemplateDocument pdf

Per altre informazioni sui tipi di supporti supportati e sui limiti di dimensioni, vedi la documentazione di WhatsApp per i supporti di messaggio.

Esempi

sample_movie_ticket_confirmation sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_movie_ticket_confirmation.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede quattro parametri di testo:

{
  "type": "BODY",
  "text": "Your ticket for *{{1}}*\n*Time* - {{2}}\n*Venue* - {{3}}\n*Seats* - {{4}}"
},

Creare una MessageTemplateImage e quattro MessageTemplateText variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello.

 # Setting template options
templateName = "sample_movie_ticket_confirmation"
templateLanguage = "en_us" 
imageUrl = "https://aka.ms/acsicon1"
sample_movie_ticket_confirmation: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
image = MessageTemplateImage(name="image", url=imageUrl)
title = MessageTemplateText(name="title", text="Contoso")
time = MessageTemplateText(name="time", text="July 1st, 2023 12:30PM")
venue = MessageTemplateText(name="venue", text="Southridge Video")
seats = MessageTemplateText(name="seats", text="Seat 1A")

bindings = WhatsAppMessageTemplateBindings(header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                            body=[WhatsAppMessageTemplateBindingsComponent(ref_value=title.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=time.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=venue.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=seats.name)])
sample_movie_ticket_confirmation.bindings = bindings
sample_movie_ticket_confirmation.template_values=[image,title,time,venue,seats]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_ticket_confirmation)

Inviare un messaggio modello con pulsanti di risposta rapida

Usare MessageTemplateQuickAction per definire il payload per i pulsanti di risposta rapida e MessageTemplateQuickAction gli oggetti con i tre attributi seguenti.

Proprietà Descrizione Type
Nome Oggetto name da cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Azione rapida textdell'opzione . string
Payload L'oggetto payload assegnato a un pulsante disponibile in una risposta di messaggio se l'utente seleziona il pulsante. string

Definizione del modello con pulsanti di risposta rapida:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Per altre informazioni sul payload nelle risposte di risposta rapida dell'utente, vedi la documentazione di WhatsApp per il callback ricevuto da un pulsante di risposta rapida.

Esempio

sample_issue_resolution sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_issue_resolution.

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
},

Il modello include due pulsanti di risposta precompilato e YesNo.

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

Creare una MessageTemplateText e due MessageTemplateQuickAction variabili. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

# Setting template options
templateName = "sample_issue_resolution"
templateLanguage = "en_us" 
shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
name = MessageTemplateText(name="first", text="Joe")
yes = MessageTemplateQuickAction(name="Yes", payload="Joe said yes")
no = MessageTemplateQuickAction(name="No", payload = "Joe said no")
bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)])
bindings.buttons = [WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=yes.name),
                    WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=no.name)]
shippingConfirmationTemplate.bindings = bindings
shippingConfirmationTemplate.template_values=[name,yes,no]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
)

Inviare un messaggio modello con la posizione nell'intestazione

Usare MessageTemplateLocation per definire il parametro location in un'intestazione.

Definizione del modello per il componente di intestazione che richiede la posizione come:

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

può format richiedere tipi di supporti diversi. In .NET SDK ogni tipo di supporto usa un tipo corrispondente MessageTemplateValue .

Proprietà Descrizione Tipo
ADDRESS Indirizzo visualizzato dopo il NAME valore, sotto la mappa generica nella parte superiore del messaggio. string
LATITUDE Latitudine della posizione. double
LONGITUDE Longitudine della posizione. double
LOCATIONNAME Testo visualizzato immediatamente sotto la mappa generica nella parte superiore del messaggio. string

Per altre informazioni sui modelli basati sulla posizione, vedi la documentazione di WhatsApp per i supporti di messaggio.

Esempio

sample_movie_location sagoma:

Screenshot che mostra i dettagli del modello per il modello denominato sample_location_template.

Assembly del modello di messaggio basato sul percorso:

 # Setting template options
        templateName = "sample_movie_location"
        templateLanguage = "en_us" 
        sample_movie_location: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        location = MessageTemplateLocation(name="location", location_name="Pablo Morales",
                                            address="1 Hacker Way, Menlo Park, CA 94025",
                                            latitude=37.483307,longitude=122.148981)
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=location.name)])
        sample_movie_location.bindings = bindings
        sample_movie_location.template_values=[name,location]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_location)

Usare MessageTemplateQuickAction per definire il suffisso URL per i pulsanti di chiamata all'azione e MessageTemplateQuickAction l'oggetto hanno i due attributi seguenti.

Proprietà Descrizione Type
Nome Oggetto name utilizzato per cercare il valore in MessageTemplateWhatsAppBindings. string
Testo Oggetto text aggiunto all'URL. string

Pulsanti di definizione del modello:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

L'ordine in cui i pulsanti vengono visualizzati nella definizione del modello deve corrispondere all'ordine in cui i pulsanti vengono definiti durante la creazione dei binding con MessageTemplateWhatsAppBindings.

Esempio

sample_purchase_feedback sagoma:

Questo modello di esempio aggiunge un pulsante con un collegamento URL dinamico al messaggio. Usa anche un'immagine nell'intestazione e un parametro di testo nel corpo. Creare modelli di pulsanti di chiamata all'azione con Dynamic tipo di URL per View website il tipo di azione.

Screenshot che mostra la modifica del tipo di URL nel gestore WhatsApp.

In questo esempio l'intestazione del modello richiede un'immagine:

{
  "type": "HEADER",
  "format": "IMAGE"
},

Il corpo del modello richiede un parametro di testo:

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

Il modello include un pulsante URL dinamico con un parametro:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

Creare un MessageTemplateImageoggetto , uno MessageTemplateTexte una MessageTemplateQuickAction variabile. Assemblare quindi l'elenco di MessageTemplateValue e MessageTemplateWhatsAppBindings specificando i parametri nell'ordine in cui i parametri vengono visualizzati nel contenuto del modello. L'ordine è importante anche quando si definiscono i pulsanti dei binding.

# Setting template options
        templateName = "sample_purchase_feedback"
        templateLanguage = "en_us"
        imageUrl = "https://aka.ms/acsicon1" 
        sample_purchase_feedback: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        image = MessageTemplateImage(name="image", url=imageUrl)
        uri_to_click = MessageTemplateQuickAction(name="url", text="questions")

        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                    buttons=[WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.URL,
                                                    ref_value=uri_to_click.name)])
        sample_purchase_feedback.bindings = bindings
        sample_purchase_feedback.template_values=[name, image, uri_to_click]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_purchase_feedback)

Esempio completo

import os
import sys

sys.path.append("..")

class SendWhatsAppTemplateMessageSample(object):

    connection_string = os.getenv("COMMUNICATION_SAMPLES_CONNECTION_STRING")
    phone_number = os.getenv("RECIPIENT_PHONE_NUMBER")
    channel_id = os.getenv("WHATSAPP_CHANNEL_ID")

    def send_template_message_without_parameters(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TemplateNotificationContent , MessageTemplate )

        # client creation
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_template: MessageTemplate = MessageTemplate(
            name="<<TEMPLATE_NAME>>",
            language="<<LANGUAGE>>")
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            template=input_template
        )

        # calling send() with WhatsApp template details.
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

    def send_template_message_with_parameters(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_shipping_confirmation"
        templateLanguage = "en_us" 
        shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        threeDays = MessageTemplateText(name="threeDays", text="3")
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=threeDays.name)])
        shippingConfirmationTemplate.bindings = bindings
        shippingConfirmationTemplate.template_values=[threeDays]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
        )

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp text parameters Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_media(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateImage)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_movie_ticket_confirmation"
        templateLanguage = "en_us" 
        imageUrl = "https://aka.ms/acsicon1"
        sample_movie_ticket_confirmation: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        image = MessageTemplateImage(name="image", url=imageUrl)
        title = MessageTemplateText(name="title", text="Contoso")
        time = MessageTemplateText(name="time", text="July 1st, 2023 12:30PM")
        venue = MessageTemplateText(name="venue", text="Southridge Video")
        seats = MessageTemplateText(name="seats", text="Seat 1A")

        bindings = WhatsAppMessageTemplateBindings(header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                   body=[WhatsAppMessageTemplateBindingsComponent(ref_value=title.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=time.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=venue.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=seats.name)])

        sample_movie_ticket_confirmation.bindings = bindings
        sample_movie_ticket_confirmation.template_values=[image,title,time,venue,seats]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_ticket_confirmation)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp media parameters in templated message header with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_buttons(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateQuickAction, WhatsAppMessageTemplateBindingsButton, WhatsAppMessageButtonSubType)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_issue_resolution"
        templateLanguage = "en_us" 
        shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        yes = MessageTemplateQuickAction(name="Yes", payload="Joe said yes")
        no = MessageTemplateQuickAction(name="No", payload = "Joe said no")
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)])
        bindings.buttons = [WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=yes.name),
                            WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=no.name)]
        shippingConfirmationTemplate.bindings = bindings
        shippingConfirmationTemplate.template_values=[name,yes,no]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
        )

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Quick Button Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_location(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateLocation)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_movie_location"
        templateLanguage = "en_us" 
        sample_movie_location: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        location = MessageTemplateLocation(name="location", location_name="Pablo Morales",
                                            address="1 Hacker Way, Menlo Park, CA 94025",
                                            latitude=37.483307,longitude=122.148981)
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=location.name)])
        sample_movie_location.bindings = bindings
        sample_movie_location.template_values=[name,location]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_location)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Location Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_call_to_action(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateQuickAction, MessageTemplateImage, WhatsAppMessageTemplateBindingsButton,
        WhatsAppMessageButtonSubType)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_purchase_feedback"
        templateLanguage = "en_us"
        imageUrl = "https://aka.ms/acsicon1" 
        sample_purchase_feedback: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        image = MessageTemplateImage(name="image", url=imageUrl)
        uri_to_click = MessageTemplateQuickAction(name="url", text="questions")

        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                    buttons=[WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.URL,
                                                                                                    ref_value=uri_to_click.name)])
        sample_purchase_feedback.bindings = bindings
        sample_purchase_feedback.template_values=[name, image, uri_to_click]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_purchase_feedback)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Call To Action Templated Message with message id {} was successfully sent to {}"
        .format(response.message_id, response.to))

if __name__ == "__main__":
    sample = SendWhatsAppTemplateMessageSample()
    sample.send_template_message_without_parameters()
    sample.send_template_message_with_parameters()
    sample.send_template_message_with_buttons()
    sample.send_template_message_with_location()
    sample.send_template_message_with_call_to_action()

Eseguire il codice

Per eseguire il codice, assicurarsi di essere nella directory in cui si trova il file messages-quickstart.py.

python messages-quickstart.py

Azure Communication Services - Advanced Messages Quickstart
WhatsApp Templated Message with message id <<GUID>> was successfully sent to <<ToRecipient>>

Passaggi successivi