Send WhatsApp from Google Sheets with Apps Script (step by step)

A ZapZap account, an instance connected by QR code, the API key and secret (x-api-key and x-api-secret) and the instance ID. The sheet needs four columns on the first tab, in this order: A Name, B Phone, C Message, D Status.

The phone goes with country code and digits only, for example 5511999999999. If the column is formatted as a number, Sheets may turn the value into scientific notation or drop zeros; format column B as Plain text. Column D starts empty: the script writes each send's result there, and that is what prevents double sends. The short version of this walkthrough is also on the Google Sheets integration page.

Never paste credentials in the sheet's code: anyone with edit access sees everything. In the Apps Script editor, open Project settings (the gear) and, under Script properties, add ZAPZAP_KEY, ZAPZAP_SECRET and ZAPZAP_INSTANCE. The code reads those values with PropertiesService.

Mind who has access: the script owner and anyone with edit permission on the sheet can open the editor and read the properties. Share the sheet as Viewer with people who only need to see the data, and use a separate instance for spreadsheet use, not the business's main number.

The code below walks the rows from the second one, skips those with a Status already filled, sends the message with UrlFetchApp.fetch and writes the result in column D. The muteHttpExceptions option stops an HTTP error from interrupting the script: you read the response code and decide what to write.

Utilities.sleep between sends creates an interval. The value is your choice: there is no official safe number from WhatsApp, and an identical burst to a cold list is the behavior that weighs the most. See the anti-ban guide before raising volume.

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

With the onOpen function, Sheets gets a WhatsApp menu when the file opens. Whoever runs the sheet does not need to open the code editor. On the first run Google asks you to authorize the script to access the sheet and make external requests; that is expected.

Also add a test function that sends only to your own number, to validate credentials and the instance before you run the whole list.

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

Add a column E with the file's public URL and use /send/media with type, file, text (caption) and docName. The file has to be reachable by public URL; a Drive link only works if it is open to anyone with the link and points to the file itself, not the viewer page.

For larger lists, consider the API's own sending queue (POST /sender/simple), which takes an array of numbers, the type, the text and a minimum and maximum interval between messages (delayMin and delayMax) and schedules the sending on the server. That way your script does not have to keep running, which also avoids Apps Script's execution time limit (check the current quotas in Google's documentation).

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

Publish the script as a web app (Deploy > New deployment > Web app) and use the generated URL as the instance's webhook. The doPost function receives the event JSON and writes a row to a Replies tab. Configure the webhook with POST to /webhook, sending url, enabled true and events with messages.

Two cautions. First, check the exact event structure in a real log: write the raw body in the first version and map fields only afterward. Second, Apps Script as a web app has limits on time and concurrent executions; it suits low to medium volume and does not replace a server for a large operation. The webhook guide explains the design for higher volume.

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"]}'

Before any investigation, run the menu test. If it answers 200, credentials and instance are correct, and the problem is in the sheet data.

A spreadsheet is great for starting out and for small operations. Always record the result per row (for auditing and to avoid resending), use a number dedicated to the sheet, write messages with variation instead of identical text for the whole list and give people an easy way out. Messaging people who did not ask to be contacted is a problem in any tool, and data protection law applies equally.

When the list or the logic grows, move the same idea to n8n or code, keeping the API the same. The send/text reference and the quick start help with the next step.