Compartilhar via

Início rápido: enviar mensagens do WhatsApp usando o Mensagens avançadas

  • Artigo

Os Serviços de Comunicação do Azure permitem que você envie e receba mensagens do WhatsApp. Neste início rápido, comece a integrar seu aplicativo ao SDK de Mensagens Avançadas de Comunicação do Azure e comece a enviar/receber mensagens do WhatsApp. A realização deste início rápido gera um pequeno custo de alguns centavos de dólar ou menos em sua conta do Azure.

Pré-requisitos

Configurando

Criar o projeto .NET

Para criar seu projeto, siga o tutorial em Criar um aplicativo de console .NET usando o Visual Studio.

Para compilar seu código, pressione Ctrl+F7.

Instalar o pacote

Instale o pacote NuGet Azure.Communication.Messages em seu projeto em C#.

  1. Abra o Gerenciador de Pacotes NuGet em Project>Manage NuGet Packages....
  2. Pesquise o pacote Azure.Communication.Messages.
  3. Instale a versão mais recente.

Configurar o framework de aplicativos

Abra o arquivo Program.cs em um editor de texto.

Substitua o conteúdo do Program.cs pelo seguinte código:

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
        }
    }
}

Para usar os recursos de Mensagens Avançadas, adicionamos uma diretiva using para incluir o namespace Azure.Communication.Messages.

using Azure.Communication.Messages;

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Mensagens Avançadas dos Serviços de Comunicação do Azure para .NET.

Nome Descrição
NotificationMessagesClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Essa classe define qual modelo você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.
TextNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de texto que você pretende enviar.
MediaNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de mídia que você pretende enviar.

Exemplos de código

Siga estas etapas para adicionar os trechos de código necessários à função Principal do arquivo Program.cs.

Autenticar o cliente

O recurso NotificationMessagesClient é usado para se conectar ao recurso dos Serviços de Comunicação do Azure.

Para simplificar, este início rápido usa uma cadeia de conexão para autenticar. Em ambientes de produção, é recomendável usar entidades de serviço.

Obtenha da cadeia de conexão no recurso Serviços de Comunicação do Azure no portal do Azure. À esquerda, navegue até a guia Keys. Copie o campo Connection string da chave primária. A cadeia de conexão está no formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo o campo

Defina a variável de ambiente COMMUNICATION_SERVICES_CONNECTION_STRING para o valor da cadeia de conexão.
Abra uma janela do console e insira o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

Para obter mais informações sobre como definir uma variável de ambiente para seu sistema, siga as etapas em Armazenar sua cadeia de conexão em uma variável de ambiente.

Para criar uma instância de NotificationMessagesClient, adicione o seguinte código ao método Main:

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

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

Definir a ID de registro do canal

O GUID da ID de Registro de Canal foi criado durante o registro do canal. Você pode pesquisá-lo no portal na guia Canais do recurso Serviços de Comunicação do Azure.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia

Atribua a uma variável chamada channelRegistrationId.

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

Definir a lista de destinatários

Você precisa fornecer um número de telefone real que tenha uma conta do WhatsApp associada a ele. Essa conta do WhatsApp recebe o modelo, o texto e as mensagens de mídia enviadas neste início rápido. Para este início rápido, esse número de telefone pode ser seu número de telefone pessoal.

O número de telefone do destinatário não pode ser o número de telefone comercial (ID do remetente) associado ao registro do canal do WhatsApp. A ID do remetente é exibida como o remetente das mensagens de texto e mídia enviadas ao destinatário.

O número de telefone deve incluir o código do país. Para obter mais informações sobre a formatação do número de telefone, consulte a documentação do WhatsApp para Formatos de número de telefone.

Observação

Atualmente, há suporte para apenas um número de telefone na lista de destinatários.

Crie a lista de destinatários da seguinte maneira:

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

Exemplo:

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

Começar a enviar mensagens entre uma empresa e um usuário do WhatsApp

As conversas entre uma conta do WhatsApp Business e um usuário do WhatsApp podem ser iniciadas de duas maneiras:

  • A empresa envia uma mensagem de modelo para o usuário do WhatsApp.
  • O usuário do WhatsApp envia qualquer mensagem para o número comercial.

Independentemente de como a conversa foi iniciada, uma empresa só pode enviar mensagens de modelo até que o usuário envie uma mensagem para a empresa. Somente depois que o usuário envia uma mensagem para a empresa, a empresa tem permissão para enviar mensagens de texto ou mídia para o usuário durante a conversa ativa. Depois que a janela de conversa de 24 horas expirar, a conversa deverá ser reiniciada. Para saber mais sobre conversas, consulte a definição na Plataforma WhatsApp Business.

(Opção 1) Iniciar conversa de negócios – Enviar uma mensagem de modelo

Inicie uma conversa enviando uma mensagem de modelo.

Primeiro, crie um MessageTemplate usando os valores de um modelo.

Observação

Para verificar quais modelos você tem disponíveis, consulte as instruções em Modelos de lista. Se você não tiver um modelo a ser usado, vá para a Opção 2.

Aqui está a criação do MessageTemplate usando um modelo padrão, sample_template.
Se sample_template não estiver disponível para você, vá para a Opção 2. Para usuários avançados, consulte a página Modelos para entender como enviar um modelo diferente com a Opção 1.

O SDK do Mensagens permite que a Contoso envie mensagens do WhatsApp com modelo para usuários do WhatsApp. Para enviar um modelo de mensagem, você precisa de:

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

Para obter mais exemplos de como montar seu MessageTemplate e como criar seu próprio modelo, consulte o seguinte recurso:

Para obter mais requisitos do WhatsApp sobre modelos, consulte as referências da API da Plataforma De Negócios do WhatsApp:

Em seguida, envie a mensagem de modelo:

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

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

Agora, o usuário precisa responder à mensagem de modelo. Na conta de usuário do WhatsApp, responda à mensagem de modelo recebida da conta comercial do WhatsApp. O conteúdo da mensagem é irrelevante para esse cenário.

Importante

O destinatário precisa responder à mensagem de modelo para iniciar a conversa antes que o texto ou a mensagem de mídia possa ser entregue ao destinatário.

(Opção 2) Iniciar conversa do usuário

A outra opção para iniciar uma conversa entre uma conta comercial do WhatsApp e um usuário do WhatsApp é fazer com que o usuário inicie a conversa. Para fazer isso, na sua conta pessoal do WhatsApp, envie uma mensagem para o número comercial (ID do remetente).

Uma conversa do WhatsApp exibida na Web mostrando uma mensagem de usuário enviada para o número da Conta Comercial do WhatsApp.

Enviar uma mensagem de texto para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de texto do WhatsApp, que iniciaram os usuários do WhatsApp. Para enviar uma mensagem de texto, você precisa de:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Neste exemplo, respondemos ao usuário do WhatsApp com o texto "Obrigado por seus comentários.\n Do SDK de Mensagens de Notificação".

Em seguida, monte a mensagem de texto:

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

Enviar uma mensagem de mídia para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de mídia do WhatsApp para usuários do WhatsApp. Para enviar uma mensagem de mídia incorporada, você precisa:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Importante

A partir do SDK versão 1.1.0, MediaNotificationContent está sendo preterido para imagens. Incentivamos você a usar ImageNotificationContent para enviar imagens e explorar outras classes específicas de conteúdo para outros tipos de mídia, como DocumentNotificationContent, VideoNotificationContent e AudioNotificationContent.

Abaixo estão exemplos de snippets de código para enviar diferentes tipos de mensagens de mídia, incluindo imagens, documentos, vídeos e arquivos de áudio.

Enviar um conteúdo de imagem

Monte a mensagem de imagem:

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

Envie a mensagem de imagem:

var imageResponse = await notificationMessagesClient.SendAsync(imageNotificationContent);

Enviar um documento

Monte o conteúdo de 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"  
};

Envie a mensagem de documento:

var documentResponse = await notificationMessagesClient.SendAsync(documentNotificationContent);

Enviar um conteúdo de vídeo

Monte a mensagem de vídeo:

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

Envie a mensagem de vídeo:

var videoResponse = await notificationMessagesClient.SendAsync(videoNotificationContent);

Enviar um conteúdo de áudio

Monte a mensagem de áudio:

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

Envie a mensagem de áudio:

var audioResponse = await notificationMessagesClient.SendAsync(audioNotificationContent);

Executar o código

Crie e execute o programa.

Para enviar uma mensagem de texto ou mídia para um usuário do WhatsApp, deve haver uma conversa ativa entre a conta do WhatsApp Business e o usuário do WhatsApp.
Se você não tiver uma conversa ativa, para fins deste início rápido, deverá adicionar uma espera entre enviar a mensagem de modelo e enviar a mensagem de texto. Esse atraso adicional oferece tempo suficiente para responder à empresa na conta do WhatsApp do usuário. Para referência, o exemplo completo em Exemplo de código solicita entrada manual do usuário antes de enviar a próxima mensagem.

Se tiver êxito, você receberá três mensagens na conta do WhatsApp do usuário.

  1. Para compilar seu código, pressione Ctrl+F7.
  2. Para executar o programa sem depuração, pressione Ctrl+F5.

Exemplo de código 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");
        }
    }
}

Pré-requisitos

Configurando

Para configurar um ambiente para o envio de mensagens, siga as etapas nas seções a seguir.

Criar um aplicativo Java

Abra o terminal ou a janela de comando e navegue até o diretório no qual você deseja criar o seu aplicativo Java. Execute o comando abaixo para gerar o projeto Java a partir do modelo maven-archetype-quickstart.

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

A meta generate cria um diretório com o mesmo nome do valor artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o diretório src/test/java contém a fonte de teste e o arquivo pom.xml é o POM (Modelo de Objeto do Projeto) do projeto.

Instalar o pacote

Abra o arquivo pom.xml no seu editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências.

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

Configurar o framework de aplicativos

Abra /src/main/java/com/communication/quickstart/App.java em um editor de texto, adicione diretivas de importação e remova a instrução 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.
    }
}

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Mensagens Avançadas dos Serviços de Comunicação do Azure para Java.

Nome Descrição
NotificationMessagesClientBuilder Essa classe cria o Cliente de Mensagens de Notificação. Você fornece um ponto de extremidade e uma credencial.
NotificationMessagesClient Essa classe é necessária para enviar mensagens do WhatsApp e baixar arquivos de mídia.
NotificationMessagesAsyncClient Essa classe é necessária para enviar mensagens do WhatsApp e baixar arquivos de mídia de forma assíncrona.
SendMessageResult Essa classe contém o resultado do serviço de Mensagens Avançadas para enviar mensagem de notificação.
MessageTemplateClientBuilder Essa classe cria o Cliente de Modelo de Mensagem. Você fornece um ponto de extremidade e uma credencial.
MessageTemplateClient Essa classe é necessária para obter a lista de modelos do WhatsApp.
MessageTemplateAsyncClient Essa classe é necessária para obter a lista de modelos do WhatsApp de forma assíncrona.

Exemplos de código

Siga estas etapas para adicionar os trechos de código necessários à função principal do arquivo App.java.

Autenticar o cliente

Há algumas opções diferentes disponíveis para autenticar um cliente de mensagem:

Para autenticar um cliente, crie uma instância de NotificationMessagesClient ou MessageTemplateClient com a cadeia de conexão. Também é possível criar uma instância do cliente com qualquer cliente HTTP personalizado que implemente a interface com.azure.core.http.HttpClient.

Para simplificar, este início rápido usa uma cadeia de conexão para autenticar. Em ambientes de produção, é recomendável usar entidades de serviço.

Obtenha da cadeia de conexão no recurso Serviços de Comunicação do Azure no portal do Azure. À esquerda, navegue até a guia Keys. Copie o campo Connection string para o Primary key. A cadeia de conexão está no formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo o campo

Defina a variável de ambiente COMMUNICATION_SERVICES_CONNECTION_STRING para o valor da cadeia de conexão.
Abra uma janela do console e insira o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Para obter mais informações sobre como definir uma variável de ambiente para seu sistema, siga as etapas em Armazenar sua cadeia de conexão em uma variável de ambiente.

Para criar uma instância de NotificationMessagesClient, adicione o seguinte código ao método 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();

Definir a ID de registro do canal

O GUID da ID de Registro de Canal foi criado durante o registro do canal. Você pode pesquisá-lo no portal na guia Canais do recurso Serviços de Comunicação do Azure.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia

Atribua a uma variável chamada channelRegistrationId.

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

Definir a lista de destinatários

Você precisa fornecer um número de telefone real que tenha uma conta do WhatsApp associada a ele. Essa conta do WhatsApp recebe as mensagens de texto e mídia enviadas neste início rápido. Para este início rápido, esse número de telefone pode ser seu número de telefone pessoal.

O número de telefone do destinatário não pode ser o número de telefone comercial (ID do remetente) associado ao registro do canal do WhatsApp. A ID do remetente é exibida como o remetente das mensagens de texto e mídia enviadas ao destinatário.

O número de telefone deve incluir o código do país. Para obter mais informações sobre a formatação do número de telefone, consulte a documentação do WhatsApp para Formatos de número de telefone.

Observação

Atualmente, há suporte para apenas um número de telefone na lista de destinatários.

Crie a lista de destinatários da seguinte maneira:

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

Exemplo:

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

Começar a enviar mensagens entre uma empresa e um usuário do WhatsApp

As conversas entre uma conta do WhatsApp Business e um usuário do WhatsApp podem ser iniciadas de duas maneiras:

  • A empresa envia uma mensagem de modelo para o usuário do WhatsApp.
  • O usuário do WhatsApp envia qualquer mensagem para o número comercial.

Independentemente de como a conversa foi iniciada, uma empresa só pode enviar mensagens de modelo até que o usuário envie uma mensagem para a empresa. Somente depois que o usuário envia uma mensagem para a empresa, a empresa tem permissão para enviar mensagens de texto ou mídia para o usuário durante a conversa ativa. Depois que a janela de conversa de 24 horas expirar, a conversa deverá ser reiniciada. Para saber mais sobre conversas, consulte a definição na Plataforma WhatsApp Business.

(Opção 1) Iniciar conversa de negócios – Enviar uma mensagem de modelo

Inicie uma conversa enviando uma mensagem de modelo.

Primeiro, crie um MessageTemplate usando os valores de um modelo.

Observação

Para verificar quais modelos você tem disponíveis, consulte as instruções em Modelos de lista. Se você não tiver um modelo a ser usado, vá para a Opção 2.

Aqui está a criação do MessageTemplate usando um modelo padrão, sample_template.
Se sample_template não estiver disponível para você, vá para a Opção 2. Para usuários avançados, consulte a página Modelos para entender como enviar um modelo diferente com a Opção 1.

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp com modelo para usuários do WhatsApp. Para enviar mensagens de modelo abaixo, são necessários detalhes:

// 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());
}

Agora, o usuário precisa responder à mensagem de modelo. Na conta de usuário do WhatsApp, responda à mensagem de modelo recebida da conta comercial do WhatsApp. O conteúdo da mensagem é irrelevante para esse cenário.

Importante

O destinatário precisa responder à mensagem de modelo para iniciar a conversa antes que o texto ou a mensagem de mídia possa ser entregue ao destinatário.

(Opção 2) Iniciar conversa do usuário

A outra opção para iniciar uma conversa entre uma conta comercial do WhatsApp e um usuário do WhatsApp é fazer com que o usuário inicie a conversa. Para fazer isso, na sua conta pessoal do WhatsApp, envie uma mensagem para o número comercial (ID do remetente).

Uma conversa do WhatsApp exibida na Web mostrando uma mensagem de usuário enviada para o número da Conta Comercial do WhatsApp.

Enviar uma mensagem de texto para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens WhatsApp de texto, que usuários do WhatsApp iniciaram. Para enviar mensagens de texto abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Neste exemplo, respondemos ao usuário do WhatsApp com o texto "Obrigado por seus comentários.\n Do SDK de Mensagens de Notificação".

Em seguida, monte a mensagem de texto:

// 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());
}

Enviar uma mensagem de mídia para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de mídia (imagem, vídeo, áudio ou documento) para usuários do WhatsApp. Para enviar uma mensagem de mídia incorporada, você precisa:

Importante

Para enviar uma mensagem de mídia a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Importante

A partir do SDK versão 1.1.0, MediaNotificationContent está sendo preterido para imagens. Incentivamos você a usar ImageNotificationContent para enviar imagens e explorar outras classes específicas de conteúdo para outros tipos de mídia, como DocumentNotificationContent, VideoNotificationContent e AudioNotificationContent.

Enviar uma mensagem de imagem

Em seguida, monte a mensagem de imagem:

// 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());
}

Enviar uma mensagem de vídeo

Em seguida, envie a mensagem de vídeo:

// 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());
}

Enviar uma mensagem de áudio

Em seguida, envie a mensagem de áudio:

// 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());
}

Enviar uma mensagem de documento

Em seguida, envie a mensagem do 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());
}

Executar o código

  1. Acesse o diretório que contém o arquivo pom.xml e compile o projeto usando o comando mvn.

    mvn compile

  2. Execute o aplicativo executando o comando mvn a seguir.

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

Exemplo de código completo

Encontre o código finalizado para este guia de início rápido no GitHub.

Pré-requisitos

Configurando

Para configurar um ambiente para o envio de mensagens, siga as etapas nas seções a seguir.

Criar um novo aplicativo do Node.js

  1. Crie um novo diretório para seu aplicativo e navegue até ele abrindo o terminal ou a janela de comando e execute o comando a seguir.

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

  2. Execute o comando a seguir para criar um arquivo package.json com as configurações padrão.

    npm init -y

  3. Use um editor de texto para criar um arquivo chamado send-messages.js no diretório raiz do projeto.

  4. Adicione o trecho de código a seguir ao arquivo 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);
});

Nas seções a seguir, você adicionou todo o código-fonte para este início rápido ao arquivo send-messages.js que você criou.

Instalar o pacote

Use o comando npm install para instalar o SDK de Mensagens Avançadas dos Serviços de Comunicação do Azure para JavaScript.

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

A opção --save lista a biblioteca como uma dependência no arquivo package.json.

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Mensagens Avançadas dos Serviços de Comunicação do Azure para JavaScript.

Nome Descrição
MessageClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Essa classe define qual modelo você usa e o conteúdo das propriedades do modelo para sua mensagem.

Exemplos de código

Siga estas etapas para adicionar os trechos de código necessários à função principal do arquivo send-messages.js.

Autenticar o cliente

O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING usando o pacote dotenv.

Para simplificar, este início rápido usa uma cadeia de conexão para autenticar. Em ambientes de produção, é recomendável usar entidades de serviço.

Obtenha da cadeia de conexão no recurso Serviços de Comunicação do Azure no portal do Azure. À esquerda, navegue até a guia Keys. Copie o campo Connection string para o Primary key. A cadeia de conexão está no formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo o campo

Defina a variável de ambiente COMMUNICATION_SERVICES_CONNECTION_STRING para o valor da cadeia de conexão.
Abra uma janela do console e insira o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Para obter mais informações sobre como definir uma variável de ambiente para seu sistema, siga as etapas em Armazenar sua cadeia de conexão em uma variável de ambiente.

Para criar uma instância de um MessageClient, adicione o seguinte código ao método 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);

Definir a ID de registro do canal

O GUID da ID de Registro de Canal foi criado durante o registro do canal. Você pode pesquisá-lo no portal na guia Canais do recurso Serviços de Comunicação do Azure.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia

Atribua a uma variável chamada channelRegistrationId.

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

Definir a lista de destinatários

Você precisa fornecer um número de telefone real que tenha uma conta do WhatsApp associada a ele. Essa conta do WhatsApp recebe o modelo, o texto e as mensagens de mídia enviadas neste início rápido. Para este início rápido, esse número de telefone pode ser seu número de telefone pessoal.

O número de telefone do destinatário não pode ser o número de telefone comercial (ID do remetente) associado ao registro do canal do WhatsApp. A ID do remetente é exibida como o remetente das mensagens de texto e mídia enviadas ao destinatário.

O número de telefone deve incluir o código do país. Para obter mais informações sobre a formatação do número de telefone, consulte a documentação do WhatsApp para Formatos de número de telefone.

Observação

Atualmente, há suporte para apenas um número de telefone na lista de destinatários.

Crie a lista de destinatários da seguinte maneira:

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

Exemplo:

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

Começar a enviar mensagens entre uma empresa e um usuário do WhatsApp

As conversas entre uma conta do WhatsApp Business e um usuário do WhatsApp podem ser iniciadas de duas maneiras:

  • A empresa envia uma mensagem de modelo para o usuário do WhatsApp.
  • O usuário do WhatsApp envia qualquer mensagem para o número comercial.

Independentemente de como a conversa foi iniciada, uma empresa só pode enviar mensagens de modelo até que o usuário envie uma mensagem para a empresa. Somente depois que o usuário envia uma mensagem para a empresa, a empresa tem permissão para enviar mensagens de texto ou mídia para o usuário durante a conversa ativa. Depois que a janela de conversa de 24 horas expirar, a conversa deverá ser reiniciada. Para saber mais sobre conversas, consulte a definição na Plataforma WhatsApp Business.

(Opção 1) Iniciar conversa de negócios – Enviar uma mensagem de modelo

Inicie uma conversa enviando uma mensagem de modelo.

Primeiro, crie um MessageTemplate usando os valores de um modelo.

Observação

Para verificar quais modelos você tem disponíveis, consulte as instruções em Modelos de lista. Se você não tiver um modelo a ser usado, vá para a Opção 2.

Aqui está a criação do MessageTemplate usando um modelo padrão, sample_template.
Se sample_template não estiver disponível para você, vá para a Opção 2. Para usuários avançados, consulte a página Modelos para entender como enviar um modelo diferente com a Opção 1.

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp com modelo para usuários do WhatsApp. Para enviar mensagens de modelo abaixo, são necessários detalhes:

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

Para obter mais exemplos de como montar seu MessageTemplate e como criar seu próprio modelo, consulte o seguinte recurso:

Para obter mais requisitos do WhatsApp sobre modelos, consulte as referências da API da Plataforma De Negócios do WhatsApp:

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

Agora, o usuário precisa responder à mensagem de modelo. Na conta de usuário do WhatsApp, responda à mensagem de modelo recebida da conta comercial do WhatsApp. O conteúdo da mensagem é irrelevante para esse cenário.

Importante

O destinatário precisa responder à mensagem de modelo para iniciar a conversa antes que o texto ou a mensagem de mídia possa ser entregue ao destinatário.

(Opção 2) Iniciar conversa do usuário

A outra opção para iniciar uma conversa entre uma conta comercial do WhatsApp e um usuário do WhatsApp é fazer com que o usuário inicie a conversa. Para fazer isso, na sua conta pessoal do WhatsApp, envie uma mensagem para o número comercial (ID do remetente).

Uma conversa do WhatsApp exibida na Web mostrando uma mensagem de usuário enviada para o número da Conta Comercial do WhatsApp.

Enviar uma mensagem de texto para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens WhatsApp de texto, que usuários do WhatsApp iniciaram. Para enviar mensagens de texto abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Neste exemplo, respondemos ao usuário do WhatsApp com o texto "Obrigado por seus comentários.\n Do SDK de Mensagens de Notificação".

Monte e envie a mensagem de mídia:

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

Enviar uma mensagem de mídia para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de mídia (imagem, vídeo, áudio ou documento) para usuários do WhatsApp. Para enviar uma mensagem de mídia incorporada, você precisa:

Importante

Para enviar uma mensagem de mídia a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Importante

A partir do SDK versão 2.0.0, MediaNotificationContent está sendo preterido para imagens. Incentivamos você a usar ImageNotificationContent para enviar imagens e explorar outras classes específicas de conteúdo para outros tipos de mídia, como DocumentNotificationContent, VideoNotificationContent e AudioNotificationContent.

Enviar conteúdo de imagem

Para enviar uma mensagem de imagem, forneça uma URL para uma imagem. Por exemplo,

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

Monte e envie a mensagem de mídia:

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

Enviar conteúdo de vídeo

Para enviar uma mensagem de vídeo, forneça uma URL para um vídeo. Por exemplo,

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

Monte e envie a mensagem de vídeo:

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

Enviar conteúdo de áudio

Para enviar uma mensagem de áudio, forneça uma URL para um arquivo de áudio. Por exemplo,

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

Monte e envie a mensagem de áudio:

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

Enviar conteúdo de documento

Para enviar uma mensagem de documento, forneça uma URL para um documento. Por exemplo,

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

Monte e envie a mensagem de 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");
}

Executar o código

Use o comando do nó para executar o código adicionado ao arquivo send-messages.js.

node ./send-messages.js

Exemplo de código completo

É possível baixar o aplicativo de exemplo do GitHub.

Pré-requisitos

Configurando

Criar um novo aplicativo Python

Em uma janela do console ou terminal, crie uma pasta para seu aplicativo e navegue até ela.

mkdir messages-quickstart && cd messages-quickstart

Instalar o pacote

Você precisa usar a biblioteca de clientes de Mensagens de Comunicação do Azure para Python versão 1.0.0 ou superior.

No prompt de console, execute o seguinte comando:

pip install azure-communication-messages

Configurar o framework de aplicativos

Crie um arquivo chamado messages-quickstart.py e adicione a estrutura básica do programa.

type nul > messages-quickstart.py

Estrutura básica do programa

import os

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

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

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Mensagens dos Serviços de Comunicação do Azure para Python.

Nome Descrição
NotificationMessagesClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Essa classe define qual modelo você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.
TextNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de texto que você pretende enviar.
ImageNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de mídia de imagem que você pretende enviar.
DocumentNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de mídia de documento que você pretende enviar.
VideoNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de mídia de vídeo que você pretende enviar.
AudioNotificationContent Essa classe define o "quem" e o "o quê" da mensagem de mídia de áudio que você pretende enviar.

Exemplos de código

Siga estas etapas para adicionar os trechos de código necessários ao programa python messages-quickstart.py.

Autenticar o cliente

O envio de mensagens é feito usando NotificationMessagesClient. NotificationMessagesClient é autenticado usando sua cadeia de conexão adquirida do recurso dos Serviços de Comunicação do Azure no portal do Azure. Para obter mais informações sobre cadeias de conexão, consulte access-your-connection-strings-and-service-endpoints.

Obtenha a cadeia de conexão do Recurso de Comunicação do Azure no portal do Azure, conforme mostrado na captura de tela. À esquerda, navegue até a guia Keys. Copie o campo Connection string da chave primária. A cadeia de conexão está no formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo o campo

Defina a variável de ambiente COMMUNICATION_SERVICES_CONNECTION_STRING para o valor da cadeia de conexão.
Abra uma janela do console e insira o seguinte comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

Para obter mais informações sobre como definir uma variável de ambiente para seu sistema, siga as etapas em Armazenar sua cadeia de conexão em uma variável de 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)

Definir a ID de registro do canal

O GUID da ID de Registro de Canal foi criado durante o registro do canal. Você pode pesquisá-lo no portal na guia Canais do recurso Serviços de Comunicação do Azure.

Captura de tela que mostra um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia

Atribua a uma variável chamada channelRegistrationId.

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

Definir a lista de destinatários

Você precisa fornecer um número de telefone real que tenha uma conta do WhatsApp associada a ele. Essa conta do WhatsApp recebe o modelo, o texto e as mensagens de mídia enviadas neste início rápido. Para este início rápido, esse número de telefone pode ser seu número de telefone pessoal.

O número de telefone do destinatário não pode ser o número de telefone comercial (ID do remetente) associado ao registro do canal do WhatsApp. A ID do remetente é exibida como o remetente das mensagens de texto e mídia enviadas ao destinatário.

O número de telefone deve incluir o código do país. Para obter mais informações sobre a formatação do número de telefone, consulte a documentação do WhatsApp para Formatos de número de telefone.

Observação

Atualmente, há suporte para apenas um número de telefone na lista de destinatários.

Defina a lista de destinatários da seguinte maneira:

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

Exemplo de uso:

    # Example only
    to=[self.phone_number],

Começar a enviar mensagens entre uma empresa e um usuário do WhatsApp

As conversas entre uma conta do WhatsApp Business e um usuário do WhatsApp podem ser iniciadas de duas maneiras:

  • A empresa envia uma mensagem de modelo para o usuário do WhatsApp.
  • O usuário do WhatsApp envia qualquer mensagem para o número comercial.

Independentemente de como a conversa foi iniciada, uma empresa só pode enviar mensagens de modelo até que o usuário envie uma mensagem para a empresa. Somente depois que o usuário envia uma mensagem para a empresa, a empresa tem permissão para enviar mensagens de texto ou mídia para o usuário durante a conversa ativa. Depois que a janela de conversa de 24 horas expirar, a conversa deverá ser reiniciada. Para saber mais sobre conversas, consulte a definição na Plataforma WhatsApp Business.

(Opção 1) Iniciar conversa de negócios – Enviar uma mensagem de modelo

Inicie uma conversa enviando uma mensagem de modelo.

Primeiro, crie um MessageTemplate usando os valores de um modelo.

Observação

Para verificar quais modelos você tem disponíveis, consulte as instruções em Modelos de lista. Se você não tiver um modelo a ser usado, vá para a Opção 2.

Aqui está a criação do MessageTemplate usando um modelo padrão, sample_template.
Se sample_template não estiver disponível para você, vá para a Opção 2. Para usuários avançados, consulte a página Modelos para entender como enviar um modelo diferente com a Opção 1.

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp com modelo para usuários do WhatsApp. Para enviar mensagens de modelo abaixo, são necessários detalhes:

Para obter mais exemplos de como montar seu MessageTemplate e como criar seu próprio modelo, consulte o seguinte recurso:

Para obter mais requisitos do WhatsApp sobre modelos, consulte as referências da API da Plataforma De Negócios do WhatsApp:

Para enviar uma mensagem de modelo do WhatsApp, adicione o código determinado na função 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")

Adicione a chamada send_template_message() ao método principal.

    # Calling send_template_message()
    messages.send_template_message()

Agora, o usuário precisa responder à mensagem de modelo. Na conta de usuário do WhatsApp, responda à mensagem de modelo recebida da conta comercial do WhatsApp. O conteúdo da mensagem é irrelevante para esse cenário.

Importante

O destinatário precisa responder à mensagem de modelo para iniciar a conversa antes que o texto ou a mensagem de mídia possa ser entregue ao destinatário.

(Opção 2) Iniciar conversa do usuário

A outra opção para iniciar uma conversa entre uma conta comercial do WhatsApp e um usuário do WhatsApp é fazer com que o usuário inicie a conversa. Para fazer isso, na sua conta pessoal do WhatsApp, envie uma mensagem para o número comercial (ID do remetente).

Uma conversa do WhatsApp exibida na Web mostrando uma mensagem de usuário enviada para o número da Conta Comercial do WhatsApp.

Enviar uma mensagem de texto para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens WhatsApp de texto, que usuários do WhatsApp iniciaram. Para enviar mensagens de texto abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Neste exemplo, respondemos ao usuário do WhatsApp com o texto "Obrigado por seus comentários.\n Do SDK de Mensagens de Notificação".

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

Para executar send_text_message(), atualize o método principal

    #Calling send_text_message()
    messages.send_text_message()

Enviar uma mensagem de mídia de imagem para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp de imagem para usuários do WhatsApp. Para enviar mensagens inseridas de imagem abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de texto a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Um exemplo de media_uri usado no envio de mensagem de WhatsApp de mídia.

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

Para executar send_text_message(), atualize o método principal

    # Calling send_image_message()
    messages.send_image_message()

Enviar uma mensagem de mídia de documento para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp de imagem para usuários do WhatsApp. Para enviar mensagens inseridas de imagem abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de documento a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Um exemplo de media_uri usado no envio de mensagem de WhatsApp de mídia.

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

Para executar send_text_message(), atualize o método principal

    # Calling send_image_message()
    messages.send_image_message()

Enviar uma mensagem de mídia de áudio para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp de imagem para usuários do WhatsApp. Para enviar mensagens inseridas de imagem abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de áudio a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Um exemplo de media_uri usado no envio de mensagem de WhatsApp de mídia.

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

Para executar send_text_message(), atualize o método principal

    # Calling send_image_message()
    messages.send_image_message()

Enviar uma mensagem de mídia de vídeo para um usuário do WhatsApp

O SDK de Mensagens permite que a Contoso envie mensagens de WhatsApp de imagem para usuários do WhatsApp. Para enviar mensagens inseridas de imagem abaixo, os detalhes são necessários:

Importante

Para enviar uma mensagem de vídeo a um usuário do WhatsApp, o usuário do WhatsApp deve primeiro enviar uma mensagem para a conta do WhatsApp Business. Para obter mais informações, consulte Começar a enviar mensagens entre empresas e usuários do WhatsApp.

Um exemplo de media_uri usado no envio de mensagem de WhatsApp de mídia.

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

Para executar send_text_message(), atualize o método principal

    # Calling send_image_message()
    messages.send_image_message()

Executar o código

Para executar o código, verifique se você está no diretório onde está o arquivo 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>>

Exemplo de código 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()

Observação

Atualize todas as variáveis de espaço reservado no código acima.

Outros exemplos

Você pode examinar e baixar outros códigos de exemplo para o SDK de Mensagens do Python no GitHub.

Próximas etapas

Neste início rápido, você experimentou o SDK de Mensagens Avançadas para WhatsApp. Em seguida, talvez também seja interessante conferir os seguintes artigos: