Condividi tramite

Guida introduttiva: Inviare messaggi WhatsApp con Messaggistica avanzata

  • Articolo

Servizi di comunicazione di Azure consente di inviare e ricevere messaggi WhatsApp. In questa guida introduttiva, iniziare a integrare l'app con Azure Communication Advanced Messages SDK e iniziare a inviare/ricevere messaggi WhatsApp. Le procedure illustrate in questa guida di avvio rapido comportano l'addebito di qualche centesimo (USD) o meno nell'account Azure.

Prerequisiti

Configurazione

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 di 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 - Send WhatsApp Messages");

            // Quickstart code goes here
        }
    }
}

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

using Azure.Communication.Messages;

Modello a oggetti

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

Nome Descrizione
NotificationMessagesClient Questa classe si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Questa classe definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Questa classe definisce il "chi" e il "cosa" del messaggio del modello che si intende inviare.
TextNotificationContent Questa classe definisce "chi" e "cosa" del messaggio di testo che si intende inviare.
MediaNotificationContent Questa classe definisce il "chi" e il "cosa" del messaggio multimediale che si intende inviare.

Esempi di codice

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

Autenticare il client

NotificationMessagesClient viene utilizzata per eseguire la connessione alla risorsa Servizi di comunicazione di Azure.

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

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.

var channelRegistrationId = new Guid("<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:

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.

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.

(Opzione 1) Avviare una conversazione dall'azienda - Inviare un messaggio modello

Avviare una conversazione inviando un messaggio modello.

Prima di tutto, creare un MessageTemplate usando i valori per un modello.

Nota

Per verificare quali modelli sono disponibili, vedere le istruzioni in Elencare i modelli. Se non si dispone di un modello da usare, procedere con l’opzione 2.

Ecco la creazione di MessageTemplate usando un modello predefinito, sample_template.
Se sample_template non è disponibile, passare all'opzione 2. Per gli utenti avanzati, vedere la pagina Modelli per comprendere come inviare un modello diverso con l'opzione 1.

Messages SDK consente a Contoso di inviare messaggi WhatsApp modello agli utenti di WhatsApp. Per inviare un messaggio di modello, è necessario:

// Assemble the template content
string templateName = "sample_template";
string templateLanguage = "en_us";
var messageTemplate = new MessageTemplate(templateName, templateLanguage);

Per altri esempi su come assemblare MessageTemplate e creare un modello personalizzato, vedere la risorsa seguente:

Per ulteriori requisiti di WhatsApp sui modelli, fai riferimento alle informazioni di riferimento sull'API WhatsApp Business Platform:

Assemblare quindi inviare il messaggio modello:

// Assemble template message
var templateContent = 
    new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);

// Send template message
Response<SendMessageResult> sendTemplateMessageResult = 
    await notificationMessagesClient.SendAsync(templateContent);

Ora, l'utente deve rispondere al messaggio del modello. Dall'account utente WhatsApp, rispondi al messaggio del modello ricevuto dall'account WhatsApp Business. Il contenuto del messaggio è irrilevante per questo scenario.

Importante

Prima di poter recapitare il testo o messaggio multimediale al destinatario, il destinatario deve rispondere al messaggio modello per avviare la conversazione.

(Opzione 2) Iniziare una conversazione dall’utente

L'altra opzione per avviare una conversazione tra un account WhatsApp Business e un utente WhatsApp consiste nell'avviare la conversazione. A tale scopo, inviare un messaggio dall’account WhatsApp personale al tuo numero business (ID mittente).

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

Inviare un SMS a un utente WhatsApp

Messages SDK consente a Contoso di inviare sms WhatsApp, che ha avviato gli utenti di WhatsApp. Per inviare un messaggio, è necessario:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

In questo esempio rispondiamo all'utente WhatsApp con il testo "Grazie per il tuo feedback.\n Da SDK messaggi di notifica".

Assemblare e inviare l’SMS:

// Assemble text message
var textContent = 
    new TextNotificationContent(channelRegistrationId, recipientList, "Thanks for your feedback.\n From Notification Messaging SDK");

// Send text message
Response<SendMessageResult> sendTextMessageResult = 
    await notificationMessagesClient.SendAsync(textContent);

Inviare un messaggio multimediale a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi WhatsApp multimediali agli utenti di WhatsApp. Per inviare un messaggio multimediale incorporato, sono necessari:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Importante

A partire dall'SDK versione 1.1.0, MediaNotificationContent è deprecato per le immagini. È consigliabile usare per l'invio ImageNotificationContent di immagini ed esplorare altre classi specifiche del contenuto per altri tipi multimediali, ad DocumentNotificationContentesempio , VideoNotificationContente AudioNotificationContent.

Di seguito sono riportati frammenti di codice di esempio per l'invio di diversi tipi di messaggi multimediali, tra cui immagini, documenti, video e file audio.

Invio di contenuto di un'immagine

Assemblare il messaggio di immagine:

var imageLink = new Uri("https://example.com/image.jpg");
var imageNotificationContent = new ImageNotificationContent(channelRegistrationId, recipientList, imageLink)  
{  
    Caption = "Check out this image."  
};

Inviare il messaggio di immagine:

var imageResponse = await notificationMessagesClient.SendAsync(imageNotificationContent);

Invio di un documento

Assemblare il contenuto del documento:

var documentLink = new Uri("https://example.com/document.pdf");
var documentNotificationContent = new DocumentNotificationContent(channelRegistrationId, recipientList, documentLink)  
{  
    Caption = "Check out this document.",  
    FileName = "document.pdf"  
};

Inviare il messaggio del documento:

var documentResponse = await notificationMessagesClient.SendAsync(documentNotificationContent);

Invio di contenuto video

Assemblare il video message:

var videoLink = new Uri("https://example.com/video.mp4");
var videoNotificationContent = new VideoNotificationContent(channelRegistrationId, recipientList, videoLink)  
{  
    Caption = "Check out this video."  
};

Inviare il video message:

var videoResponse = await notificationMessagesClient.SendAsync(videoNotificationContent);

Invio di contenuto audio

Assemblare il messaggio audio:

var audioLink = new Uri("https://example.com/audio.mp3");
var audioNotificationContent = new AudioNotificationContent(channelRegistrationId, recipientList, audioLink);

Inviare il messaggio audio:

var audioResponse = await notificationMessagesClient.SendAsync(audioNotificationContent);

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 ha una conversazione attiva, ai fini di questa guida introduttiva, è necessario 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 completo in codice di esempio richiede l'input manuale dell'utente prima di inviare il messaggio successivo.

Se ha esito positivo, ricevi tre messaggi sull'account WhatsApp dell'utente.

  1. Per compilare il codice, premere CTRL+F7.
  2. Per eseguire il programma senza eseguire il debug, premere CTRL+F5.

Codice di esempio completo

using System;
using System.Collections.Generic;
using System.Linq;
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 - Send WhatsApp 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>" };

            // Send sample template sample_template
            string templateName = "sample_template";
            string templateLanguage = "en_us";
            MessageTemplate sampleTemplate = new MessageTemplate(templateName, templateLanguage);
            TemplateNotificationContent templateContent = 
                new TemplateNotificationContent(channelRegistrationId, recipientList, sampleTemplate);
            Response<SendMessageResult> sendTemplateMessageResult = 
                await notificationMessagesClient.SendAsync(templateContent);

            PrintResult(sendTemplateMessageResult);
            Console.WriteLine("Template message sent.\nWait until the WhatsApp user responds " +
                "to the template message, then press any key to continue.\n");
            Console.ReadKey();

            // Send a text message
            string messageText = "Thanks for your feedback.";
            TextNotificationContent textContent =
                new TextNotificationContent(channelRegistrationId, recipientList, messageText);
            Response<SendMessageResult> sendTextMessageResult =
                await notificationMessagesClient.SendAsync(textContent);

            PrintResult(sendTextMessageResult);
            Console.WriteLine($"Text message sent to my phoneNumber.\nPress any key to continue.\n");
            Console.ReadKey();

            // Send a media message
            Uri uri = new Uri("https://aka.ms/acsicon1");
            ImageNotificationContent imageContent =
                new ImageNotificationContent(channelRegistrationId, recipientList, uri);
            Response<SendMessageResult> sendMediaMessageResult =
                await notificationMessagesClient.SendAsync(imageContent);

            PrintResult(sendMediaMessageResult);
            Console.WriteLine("Media message sent.\nPress any key to exit.\n");
            Console.ReadKey();
        }

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

Prerequisiti

Configurazione

Per configurare un ambiente per l'invio di messaggi, seguire questa procedura nelle sezioni seguenti.

Creare una nuova applicazione Java

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

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 directory src/main/java contiene il codice sorgente del progetto, la directory src/test/java contiene l'origine di test e il file pom.xml è il modello a oggetti del progetto (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>
    <version>1.0.0</version>
</dependency>

Configurare il framework dell'app

Aprire /src/main/java/com/communication/quickstart/App.java in un editor di testo, aggiungere le 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.
    }
}

Modello a oggetti

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

Nome Descrizione
NotificationMessagesClientBuilder Questa classe crea il client di messaggi di notifica. È possibile fornirla con un endpoint e le credenziali.
NotificationMessagesClient Questa classe è necessaria per inviare messaggi WhatsApp e scaricare file multimediali.
NotificationMessagesAsyncClient Questa classe è necessaria per inviare messaggi WhatsApp e scaricare file multimediali in modo asincrono.
SendMessageResult Questa classe contiene il risultato del servizio di messaggistica avanzata per l'invio del messaggio di notifica.
MessageTemplateClientBuilder Questa classe crea il client del modello di messaggio. È possibile fornirla con un endpoint e le credenziali.
MessageTemplateClient Classe necessaria per ottenere l’elenco dei modelli WhatsApp.
MessageTemplateAsyncClient Classe necessaria per ottenere l’elenco dei modelli WhatsApp in modo asincrono.

Esempi di codice

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

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");

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.

(Opzione 1) Avviare una conversazione dall'azienda - Inviare un messaggio modello

Avviare una conversazione inviando un messaggio modello.

Prima di tutto, creare un MessageTemplate usando i valori per un modello.

Nota

Per verificare quali modelli sono disponibili, vedere le istruzioni in Elencare i modelli. Se non si dispone di un modello da usare, procedere con l’opzione 2.

Ecco la creazione di MessageTemplate usando un modello predefinito, sample_template.
Se sample_template non è disponibile, passare all'opzione 2. Per gli utenti avanzati, vedere la pagina Modelli per comprendere come inviare un modello diverso con l'opzione 1.

Messages SDK consente a Contoso di inviare messaggi WhatsApp modello agli utenti di WhatsApp. Per inviare messaggi modello sotto i dettagli sono necessari:

// Assemble the template content
String templateName = "sample_template";
String templateLanguage = "en_us";
MessageTemplate messageTemplate = new MessageTemplate(templateName, templateLanguage);

// Assemble template message
TemplateNotificationContent templateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);

// Send template message
SendMessageResult templateMessageResult = notificationClient.send(templateContent);

// Process result
for (MessageReceipt messageReceipt : templateMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Ora, l'utente deve rispondere al messaggio del modello. Dall'account utente WhatsApp, rispondi al messaggio del modello ricevuto dall'account WhatsApp Business. Il contenuto del messaggio è irrilevante per questo scenario.

Importante

Prima di poter recapitare il testo o messaggio multimediale al destinatario, il destinatario deve rispondere al messaggio modello per avviare la conversazione.

(Opzione 2) Iniziare una conversazione dall’utente

L'altra opzione per avviare una conversazione tra un account WhatsApp Business e un utente WhatsApp consiste nell'avviare la conversazione. A tale scopo, inviare un messaggio dall’account WhatsApp personale al tuo numero business (ID mittente).

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

Inviare un SMS a un utente WhatsApp

Messages SDK consente a Contoso di inviare SMS WhatsApp, che ha avviato gli utenti di WhatsApp. Per i inviare gli SMS sono necessari i seguenti dettagli:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

In questo esempio rispondiamo all'utente WhatsApp con il testo "Grazie per il tuo feedback.\n Da SDK messaggi di notifica".

Assemblare e inviare l’SMS:

// Assemble text message
TextNotificationContent textContent = new TextNotificationContent(channelRegistrationId, recipientList, "“Thanks for your feedback.\n From Notification Messaging SDK");

// Send text message
SendMessageResult textMessageResult = notificationClient.send(textContent);

// Process result
for (MessageReceipt messageReceipt : textMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Inviare un messaggio multimediale a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi multimediali (immagine, video, audio o documento) agli utenti di WhatsApp. Per inviare un messaggio multimediale incorporato, sono necessari:

Importante

Per inviare un messaggio multimediale a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Importante

A partire dall'SDK versione 1.1.0, MediaNotificationContent è deprecato per le immagini. È consigliabile usare per l'invio ImageNotificationContent di immagini ed esplorare altre classi specifiche del contenuto per altri tipi multimediali, ad DocumentNotificationContentesempio , VideoNotificationContente AudioNotificationContent.

Invio di un messaggio di immagine

Assemblare quindi inviare il messaggio di immagine:

// Assemble image message
String imageUrl = "https://example.com/image.jpg";
ImageNotificationContent imageContent = new ImageNotificationContent(channelRegistrationId, recipientList, imageUrl);

// Send image message
SendMessageResult imageMessageResult = notificationClient.send(imageContent);

// Process result
for (MessageReceipt messageReceipt : imageMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Invio di un video message

Assemblare quindi inviare il video message:

// Assemble video message
String videoUrl = "https://example.com/video.mp4";
VideoNotificationContent videoContent = new VideoNotificationContent(channelRegistrationId, recipientList, videoUrl);

// Send video message
SendMessageResult videoMessageResult = notificationClient.send(videoContent);

// Process result
for (MessageReceipt messageReceipt : videoMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Invio di un messaggio audio

Assemblare quindi inviare il messaggio audio:

// Assemble audio message
String audioUrl = "https://example.com/audio.mp3";
AudioNotificationContent audioContent = new AudioNotificationContent(channelRegistrationId, recipientList, audioUrl);

// Send audio message
SendMessageResult audioMessageResult = notificationClient.send(audioContent);

// Process result
for (MessageReceipt messageReceipt : audioMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Invio di un messaggio di documento

Assemblare quindi inviare il messaggio del documento:

// Assemble document message
String docUrl = "https://example.com/document.pdf";
DocumentNotificationContent docContent = new DocumentNotificationContent(channelRegistrationId, recipientList, docUrl);

// Send document message
SendMessageResult docMessageResult = notificationClient.send(docContent);

// Process result
for (MessageReceipt messageReceipt : docMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Eseguire il codice

  1. Passare alla directory che contiene il file pom.xml e compilare il progetto tramite il comando mvn.

    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

Configurazione

Per configurare un ambiente per l'invio di messaggi, seguire questa procedura nelle sezioni seguenti.

Creare una nuova applicazione Node.js

  1. Creare una nuova directory per l’app e aprire tramite la finestra del terminale o di comando, quindi eseguire il comando seguente.

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

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

    npm init -y

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

  4. 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);
});

Nelle sezioni seguenti, tutto il codice sorgente usato in questa guida introduttiva verrà aggiunto al file send-messages.py appena 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.

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità SDK Messaggistica avanzata dei Servizi di comunicazione di Azure per JavaScript.

Nome Descrizione
MessageClient Questa classe si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Questa classe definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.

Esempi di codice

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

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 MessageClient, aggiungere il codice seguente al metodo Main:

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

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

// Instantiate the client
const client = MessageClient(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"];

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.

(Opzione 1) Avviare una conversazione dall'azienda - Inviare un messaggio modello

Avviare una conversazione inviando un messaggio modello.

Prima di tutto, creare un MessageTemplate usando i valori per un modello.

Nota

Per verificare quali modelli sono disponibili, vedere le istruzioni in Elencare i modelli. Se non si dispone di un modello da usare, procedere con l’opzione 2.

Ecco la creazione di MessageTemplate usando un modello predefinito, sample_template.
Se sample_template non è disponibile, passare all'opzione 2. Per gli utenti avanzati, vedere la pagina Modelli per comprendere come inviare un modello diverso con l'opzione 1.

Messages SDK consente a Contoso di inviare messaggi WhatsApp modello agli utenti di WhatsApp. Per inviare messaggi modello sotto i dettagli sono necessari:

// Assemble the template content
const template = {
    name: "sample_template",
    language: "en_US"
};

Per altri esempi su come assemblare MessageTemplate e creare un modello personalizzato, vedere la risorsa seguente:

Per ulteriori requisiti di WhatsApp sui modelli, fai riferimento alle informazioni di riferimento sull'API WhatsApp Business Platform:

// Send template message
const templateMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "template",
        template: template
    }
});

// Process result
if (templateMessageResult.status === "202") {
    templateMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Ora, l'utente deve rispondere al messaggio del modello. Dall'account utente WhatsApp, rispondi al messaggio del modello ricevuto dall'account WhatsApp Business. Il contenuto del messaggio è irrilevante per questo scenario.

Importante

Prima di poter recapitare il testo o messaggio multimediale al destinatario, il destinatario deve rispondere al messaggio modello per avviare la conversazione.

(Opzione 2) Iniziare una conversazione dall’utente

L'altra opzione per avviare una conversazione tra un account WhatsApp Business e un utente WhatsApp consiste nell'avviare la conversazione. A tale scopo, inviare un messaggio dall’account WhatsApp personale al tuo numero business (ID mittente).

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

Inviare un SMS a un utente WhatsApp

Messages SDK consente a Contoso di inviare SMS WhatsApp, che ha avviato gli utenti di WhatsApp. Per i inviare gli SMS sono necessari i seguenti dettagli:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

In questo esempio rispondiamo all'utente WhatsApp con il testo "Grazie per il tuo feedback.\n Da SDK messaggi di notifica".

Assemblare e inviare il messaggio multimediale:

// Send text message
const textMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "text",
        content: "Thanks for your feedback.\n From Notification Messaging SDK"
    }
});

// Process result
if (textMessageResult.status === "202") {
    textMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Inviare un messaggio multimediale a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi multimediali (immagine, video, audio o documento) agli utenti di WhatsApp. Per inviare un messaggio multimediale incorporato, sono necessari:

Importante

Per inviare un messaggio multimediale a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Importante

A partire dall'SDK versione 2.0.0, MediaNotificationContent viene deprecato per le immagini. È consigliabile usare per l'invio ImageNotificationContent di immagini ed esplorare altre classi specifiche del contenuto per altri tipi multimediali, ad DocumentNotificationContentesempio , VideoNotificationContente AudioNotificationContent.

Invio del contenuto dell'immagine

Per inviare un messaggio di immagine, fornire un URL a un'immagine. Ad esempio,

const url = "https://example.com/image.jpg";

Assemblare e inviare il messaggio multimediale:

// Send image message
const mediaMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "image",
        mediaUri: url
    }
});

// Process result
if (mediaMessageResult.status === "202") {
    mediaMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Invio di contenuti video

Per inviare un messaggio video, fornire un URL a un video. Ad esempio,

const url = "https://example.com/video.mp4";

Assemblare e inviare il video message:

// Send video message
const mediaMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "video",
        mediaUri: url
    }
});

// Process result
if (mediaMessageResult.status === "202") {
    mediaMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Invio di contenuti audio

Per inviare un messaggio audio, fornire un URL a un file audio. Ad esempio,

const url = "https://example.com/audio.mp3";

Assemblare e inviare il messaggio audio:

// Send audio message
const mediaMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "audio",
        mediaUri: url
    }
});

// Process result
if (mediaMessageResult.status === "202") {
    mediaMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Invio del contenuto del documento

Per inviare un messaggio di documento, specificare un URL a un documento. Ad esempio,

const url = "https://example.com/document.pdf";

Assemblare e inviare il messaggio del documento:

// Send document message
const mediaMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "document",
        mediaUri: url
    }
});

// Process result
if (mediaMessageResult.status === "202") {
    mediaMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

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

È possibile scaricare l'app di esempio da GitHub.

Prerequisiti

Configurazione

Creare una nuova applicazione Python

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

mkdir messages-quickstart && cd messages-quickstart

Installare il pacchetto

È necessario usare la libreria client messaggi di comunicazione di Azure per Python versione 1.0.0 o successiva.

Dal prompt della console, eseguire il seguente comando:

pip install azure-communication-messages

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()

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 Descrizione
NotificationMessagesClient Questa classe si connette alla risorsa Servizi di comunicazione di Azure. Invia i messaggi.
MessageTemplate Questa classe definisce il modello usato e il contenuto delle proprietà del modello per il messaggio.
TemplateNotificationContent Questa classe definisce il "chi" e il "cosa" del messaggio del modello che si intende inviare.
TextNotificationContent Questa classe definisce "chi" e "cosa" del messaggio di testo che si intende inviare.
ImageNotificationContent Questa classe definisce il "chi" e il "cosa" del messaggio multimediale con immagine che si intende inviare.
DocumentNotificationContent Questa classe definisce il "chi" e il "what" del messaggio multimediale document che si intende inviare.
VideoNotificationContent Questa classe definisce il "chi" e il "cosa" del messaggio multimediale Video che si intende inviare.
AudioNotificationContent Questa classe definisce "chi" e "cosa" del messaggio multimediale audio che si intende inviare.

Esempi di codice

Seguire questa procedura per aggiungere i frammenti di codice necessari al programma python quickstart.py.

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

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.

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_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.

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.

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.

(Opzione 1) Avviare una conversazione dall'azienda - Inviare un messaggio modello

Avviare una conversazione inviando un messaggio modello.

Prima di tutto, creare un MessageTemplate usando i valori per un modello.

Nota

Per verificare quali modelli sono disponibili, vedere le istruzioni in Elencare i modelli. Se non si dispone di un modello da usare, procedere con l’opzione 2.

Ecco la creazione di MessageTemplate usando un modello predefinito, sample_template.
Se sample_template non è disponibile, passare all'opzione 2. Per gli utenti avanzati, vedere la pagina Modelli per comprendere come inviare un modello diverso con l'opzione 1.

Messages SDK consente a Contoso di inviare messaggi WhatsApp modello agli utenti di WhatsApp. Per inviare messaggi modello sotto i dettagli sono necessari:

Per altri esempi su come assemblare MessageTemplate e creare un modello personalizzato, vedere la risorsa seguente:

Per ulteriori requisiti di WhatsApp sui modelli, fai riferimento alle informazioni di riferimento sull'API WhatsApp Business Platform:

Per inviare un messaggio di modello WhatsApp, aggiungere il codice specificato nella funzione send_template_message(self).

        input_template: MessageTemplate = MessageTemplate(
            name="<<template_name>>",
            language="<<template_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")

Aggiungere send_template_message() chiamata al metodo principale.

    # Calling send_template_message()
    messages.send_template_message()

Ora, l'utente deve rispondere al messaggio del modello. Dall'account utente WhatsApp, rispondi al messaggio del modello ricevuto dall'account WhatsApp Business. Il contenuto del messaggio è irrilevante per questo scenario.

Importante

Prima di poter recapitare il testo o messaggio multimediale al destinatario, il destinatario deve rispondere al messaggio modello per avviare la conversazione.

(Opzione 2) Iniziare una conversazione dall’utente

L'altra opzione per avviare una conversazione tra un account WhatsApp Business e un utente WhatsApp consiste nell'avviare la conversazione. A tale scopo, inviare un messaggio dall’account WhatsApp personale al tuo numero business (ID mittente).

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

Inviare un SMS a un utente WhatsApp

Messages SDK consente a Contoso di inviare SMS WhatsApp, che ha avviato gli utenti di WhatsApp. Per i inviare gli SMS sono necessari i seguenti dettagli:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

In questo esempio rispondiamo all'utente WhatsApp con il testo "Grazie per il tuo feedback.\n Da Notification Messaging SDK".

    def send_text_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TextNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        text_options = TextNotificationContent (
            channel_registration_id=self.channelRegistrationId,
            to= [self.phone_number],
            content="Thanks for your feedback.\n From Notification Messaging SDK",
        )
        
        # calling send() with whatsapp message details
        message_responses = messaging_client.send(text_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Text Message with message id {} was successfully sent to {}."
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

Per eseguire send_text_message(), aggiornare il metodo main

    #Calling send_text_message()
    messages.send_text_message()

Inviare un messaggio multimediale immagine a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

Importante

Per inviare un SMS a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Un esempio di media_uri usato per l'invio di messaggi WhatsApp multimediali.

input_media_uri: str = "https://aka.ms/acsicon1"

    def send_image_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( ImageNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "https://aka.ms/acsicon1"
        image_message_options = ImageNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri
        )

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

Per eseguire send_text_message(), aggiornare il metodo main

    # Calling send_image_message()
    messages.send_image_message()

Inviare un messaggio multimediale di documento a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

Importante

Per inviare un messaggio di documento a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Un esempio di media_uri usato per l'invio di messaggi WhatsApp multimediali.

input_media_uri: str = "##DocumentLinkPlaceholder##"

    def send_document_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( DocumentNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##DocumentLinkPlaceholder##"
        documents_options = DocumentNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            caption="Hello World via Advanced Messaging SDK.This is document message",
            file_name="Product roadmap timeline.pptx",
            media_uri=input_media_uri,
        )

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

Per eseguire send_text_message(), aggiornare il metodo main

    # Calling send_image_message()
    messages.send_image_message()

Inviare un messaggio multimediale audio a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

Importante

Per inviare un messaggio audio a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Un esempio di media_uri usato per l'invio di messaggi WhatsApp multimediali.

input_media_uri: str = "##AudioLinkPlaceholder##"

    def send_audio_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( AudioNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##AudioLinkPlaceholder##"
        audio_options = AudioNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri,
        )

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

Per eseguire send_text_message(), aggiornare il metodo main

    # Calling send_image_message()
    messages.send_image_message()

Inviare un messaggio multimediale video a un utente WhatsApp

Messages SDK consente a Contoso di inviare messaggi WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

Importante

Per inviare un video messaggio a un utente WhatsApp, l'utente WhatsApp deve prima inviare un messaggio all'account WhatsApp Business. Per altre informazioni, vedi Iniziare a inviare messaggi tra utenti business e WhatsApp.

Un esempio di media_uri usato per l'invio di messaggi WhatsApp multimediali.

input_media_uri: str = "##VideoLinkPlaceholder##"

    def send_video_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( VideoNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##VideoLinkPlaceholder##"
        video_options = VideoNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri,
        )

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

Per eseguire send_text_message(), aggiornare il metodo main

    # Calling send_image_message()
    messages.send_image_message()

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>>
WhatsApp Text Message with message id <<GUID>> was successfully sent to <<ToRecipient>>
WhatsApp Image containing Message with message id <<GUID>> was successfully sent to <<ToRecipient>>

Codice di esempio completo

import os

class MessagesQuickstart(object):
    print("Azure Communication Services - Advanced Messages SDK Quickstart using connection string.")
    # Advanced Messages SDK implementations goes in this section.
   
    connection_string = os.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING")
    phone_number = os.getenv("RECIPIENT_PHONE_NUMBER")
    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID")

    def send_template_message(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_text_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TextNotificationContent )

        # client creation
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        text_options = TextNotificationContent (
            channel_registration_id=self.channelRegistrationId,
            to= [self.phone_number],
            content="Hello World via ACS Advanced Messaging SDK.",
        )
        
        # calling send() with WhatsApp message details
        message_responses = messaging_client.send(text_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Text Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

    def send_image_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( ImageNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "https://aka.ms/acsicon1"
        image_message_options = ImageNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri
        )

        # calling send() with whatsapp image message
        message_responses = messaging_client.send(image_message_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Image containing Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")
    
    def send_document_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( DocumentNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##DocumentLinkPlaceholder##"
        documents_options = DocumentNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            caption="Hello World via Advanced Messaging SDK.This is document message",
            file_name="Product roadmap timeline.pptx",
            media_uri=input_media_uri,
        )

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

    def send_audio_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( AudioNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##AudioLinkPlaceholder##"
        audio_options = AudioNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri,
        )

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

    def send_video_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( VideoNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "##VideoLinkPlaceholder##"
        video_options = VideoNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri,
        )

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

if __name__ == '__main__':
    messages = MessagesQuickstart()
    messages.send_template_message()
    messages.send_text_message()
    messages.send_image_message()
    messages.send_document_message()
    messages.send_audio_message()
    messages.send_video_message()

Nota

Aggiornare tutte le variabili segnaposto nel codice precedente.

Altri esempi

È possibile esaminare e scaricare altri codici di esempio per Python Messages SDK in GitHub.

Passaggi successivi

In questa guida per l’avvio rapido, si è utilizzato l’SDK Messaggistica avanzata per WhatsApp. I seguenti articoli potrebbero risultare interessanti: