Compartilhar via

Enviar mensagens de modelo do WhatsApp usando as Mensagens Avançadas

Este artigo descreve como enviar mensagens de modelo do WhatsApp usando o SDK de Mensagens de Comunicação Avançada.

Pré-requisitos

Modelo de objeto

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

Nome da Classe Descrição
NotificationMessagesClient Conecta-se ao seu recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Define o modelo que você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.

Observação

Para obter mais informações, consulte a referência do Azure SDK para .NET Namespace Azure.Communication.Messages.

Tipos de modelo do WhatsApp com suporte

Tipo do modelo Descrição
Modelos de mensagem baseados em texto Os modelos de mensagem do WhatsApp são formatos de mensagem específicos com ou sem parâmetros.
Modelos de mensagem baseados em mídia Modelos de mensagem do WhatsApp com parâmetros de mídia para componentes de cabeçalho.
Modelos de mensagens interativas Modelos de mensagens interativas expandem o conteúdo que você pode enviar aos destinatários, incluindo botões interativos usando o objeto de componentes. Há suporte para chamada a ação e resposta rápida.
Modelos de mensagem baseados em localização Modelos de mensagem do WhatsApp com parâmetros de localização em termos Longitude e Latitude para componentes de cabeçalho.

Configuração comum

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

Criar e gerenciar mensagem de modelo do WhatsApp

Os modelos de mensagem do WhatsApp são formatos de mensagem específicos que as empresas usam para enviar notificações ou mensagens de atendimento ao cliente para pessoas que optaram por notificações. As mensagens podem incluir lembretes de compromisso, informações de envio, resolução de problemas ou atualizações de pagamento. Antes de começar a usar o SDK de Mensagens Avançadas para enviar mensagens modeladas, o usuário precisa criar modelos necessários na Plataforma de Negócios do WhatsApp.

Para obter mais informações sobre os requisitos do WhatsApp para modelos, consulte as referências à API da Plataforma de Negócios do WhatsApp:

Autenticar o cliente

O SDK de Mensagens usa o NotificationMessagesClient para enviar mensagens. O método NotificationMessagesClient autentica 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 strings de conexão, veja access-your-connection-strings-and-service-endpoints.

Para simplificar, este artigo 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

Você criou o GUID da ID de registro do canal durante o registro do canal. Encontre-o no portal na guia Canais do seu recurso dos 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 ativo associado a uma conta do WhatsApp. Essa conta do WhatsApp recebe o modelo, o texto e as mensagens de mídia enviadas neste início rápido.

Para esse exemplo, você pode usar 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/região. Para obter mais informações sobre a formatação de números de telefone, confira a documentação do WhatsApp para Formatos de números 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.

Uma empresa não pode iniciar uma conversa interativa. Uma empresa só pode enviar uma mensagem interativa após receber uma mensagem do usuário. A empresa só pode enviar mensagens interativas ao usuário durante a conversa ativa. Após o término da janela de conversa de 24 horas, somente o usuário poderá reiniciar a conversa interativa. Para mais informações sobre conversas, confira a definição na Plataforma do WhatsApp Business.

Para iniciar uma conversa interativa na sua conta pessoal do WhatsApp, envie uma mensagem para o seu 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.

Configurar o ambiente

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 de 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 - Advanced Messages quickstart samples.");

            // Quickstart code goes here
        }
    }
}

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

using Azure.Communication.Messages;

Exemplos de código

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

Listar modelos do WhatsApp

A lista de modelos pode ser exibida no portal do Azure ou no WhatsApp Manager ou usando o SDK. Todas as opções são listadas da seguinte maneira:

É possível exibir seus modelos no portal do Azure acessando o recurso de >Mensagens Avançadas>Modelos do Serviço de Comunicação do Azure.

Captura de tela mostrando um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia Modelos > Mensagem avançada.

Selecione um modelo para exibir os detalhes.

O campo content dos detalhes do modelo pode incluir associações de parâmetros. As associações de parâmetro podem ser indicadas como:

  • Um campo format com um valor como IMAGE.
  • Colchetes duplos ao redor de um número, como {{1}}. O número, indexado iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem.

Captura de tela mostrando os detalhes do modelo.

Como alternativa, você poderá exibir e editar todos os modelos da sua conta Comercial do WhatsApp nas ferramentas da conta do Gerenciador de WhatsApp> e dos >Modelos de mensagens.

Para listar seus modelos de forma programática, você pode buscar todos os modelos para a ID do seu canal da seguinte forma:

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

Enviar mensagem de modelo sem parâmetros

Se o modelo não exigir parâmetros, você não precisará fornecer valores ou associações ao criar o MessageTemplate.

var messageTemplate = new MessageTemplate(templateName, templateLanguage);

Exemplo

O sample_template não usa nenhum parâmetro.

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_template.

Monte o MessageTemplate referenciando o nome e o idioma do modelo de destino.

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

var sampleTemplate = new MessageTemplate(templateName, templateLanguage);

Enviar mensagem de modelo com parâmetros de texto no corpo

Use MessageTemplateText para definir parâmetros no corpo indicados com colchetes duplos ao redor de um número, como {{1}}. O número, com índice iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem. A inclusão de parâmetros que não estão no modelo é inválida.

Definição de modelo com dois parâmetros:

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

Exemplos

Modelo sample_shipping_confirmation:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_shipping_confirmation.

Neste exemplo, o corpo do modelo tem um parâmetro:

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

Os parâmetros são definidos com os valores MessageTemplateValue e as associações de MessageTemplateWhatsAppBindings. Use os valores e as associações para montar o MessageTemplate.

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

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

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

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

Enviar mensagem de modelo com o parâmetro de mídia no cabeçalho

Use MessageTemplateImage, MessageTemplateVideo, ou MessageTemplateDocument para definir o parâmetro de mídia em um cabeçalho.

Definição de modelo com parâmetro de mídia de imagem no cabeçalho:

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

O format pode ter diferentes tipos de mídia com suporte pelo WhatsApp. No SDK do .NET, cada tipo de mídia usa um tipo MessageTemplateValue correspondente.

Formatar Tipo MessageTemplateValue Tipo de arquivo
IMAGE MessageTemplateImage png, jpg
VIDEO MessageTemplateVideo mp4
DOCUMENT MessageTemplateDocument Pdf

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

Assembly de modelo de mensagem para mídia de imagem:

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

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

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

Exemplos

Modelo sample_movie_ticket_confirmation:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_movie_ticket_confirmation.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer quatro parâmetros de texto:

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

Crie uma MessageTemplateImage e quatro variáveis MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo.

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

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

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

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

Mais exemplos

Enviar mensagem de modelo com o local no cabeçalho

Use MessageTemplateLocation para definir o parâmetro de localização em um cabeçalho.

Definição de modelo para o componente de cabeçalho que requer a localização como:

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

O format pode exigir diferentes tipos de mídia. No SDK do .NET, cada tipo de mídia usa um tipo MessageTemplateValue correspondente.

Propriedades Descrição Tipo
ADDRESS Endereço que aparece após o valor NAME, abaixo do mapa genérico na parte superior da mensagem. cadeia de caracteres
LATITUDE Latitude da localização. duplo
LONGITUDE Longitude da localização. duplo
LOCATIONNAME Texto que aparece logo abaixo do mapa genérico na parte superior da mensagem. cadeia de caracteres

Para obter mais informações sobre modelos baseados em localização, confira a documentação do WhatsApp para mídias de mensagens.

Exemplo

Modelo sample_movie_location:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_location_template.

Montagem de modelo de mensagem baseada em localização:

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

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

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

Enviar mensagem de modelo com botões de resposta rápida

Use MessageTemplateQuickAction para definir a carga para botões de resposta rápida e os objetos MessageTemplateQuickAction têm os três atributos a seguir.

Propriedades Descrição Tipo
Nome O name é usado para pesquisar o valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto A ação rápida text opcional. cadeia de caracteres
Conteúdo O Atribuído(a) a payload, um botão estará disponível em uma resposta de mensagem se o usuário selecionar o botão. cadeia de caracteres

Definição de modelo com botões de resposta rápida:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Para obter mais informações sobre o conteúdo nas respostas rápidas do usuário, confira a documentação do WhatsApp para Retorno de Chamada Recebido de um Botão de Resposta Rápida.

Exemplo

Modelo sample_issue_resolution:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_issue_resolution.

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui dois botões de resposta pré-preenchidos, Yes e No.

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

Crie uma MessageTemplateText e duas variáveis MessageTemplateQuickAction. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

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

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

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

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

Use MessageTemplateQuickAction para definir o sufixo de URL para botões de chamada à ação e o objeto MessageTemplateQuickAction tem os dois atributos a seguir.

Propriedades Descrição Tipo
Nome O name é usado para pesquisar o valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto O text que é acrescentado ao URL. cadeia de caracteres

Botões de definição de modelo:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Exemplo

Modelo sample_purchase_feedback:

Esse modelo de exemplo adiciona um botão com um link de URL dinâmico à mensagem. Também usa uma imagem no cabeçalho e um parâmetro de texto no corpo.

Captura de tela do painel de ação Chamar para o Editor de botões do gerenciador do WhatsApp que mostra o botão Tipo de URL que você pode usar para escolher entre Estático e Dinâmico.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui um botão de URL dinâmico com um parâmetro:

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

Crie uma MessageTemplateImage, uma MessageTemplateTexte uma variável MessageTemplateQuickAction. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

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

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

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

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

Para links estáticos, você não precisa incluir MessageTemplateQuickAction o modelo porque o modelo do WhatsApp tem um link estático CallToAction sem nenhuma entrada necessária do usuário.

Botões de definição de modelo:

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

Exemplo

Modelo purchase_feedback_static:

Esse modelo de exemplo adiciona um botão com um link de URL estático à mensagem. Também usa uma imagem no cabeçalho e um parâmetro de texto no corpo.

Captura de tela que mostra detalhes para o modelo estático de feedback de compra.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui um botão de URL dinâmico com um parâmetro:

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

Crie um MessageTemplateImage, um MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

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

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

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

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

Enviar mensagem de modelo de autenticação

Este modelo de exemplo envia uma mensagem de modelo de autenticação com botões de senha de uso único. Para obter mais informações, consulte o artigo da API de Modelos de Autenticação do Facebook Enviando Modelos de Autenticação.

Exemplo

auth_sample_template modelo no portal do Azure:

Captura de tela que mostra detalhes do modelo de autenticação.

O json de modelo tem esta aparência:

[
  {
    "type": "BODY",
    "text": "*{{1}}* is your verification code.",
    "add_security_recommendation": false,
    "example": {
      "body_text": [
        [
          "123456"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "URL",
        "text": "Copy code",
        "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}",
        "example": [
          "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456"
        ]
      }
    ]
  }
]

Criar um MessageTemplateText, um MessageTemplateQuickAction params. Em seguida, monte sua lista de valores de parâmetros e seus WhatsAppMessageTemplateBindingsButton fornecendo os parâmetros na ordem em que os parâmetros aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

  // Send auth sample template message
  string templateNameWithauth = "auth_sample_template";
  string oneTimePassword = "3516517";
  var messageTemplateWithAuth = new MessageTemplate(templateNameWithauth, templateLanguage);
  WhatsAppMessageTemplateBindings auth_bindings = new();
  var bodyParam2 = new MessageTemplateText(name: "code", text: oneTimePassword);
  var uri_to_copy = new MessageTemplateQuickAction("url") { Text = oneTimePassword };

  auth_bindings.Body.Add(new(bodyParam2.Name));
  auth_bindings.Buttons.Add(new WhatsAppMessageTemplateBindingsButton(WhatsAppMessageButtonSubType.Url.ToString(), uri_to_copy.Name));
  messageTemplateWithAuth.Values.Add(bodyParam2);
  messageTemplateWithAuth.Values.Add(uri_to_copy);
  messageTemplateWithAuth.Bindings = auth_bindings;

  TemplateNotificationContent templateContent5 =
      new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplateWithAuth);
  Response<SendMessageResult> sendTemplateMessageResult5 =
      notificationMessagesClient.Send(templateContent5);

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.

Caso não tenha uma conversa ativa, para fins deste exemplo, você poderá 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 especificado solicita entrada manual do usuário antes de enviar a próxima mensagem. Para obter mais informações, consulte o exemplo completo em Exemplo de código. Se tiver êxito, você receberá três mensagens na conta do WhatsApp do usuário.

Crie e execute o programa.

dotnet build
dotnet run

Exemplo de código completo

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

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

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

            NotificationMessagesClient notificationMessagesClient = new NotificationMessagesClient(connectionString);

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

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

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

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

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

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

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

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

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

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

            return new MessageTemplate(templateName, templateLanguage);
        }

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

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

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

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

            return shippingConfirmationTemplate;
        }

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

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

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

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

            return movieTicketConfirmationTemplate;
        }

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

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

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

            return happyHourAnnouncementTemplate;
        }

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

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

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

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

            return flightConfirmationTemplate;
        }

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

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

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

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

            return issueResolutionTemplate;
        }

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

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

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

            return purchaseFeedbackTemplate;
        }

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

Mais exemplos

Esses exemplos usam modelos de exemplos disponíveis para contas do WhatsApp Business criadas por meio da inscrição incorporada no portal do Azure.

Usar o modelo de exemplo sample_happy_hour_announcement

Esse modelo de exemplo usa um vídeo no cabeçalho e dois parâmetros de texto no corpo.

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_happy_hour_announcement.

O cabeçalho do modelo requer um vídeo:

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

O vídeo deve ser um URL para hospedar o vídeo mp4.

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

O corpo do modelo requer dois parâmetros de texto:

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

Crie uma MessageTemplateVideo e duas variáveis MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo.

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

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

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

Usar o modelo de exemplo sample_flight_confirmation

Esse modelo de exemplo usa um documento no cabeçalho e três parâmetros de texto no corpo.

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_flight_confirmation.

O cabeçalho do modelo requer um documento:

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

O documento deve ser um URL para o documento em PDF hospedado.

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

O corpo do modelo requer três parâmetros de texto:

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

Crie uma MessageTemplateDocument e três variáveis MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo.

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

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

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

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

Pré-requisitos

Modelo de objeto

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

Nome da Classe Descrição
NotificationMessagesClient Conecta-se ao seu recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Define o modelo que você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.

Observação

Para obter mais informações, confira a referência do SDK do Azure para Java em com.azure.communication.messages Pacote.

Tipos de modelo do WhatsApp com suporte

Tipo do modelo Descrição
Modelos de mensagem baseados em texto Os modelos de mensagem do WhatsApp são formatos de mensagem específicos com ou sem parâmetros.
Modelos de mensagem baseados em mídia Modelos de mensagem do WhatsApp com parâmetros de mídia para componentes de cabeçalho.
Modelos de mensagens interativas Modelos de mensagens interativas expandem o conteúdo que você pode enviar aos destinatários, incluindo botões interativos usando o objeto de componentes. Há suporte para chamada a ação e resposta rápida.
Modelos de mensagem baseados em localização Modelos de mensagem do WhatsApp com parâmetros de localização em termos Longitude e Latitude para componentes de cabeçalho.

Configuração comum

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

Criar e gerenciar mensagem de modelo do WhatsApp

Os modelos de mensagem do WhatsApp são formatos de mensagem específicos que as empresas usam para enviar notificações ou mensagens de atendimento ao cliente para pessoas que optaram por notificações. As mensagens podem incluir lembretes de compromisso, informações de envio, resolução de problemas ou atualizações de pagamento. Antes de começar a usar o SDK de Mensagens Avançadas para enviar mensagens modeladas, o usuário precisa criar modelos necessários na Plataforma de Negócios do WhatsApp.

Para obter mais informações sobre os requisitos do WhatsApp para modelos, consulte as referências à API da Plataforma de Negócios do WhatsApp:

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.

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 artigo 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. Esta conta do WhatsApp recebe as mensagens de texto e mídia enviadas neste artigo. Para este artigo, 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");

Configurar o ambiente

Para configurar um ambiente para enviar mensagens, conclua as etapas nas seções a seguir.

Pré-requisito

Criar um aplicativo Java

Abra um terminal ou janela de comando e navegue até o diretório onde deseja criar seu aplicativo Java. Execute o seguinte comando 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 o código-fonte do teste e o arquivo pom.xml é o Modelo de Objeto do Projeto (POM) 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>
</dependency>

Configurar o framework de aplicativos

Abra /src/main/java/com/communication/quickstart/App.java em um editor de texto, adicione as 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.
    }
}

Exemplos de código

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

Listar modelos do WhatsApp no portal do Azure

Para exibir seus modelos no portal do Azure, acesse seus o recurso de >Mensagens Avançadas>Modelos do Serviço de Comunicação do Azure.

Captura de tela mostrando um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia Modelos de mensagens avançadas.

Selecionando um modelo para exibir os detalhes do modelo.

O campo Conteúdo dos detalhes do modelo pode incluir associações de parâmetros. As associações de parâmetro podem ser indicadas como:

  • Um campo "format" com um valor como IMAGE.
  • Colchetes duplos ao redor de um número, como {{1}}. O número, com índice iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem.

Captura de tela mostrando os detalhes do modelo.

Como alternativa, você poderá exibir e editar todos os modelos da sua conta Comercial do WhatsApp nas ferramentas da conta do Gerenciador de WhatsApp> e dos >Modelos de mensagens.

Para listar seus modelos de forma programática, você pode buscar todos os modelos para a ID do seu canal usando o seguinte código:

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

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

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

Enviar mensagem de modelo com parâmetros de texto no corpo

Se o modelo não aceitar parâmetros, você não precisará fornecer nenhum valor ou vinculação ao criar o MessageTemplate.

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

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

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

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

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

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

Enviar mensagem de modelo com o parâmetro de mídia no cabeçalho

Use MessageTemplateImage, MessageTemplateVideo, ou MessageTemplateDocument para definir o parâmetro de mídia em um cabeçalho.

Definição de modelo com parâmetro de mídia de imagem no cabeçalho:

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

O "format" pode ser de quatro tipos de mídia diferentes compatíveis com o WhatsApp. No SDK do .NET, cada tipo de mídia usa um tipo MessageTemplateValue correspondente.

Formatar Tipo MessageTemplateValue Tipo de arquivo
IMAGEM MessageTemplateImage png, jpg
VÍDEO MessageTemplateVideo mp4
DOCUMENTO MessageTemplateDocument Pdf

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

Exemplo

Modelo sample_happy_hour_announcement:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_happy_hour_announcement.

Aqui, o cabeçalho do modelo requer um vídeo:

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

O vídeo deve ser um URL para um vídeo mp4 hospedado.

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

O corpo do modelo requer dois parâmetros de texto:

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

Crie uma MessageTemplateVideo e quatro variáveis MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo.

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

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

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

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

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

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

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

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

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

Enviar mensagem de modelo com botões de resposta rápida

Use MessageTemplateQuickAction para definir a carga para botões de resposta rápida e os objetos MessageTemplateQuickAction têm os três atributos a seguir.

Propriedades Descrição Tipo
Nome O name é usado para pesquisar o valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto A opção ação rápida text. cadeia de caracteres
Conteúdo O Atribuído(a) a payload, um botão estará disponível em uma resposta de mensagem se o usuário selecionar o botão. cadeia de caracteres

Definição de modelo com botões de resposta rápida:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Para obter mais informações sobre o conteúdo nas respostas rápidas do usuário, confira a documentação do WhatsApp para Retorno de Chamada Recebido de um Botão de Resposta Rápida.

Exemplo

Modelo sample_issue_resolution:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_issue_resolution.

O corpo do modelo requer um parâmetro de texto:

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

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

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

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

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

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

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

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

Use MessageTemplateQuickAction para definir o sufixo de URL para botões de chamada à ação e o objeto MessageTemplateQuickAction tem os dois atributos a seguir.

Propriedades Descrição Tipo
Nome O name é usado para pesquisar o valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto O text acréscimo ao URL. cadeia de caracteres

Botões de definição de modelo:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Exemplo

Modelo sample_purchase_feedback:

Esse modelo de exemplo adiciona um botão com um link de URL dinâmico à mensagem. Também usa uma imagem no cabeçalho e um parâmetro de texto no corpo.

Captura de tela mostrando a edição do Tipo de URL no gerenciador do WhatsApp.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui um botão de URL dinâmico com um parâmetro:

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

Crie uma MessageTemplateImage, uma MessageTemplateTexte uma variável MessageTemplateQuickAction. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

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

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

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

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

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

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

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

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

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

Executar o código

  1. Abra 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

Modelo de objeto

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

Nome da Classe Descrição
NotificationMessagesClient Conecta-se ao seu recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Define o modelo que você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.

Observação

Para obter mais informações, consulte o pacote de referência do SDK do Azure para JavaScript @Azure-rest/communication-messages

Tipos de modelo do WhatsApp com suporte

Tipo do modelo Descrição
Modelos de mensagem baseados em texto Os modelos de mensagem do WhatsApp são formatos de mensagem específicos com ou sem parâmetros.
Modelos de mensagem baseados em mídia Modelos de mensagem do WhatsApp com parâmetros de mídia para componentes de cabeçalho.
Modelos de mensagens interativas Modelos de mensagens interativas expandem o conteúdo que você pode enviar aos destinatários, incluindo botões interativos usando o objeto de componentes. Há suporte para chamada a ação e resposta rápida.
Modelos de mensagem baseados em localização Modelos de mensagem do WhatsApp com parâmetros de localização em termos Longitude e Latitude para componentes de cabeçalho.

Configuração comum

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

Criar e gerenciar mensagem de modelo do WhatsApp

Os modelos de mensagem do WhatsApp são formatos de mensagem específicos que as empresas usam para enviar notificações ou mensagens de atendimento ao cliente para pessoas que optaram por notificações. As mensagens podem incluir lembretes de compromisso, informações de envio, resolução de problemas ou atualizações de pagamento. Antes de começar a usar o SDK de Mensagens Avançadas para enviar mensagens modeladas, o usuário precisa criar modelos necessários na Plataforma de Negócios do WhatsApp.

Para obter mais informações sobre os requisitos do WhatsApp para modelos, consulte as referências à API da Plataforma de Negócios do WhatsApp:

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.

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 artigo 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 instanciar um NotificationClient, adicione o seguinte código ao método Main:

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

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

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

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 artigo. Para este artigo, 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"];

Configurando

Para configurar um ambiente para enviar mensagens, conclua as etapas nas seções a seguir.

Criar um novo aplicativo do Node.js

  1. Crie um novo diretório para seu aplicativo e abra-o em um terminal ou janela de comando.

  2. Execute o comando a seguir.

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

  3. Execute o seguinte comando para criar um arquivo package.json com as configurações padrão.

    npm init -y

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

  5. Adicione o seguinte trecho de código 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);
});

Preencha a seção a seguir para adicionar seu código-fonte para esse exemplo 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.

Exemplos de código

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

Listar modelos do WhatsApp no portal do Azure

Para exibir seus modelos no portal do Azure, acesse seus o recurso de >Mensagens Avançadas>Modelos do Serviço de Comunicação do Azure.

Captura de tela mostrando um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia Modelos de mensagens avançadas.

Selecionando um modelo para exibir os detalhes do modelo.

O campo Conteúdo dos detalhes do modelo pode incluir associações de parâmetros. As associações de parâmetro podem ser indicadas como:

  • Um campo "format" com um valor como IMAGE.
  • Colchetes duplos ao redor de um número, como {{1}}. O número, com índice iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem.

Captura de tela mostrando os detalhes do modelo.

Como alternativa, você poderá exibir e editar todos os modelos da sua conta Comercial do WhatsApp nas ferramentas da conta do Gerenciador de WhatsApp> e dos >Modelos de mensagens.

Para listar seus modelos de forma programática, você pode buscar todos os modelos para a ID do seu canal usando o seguinte código:

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

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

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

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

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

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

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

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

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

Enviar mensagem de modelo com parâmetros de texto no corpo

Modelo sample_shipping_confirmation:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_shipping_confirmation.

Neste exemplo, o corpo do modelo tem um parâmetro:

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

Os parâmetros são definidos com os valores values e as associações de bindings. Use os valores e as associações para montar o objeto template.

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

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

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

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

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

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

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

  const client = NotificationClient(endpoint, credential);

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

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

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

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

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

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

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

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

module.exports = { main };

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

Encontre o código finalizado para esse exemplo em GitHub.

Pré-requisitos

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 da Classe Descrição
NotificationMessagesClient Conecta-se ao seu recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
MessageTemplate Define o modelo que você usa e o conteúdo das propriedades do modelo para sua mensagem.
TemplateNotificationContent Define o "quem" e o "o quê" da mensagem de modelo que você pretende enviar.

Observação

Para obter mais informações, veja a referência do SDK do Azure para Python Pacote de mensagens.

Tipos de modelo do WhatsApp com suporte

Tipo do modelo Descrição
Modelos de mensagem baseados em texto Os modelos de mensagem do WhatsApp são formatos de mensagem específicos com ou sem parâmetros.
Modelos de mensagem baseados em mídia Modelos de mensagem do WhatsApp com parâmetros de mídia para componentes de cabeçalho.
Modelos de mensagens interativas Modelos de mensagens interativas expandem o conteúdo que você pode enviar aos destinatários, incluindo botões interativos usando o objeto de componentes. Há suporte para chamada a ação e resposta rápida.
Modelos de mensagem baseados em localização Modelos de mensagem do WhatsApp com parâmetros de localização em termos Longitude e Latitude para componentes de cabeçalho.

Configuração comum

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

Criar e gerenciar mensagem de modelo do WhatsApp

Os modelos de mensagem do WhatsApp são formatos de mensagem específicos que as empresas usam para enviar notificações ou mensagens de atendimento ao cliente para pessoas que optaram por notificações. As mensagens podem incluir lembretes de compromisso, informações de envio, resolução de problemas ou atualizações de pagamento. Antes de começar a usar o SDK de Mensagens Avançadas para enviar mensagens modeladas, o usuário precisa criar modelos necessários na Plataforma de Negócios do WhatsApp.

Para obter mais informações sobre os requisitos do WhatsApp para modelos, consulte as referências à API da Plataforma de Negócios do WhatsApp:

Autenticar o cliente

O envio de mensagens usa NotificationMessagesClient. NotificationMessagesClient autentica usando sua cadeia de conexão adquirida do recurso 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

Você criou o GUID da ID de registro do canal durante o registro do canal. Encontre-o no portal na guia Canais do seu recurso dos 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 ativo associado a uma conta do WhatsApp. Essa conta do WhatsApp recebe o modelo, o texto e as mensagens de mídia enviadas neste artigo.

Para esse exemplo, você pode usar 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/região. Para obter mais informações sobre a formatação de números de telefone, confira a documentação do WhatsApp para Formatos de números 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.

Uma empresa não pode iniciar uma conversa interativa. Uma empresa só pode enviar uma mensagem interativa após receber uma mensagem do usuário. A empresa só pode enviar mensagens interativas ao usuário durante a conversa ativa. Após o término da janela de conversa de 24 horas, somente o usuário poderá reiniciar a conversa interativa. Para mais informações sobre conversas, confira a definição na Plataforma do WhatsApp Business.

Para iniciar uma conversa interativa na sua conta pessoal do WhatsApp, envie uma mensagem para o seu 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.

Configurar o ambiente

Criar um novo aplicativo Python

Em um terminal ou janela do console, crie uma nova pasta para seu aplicativo e abra-a.

mkdir messages-quickstart && cd messages-quickstart

Instalar o pacote

Use a biblioteca de clientes de Mensagens de Comunicação do Azure para Python 1.1.0 ou superior.

No prompt do console, execute o seguinte comando:

pip install azure-communication-messages

Para InteractiveMessages, Reações e Adesivos, use a versão Beta abaixo:

pip install azure-communication-messages==1.2.0b1

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

Estrutura básica do programa

import os

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

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

Exemplos de código

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

Listar modelos do WhatsApp no portal do Azure

É possível exibir seus modelos no portal do Azure acessando o recurso de >Mensagens Avançadas>Modelos do Serviço de Comunicação do Azure.

Captura de tela mostrando um recurso dos Serviços de Comunicação do Azure no portal do Azure, exibindo a guia 'Modelos'.

Selecione um modelo para exibir os detalhes do modelo.

O campo content dos detalhes do modelo pode incluir associações de parâmetros. As associações de parâmetro podem ser indicadas como:

  • Um campo format com um valor como IMAGE.
  • Colchetes duplos ao redor de um número, como {{1}}. O número, com índice iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem.

Captura de tela mostrando os detalhes do modelo.

Como alternativa, você pode exibir e editar todos os modelos da sua conta do WhatsApp Business nas ferramentas da conta do WhatsApp Manager> e dos >Modelos de mensagens.

Para listar seus modelos de forma programática, você pode buscar todos os modelos para a ID do seu canal da seguinte forma:

def get_templates_list(self):

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

Enviar mensagem de modelo sem parâmetros

Se o modelo não aceitar parâmetros, você não precisará fornecer os valores ou associações ao criar o MessageTemplate.

Exemplo

O sample_template não tem parâmetros.

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_template.

Monte o MessageTemplate referenciando o nome e o idioma do modelo de destino.

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

Enviar mensagem de modelo com parâmetros de texto no corpo

Use MessageTemplateText para definir parâmetros no corpo indicados com colchetes duplos ao redor de um número, como {{1}}. O número, com índice iniciado em 1, indica a ordem na qual os valores de associação devem ser fornecidos para criar o modelo de mensagem. A tentativa de incluir parâmetros que não estão no modelo é inválida.

Definição de modelo com dois parâmetros:

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

Exemplos

Modelo sample_shipping_confirmation:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_shipping_confirmation.

Neste exemplo, o corpo do modelo tem um parâmetro:

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

Defina parâmetros usando os valores MessageTemplateValue e as associações MessageTemplateWhatsAppBindings. Use os valores e as associações para montar o MessageTemplate.

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

Enviar mensagem de modelo com o parâmetro de mídia no cabeçalho

Use MessageTemplateImage, MessageTemplateVideo, ou MessageTemplateDocument para definir o parâmetro de mídia em um cabeçalho.

Definição de modelo com parâmetro de mídia de imagem no cabeçalho:

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

O format pode ter diferentes tipos de mídia com suporte pelo WhatsApp. No SDK do .NET, cada tipo de mídia usa um tipo MessageTemplateValue correspondente.

Formatar Tipo MessageTemplateValue Tipo de arquivo
IMAGEM MessageTemplateImage png, jpg
VÍDEO MessageTemplateVideo mp4
DOCUMENTO MessageTemplateDocument Pdf

Para obter mais informações sobre os tipos de mídia com suporte e limites de tamanho, confira a documentação do WhatsApp para mídias de mensagens.

Exemplos

Modelo sample_movie_ticket_confirmation:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_movie_ticket_confirmation.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer quatro parâmetros de texto:

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

Crie uma MessageTemplateImage e quatro variáveis MessageTemplateText. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo.

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

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

Enviar mensagem de modelo com botões de resposta rápida

Use MessageTemplateQuickAction para definir a carga para botões de resposta rápida e os objetos MessageTemplateQuickAction têm os três atributos a seguir.

Propriedades Descrição Tipo
Nome A name pesquisa do valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto A opção ação rápida text. cadeia de caracteres
Conteúdo O Atribuído(a) a payload, um botão estará disponível em uma resposta de mensagem se o usuário selecionar o botão. cadeia de caracteres

Definição de modelo com botões de resposta rápida:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Para obter mais informações sobre o conteúdo nas respostas rápidas do usuário, confira a documentação do WhatsApp para Retorno de Chamada Recebido de um Botão de Resposta Rápida.

Exemplo

Modelo sample_issue_resolution:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_issue_resolution.

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui dois botões de resposta pré-preenchidos, Yes e No.

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

Crie uma MessageTemplateText e duas variáveis MessageTemplateQuickAction. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões de suas associações.

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

Enviar mensagem de modelo com o local no cabeçalho

Use MessageTemplateLocation para definir o parâmetro de localização em um cabeçalho.

Definição de modelo para o componente de cabeçalho que requer a localização como:

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

O format pode exigir diferentes tipos de mídia. No SDK do .NET, cada tipo de mídia usa um tipo MessageTemplateValue correspondente.

Propriedades Descrição Tipo
ADDRESS Endereço que aparece após o valor NAME, abaixo do mapa genérico na parte superior da mensagem. cadeia de caracteres
LATITUDE Latitude da localização. duplo
LONGITUDE Longitude da localização. duplo
LOCATIONNAME Texto que aparece logo abaixo do mapa genérico na parte superior da mensagem. cadeia de caracteres

Para obter mais informações sobre modelos baseados em localização, confira a documentação do WhatsApp para mídias de mensagens.

Exemplo

Modelo sample_movie_location:

Captura de tela mostrando detalhes do modelo para o modelo denominado sample_location_template.

Montagem de modelo de mensagem baseada em localização:

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

Use MessageTemplateQuickAction para definir o sufixo de URL para botões de chamada à ação e o objeto MessageTemplateQuickAction tem os dois atributos a seguir.

Propriedades Descrição Tipo
Nome O name é usado para pesquisar o valor em MessageTemplateWhatsAppBindings. cadeia de caracteres
Texto O text acréscimo ao URL. cadeia de caracteres

Botões de definição de modelo:

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

A ordem em que os botões aparecem na definição de modelo deve corresponder à ordem em que os botões são definidos ao criar as associações com o MessageTemplateWhatsAppBindings.

Exemplo

Modelo sample_purchase_feedback:

Esse modelo de exemplo adiciona um botão com um link de URL dinâmico à mensagem. Também usa uma imagem no cabeçalho e um parâmetro de texto no corpo. Crie modelos de botão de chamada para ação com tipo de URL Dynamic para tipo de ação View website.

Captura de tela mostrando a edição do Tipo de URL no gerenciador do WhatsApp.

Neste exemplo, o cabeçalho do modelo requer uma imagem:

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

O corpo do modelo requer um parâmetro de texto:

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

O modelo inclui um botão de URL dinâmico com um parâmetro:

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

Crie uma MessageTemplateImage, uma MessageTemplateTexte uma variável MessageTemplateQuickAction. Em seguida, monte sua lista de MessageTemplateValue e seu MessageTemplateWhatsAppBindings fornecendo os parâmetros na ordem em que aparecem no conteúdo do modelo. A ordem também é importante ao definir os botões da associação.

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

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

Exemplo completo

import os
import sys

sys.path.append("..")

class SendWhatsAppTemplateMessageSample(object):

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

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

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

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

    def send_template_message_with_parameters(self):

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

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

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

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

    def send_template_message_with_media(self):

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

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

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

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

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

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

    def send_template_message_with_buttons(self):

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

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

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

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

    def send_template_message_with_location(self):

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

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

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

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

    def send_template_message_with_call_to_action(self):

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

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

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

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

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

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

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

Próximas etapas