Guida introduttiva: Inviare messaggi WhatsApp con Messaggistica avanzata

Prerequisiti

• Account WhatsApp Business registrato con la risorsa di Servizi di comunicazione di Azure

• Numero di telefono WhatsApp attivo per ricevere messaggi

• Ambiente di sviluppo locale .NET (come ad esempio Visual Studio, Visual Studio Code o .NET CLI)

Configurazione

Creazione di un progetto .NET

dotnet build
dotnet run

dotnet new console -o AdvancedMessagingQuickstart

cd AdvancedMessagingQuickstart
dotnet build

Installare il pacchetto

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

dotnet add package Azure.Communication.Messages

dotnet add package Azure.Communication.Messages

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.

Esempi di codice

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

• Autenticare il client
• Configurare l’ID di registrazione di canali
• Configurare l’elenco di destinatari
• Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp
  • Inviare un messaggio modello a un utente WhatsApp
  • Iniziare una conversazione dall’utente
• Inviare un SMS a un utente WhatsApp
• Inviare un messaggio multimediale a un utente WhatsApp

Autenticare il client

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

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

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

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

setx COMMUNICATION_SERVICES_KEY "<your key>"

// Retrieve key from environment variable
string key = 
    Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_KEY");

// Configure authentication
var endpoint = new Uri("https://<resource name>.communication.azure.com");
var credential = new AzureKeyCredential(key);

// Instantiate the client
var notificationMessagesClient = 
    new NotificationMessagesClient(endpoint, credential);

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.

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.

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.

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:

• Authenticated NotificationMessagesClient
• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Dettagli modello
  • Nome 'sample_template'
  • Linguaggio "en_us"
  • Parametri, se presenti

// 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:

• Inviare messaggi modello WhatsApp

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

• Crearee gestire i modelli
• Componenti modello
• Invio di messaggi modello

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.

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

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:

• Authenticated NotificationMessagesClient
• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Corpo/testo del messaggio da inviare

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:

• Authenticated NotificationMessagesClient
• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• MediaUri dell'immagine

Ad esempio, creare un URI:

var uri = new Uri("https://aka.ms/acsicon1");

Assemblare quindi inviare il messaggio multimediale:

// Assemble media message
var mediaContent = 
    new MediaNotificationContent(channelRegistrationId, recipientList, uri);

// Send media message
Response<SendMessageResult> sendMediaMessageResult = 
    await notificationMessagesClient.SendAsync(mediaContent);

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.

dotnet build
dotnet run

dotnet build
dotnet run

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");
            MediaNotificationContent mediaContent =
                new MediaNotificationContent(channelRegistrationId, recipientList, uri);
            Response<SendMessageResult> sendMediaMessageResult =
                await notificationMessagesClient.SendAsync(mediaContent);

            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

• Account WhatsApp Business registrato con la risorsa di Servizi di comunicazione di Azure

• Numero di telefono WhatsApp attivo per ricevere messaggi

• Java Development Kit (JDK), versione 8 o successiva

• Apache Maven

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.

Esempi di codice

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

• Autenticare il client
• Configurare l’ID di registrazione di canali
• Configurare l’elenco di destinatari
• Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp
  • Inviare un messaggio modello a un utente WhatsApp
  • Iniziare una conversazione dall’utente
• Inviare un SMS a un utente WhatsApp
• Inviare un messaggio multimediale a un utente WhatsApp

Autenticare il client

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

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

// 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.

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.

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.

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Dettagli modello
  • Nome 'sample_template'
  • Linguaggio "en_us"
  • Parametri, se presenti

// 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.

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

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Corpo/testo del messaggio da inviare

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 WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• MediaUri dell'immagine

Ad esempio, creare un URI:

String mediaUrl = "https://aka.ms/acsicon1";

Assemblare quindi inviare il messaggio multimediale:

// Assemble media message
MediaNotificationContent mediaContent = new MediaNotificationContent(channelRegistrationId, recipientList, mediaUrl);

// Send media message
SendMessageResult mediaMessageResult = notificationClient.send(mediaContent);

// Process result
for (MessageReceipt messageReceipt : mediaMessageResult.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

• Account WhatsApp Business registrato con la risorsa di Servizi di comunicazione di Azure

• Numero di telefono WhatsApp attivo per ricevere messaggi

• Versioni di Active LTS e Maintenance LTS Node.js(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

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.

Esempi di codice

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

• Autenticare il client
• Configurare l’ID di registrazione di canali
• Configurare l’elenco di destinatari
• Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp
  • Inviare un messaggio modello a un utente WhatsApp
  • Iniziare una conversazione dall’utente
• Inviare un SMS a un utente WhatsApp
• Inviare un messaggio multimediale a un utente WhatsApp

Autenticare il client

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

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

setx COMMUNICATION_SERVICES_KEY "<your key>"

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

// Configure authentication
const endpoint = "https://<resource name>.communication.azure.com";
const credential = new AzureKeyCredential("<your key credential>");

// Instantiate the client
const client = MessageClient(endpoint, credential);

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.

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.

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.

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Dettagli modello
  • Nome 'sample_template'
  • Linguaggio "en_us"
  • Parametri, se presenti

// 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:

• Inviare messaggi modello WhatsApp

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

• Crearee gestire i modelli
• Componenti modello
• Invio di messaggi modello

// 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.

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

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Corpo/testo del messaggio da inviare

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 WhatsApp con immagini agli utenti di WhatsApp. Per inviare messaggi con immagini incorporate sono necessari i seguenti dettagli:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• MediaUri dell'immagine

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

const url = "https://aka.ms/acsicon1";

Assemblare e inviare il messaggio multimediale:

// Send media 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");
}

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

• Account WhatsApp Business registrato con la risorsa Servizi di comunicazione di Azure.

• Numero di telefono WhatsApp attivo per ricevere messaggi.

• Python 3.7+ come sistema operativo.

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.

Esempi di codice

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

• Autenticare il client
• Configurare l’ID di registrazione di canali
• Configurare l’elenco di destinatari
• Iniziare a inviare messaggi tra un'azienda e un utente di WhatsApp
  • Inviare un messaggio modello a un utente WhatsApp
  • Iniziare una conversazione dall’utente
• Inviare un SMS a un utente WhatsApp
• Inviare un messaggio multimediale a un utente WhatsApp

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.

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

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

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

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string,
                                                    credential=DefaultAzureCredential())

setx COMMUNICATION_SERVICES_ENDPOINT_STRING "<https://<resource name>.communication.azure.com>"
setx COMMUNICATION_SERVICES_KEY "<your key>"

    # Get a connection string to our Azure Communication Services resource.
    endpoint_string = os.getenv("COMMUNICATION_SERVICES_ENDPOINT_STRING")
    key = os.getenv("COMMUNICATION_SERVICES_KEY")

    def send_template_message(self):
        from azure.core.credentials import AzureKeyCredential
        from azure.communication.messages import NotificationMessagesClient

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string,
                                                    credential=AzureKeyCredential(self.key))

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.

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.

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.

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Dettagli modello
  • Nome 'sample_template'
  • Linguaggio "en_us"
  • Parametri, se presenti

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

• Inviare messaggi modello WhatsApp

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

• Crearee gestire i modelli
• Componenti modello
• Invio di messaggi modello

Per inviare il messaggio del modello WhatsApp, aggiungere il codice seguente 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.

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

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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• Corpo/testo del messaggio da inviare

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

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

Aggiornare il metodo principale per eseguire send_text_message()

    #Calling send_text_message()
    messages.send_text_message()

Inviare un messaggio multimediale 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:

• ID canale WhatsApp
• Numero di telefono destinatario in formato E16
• MediaUri dell'immagine

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

Aggiornare il metodo principale per eseguire send_image_message()

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

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

Altri esempi

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