Compartir a través de

Inicio rápido: Descarga de elementos multimedia de mensajes de WhatsApp

Azure Communication Services le permite enviar y recibir mensajes de WhatsApp. En este artículo se describe la forma de descargar la carga multimedia recibida en un mensaje de WhatsApp.

Caso de uso: una empresa recibe un mensaje de WhatsApp de su cliente que contiene una imagen. La empresa debe descargar la imagen de WhatsApp para ver la imagen.

Los mensajes entrantes a la empresa se publican como eventos de Event Grid Microsoft.Communication.AdvancedMessageReceived. En este ejemplo se usa el id. multimedia y el tipo MIME multimedia en el evento AdvancedMessageReceived para descargar la carga multimedia.

Ejemplo de un evento AdvancedMessageReceived con contenido multimedia:

[{
  "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"
}]

Requisitos previos

Configuración de entorno

Crear el proyecto .NET

Para crear su proyecto, siga el tutorial en Crear una aplicación de consola .NET con Visual Studio.

Para compilar su código, presione Ctrl+F7.

Instalar el paquete

Instale el paquete Azure.Communication.Messages NuGet en su proyecto C#.

  1. Abra el Administrador de paquetes NuGet en Project>Manage NuGet Packages....
  2. Buscar el paquete Azure.Communication.Messages.
  3. Instale la última versión.

Instalación del marco de la aplicación

Abra el archivo Program.cs en un editor de texto.

Reemplace el contenido de Program.cs por el código siguiente:

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 utilizar las funciones de Mensajería avanzada, agregue una directiva using para incluir el espacio de nombres Azure.Communication.Messages.

using Azure.Communication.Messages;

Modelo de objetos

Las siguientes clases e interfaces administran algunas de las principales funciones del SDK de Mensajería avanzada de Azure Communication Services para .NET.

Nombre Descripción
NotificationMessagesClient Esta clase se conecta a su recurso Azure Communication Services. Envía los mensajes.
DownloadMediaAsync Descargue la carga multimedia de un mensaje de usuario a empresa de forma asincrónica y escriba el contenido en una secuencia.
DownloadMediaToAsync Descargue la carga multimedia de un mensaje de usuario a empresa de forma asincrónica y escriba el contenido en un archivo.
Microsoft.Communication.AdvancedMessageReceived Evento de Event Grid que se publica cuando Mensajería avanzada recibe un mensaje.

Configuración común

Siga estos pasos para agregar fragmentos de código necesarios al programa messages-quickstart.py python.

Autenticar el cliente

El SDK de mensajes usa el NotificationMessagesClient para enviar mensajes. El método NotificationMessagesClient se autentica mediante la cadena de conexión adquirida desde el recurso de Azure Communication Services en Azure Portal. Para más información sobre las cadenas de conexión, consulte access-your-connection-strings-and-service-endpoints.

Para simplificar, en este artículo se usa una cadena de conexión para autenticarse. En entornos de producción, se recomienda utilizar los servicios principales.

Obtenga la cadena de conexión del recurso de Azure Communication Services en Azure Portal. A la izquierda, navegue hasta la pestaña Keys. Copie el campo Connection string para la clave primaria. La cadena de conexión tiene el formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal y que muestra el campo

Establezca la variable de entorno COMMUNICATION_SERVICES_CONNECTION_STRING en el valor de la cadena de conexión.
Abra una ventana de consola y escriba el siguiente comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Tras agregar la variable de entorno, es posible que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de la consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Para obtener más información sobre cómo configurar una variable de entorno para su sistema, siga los pasos indicados en Almacene su cadena de conexión en una variable de entorno.

Para crear una instancia un NotificationMessagesClient, agregue el siguiente código al 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);

Establecimiento del identificador de registro de canales

El Id. GUID del registro del canal se creó durante el registro del canal. Puede buscarlo en el portal en la pestaña Canales del recurso de Azure Communication Services.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal, en la pestaña

Asígnelo a una variable llamada channelRegistrationId.

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

Establecimiento de la lista de destinatarios

Debe proporcionar un número de teléfono activo asociado a una cuenta de WhatsApp. Esta cuenta de WhatsApp recibe la plantilla, el texto y los mensajes multimedia enviados en este inicio rápido.

En este ejemplo, puede usar su número de teléfono personal.

El número de teléfono del destinatario no puede ser el número de teléfono del trabajo (id. de remitente) asociado al registro de canales de WhatsApp. El id. de remitente aparece como remitente de los mensajes de texto y multimedia enviados al destinatario.

El número de teléfono debe incluir el código de país. Para obtener más información sobre el formato del número de teléfono, consulte la documentación de WhatsApp sobre Formatos de número de teléfono.

Nota:

Actualmente solo se admite un número de teléfono en la lista de destinatarios.

Cree la lista de destinatarios de la siguiente manera:

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

Ejemplo:

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

Comience a enviar mensajes entre una empresa y un usuario de WhatsApp

Las conversaciones entre una cuenta empresarial de WhatsApp y un usuario de WhatsApp se pueden iniciar de una de estas dos maneras:

  • La empresa envía un mensaje de plantilla al usuario de WhatsApp.
  • El usuario de WhatsApp envía cualquier mensaje al número del trabajo.

Una empresa no puede iniciar una conversación interactiva. Solo puede enviar un mensaje interactivo después de recibir un mensaje del usuario. La empresa solo puede enviar mensajes interactivos al usuario durante la conversación activa. Una vez que expire la ventana de conversación de 24 horas, solo el usuario puede reiniciar la conversación interactiva. Para obtener más información sobre las conversaciones, consulte la definición en la Plataforma de WhatsApp Business.

Para iniciar una conversación interactiva desde su cuenta personal de WhatsApp, envíe un mensaje al número de empresarial (id. de remitente).

Una conversación de WhatsApp vista en la web que muestra un mensaje de usuario enviado al número de cuenta empresarial de WhatsApp.

Ejemplos de código

Siga estos pasos para agregar los fragmentos de código necesarios a la función Main del archivo Program.cs.

Descargar la carga multimedia en una secuencia

El SDK de mensajes permite a Contoso descargar los medios en los mensajes multimedia de WhatsApp recibidos de los usuarios de WhatsApp. Para descargar la carga multimedia en una secuencia, necesita:

Defina el id. multimedia del elemento multimedia que desea capturar.

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

Descargue el elemento multimedia en la secuencia de destino.

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

La carga multimedia ya está disponible en el flujo de respuesta.

Continúe con este ejemplo para escribir la secuencia en un archivo.

El id. multimedia y el tipo MIME de la carga están disponibles en el contenido multimedia del evento AdvancedMessageReceived. Sin embargo, al descargar elementos multimedia en una secuencia, el tipo MIME vuelve a estar disponible en los encabezados de respuesta del Response<Stream>.

En cualquier caso, debe convertir el tipo MIME en un tipo de archivo. Defina este asistente para la conversión.

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 la ubicación del archivo donde desea escribir el elemento multimedia. En este ejemplo se usa el tipo MIME devuelto en los encabezados de respuesta 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;

Escriba la secuencia en el archivo.

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

Descargar la carga multimedia en un archivo

El SDK de mensajes permite a Contoso descargar los elementos multimedia en los mensajes multimedia de WhatsApp recibidos de los usuarios de WhatsApp. Para descargar la carga multimedia en un archivo, necesita:

Defina el ID del elemento multimedia que desea recuperar y la ubicación del archivo donde desea escribir el elemento multimedia.

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

Descargue el elemento multimedia en la ruta de acceso de destino.

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

Ejecución del código

Compile y ejecute el programa.

  1. Para compilar su código, presione Ctrl+F7.
  2. Para ejecutar el programa sin depurar, presione Ctrl+F5.

Ejemplo completo de código

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

Requisitos previos

Configuración de entorno

Para configurar un entorno para enviar mensajes, siga los pasos siguientes.

Creación de una aplicación Java

Abra la ventana Comandos o el terminal y navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecute el comando siguiente para generar el proyecto de Java a partir de la plantilla maven-archetype-quickstart.

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

El objetivo generate crea un directorio con el mismo nombre que el valor artifactId. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de la prueba y el archivo pom.xml es el modelo de objetos del proyecto o POM.

Instalar el paquete

Abra el archivo pom.xml en el editor de texto. Agregue el siguiente elemento de dependencia al grupo de dependencias.

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

Instalación del marco de la aplicación

Abra /src/main/java/com/communication/quickstart/App.java en un editor de texto, agregue directivas de importación y quite la instrucción 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 objetos

Las siguientes clases e interfaces administran algunas de las principales funciones del SDK de Mensajería avanzada de Azure Communication Services para Java.

Nombre Descripción
NotificationMessagesClient Esta clase se conecta a su recurso Azure Communication Services. Envía los mensajes.
DownloadMediaAsync Descargue la carga multimedia de un mensaje de usuario a empresa de forma asincrónica y escriba el contenido en una secuencia.
Microsoft.Communication.AdvancedMessageReceived Evento de Event Grid que se publica cuando Mensajería avanzada recibe un mensaje.

Nota:

Para más información, consulte la referencia del SDK de Azure para Java en Paquete com.azure.communication.messages.

Configuración común

Siga estos pasos para agregar los fragmentos de código necesarios a la función principal de su archivo App.java.

Comience a enviar mensajes entre una empresa y un usuario de WhatsApp

Las conversaciones entre una cuenta empresarial de WhatsApp y un usuario de WhatsApp se pueden iniciar de una de estas dos maneras:

  • La empresa envía un mensaje de plantilla al usuario de WhatsApp.
  • El usuario de WhatsApp envía cualquier mensaje al número del trabajo.

Independientemente de cómo se haya iniciado la conversación, una empresa solo puede enviar mensajes de plantilla hasta que el usuario envíe un mensaje a la empresa. Solo después de que el usuario envíe un mensaje a la empresa, ésta podrá enviarle mensajes de texto o multimedia durante la conversación activa. Una vez transcurrido el plazo de 24 horas, la conversación debe reiniciarse. Para obtener más información sobre las conversaciones, consulte la definición en Plataforma de WhatsApp Business.

Autenticar el cliente

Existen varias opciones para autenticar a un cliente de mensajes:

Para autenticar a un cliente, cree una instancia NotificationMessagesClient o MessageTemplateClient con su cadena de conexión. También puede iniciar el cliente con cualquier cliente HTTP personalizado que implemente la interfaz com.azure.core.http.HttpClient.

Para simplificar, en este artículo se usa una cadena de conexión para autenticarse. En entornos de producción, se recomienda utilizar los servicios principales.

Obtenga la cadena de conexión del recurso de Azure Communication Services en Azure Portal. A la izquierda, navegue hasta la pestaña Keys. Copie el campo Connection string para el Primary key. La cadena de conexión tiene el formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal y que muestra el campo

Establezca la variable de entorno COMMUNICATION_SERVICES_CONNECTION_STRING en el valor de la cadena de conexión.
Abra una ventana de consola y escriba el siguiente comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Para obtener más información sobre cómo configurar una variable de entorno para su sistema, siga los pasos indicados en Almacene su cadena de conexión en una variable de entorno.

Para crear una instancia de NotificationMessagesClient, agregue el siguiente código al 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();

Establecimiento del identificador de registro de canales

El Id. GUID de registro de canal se creó durante el registro del canal. Puede buscarlo en el portal en la pestaña Canales del recurso de Azure Communication Services.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal, en la pestaña

Asígnelo a una variable llamada channelRegistrationId.

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

Establecimiento de la lista de destinatarios

Debe proporcionar un número de teléfono real que tenga una cuenta de WhatsApp asociada. Esta cuenta de WhatsApp recibe los mensajes de texto y multimedia enviados en este artículo. Para este artículo, este número de teléfono puede ser su número de teléfono personal.

El número de teléfono del destinatario no puede ser el número de teléfono del trabajo (id. de remitente) asociado al registro de canales de WhatsApp. El id. de remitente aparece como remitente de los mensajes de texto y multimedia enviados al destinatario.

El número de teléfono debe incluir el código de país. Para obtener más información sobre el formato del número de teléfono, consulte la documentación de WhatsApp sobre formatos de número de teléfono.

Nota:

Actualmente solo se admite un número de teléfono en la lista de destinatarios.

Cree la lista de destinatarios de la siguiente manera:

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

Ejemplo:

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

Ejemplos de código

Siga estos pasos para agregar fragmentos de código necesarios a la función principal de App.java.

Descargar la carga multimedia en una secuencia

El SDK de mensajes permite a Contoso descargar los medios en los mensajes multimedia de WhatsApp recibidos de los usuarios de WhatsApp. Para descargar la carga multimedia en una secuencia, necesita:

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

Ejecución del código

  1. Abra en el directorio que contiene el archivo pom.xml y compile el proyecto mediante el comando mvn.

    mvn compile

  2. Ejecute la aplicación ejecutando el siguiente comando mvn.

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

Ejemplo completo de código

Busque el código finalizado en GitHub en el SDK de mensajes de Java.

Requisitos previos

Configuración de entorno

Para configurar un entorno para enviar mensajes, siga los pasos siguientes.

Creación de una aplicación Node.js

  1. Cree un directorio para la aplicación y ábralo en un terminal o ventana Comandos.

  2. Ejecute el siguiente comando:

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

  3. Ejecute el siguiente comando para crear un archivo package.json con la configuración predeterminada.

    npm init -y

  4. Use un editor de texto para crear un archivo denominado send-messages.js en el directorio raíz del proyecto.

  5. Agregue el siguiente fragmento de código al archivo 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);
});

Complete la siguiente sección para agregar el código fuente de este ejemplo al archivo send-messages.js que ha creado.

Instalar el paquete

Utilice el comando npm install para instalar el SDK de la Mensajería avanzada de Azure Communication Services para JavaScript.

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

La opción --save muestra la biblioteca como dependencia en el archivo package.json.

Modelo de objetos

Las siguientes clases e interfaces administran algunas de las principales funciones del SDK de Mensajería avanzada de Azure Communication Services para JavaScript.

Nombre Descripción
NotificationClient Esta clase se conecta a su recurso Azure Communication Services. Envía los mensajes.
DownloadMediaAsync Descargue la carga multimedia de un mensaje de usuario a empresa de forma asincrónica y escriba el contenido en una secuencia.
Microsoft.Communication.AdvancedMessageReceived Evento de Event Grid que se publica cuando Mensajería avanzada recibe un mensaje.

Nota:

Para más información, consulte la referencia del SDK de Azure para JavaScript Paquete @Azure-rest/communication-messages

Configuración común

Siga estos pasos para agregar fragmentos de código necesarios a la función principal del archivo DownloadMedia.js.

Comience a enviar mensajes entre una empresa y un usuario de WhatsApp

Las conversaciones entre una cuenta empresarial de WhatsApp y un usuario de WhatsApp se pueden iniciar de una de estas dos maneras:

  • La empresa envía un mensaje de plantilla al usuario de WhatsApp.
  • El usuario de WhatsApp envía cualquier mensaje al número del trabajo.

Independientemente de cómo se haya iniciado la conversación, una empresa solo puede enviar mensajes de plantilla hasta que el usuario envíe un mensaje a la empresa. Solo después de que el usuario envíe un mensaje a la empresa, ésta podrá enviarle mensajes de texto o multimedia durante la conversación activa. Una vez transcurrido el plazo de 24 horas, la conversación debe reiniciarse. Para obtener más información sobre las conversaciones, consulte la definición en Plataforma de WhatsApp Business.

Autenticar el cliente

El código siguiente recupera la cadena de conexión del recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING mediante el paquete dotenv.

Para simplificar, en este artículo se usa una cadena de conexión para autenticarse. En entornos de producción, se recomienda utilizar los servicios principales.

Obtenga la cadena de conexión del recurso de Azure Communication Services en Azure Portal. A la izquierda, navegue hasta la pestaña Keys. Copie el campo Connection string para el Primary key. La cadena de conexión tiene el formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal y que muestra el campo

Establezca la variable de entorno COMMUNICATION_SERVICES_CONNECTION_STRING en el valor de la cadena de conexión.
Abra una ventana de consola y escriba el siguiente comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Para obtener más información sobre cómo configurar una variable de entorno para su sistema, siga los pasos indicados en Almacene su cadena de conexión en una variable de entorno.

Para crear una instancia de NotificationClient, agregue el siguiente código al 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);

Establecimiento del identificador de registro de canales

El Id. GUID de registro de canal se creó durante el registro del canal. Puede buscarlo en el portal en la pestaña Canales del recurso de Azure Communication Services.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal, en la pestaña

Asígnelo a una variable llamada channelRegistrationId.

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

Establecimiento de la lista de destinatarios

Debe proporcionar un número de teléfono real que tenga una cuenta de WhatsApp asociada. Esta cuenta de WhatsApp recibe los mensajes multimedia, texto y plantilla enviados en este artículo. Para este artículo, este número de teléfono puede ser su número de teléfono personal.

El número de teléfono del destinatario no puede ser el número de teléfono del trabajo (id. de remitente) asociado al registro de canales de WhatsApp. El id. de remitente aparece como remitente de los mensajes de texto y multimedia enviados al destinatario.

El número de teléfono debe incluir el código de país. Para obtener más información sobre el formato del número de teléfono, consulte la documentación de WhatsApp sobre formatos de número de teléfono.

Nota:

Actualmente solo se admite un número de teléfono en la lista de destinatarios.

Cree la lista de destinatarios de la siguiente manera:

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

Ejemplo:

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

Ejemplos de código

Siga estos pasos para agregar fragmentos de código necesarios a la función principal del archivo DownloadMedia.js.

Descargar la carga multimedia en una secuencia

El SDK de mensajes permite a Contoso responder con mensajes de texto de WhatsApp cuando lo inician los usuarios de WhatsApp. Para enviar mensajes de texto, siga estos pasos:

En este ejemplo, respondemos al usuario de WhatsApp con el texto: "Thanks for your feedback.\n From Notification Messaging SDK."

Agrupe y envíe el mensaje multimedia:

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

Ejecución del código

Use el comando node para ejecutar el código que agregó al archivo send-messages.js.

node ./send-messages.js

Ejemplo completo de código

Descargue el contenido multimedia recibido por eventos avanzados de mensajería.

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

Requisitos previos

Instalación

Creación de una nueva aplicación de Python

En una ventana del terminal o la consola, cree una carpeta para la aplicación y ábrala.

mkdir messages-quickstart && cd messages-quickstart

Instalar el paquete

Deberá utilizar la biblioteca de clientes de Azure Communication Messages para Python versión 1.1.0 o superior.

En el símbolo del sistema o la consola, ejecute el comando siguiente:

pip install azure-communication-messages

Para InteractiveMessages, Reacciones y Stickers, use la versión beta siguiente:

pip install azure-communication-messages==1.2.0b1

Instalación del marco de la aplicación

Cree un archivo llamado messages-quickstart.py y agregue la estructura básica del programa.

type nul > messages-quickstart.py

Estructura básica del programa

import os

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

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

Modelo de objetos

Las siguientes clases e interfaces controlan algunas de las características principales del SDK de mensajes de Azure Communication Services para Python.

Nombre Descripción
NotificationMessagesClient Esta clase se conecta a su recurso Azure Communication Services. Envía los mensajes.
DownloadMediaAsync Descargue la carga multimedia de un mensaje de usuario a empresa de forma asincrónica y escriba el contenido en una secuencia.
Microsoft.Communication.AdvancedMessageReceived Evento de Event Grid que se publica cuando Mensajería avanzada recibe un mensaje.

Nota:

Para más información, consulte la referencia del SDK de Azure para Python Paquete de mensajes.

Configuración común

Siga estos pasos para agregar fragmentos de código necesarios al programa de python messages-quickstart.py.

Autenticar el cliente

El envío de mensajes utiliza NotificationMessagesClient. NotificationMessagesClient se autentica mediante la cadena de conexión adquirida desde el recurso de Azure Communication Services en Azure Portal.F

Para más información sobre las cadenas de conexión, consulte access-your-connection-strings-and-service-endpoints.

Obtenga la cadena de conexión de Recursos de comunicación de Azure desde Azure Portal como se indica en el recorte de pantalla. A la izquierda, navegue hasta la pestaña Keys. Copie el campo Connection string para la clave primaria. La cadena de conexión tiene el formato endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal y que muestra el campo

Establezca la variable de entorno COMMUNICATION_SERVICES_CONNECTION_STRING en el valor de la cadena de conexión.
Abra una ventana de consola y escriba el siguiente comando:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Tras agregar la variable de entorno, es posible que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de la consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Para obtener más información sobre cómo configurar una variable de entorno para su sistema, siga los pasos indicados en Almacene su cadena de conexión en una variable de entorno.

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

Establecimiento del identificador de registro de canales

El Id. GUID del registro del canal se creó durante el registro del canal. Puede buscarlo en el portal en la pestaña Canales del recurso de Azure Communication Services.

Captura de pantalla que muestra un recurso de Azure Communication Services en Azure Portal, en la pestaña

Asígnelo a una variable llamada channelRegistrationId.

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

Establecimiento de la lista de destinatarios

Debe proporcionar un número de teléfono activo asociado a una cuenta de WhatsApp. Esta cuenta de WhatsApp recibe los mensajes multimedia, texto y plantilla enviados en este artículo.

En este ejemplo, puede usar su número de teléfono personal.

El número de teléfono del destinatario no puede ser el número de teléfono del trabajo (id. de remitente) asociado al registro de canales de WhatsApp. El id. de remitente aparece como remitente de los mensajes de texto y multimedia enviados al destinatario.

El número de teléfono debe incluir el código de país. Para obtener más información sobre el formato del número de teléfono, consulte la documentación de WhatsApp sobre Formatos de número de teléfono.

Nota:

Actualmente solo se admite un número de teléfono en la lista de destinatarios.

Establezca la lista de destinatarios así:

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

Ejemplo de uso:

    # Example only
    to=[self.phone_number],

Comience a enviar mensajes entre una empresa y un usuario de WhatsApp

Las conversaciones entre una cuenta empresarial de WhatsApp y un usuario de WhatsApp se pueden iniciar de una de estas dos maneras:

  • La empresa envía un mensaje de plantilla al usuario de WhatsApp.
  • El usuario de WhatsApp envía cualquier mensaje al número del trabajo.

Una empresa no puede iniciar una conversación interactiva. Solo puede enviar un mensaje interactivo después de recibir un mensaje del usuario. La empresa solo puede enviar mensajes interactivos al usuario durante la conversación activa. Una vez que expire la ventana de conversación de 24 horas, solo el usuario puede reiniciar la conversación interactiva. Para obtener más información sobre las conversaciones, consulte la definición en la Plataforma de WhatsApp Business.

Para iniciar una conversación interactiva desde su cuenta personal de WhatsApp, envíe un mensaje al número de empresarial (id. de remitente).

Una conversación de WhatsApp vista en la web que muestra un mensaje de usuario enviado al número de cuenta empresarial de WhatsApp.

Ejemplos de código

Siga estos pasos para agregar fragmentos de código necesarios al programa de python messages-quickstart.py.

Descargar la carga multimedia en una secuencia

El SDK de mensajes permite a Contoso recibir o descargar contenido multimedia de un usuario de WhatsApp cuando lo inician los usuarios de WhatsApp. Para descargar la carga multimedia en una secuencia, necesita:

Importante

Para enviar un mensaje de texto a un usuario de WhatsApp, este debe enviar primero un mensaje a la cuenta de WhatsApp Business. Para obtener más información, consulte Empezar a enviar mensajes entre la empresa y el usuario de WhatsApp.

En este ejemplo, la empresa envía una reacción al mensaje de usuario.

      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 ejecutar download_media(), actualice el método principal.

    #Calling download_media()
    messages.download_media()

Ejecución del código

Para ejecutar el código, asegúrese de que está en el mismo directorio donde se encuentra el archivo download-media-quickstart.py.

python download-media-quickstart.py

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

Ejemplo completo de código

Nota:

Cambie todas las variables de marcador de posición en el código siguiente para que coincidan con los 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 ejemplo

Revise y descargue otro código de ejemplo en GitHub en el SDK de mensajes de Python.

Pasos siguientes