登录开始免费试用
Meta Tech Provider

自动将 WhatsApp 消息和联系人保存到 Google Sheets

要将 WhatsApp Business 消息自动保存到 Google Sheets,请以已签名的 HTTP POST 将其发送到 n8n、Make 或 Zapier 等自动化工具,再由其 Google Sheets 步骤为每条消息新增一行,包括:时间、方向、电话号码、姓名、文本和消息 ID。第二个标签页以电话号码为键,每位联系人保留一行,对方再次发消息时更新该行。

easyCoexistence 通过 Coexistence 将您在应用中保留的 WhatsApp Business 号码连接到 Meta 的 Cloud API。

7 attempts

当您的 URL 无法响应时,转发的投递将在约 1、5、30、120、360 和 1,440 分钟后重试。

10 s

转发的 POST 等待 2xx 响应的时长,超时后该次投递将重试。

60 / min

每个项目每位用户每分钟允许的 Google Sheets API 写入请求数;每个项目 300 次。

Redirect

Apps Script 网页应用的输出会重定向到一次性的 script.googleusercontent.com URL。

No headers

Apps Script 的 doPost 事件对象只提供正文和参数,不提供 HTTP 请求标头。

应由哪条路径填充表格?

在消息经由 easyCoexistence 的号码上有两条路径,各自满足不同需求。Forward URL 每个号码只需设置一次,无论是否有自动化作出响应,它都会转发 Meta 的原始事件:客户消息、您的团队在 WhatsApp Business 应用中输入的回复,以及投递状态。这是完整消息记录的路径。自动化内的「Call my webhook」步骤只针对该自动化所选的消息触发,并携带近期聊天内容,包括自动化刚刚发出的回复。它适合由某一个自动化处理的潜在客户、订单或请求表格。两者均已签名,但使用不同的签名密钥。

Forward URL (per number)Call my webhook step (per automation)
Fires onAny message event on the number, with or without automationsOnly messages that automation is picked for
CarriesMeta's original value: messages, phone replies, statusesThe message, the contact and up to 10 recent messages
Automated repliesDelivery statuses only, without the textIn history, direction out
Retries7 attempts over about 33 hoursOne attempt
Signed withThe number's forward secret, shown onceThe automation's Signing secret
Set inNumber page, Where incoming messages go cardThe automation editor, or create_automation

会收到哪些字段,表格应设置哪些列?

转发的 POST 包装了一条 Meta 变更:id(投递标识)、event(Meta 的字段名,如 messages 或 smb_message_echoes)、received_at、connection(您号码的 id、phone 和 phone_number_id),以及原样保留的 value。在 value 中,messages 保存客户发来的内容,message_echoes 保存您的团队在手机上输入的内容。电话号码以带国家代码的数字形式到达,不带加号;请将该列存储为纯文本,以免 Sheets 将其转换为数字。拥有 WhatsApp 用户名的用户可能会附带与号码并存,或取代号码,出现业务范围用户 ID,因此请为其保留一列。

Timemessages[].timestamp, Unix seconds, converted to a date
Directionin for messages, out for smb_message_echoes
Phonemessages[].from, or message_echoes[].to for your replies
User IDmessages[].from_user_id, the BSUID, when Meta sends it
Namecontacts[].profile.name, the customer's WhatsApp profile name
Texttext.body, a button's text, or [image] with its caption
Message idmessages[].id, the wamid: the key that stops duplicates
Your numberconnection.phone, to tell several numbers apart

如何在 n8n 中构建消息记录?

共三个节点。一个 Webhook 节点,HTTP Method 设为 POST,Respond 设为 Immediately,并将其 Production URL 保存为该号码的 Forward URL。一个 Code 节点,用转发密钥检查 X-EC-Signature,并将事件转换为行,同时跳过投递状态。一个 Google Sheets 节点,选择 Append or Update Row 操作,Column to match on 设为消息 ID,这样重试的投递会改写同一行,而不是新增一行。

转发密钥仅在您保存 Forward URL 时显示一次;若丢失,请点击 New secret 并粘贴新密钥。n8n Cloud 允许 Code 节点使用 crypto 模块;自托管的 n8n 需要设置 NODE_FUNCTION_ALLOW_BUILTIN=crypto。

n8n Code node (Run Once for All Items): verify a forward and return rows
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 }));

如何为每位联系人保留一行?

在 Contacts 标签页上再添加一个 Google Sheets 节点,同样使用 Append or Update Row,并以 Phone 匹配。映射电话号码、个人资料名称、用户 ID、时间,以及最新消息的文本。来自某个号码的第一条消息会创建其行;之后的消息会更新姓名和最后联系时间列,因此该标签页也可作为谁在何时发过消息的名单。请将手动撰写的备注保存在单独的标签页,并按电话号码查找,以免工作流覆盖这些内容。

保存在手机通讯录中的联系人不会以这种方式到达。Meta 只会将其(最多含 6 个月的聊天记录)发送到连接号码后 24 小时内保存的直接 Webhook 目标地址。

Apps Script 能否直接接收消息?

不能干净地接收,因此请在表格前放置一个工作流工具。Google 通过重定向到一次性的 script.googleusercontent.com URL 提供 Apps Script 网页应用的响应,而 easyCoexistence 不会跟随重定向。302 会被视为投递失败:转发最多重试 7 次,每次重试都会再次运行 doPost 并写入另一行;而 Call my webhook 步骤会失败并向您发送邮件。doPost 也无法读取请求标头,因此无法在那里进行 X-EC-Signature 检查。

Apps Script 仍然适合另一方向,即从表格的行发送已批准的消息模板,Google Sheets 集成页面附有相关代码。

Make 或 Zapier 能否改为填充表格?

可以。在 Make 中,以 Webhooks > Custom webhook 开始场景,并添加 Google Sheets > Add a Row;在 Zapier 中,使用 Webhooks by Zapier 的 Catch Raw Hook(它会保留标头),然后添加 Google Sheets > Create Spreadsheet Row。两者都会立即以 2xx 响应 POST,这正是转发在其 10 秒时限内所需的。从 value.messages 映射上述相同字段,并过滤掉 value 中包含 statuses 而非 messages 的事件。

请将 hook URL 视为密码,因为任何持有它的人都可以写入行。若您的套餐包含代码步骤,请在那里使用 n8n 节点中相同的 HMAC 方法检查 X-EC-Signature。

如何避免重复或缺失的行?

重复行来自重试。若转发在 10 秒内未收到 2xx 响应,将以相同的 X-EC-Delivery 标头和正文中相同的 id 再次发送,其中的消息保留其 wamid,因此以消息 ID 匹配即可让重试无害。在 Webhook 步骤路径上,来自 Try it 的测试会携带 dry_run true:请将其路由到测试标签页或直接丢弃。

缺失的行来自 Google 的写入配额。Sheets API 允许每个项目每位用户每分钟 60 次写入请求,而一个 n8n 凭据即对应一个用户;营销活动后的一阵回复突发可能超出该限制,并返回 HTTP 429。请在 Google Sheets 节点的设置中开启 Retry On Fail,或先收集几秒钟的消息,再通过一次请求全部添加。

设置方法

  1. 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.
  2. 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.
  3. 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.
  4. 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.

常见错误

  • 使用自动化的签名密钥检查转发,或反过来。Forward URL 使用该号码的转发密钥签名,Call my webhook 使用自动化自身的密钥签名;请根据 X-EC-Event 标头选择密钥。
  • 每次 POST 都新增一行而没有键。若投递在响应缓慢后被重试,会写入同一条消息两次;请使用 Append or Update Row,并以消息 ID 匹配。
  • 将投递状态写成消息。messages 事件的 value.statuses 中也包含已发送、已送达和已读状态,这些状态没有文本,会产生空行。
  • 将 Apps Script 网页应用 URL 保存为 Forward URL。其重定向会被计为失败,因此 7 次尝试中的每一次都会再次运行 doPost 并新增一行重复记录。
使用 EasyCoexistence 完成这些操作

开启自动化后,Forward URL 会将 Meta 的原始事件传递到您的工作流,使用只有您持有的密钥签名,并在您的 URL 不可用时重试;Call my webhook 步骤则发送自动化所处理的内容及其回复。两者均包含在套餐中。每个号码每月 US$ 9 降至 US$ 0.75,号码越多单价越低,前 3 天免费试用。

常见问题

我的团队在手机上输入的内容会进入表格吗?

会,通过 Forward URL 实现。在 WhatsApp Business 应用中输入的回复会以 smb_message_echoes 事件到达,其中 to 字段为客户的号码。自动化发出的回复仅以投递状态返回,因此请在回复之后放置的 Call my webhook 步骤中记录其文本。

我可以将现有聊天记录载入表格吗?

消息经由 easyCoexistence 的号码不可以。Meta 仅会将最多 6 个月的一对一聊天记录发送到连接后 24 小时内保存的直接 Webhook 目标地址,每个连接一次。经由 easyCoexistence 路由的号码,从保存 Forward URL 的那一刻起开始记录。

easyCoexistence 会保存消息的副本吗?

部分保存。在通过 easyCoexistence 路由且开启自动化的号码上,消息文本会按您选择的期限保留,可选 30、90 或 365 天(默认 90 天),并显示在 Conversations 中;转发的投递最多保留 7 天用于重试,运行日志保留 30 天。表格才是您的永久副本。

我的 AI 能否读取表格来回答客户?

无法通过 Reply with AI 步骤实现,该步骤只读取其指令和聊天内容。AI 智能体可以通过自定义 HTTP 工具查找信息,Call my webhook 或 Call an API 步骤则可以将问题发送到一个工作流,由该工作流在表格中查找答案,并将其作为回复返回。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间