Enviar WhatsApp desde Google Sheets con Apps Script (paso a paso)

Una cuenta en ZapZap, una instancia conectada por código QR, la clave y el secreto de la API (x-api-key y x-api-secret) y el ID de la instancia. La hoja necesita cuatro columnas en la primera pestaña, en este orden: A Nombre, B Teléfono, C Mensaje, D Estado.

El teléfono va con código de país y solo dígitos, por ejemplo 5511999999999. Si la columna está formateada como número, Sheets puede convertir el valor a notación científica o quitar ceros; formatea la columna B como Texto sin formato. La columna D empieza vacía: el script escribe ahí el resultado de cada envío, y eso es lo que impide el reenvío doble. El resumen del paso a paso también está en la integración con Google Sheets.

Nunca pegues credenciales en el código de la hoja: quien tenga acceso de edición lo ve todo. En el editor de Apps Script, abre Configuración del proyecto (el engranaje) y, en Propiedades del script, agrega ZAPZAP_KEY, ZAPZAP_SECRET y ZAPZAP_INSTANCE. El código lee esos valores con PropertiesService.

Ojo con quién tiene acceso: el dueño del script y quien tenga permiso de edición en la hoja puede abrir el editor y leer las propiedades. Comparte la hoja como Lector con quien solo necesita ver los datos, y usa una instancia separada para el uso en hoja de cálculo, no el número principal del negocio.

El código de abajo recorre las filas desde la segunda, salta las que ya tienen Estado, envía el mensaje con UrlFetchApp.fetch y escribe el resultado en la columna D. El parámetro muteHttpExceptions evita que un error HTTP interrumpa el script: lees el código de respuesta y decides qué escribir.

Utilities.sleep entre envíos crea un intervalo. El valor es decisión tuya: no existe un número oficial de seguridad de WhatsApp, y una ráfaga idéntica a una lista fría es el comportamiento que más pesa. Mira la guía de antibloqueo antes de subir el volumen.

function enviarMensagens() {
  const props = PropertiesService.getScriptProperties();
  const key = props.getProperty("ZAPZAP_KEY");
  const secret = props.getProperty("ZAPZAP_SECRET");
  const instancia = props.getProperty("ZAPZAP_INSTANCE");
  const url = "https://api.zapzapapi.com/api/v1/" + instancia + "/send/text";

  const aba = SpreadsheetApp.getActiveSheet();
  const linhas = aba.getDataRange().getValues();

  for (let i = 1; i < linhas.length; i++) {
    const [nome, telefone, mensagem, status] = linhas[i];
    if (status || !telefone || !mensagem) continue;

    const texto = String(mensagem).replace("{nome}", nome);
    const resposta = UrlFetchApp.fetch(url, {
      method: "post",
      contentType: "application/json",
      headers: { "x-api-key": key, "x-api-secret": secret },
      payload: JSON.stringify({ number: String(telefone), text: texto }),
      muteHttpExceptions: true,
    });

    const codigo = resposta.getResponseCode();
    aba.getRange(i + 1, 4).setValue(
      codigo < 300 ? "OK " + new Date().toLocaleString("pt-BR") : "ERROR " + codigo + ": " + resposta.getContentText().slice(0, 120)
    );
    SpreadsheetApp.flush();
    Utilities.sleep(3000 + Math.floor(Math.random() * 4000));
  }
}

Con la función onOpen, Sheets gana un menú WhatsApp al abrir el archivo. Quien opera la hoja no necesita entrar al editor de código. En la primera ejecución Google pide autorización para que el script acceda a la hoja y haga peticiones externas; es lo esperado.

Agrega también una función de prueba que envíe solo a tu número, para validar credenciales e instancia antes de ejecutar la lista completa.

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("WhatsApp")
    .addItem("Enviar pendentes", "enviarMensagens")
    .addItem("Enviar teste para mim", "enviarTeste")
    .addToUi();
}

function enviarTeste() {
  const props = PropertiesService.getScriptProperties();
  const url = "https://api.zapzapapi.com/api/v1/" + props.getProperty("ZAPZAP_INSTANCE") + "/send/text";
  const r = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    headers: { "x-api-key": props.getProperty("ZAPZAP_KEY"), "x-api-secret": props.getProperty("ZAPZAP_SECRET") },
    payload: JSON.stringify({ number: props.getProperty("MEU_NUMERO"), text: "Test from Google Sheets" }),
    muteHttpExceptions: true,
  });
  SpreadsheetApp.getUi().alert("Response " + r.getResponseCode() + ": " + r.getContentText());
}

Agrega una columna E con la URL pública del archivo y usa /send/media con type, file, text (leyenda) y docName. El archivo debe ser accesible por URL pública; un enlace de Drive solo funciona si está abierto a cualquiera con el enlace y apunta al archivo en sí, no a la página de vista previa.

Para listas mayores, considera la cola de envío de la propia API (POST /sender/simple), que recibe un arreglo de numbers, el tipo, el texto y un intervalo mínimo y máximo entre mensajes (delayMin y delayMax) y programa el envío en el servidor. Así tu script no tiene que quedarse ejecutando, lo que también evita el límite de tiempo de ejecución de Apps Script (consulta las cuotas vigentes en la documentación de Google).

function enviarDocumento(numero, urlArquivo, nome, legenda) {
  const props = PropertiesService.getScriptProperties();
  const url = "https://api.zapzapapi.com/api/v1/" + props.getProperty("ZAPZAP_INSTANCE") + "/send/media";
  return UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    headers: { "x-api-key": props.getProperty("ZAPZAP_KEY"), "x-api-secret": props.getProperty("ZAPZAP_SECRET") },
    payload: JSON.stringify({ number: numero, type: "document", file: urlArquivo, docName: nome, text: legenda }),
    muteHttpExceptions: true,
  });
}

Publica el script como aplicación web (Implementar > Nueva implementación > Aplicación web) y usa la URL generada como webhook de la instancia. La función doPost recibe el JSON del evento y escribe una fila en una pestaña Respuestas. Configura el webhook con POST a /webhook, enviando url, enabled true y events con messages.

Dos cuidados. Primero, comprueba la estructura exacta del evento en un log real: guarda el cuerpo crudo en la primera versión y solo después mapea los campos. Segundo, Apps Script como aplicación web tiene límites de tiempo y de ejecuciones simultáneas; sirve bien para volumen bajo o medio y no sustituye a un servidor en una operación grande. La guía de webhook explica el diseño para volumen mayor.

function doPost(e) {
  const evento = JSON.parse(e.postData.contents);
  const aba = SpreadsheetApp.getActive().getSheetByName("Respostas") || SpreadsheetApp.getActive().insertSheet("Respostas");
  aba.appendRow([new Date(), JSON.stringify(evento).slice(0, 4000)]);
  return ContentService.createTextOutput("ok");
}

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"url":"https://script.google.com/macros/s/SEU_ID/exec","enabled":true,"events":["messages"]}'

Antes de cualquier investigación, ejecuta la prueba del menú. Si responde 200, credenciales e instancia están correctas, y el problema está en los datos de la hoja.

Una hoja es excelente para empezar y para operaciones pequeñas. Registra siempre el resultado por fila (para auditoría y para no reenviar), usa un número dedicado a la hoja, escribe mensajes con variación en vez de texto idéntico para toda la lista y da una salida fácil a quien no quiere recibir. Escribirle a quien no pidió contacto es un problema en cualquier herramienta, y la protección de datos aplica igual.

Cuando la lista o la lógica crezca, lleva la misma idea a n8n o a código, manteniendo la misma API. La referencia de send/text y el inicio rápido ayudan a dar el siguiente paso.