Compartilhar via

Início Rápido: baixar a mídia de mensagens do WhatsApp

Os Serviços de Comunicação do Azure permitem que você envie e receba mensagens do WhatsApp. Este artigo descreve como baixar a carga de mídia recebida em uma mensagem do WhatsApp.

Caso de uso: uma empresa recebe uma mensagem do WhatsApp de seu cliente que contém uma imagem. A empresa precisa baixar a imagem do WhatsApp para visualizá-la.

As mensagens de entrada para a empresa são publicadas como a Grade de Eventos Microsoft.Communication.AdvancedMessageReceived. Este exemplo usa a ID de mídia e o tipo MIME de mídia no evento AdvancedMessageReceived para baixar o conteúdo da mídia.

Um exemplo de um evento AdvancedMessageReceived com conteúdo de mídia:

[{
  "id": "00000000-0000-0000-0000-000000000000",
  "topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
  "subject": "advancedMessage/sender/{sender@id}/recipient/11111111-1111-1111-1111-111111111111",
  "data": {
    "channelType": "whatsapp",
    "media": {
      "mimeType": "image/jpeg",
      "id": "22222222-2222-2222-2222-222222222222"
    },
    "from": "{sender@id}",
    "to": "11111111-1111-1111-1111-111111111111",
    "receivedTimestamp": "2023-07-06T18:30:19+00:00"
  },
  "eventType": "Microsoft.Communication.AdvancedMessageReceived",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2023-07-06T18:30:22.1921716Z"
}]

Pré-requisitos

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;

Modelo de objeto

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

Nome Descrição
NotificationMessagesClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
DownloadMediaAsync Baixe o conteúdo de mídia de uma mensagem de Usuário para Empresas de forma assíncrona, gravando o conteúdo em um fluxo.
DownloadMediaToAsync Baixe o conteúdo de mídia de uma mensagem de Usuário para Empresas de forma assíncrona, gravando o conteúdo em um arquivo.
Microsoft.Communication.AdvancedMessageReceived Evento da Grade de Eventos que é publicado quando a Advanced Messaging recebe uma mensagem.

Configuração comum

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

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 do 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. Para obter mais informações sobre a formatação de números de telefone, consulte 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, veja a definição em WhatsApp Business Platform.

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.

Exemplos de código

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

Baixar o conteúdo de mídia em um fluxo

O SDK de Mensagens permite que a Contoso baixe a mídia em mensagens de mídia recebidas do WhatsApp de usuários do WhatsApp. Para baixar o conteúdo de mídia em um fluxo, você precisa:

Defina a ID de mídia da mídia que você deseja buscar.

// MediaId GUID of the media received in an incoming message.
// Ex. "00000000-0000-0000-0000-000000000000"
var mediaId = "<MediaId>";

Baixe a mídia para o fluxo de destino.

// Download media to stream
Response<Stream> fileResponse = await notificationMessagesClient.DownloadMediaAsync(mediaId);

O conteúdo da mídia agora está disponível no fluxo de resposta.

Continue com este exemplo para gravar o fluxo em um arquivo.

A ID de mídia e o tipo MIME do conteúdo estão disponíveis no conteúdo de mídia do evento AdvancedMessageReceived. No entanto, ao baixar a mídia para um fluxo, o tipo MIME estará novamente disponível para você nos cabeçalhos de resposta no Response<Stream>.

Em ambos os casos, você precisa converter o tipo MIME em um tipo de arquivo. Defina este auxiliar para a conversão.

private static string GetFileExtension(string contentType)
{
    return MimeTypes.TryGetValue(contentType, out var extension) ? extension : string.Empty;
}

private static readonly Dictionary<string, string> MimeTypes = new Dictionary<string, string>
{
    { "application/pdf", ".pdf" },
    { "image/jpeg", ".jpg" },
    { "image/png", ".png" },
    { "video/mp4", ".mp4" },
    // Add more mappings as needed
};

Defina o local do arquivo em que você deseja gravar a mídia. Este exemplo usa o tipo MIME retornado nos cabeçalhos de resposta de DownloadMediaAsync.

// File extension derived from the MIME type in the response headers.
// Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
var contentType = fileResponse.GetRawResponse().Headers.ContentType;
string fileExtension = GetFileExtension(contentType);

// File location to write the media. 
// Ex. @"c:\temp\media.jpg"
string filePath = @"<FilePath>" + "<FileName>" + fileExtension;

Escreva o fluxo no arquivo.

 // Write the media stream to the file
using (Stream outStream = File.OpenWrite(filePath))
{
    fileResponse.Value.CopyTo(outStream);
}

Baixar o conteúdo da mídia em um arquivo

O SDK de Mensagens permite que a Contoso baixe a mídia em mensagens de mídia do WhatsApp recebidas de usuários do WhatsApp. Para baixar o conteúdo de mídia em um arquivo, você precisa:

Defina a ID da mídia que você deseja buscar e o local do arquivo onde deseja gravar a mídia.

// MediaId GUID of the media received in an incoming message.
// Ex. "00000000-0000-0000-0000-000000000000"
var mediaId = "<MediaId>";

// File extension derived from the MIME type received in an incoming message
// Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
string fileExtension = "<FileExtension>";
// File location to write the media. 
// Ex. @"c:\temp\media.jpg"
string filePath = @"<FilePath>" + "<FileName>" + fileExtension;

Baixe a mídia para o caminho de destino.

// Download media to file
Response response = await notificationMessagesClient.DownloadMediaToAsync(mediaId, filePath);

Executar o código

Crie e execute o programa.

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

Exemplo de código completo

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

namespace AdvancedMessagingDownloadMediaQuickstart
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Download WhatsApp message media");

            // Authenticate the client
            string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
            NotificationMessagesClient notificationMessagesClient =
                new NotificationMessagesClient(connectionString);

            await DownloadMediaWithStreamAsync(notificationMessagesClient);
            await DownloadMediaToFileAsync(notificationMessagesClient);

            Console.WriteLine("\n\nPress any key to exit.");
            Console.ReadKey();
        }

        public static async Task DownloadMediaWithStreamAsync(NotificationMessagesClient notificationMessagesClient)
        {
            // MediaId GUID of the media received in an incoming message.
            // Ex. "00000000-0000-0000-0000-000000000000"
            var mediaId = "<MediaId>";

            Response<Stream> fileResponse;
            try
            {
                // Download media to stream
                fileResponse = await notificationMessagesClient.DownloadMediaAsync(mediaId);

                Console.WriteLine(fileResponse.ToString());
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine(e);
                return;
            }

            // File extension derived from the MIME type in the response headers.
            // Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
            var contentType = fileResponse.GetRawResponse().Headers.ContentType;
            string fileExtension = GetFileExtension(contentType);

            // File location to write the media. 
            // Ex. @"c:\temp\media.jpg"
            string filePath = @"<FilePath>" + "<FileName>" + fileExtension;
            Console.WriteLine(filePath);

            // Write the media stream to the file
            using (Stream outStream = File.OpenWrite(filePath))
            {
                fileResponse.Value.CopyTo(outStream);
            }
        }

        private static string GetFileExtension(string contentType)
        {
            return MimeTypes.TryGetValue(contentType, out var extension) ? extension : string.Empty;
        }

        private static readonly Dictionary<string, string> MimeTypes = new Dictionary<string, string>
        {
            { "application/pdf", ".pdf" },
            { "image/jpeg", ".jpg" },
            { "image/png", ".png" },
            { "video/mp4", ".mp4" },
            // Add more mappings as needed
        };

        public static async Task DownloadMediaToFileAsync(NotificationMessagesClient notificationMessagesClient)
        {
            // MediaId GUID of the media received in an incoming message.
            // Ex. "00000000-0000-0000-0000-000000000000"
            var mediaId = "<MediaId>";

            // File extension derived from the MIME type received in an incoming message
            // Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
            string fileExtension = "<FileExtension>";

            // File location to write the media. 
            // Ex. @"c:\temp\media.jpg"
            string filePath = @"<FilePath>" + "<FileName>" + fileExtension;
            Console.WriteLine(filePath);

            try
            {
                // Download media to file
                Response response = await notificationMessagesClient.DownloadMediaToAsync(mediaId, filePath);

                Console.WriteLine(response.ToString());
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine(e);
                return;
            }
        }
    }
}

Pré-requisitos

Configurar o ambiente

Para configurar um ambiente para enviar mensagens, conclua as etapas a seguir.

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 diretivas de importação e remova a instrução System.out.println("Hello world!");:

package com.communication.quickstart;

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

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

Modelo de objeto

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

Nome Descrição
NotificationMessagesClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
DownloadMediaAsync Baixe o conteúdo de mídia de uma mensagem de Usuário para Empresas de forma assíncrona, gravando o conteúdo em um fluxo.
Microsoft.Communication.AdvancedMessageReceived Evento da Grade de Eventos que é publicado quando a Advanced Messaging recebe uma mensagem.

Observação

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

Configuração comum

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

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

Exemplos de código

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

Baixar o conteúdo de mídia em um fluxo

O SDK de Mensagens permite que a Contoso baixe a mídia em mensagens de mídia recebidas do WhatsApp de usuários do WhatsApp. Para baixar o conteúdo de mídia em um fluxo, você precisa:

    public static void main(String[] args) throws IOException {

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

        BinaryData data = messagesClient.downloadMedia("<MEDIA_ID>");
        BufferedImage image = ImageIO.read(data.toStream());
        ImageIcon icon = new ImageIcon(image);
        JLabel label  = new JLabel(icon);
        JFrame frame = new JFrame();
        frame.add(label);
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        frame.pack();
        frame.setVisible(true);
    }

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

Localize o código finalizado no GitHub em Java Messages SDK.

Pré-requisitos

Configurar o ambiente

Para configurar um ambiente para enviar mensagens, conclua as etapas 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 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.

Modelo de objeto

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

Nome Descrição
NotificationClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
DownloadMediaAsync Baixe o conteúdo de mídia de uma mensagem de Usuário para Empresas de forma assíncrona, gravando o conteúdo em um fluxo.
Microsoft.Communication.AdvancedMessageReceived Evento da Grade de Eventos que é publicado quando a Advanced Messaging recebe uma mensagem.

Observação

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

Configuração comum

Siga essas etapas para adicionar trechos de código necessários à função principal do seu arquivo DownloadMedia.js.

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

Exemplos de código

Siga essas etapas para adicionar trechos de código necessários à função principal do seu arquivo DownloadMedia.js.

Baixar o conteúdo de mídia em um fluxo

O SDK de Mensagens permite que a Contoso responda com mensagens de texto do WhatsApp quando iniciadas por usuários do WhatsApp. Para enviar mensagens de texto, conclua as seguintes etapas:

Neste exemplo, respondemos ao usuário do WhatsApp com o texto: "Thanks for your feedback.\n From Notification Messaging SDK."

Monte e envie a mensagem de mídia:

const credential = new AzureKeyCredential(process.env.ACS_ACCESS_KEY || "");
const endpoint = process.env.ACS_URL || "";
const client = NotificationClient(endpoint, credential);
console.log("Downloading...");
await client
.path("/messages/streams/{id}", "<MEDIA_ID>")
.get()
.asNodeStream()
.then((resp) => {
    resp.body?.pipe(fs.createWriteStream("downloadedMedia.jpeg"));
    return;
});

Executar o código

Use o comando do nó para executar o código que você adicionou ao arquivo send-messages.js.

node ./send-messages.js

Exemplo de código completo

Baixe a mídia recebida por eventos de mensagens avançadas.

/**
 * @summary Download a media file
 */

const NotificationClient = require("@azure-rest/communication-messages").default;
const { AzureKeyCredential } = require("@azure/core-auth");
const fs = require("fs");

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

async function main() {
  const credential = new AzureKeyCredential(process.env.ACS_ACCESS_KEY || "");
  const endpoint = process.env.ACS_URL || "";
  const client = NotificationClient(endpoint, credential);
  console.log("Downloading...");
  await client
    .path("/messages/streams/{id}", "<MEDIA_ID>")
    .get()
    .asNodeStream()
    .then((resp) => {
      resp.body?.pipe(fs.createWriteStream("downloadedMedia.jpeg"));
      return;
    });
}

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

Pré-requisitos

Configurando

Criar um novo aplicativo Python

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

mkdir messages-quickstart && cd messages-quickstart

Instalar o pacote

Use a biblioteca de cliente do Azure Communication Messages 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()

Modelo de objeto

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

Nome Descrição
NotificationMessagesClient Essa classe se conecta ao recurso dos Serviços de Comunicação do Azure. Ele envia as mensagens.
DownloadMediaAsync Baixe o conteúdo de mídia de uma mensagem de Usuário para Empresas de forma assíncrona, gravando o conteúdo em um fluxo.
Microsoft.Communication.AdvancedMessageReceived Evento da Grade de Eventos que é publicado quando a Advanced Messaging recebe uma mensagem.

Observação

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

Configuração comum

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

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 do 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. Para obter mais informações sobre a formatação de números de telefone, consulte 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, veja a definição em WhatsApp Business Platform.

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.

Exemplos de código

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

Baixar o conteúdo de mídia em um fluxo

O SDK de Mensagens permite que a Contoso receba ou baixe mídia de um usuário do WhatsApp, quando iniciada pelos usuários do WhatsApp. Para baixar o conteúdo de mídia em um fluxo, você precisa:

Importante

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

Neste exemplo, a empresa envia uma reação à mensagem do usuário.

      def download_media(self):

        from azure.communication.messages import NotificationMessagesClient

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_id: str = "de7558b5-e169-4d47-9ba4-37a95c28f390"

        # calling send() with whatsapp message details
        media_stream = messaging_client.download_media(input_media_id)
        length : int = 0
        for byte in media_stream:
            length = length + 1
        print("WhatsApp Media stream downloaded.It's length is {}".format(length))

Para executar download_media(), atualize o método principal.

    #Calling download_media()
    messages.download_media()

Executar o código

Para executar o código, certifique-se de estar no mesmo diretório em que o arquivo download-media-quickstart.py está localizado.

python download-media-quickstart.py

Azure Communication Services - Advanced Messages Quickstart
WhatsApp Media stream downloaded.

Exemplo de código completo

Observação

Altere todas as variáveis de espaço reservado no código a seguir para que elas correspondam aos seus valores.

import os
from io import BytesIO

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

     def download_media(self):

        from azure.communication.messages import NotificationMessagesClient

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_id: str = "de7558b5-e169-4d47-9ba4-37a95c28f390"

        # calling send() with whatsapp message details
        media_stream = messaging_client.download_media(input_media_id)
        length : int = 0
        for byte in media_stream:
            length = length + 1
        print("WhatsApp Media stream downloaded.It's length is {}".format(length))

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

Código de exemplo

Examine e baixe outro código de exemplo no GitHub no SDK de Mensagens do Python.

Próximas etapas