自动将 WhatsApp 消息和联系人保存到 Google Sheets
要将 WhatsApp Business 消息自动保存到 Google Sheets,请以已签名的 HTTP POST 将其发送到 n8n、Make 或 Zapier 等自动化工具,再由其 Google Sheets 步骤为每条消息新增一行,包括:时间、方向、电话号码、姓名、文本和消息 ID。第二个标签页以电话号码为键,每位联系人保留一行,对方再次发消息时更新该行。
easyCoexistence 通过 Coexistence 将您在应用中保留的 WhatsApp Business 号码连接到 Meta 的 Cloud API。
当您的 URL 无法响应时,转发的投递将在约 1、5、30、120、360 和 1,440 分钟后重试。
转发的 POST 等待 2xx 响应的时长,超时后该次投递将重试。
每个项目每位用户每分钟允许的 Google Sheets API 写入请求数;每个项目 300 次。
Apps Script 网页应用的输出会重定向到一次性的 script.googleusercontent.com URL。
Apps Script 的 doPost 事件对象只提供正文和参数,不提供 HTTP 请求标头。
应由哪条路径填充表格?
在消息经由 easyCoexistence 的号码上有两条路径,各自满足不同需求。Forward URL 每个号码只需设置一次,无论是否有自动化作出响应,它都会转发 Meta 的原始事件:客户消息、您的团队在 WhatsApp Business 应用中输入的回复,以及投递状态。这是完整消息记录的路径。自动化内的「Call my webhook」步骤只针对该自动化所选的消息触发,并携带近期聊天内容,包括自动化刚刚发出的回复。它适合由某一个自动化处理的潜在客户、订单或请求表格。两者均已签名,但使用不同的签名密钥。
| 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 |
会收到哪些字段,表格应设置哪些列?
转发的 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,因此请为其保留一列。
如何在 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。
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,或先收集几秒钟的消息,再通过一次请求全部添加。
设置方法
- 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.
常见错误
- 使用自动化的签名密钥检查转发,或反过来。Forward URL 使用该号码的转发密钥签名,Call my webhook 使用自动化自身的密钥签名;请根据 X-EC-Event 标头选择密钥。
- 每次 POST 都新增一行而没有键。若投递在响应缓慢后被重试,会写入同一条消息两次;请使用 Append or Update Row,并以消息 ID 匹配。
- 将投递状态写成消息。messages 事件的 value.statuses 中也包含已发送、已送达和已读状态,这些状态没有文本,会产生空行。
- 将 Apps Script 网页应用 URL 保存为 Forward URL。其重定向会被计为失败,因此 7 次尝试中的每一次都会再次运行 doPost 并新增一行重复记录。
开启自动化后,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,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间