Guardar mensagens e contactos do WhatsApp no Google Sheets automaticamente
Para guardar automaticamente as mensagens do WhatsApp Business no Google Sheets, envie-as como POST HTTP assinados para uma ferramenta de automação, como n8n, Make ou Zapier, e deixe o respetivo passo do Google Sheets acrescentar uma linha por mensagem: hora, direção, número de telefone, nome, texto e ID da mensagem. Um segundo separador, associado ao número de telefone, mantém uma linha por contacto, atualizada quando voltam a escrever.
A easyCoexistence liga o número do WhatsApp Business que mantém na app à Cloud API da Meta através da Coexistência.
As entregas encaminhadas são repetidas após cerca de 1, 5, 30, 120, 360 e 1 440 minutos quando o seu URL falha.
Tempo de espera de um POST encaminhado por uma resposta 2xx antes de a entrega ser repetida.
Pedidos de escrita à API do Google Sheets permitidos por minuto e por utilizador, por projeto; 300 por projeto.
O resultado de uma aplicação web do Apps Script é redirecionado para um URL de utilização única em script.googleusercontent.com.
O objeto de evento doPost do Apps Script expõe o corpo e os parâmetros, não os cabeçalhos do pedido HTTP.
Qual rota deve preencher a folha?
Existem duas rotas num número cujas mensagens passam pelo easyCoexistence, e respondem a necessidades diferentes. O URL de encaminhamento, definido uma vez por número, transmite os eventos originais da Meta, haja ou não uma automação a responder: mensagens dos clientes, as respostas que a sua equipa escreve na app WhatsApp Business e os estados de entrega. É a rota para um registo completo de mensagens. Um passo Chamar o meu webhook dentro de uma automação dispara apenas para as mensagens que essa automação seleciona, e transporta a conversa recente, incluindo a resposta que a automação acabou de enviar. Adequa-se a uma folha de contactos potenciais, encomendas ou pedidos de apoio que uma só automação trata. Ambas são assinadas, com segredos diferentes.
| Forward URL (per number) | Call my webhook step (per automation) | |
|---|---|---|
| Fires on | Any message event on the number, with or without automations | Only messages that automation is picked for |
| Carries | Meta's original value: messages, phone replies, statuses | The message, the contact and up to 10 recent messages |
| Automated replies | Delivery statuses only, without the text | In history, direction out |
| Retries | 7 attempts over about 33 hours | One attempt |
| Signed with | The number's forward secret, shown once | The automation's Signing secret |
| Set in | Number page, Where incoming messages go card | The automation editor, or create_automation |
Que campos chegam, e que colunas deve ter a folha?
Um POST encaminhado transporta uma alteração da Meta: id (a entrega), event (o nome do campo da Meta, como messages ou smb_message_echoes), received_at, connection (o identificador do número, phone e phone_number_id) e value, exatamente como a Meta o enviou. Em value, messages contém o que os clientes escreveram, e message_echoes o que a sua equipa escreveu no telemóvel. Os números de telefone chegam como dígitos, com o indicativo do país e sem sinal de mais; guarde essa coluna como texto simples para que o Sheets não a converta em número. Um utilizador com nome de utilizador do WhatsApp pode chegar com um ID de utilizador de âmbito empresarial junto ao número, ou em vez dele, pelo que deve manter uma coluna para o guardar.
Como constrói o registo de mensagens no n8n?
Três nós. Um nó Webhook com HTTP Method POST, Respond definido como Immediately, e o URL de produção guardado como URL de encaminhamento do número. Um nó Code que verifica X-EC-Signature com o segredo de encaminhamento e transforma o evento em linhas, ignorando os estados de entrega. Um nó Google Sheets com a operação Append or Update Row, e Column to match on definido como ID da mensagem, para que uma entrega repetida reescreva a mesma linha em vez de acrescentar outra.
O segredo de encaminhamento aparece uma única vez, ao guardar o URL de encaminhamento; se for perdido, clique em New secret e cole o novo. O n8n Cloud permite o módulo crypto nos nós Code; o n8n auto-alojado precisa de NODE_FUNCTION_ALLOW_BUILTIN=crypto.
const crypto = require('crypto');
const SECRET = 'whsec_...'; // the number's forward secret, shown once when you saved the Forward URL
const { headers, body } = $input.first().json;
const sig = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-ec-signature'] || '');
if (!sig || Math.abs(Date.now() / 1000 - Number(sig[1])) > 300) throw new Error('Bad or stale signature');
// n8n has parsed the body; it was sent as compact JSON, so JSON.stringify rebuilds the signed bytes.
const mac = crypto.createHmac('sha256', SECRET).update(sig[1] + '.' + JSON.stringify(body)).digest();
if (!crypto.timingSafeEqual(mac, Buffer.from(sig[2], 'hex'))) throw new Error('Bad signature');
const { event, connection, value } = body;
const names = Object.fromEntries((value.contacts || []).map((c) => [c.wa_id, c.profile?.name || '']));
const textOf = (m) => m.text?.body ?? m.button?.text ?? m.interactive?.button_reply?.title
?? m.interactive?.list_reply?.title ?? ('[' + m.type + '] ' + (m[m.type]?.caption || '')).trim();
const row = (m, direction, phone) => ({
time: new Date(Number(m.timestamp) * 1000).toISOString(), direction, phone,
user_id: m.from_user_id || '', name: names[phone] || '', text: textOf(m),
message_id: m.id, number: connection.phone,
});
let rows = [];
if (event === 'messages') rows = (value.messages || []).map((m) => row(m, 'in', m.from || '')); // statuses skipped
if (event === 'smb_message_echoes') rows = (value.message_echoes || []).map((m) => row(m, 'out', m.to || ''));
return rows.map((json) => ({ json }));Como mantém uma linha por contacto?
Acrescente um segundo nó Google Sheets num separador Contactos, também com Append or Update Row, associado à coluna Telefone. Mapeie o telefone, o nome do perfil, o ID de utilizador, a hora e o texto da mensagem mais recente. A primeira mensagem de um número cria a respetiva linha; as seguintes atualizam o nome e as colunas do último contacto, de modo que o separador funciona também como lista de quem escreveu e quando. Guarde as notas escritas à mão num separador próprio, pesquisado pelo telefone, para que o fluxo de trabalho nunca as substitua.
Os contactos guardados na lista de endereços do telemóvel não chegam por esta via. A Meta envia-os, com até 6 meses de conversas, apenas para um destino de webhook direto guardado nas 24 horas seguintes à ligação do número.
A Apps Script pode receber as mensagens diretamente?
Não de forma limpa, por isso coloque uma ferramenta de automação à frente da folha. O Google serve a resposta de uma aplicação web do Apps Script através de um redirecionamento para um URL de utilização única em script.googleusercontent.com, e a easyCoexistence não segue redirecionamentos. O 302 conta como entrega falhada: um encaminhamento é repetido até 7 vezes, e cada repetição volta a executar doPost e escreve outra linha, ao passo que um passo Chamar o meu webhook falha e envia-lhe um e-mail. O doPost também não consegue ler cabeçalhos de pedidos, pelo que a verificação de X-EC-Signature é impossível aí.
O Apps Script continua a ser uma boa opção para o sentido contrário: enviar templates aprovados a partir de linhas de uma folha, o que a página de integração com o Google Sheets explica com código.
O Make ou o Zapier podem preencher a folha?
Sim. No Make, inicie o cenário com Webhooks > Custom webhook e acrescente Google Sheets > Add a Row; no Zapier, use Webhooks by Zapier com Catch Raw Hook, que mantém os cabeçalhos, e depois Google Sheets > Create Spreadsheet Row. Ambos respondem ao POST de imediato com um 2xx, que é o que um encaminhamento precisa dentro dos seus 10 segundos. Mapeie os mesmos campos acima a partir de value.messages, e filtre os eventos cujo value traz statuses em vez de messages.
Trate o URL do hook como uma palavra-passe, já que quem o tiver pode acrescentar linhas. Se o seu plano incluir um passo de código, verifique aí X-EC-Signature com a mesma receita HMAC usada no nó do n8n.
Como evitar linhas duplicadas ou em falta?
As linhas duplicadas vêm das repetições. Um encaminhamento que não obtenha um 2xx em 10 segundos é enviado de novo com o mesmo cabeçalho X-EC-Delivery e o mesmo id no corpo, e as mensagens internas mantêm o seu wamid, pelo que associar por Message id torna uma repetição inofensiva. No caso do passo de webhook, os testes feitos em Try it chegam com dry_run true: encaminhe-os para um separador de teste ou descarte-os.
As linhas em falta vêm da quota de escrita do Google. A API do Sheets permite 60 pedidos de escrita por minuto, por utilizador e por projeto, e uma credencial do n8n corresponde a um único utilizador; uma rajada de respostas após uma campanha de templates pode exceder esse limite e obter HTTP 429. Ative Retry On Fail nas definições do nó Google Sheets, ou reúna as mensagens durante alguns segundos e acrescente-as num único pedido.
Como configurar
- Check the number's modeOn the number's page, the card Where incoming messages go must show Through easyCoexistence. If it shows Straight to your system, choose Through easyCoexistence.
- Build the workflowWebhook node (POST, Respond Immediately), the Code node above, then Google Sheets with Append or Update Row matched on Message id. Activate it and copy the Production URL.
- Save the Forward URLPaste the Production URL into Forward URL (optional) and click Save forward URL. Copy the signing secret shown once into the Code node.
- Send a test messageFrom another phone, write to your number and reply to it from the WhatsApp Business app. Two rows should appear: one in, one out.
Erros comuns
- Verificar um encaminhamento com o segredo de assinatura de uma automação, ou o contrário. O URL de encaminhamento é assinado com o segredo de encaminhamento do número, e Chamar o meu webhook com o da própria automação; escolha o segredo consoante o cabeçalho X-EC-Event.
- Acrescentar uma linha por POST sem chave. Uma entrega repetida após uma resposta lenta escreve a mesma mensagem duas vezes; use Append or Update Row associado ao ID da mensagem.
- Escrever estados de entrega como mensagens. O evento messages traz também os estados sent, delivered e read em value.statuses, que não têm texto e criam linhas vazias.
- Guardar o URL de uma aplicação web do Apps Script como URL de encaminhamento. O seu redirecionamento conta como falha, pelo que cada uma das 7 tentativas volta a executar doPost e acrescenta uma linha duplicada.
Com as automatizações ativadas, um URL de encaminhamento transmite os eventos originais da Meta ao seu fluxo de trabalho, assinados com um segredo que só o seu negócio conhece e repetidos quando o seu URL estiver em baixo, e um passo Chamar o meu webhook envia o que uma automação tratou, com a respetiva resposta. Ambos estão incluídos no plano. De US$ 9 a US$ 0.75 por número e por mês, descendo à medida que acrescenta números, com os primeiros 3 dias grátis.
Perguntas frequentes
A folha recebe as mensagens que a minha equipa escreve no telemóvel?
Sim, através do URL de encaminhamento. As respostas escritas na app do WhatsApp Business chegam como eventos smb_message_echoes, com o número do cliente no campo to. As respostas enviadas por automações voltam apenas como estados de entrega, pelo que deve registar o respetivo texto a partir de um passo Chamar o meu webhook colocado após a resposta.
Posso carregar as minhas conversas existentes para a folha?
Não num número cujas mensagens passam pelo easyCoexistence. A Meta envia até 6 meses de conversas individuais apenas para um destino de webhook direto guardado nas 24 horas seguintes à ligação, uma única vez por ligação. Um número encaminhado pelo easyCoexistence regista a partir do momento em que o URL de encaminhamento é guardado.
A easyCoexistence guarda uma cópia das mensagens?
Parcialmente. Num número encaminhado através da easyCoexistence com as Automatizações ativadas, o texto das mensagens é mantido durante o período que escolher, 30, 90 ou 365 dias (90 por predefinição), e mostrado em Conversas; as entregas encaminhadas são retidas até 7 dias para repetições, e os registos de execução são mantidos 30 dias. A folha é a sua cópia permanente.
A minha IA pode ler a folha para responder aos clientes?
Não a partir de um passo Responder com IA, que lê apenas as suas Instruções e a conversa. Um agente de IA pode consultar dados através de uma ferramenta HTTP personalizada, e um passo Chamar o meu webhook ou Chamar uma API pode enviar a pergunta para um fluxo de trabalho que procura a resposta na folha e a devolve como resposta.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em