WhatsApp の会話を CRM に自動で送信する
WhatsApp の会話を CRM に自動で送信するには、受信メッセージを署名付きの Webhook として、お使いのバックエンドまたはワークフローツールに配信します。電話番号で連絡先を検索し、見つからなければ作成します。そのうえで、メッセージをその連絡先のアクティビティとして記録します。WhatsApp のメッセージ ID をアクティビティの一意キーに使うと、再試行された配信は、別のレコードを作る代わりに同じレコードを更新します。
easyCoexistence は、アプリで使っている WhatsApp Business の番号を Coexistence 経由で Meta の Cloud API に接続します。
転送される POST のヘッダーには配信 ID が含まれ、その配信の再試行ごとに同じ値になります。
7回の転送試行の間隔は、おおよそ1、5、30、120、360、1,440分後です。
「Call my webhook」ステップは URL を1回だけ呼び出します。タイムアウトやエラーが起きると実行は失敗し、メールで通知されます。
ビジネススコープのユーザーID(例:US.13491208655302741918)を、電話番号の横、または代わりに user_id と from_user_id で送信します。
オートメーションの実行ログが、トリガーとなったメッセージ、返信、各ステップを保持する期間です。
CRM に届けるべきイベントはどれですか?
Coexistence 番号の会話は3種類のメッセージで構成され、2つの経路で届きます。番号ごとに設定する「Forward URL」は、顧客が送信した内容と、チームが WhatsApp Business アプリで入力した内容を、Meta の元のイベントのまま送信します。CRM が応答するまで再試行されます。オートメーションによる返信は API 経由で Meta に送られ、テキストを含まない配信ステータスとしてのみ報告されます。その文面を記録するには、オートメーションの最後に「Call my webhook」ステップを置いてください。その履歴には、実行が送信した返信が含まれます。1つのエンドポイントで両方を受け取れます。X-EC-Event ヘッダーでは、ステップの場合は automation.step、転送の場合は Meta のフィールド名を読み取ります。
WhatsApp の送信者を CRM の連絡先とどう照合しますか?
電話番号で照合します。正規化した形式を使います。WhatsApp は国番号付きの数字のみ(+ 記号なし)を送ります。例えば 5511987654321 です。これは転送の messages[].from と、「Call my webhook」ステップの contact.wa_id に含まれます。人が入力した CRM のレコードには +55 11 98765-4321 や (11) 98765-4321 が入っているため、数字のみの形式を保持する専用のプロパティを用意し、それで検索してください。一致しない場合は、WhatsApp のプロフィール名と番号で連絡先を作成します。
BSUID も連絡先に保存してください。WhatsApp のユーザーネームを持ち、30日間この番号とやり取りがないユーザーは、from_user_id と contacts[].user_id に BSUID だけが入って届く場合があります。転送には BSUID が含まれ、「Call my webhook」ステップには電話番号が含まれます。
各 CRM レコードには何を保存すべきですか?
連絡先には識別子を、メッセージごとに1つのアクティビティを作成し、方向、テキスト、時刻、一意キーを保存します。以下の図は、各値が両方の経路でどこに入るかを示しています。転送のメッセージ時刻は Meta から届く Unix 秒です。Webhook ステップは ISO 形式の日付を送ります。メディアは、転送では種類と ID として届き、Webhook ステップでは [image] などのプレースホルダーとキャプションとして届きます。そのため、ファイルを保存しようとせず、短いラベルを記録してください。
| Forwarded event (value is Meta's) | Call my webhook step | |
|---|---|---|
| Contact phone | messages[].from | contact.wa_id |
| Contact name | contacts[].profile.name | contact.name |
| BSUID | contacts[].user_id, messages[].from_user_id | Not sent |
| Activity text | text.body, or the media type | message.text and history[].text |
| Direction | messages = in, smb_message_echoes = out | history[].direction: in, out or echo |
| Time | timestamp, Unix seconds | message.at and history[].at, ISO 8601 |
| Unique key | messages[].id (wamid) | message.id; run_id for history entries |
再試行による重複をどう防ぎますか?
まず素早く応答し、その後すべてにキーを付けます。転送が10秒以内に 2xx を受け取れないと、同じ X-EC-Delivery ID で再試行され、最大7回まで続きます。そのため、12秒かかる CRM への呼び出しは、アクティビティを wamid で upsert しない限り2回実行されます。先に 200 を返し、CRM への処理はキューまたはバックグラウンドジョブで行ってください。
「Call my webhook」ステップは再試行されず、Meta 自身の繰り返し配信はオートメーションの実行前にフィルタされるため、メッセージ1件につき最大1回だけ呼び出されます。その履歴のエントリにはメッセージ ID が含まれません。自動返信には run_id と、その位置の組み合わせでキーを付けてください。「Try it」からのテストは、dry_run が true で、サンプルの連絡先 15550000000 とともに届きます。テスト実行で CRM レコードが作られないよう、これらはスキップしてください。
Node.js の受信処理はどのようになりますか?
1つの Express ルートで両方のイベント種類を受け取ります。生のボディを読み取り、X-EC-Event ヘッダーでシークレットを選択し、X-EC-Signature を検証し、すぐに 200 を返して、処理をバックグラウンド関数に渡します。crm オブジェクトは、お使いの CRM の API クライアントを表します。連絡先は数字のみの電話番号で upsert し、アクティビティは一意キーで upsert します。同じ構成は n8n のワークフローでも使えます。署名の検証には Code ノードを使い、その後に CRM のノードを続けてください。
import express from "express";
import crypto from "node:crypto";
const FORWARD_SECRET = process.env.EC_FORWARD_SECRET; // the number's, shown once with the Forward URL
const STEP_SECRET = process.env.EC_STEP_SECRET; // the automation's Signing secret
function signed(req, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get("X-EC-Signature") || "");
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
const mac = crypto.createHmac("sha256", secret).update(m[1] + "." + req.body).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
const app = express();
app.post("/whatsapp/crm", express.text({ type: "application/json" }), (req, res) => {
const kind = req.get("X-EC-Event"); // automation.step, or Meta's field name for a forward
if (!signed(req, kind === "automation.step" ? STEP_SECRET : FORWARD_SECRET)) return res.status(401).end();
res.json({}); // no reply field: nothing is sent to the customer
handle(kind, JSON.parse(req.body)).catch(console.error);
});
async function handle(kind, body) {
if (kind === "messages") {
for (const m of body.value.messages ?? []) { // statuses are skipped
const c = (body.value.contacts ?? []).find((x) => x.wa_id === m.from);
const contact = await crm.upsertContact({ phone: m.from, bsuid: m.from_user_id, name: c?.profile?.name });
await crm.upsertActivity({ key: m.id, contact, direction: "in", text: m.text?.body ?? "[" + m.type + "]", at: new Date(m.timestamp * 1000) });
}
} else if (kind === "smb_message_echoes") {
for (const m of body.value.message_echoes ?? []) {
const contact = await crm.upsertContact({ phone: m.to, bsuid: m.to_user_id });
await crm.upsertActivity({ key: m.id, contact, direction: "out", text: m.text?.body ?? "[" + m.type + "]", at: new Date(m.timestamp * 1000) });
}
} else if (kind === "automation.step" && !body.dry_run) {
const contact = await crm.upsertContact({ phone: body.contact.wa_id, name: body.contact.name });
const sentAfter = body.history.filter((h) => h.direction === "out" && h.at >= body.message.at);
for (const [i, h] of sentAfter.entries()) {
await crm.upsertActivity({ key: body.run_id + ":" + i, contact, direction: "out", text: h.text, at: new Date(h.at) });
}
}
}
app.listen(3000);AI が学習した内容で CRM がリードを更新できますか?
はい、ワークフローで可能です。「Call my webhook」ステップで届くチャットには、AI が尋ねた質問と顧客の回答が含まれます。そのため、n8n のモデルノード、またはバックエンドでの呼び出しによって、ニーズ、予算、時期、所在地を抽出し、リードのフィールドに書き込み、そのステージを進めることができます。返信は返さないでください。顧客はすでに AI のメッセージを受け取っています。ワークフローがリードを電話でのフォローアップに値すると判断した場合は、営業担当者向けのタスクを作成したり、チームに通知したりできます。または、抽出を easyCoexistence に任せることもできます。エージェントまたは「AI saves details」ステップがニーズ、予算、時期をコンタクトのフィールドに書き込み、「Call an API」ステップが本文の {{contact.budget}} 形式のトークンを使って、それらを CRM に送信できます。リード選別のページには、その設定のためのインタビュー指示とペイロードがあります。
設定方法
- Send the number's messages through easyCoexistenceOn the number's page, the Where incoming messages go card must be set to Through easyCoexistence; choose it if it shows Straight to your system.
- Deploy the receiverPublish the endpoint or n8n workflow on public HTTPS, with the CRM upserts keyed on the phone and the message id.
- Save the Forward URLPaste the receiver's URL into Forward URL (optional), click Save forward URL and store the signing secret shown once.
- Log automated repliesIn each automation that replies, add Call my webhook as the last step with the same URL, save, and copy that automation's Signing secret.
- Check one real conversationWrite to the number from another phone, let the automation answer, reply from the app, and confirm three activities on the contact: in, automated out and phone out.
よくある間違い
- フリーテキストの電話番号フィールドで CRM を検索すること。WhatsApp の数字のみの形式は、人が入力した内容とほとんど一致せず、一致しなかったときごとに重複した連絡先が作られます。正規化された数字のみのプロパティで検索してください。
- 転送に応答する前に CRM を呼び出すこと。CRM の応答が10秒を超えると easyCoexistence が再試行し、wamid による upsert がなければアクティビティが2回記録されます。
- 転送だけを記録し、自動返信も含まれると期待すること。API による送信はテキストのないステータスとして戻ります。返信の後に置いた「Call my webhook」ステップが、その文面を運びます。
- テストが CRM に届いてしまうこと。「Try it」は、dry_run が true の状態で実際にお使いの URL を呼び出します。サンプルの連絡先 15550000000 も使われます。upsert の前に、これらのイベントを破棄してください。
「Forward URL」は、顧客のメッセージと電話からの返信を、Meta の元のイベントのまま CRM に渡します。イベントは番号ごとに署名され、CRM が停止している場合は約33時間にわたって再試行されます。「Call my webhook」ステップは、自動返信も追加します。転送とオートメーションはプランに含まれています。料金は接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。無料トライアルは 3 日間です。
よくある質問
どの CRM と連携できますか?
API を備えた CRM であれば、自社のバックエンド経由でも、n8n、Make、Zapier などのワークフローツールを通じてでも利用できます。これらのツールには該当するノードがあります。HubSpot には、これらのメッセージを記録するために作られた WhatsApp チャネルタイプを持つ Communications オブジェクトがあります。HubSpot のページで呼び出し方法を紹介しています。
チームは CRM から顧客に返信できますか?
はい。CRM が番号の送信エンドポイントと get_api_credentials で取得したトークンを使い、Meta の Cloud API 経由で送信する場合に限ります。顧客の最後のメッセージから24時間以内はフリーテキスト、その後は承認済みのメッセージテンプレートを使います。これらのメッセージは、スマートフォン上のアプリのチャットスレッドにも表示されます。
過去の会話を CRM に読み込めますか?
Meta の履歴インポート経由でのみ可能です。これは、接続から24時間以内に保存された直接の Webhook 送信先に、1対1のチャットを最大6か月分送信します。接続ごとに1回のみです。「Through easyCoexistence」に設定した番号は、転送を開始した時点からのみ記録されます。
easyCoexistence は途中で何を保存しますか?
転送された変更は再試行のためにキューに入れられ、7日後に削除されます。easyCoexistence を経由する番号では、メッセージのテキストは Conversations と AI のコンテキストのために、お客様が選んだ期間(30日、90日、365日)も保持され、実行ログは30日間保存されます。永続的な記録は CRM が保持します。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日