Enviar WhatsApp pelo Google Sheets com Apps Script (passo a passo)

Uma conta no ZapZap, uma instância conectada por QR code, a chave e o segredo da API (x-api-key e x-api-secret) e o ID da instância. A planilha precisa de quatro colunas na primeira aba, nesta ordem: A Nome, B Telefone, C Mensagem, D Status.

O telefone vai com DDI e só dígitos, por exemplo 5511999999999. Se a coluna estiver formatada como número, o Sheets pode transformar o valor em notação científica ou remover zeros; formate a coluna B como Texto simples. A coluna D começa vazia: o script escreve nela o resultado de cada envio, e é isso que impede reenvio em dobro. O passo a passo resumido também está na integração com Google Sheets.

Nunca cole credenciais no código da planilha: quem tem acesso de edição vê tudo. No editor do Apps Script, abra Configurações do projeto (engrenagem) e, em Propriedades do script, adicione ZAPZAP_KEY, ZAPZAP_SECRET e ZAPZAP_INSTANCE. O código lê esses valores com PropertiesService.

Atenção a quem tem acesso: o dono do script e quem tem permissão de edição na planilha conseguem abrir o editor e ler as propriedades. Compartilhe a planilha como Leitor com quem só precisa ver os dados, e use uma instância separada para uso em planilha, não o número principal do negócio.

O código abaixo percorre as linhas a partir da segunda, pula as que já têm Status preenchido, envia a mensagem com UrlFetchApp.fetch e escreve o resultado na coluna D. O parâmetro muteHttpExceptions evita que um erro HTTP interrompa o script: você lê o código de resposta e decide o que gravar.

O Utilities.sleep entre envios cria um intervalo. O valor é escolha sua: não existe número oficial de segurança do WhatsApp, e rajada idêntica para uma lista fria é o comportamento que mais pesa. Veja o guia de anti-bloqueio antes de aumentar 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));
  }
}

Com a função onOpen, o Sheets ganha um menu WhatsApp ao abrir o arquivo. Quem opera a planilha não precisa entrar no editor de código. Na primeira execução o Google pede autorização para o script acessar a planilha e fazer requisições externas; é esperado.

Acrescente também uma função de teste que envia só para o seu número, para validar credenciais e instância antes de rodar a lista inteira.

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

Acrescente uma coluna E com a URL pública do arquivo e use /send/media com type, file, text (legenda) e docName. O arquivo precisa estar acessível por URL pública; um link do Drive só funciona se estiver aberto para qualquer pessoa com o link e apontar para o arquivo em si, não para a página de visualização.

Para listas maiores, considere a fila de disparo da própria API (POST /sender/simple), que recebe um array de numbers, o tipo, o texto e um intervalo mínimo e máximo entre mensagens (delayMin e delayMax) e agenda o envio no servidor. Assim o seu script não precisa ficar rodando, o que também evita o limite de tempo de execução do Apps Script (consulte as cotas atuais na documentação do 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,
  });
}

Publique o script como aplicativo da Web (Implantar > Nova implantação > App da Web) e use a URL gerada como webhook da instância. A função doPost recebe o JSON do evento e grava uma linha em uma aba Respostas. Configure o webhook com POST em /webhook, enviando url, enabled true e events com messages.

Dois cuidados. Primeiro, a estrutura exata do evento deve ser conferida em um log real: grave o corpo cru na primeira versão e só depois mapeie os campos. Segundo, o Apps Script como web app tem limites de tempo e de execuções simultâneas; serve bem para volume baixo ou médio e não substitui um servidor para operação grande. O guia de webhook explica o desenho para volume maior.

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 qualquer investigação, rode o teste do menu. Se ele responde 200, credenciais e instância estão corretas, e o problema está nos dados da planilha.

Planilha é ótima para começar e para operações pequenas. Registre sempre o resultado por linha (para auditoria e para não reenviar), use um número dedicado à planilha, escreva mensagens com variação em vez de texto idêntico para toda a lista e dê uma saída fácil a quem não quer receber. Mensagens para quem não pediu contato são problema em qualquer ferramenta, e a LGPD vale igual.

Quando a lista ou a lógica crescer, migre a mesma ideia para n8n ou código, mantendo a API igual. A referência de send/text e o início rápido ajudam a dar o próximo passo.