Coexistence 番号の WhatsApp を Bitrix24 CRM に接続する

n8n は Bitrix24 とどのように連携しますか？

受信 Webhook を使います。Bitrix24 の受信 Webhook はイベントを受け取る口ではなく、認証情報の役割を持ちます。Bitrix24 の開発者向けリソースで作成し、使用できるスコープを選ぶと、ポータルのアドレス、作成したユーザーの ID、秘密コードを含む URL が発行されます。この URL の末尾にメソッド名を付けると、そのユーザーの権限で REST API を呼び出せます。

そのため n8n では、Bitrix24 に対する各ステップを、この URL に crm.lead.add.json のようなメソッドを付けて POST する HTTP Request ノードとして組みます。OAuth の手順を踏む必要はなく、アプリを公開する必要もありません。Webhook には CRM スコープだけを付与してください。また、Bitrix24 はそのユーザーの権限でアクセスを確認するため、ワークフローが参照すべきリードと連絡先をすべて見られるユーザーで作成してください。

ワークフローはどの Bitrix24 メソッドを呼び出しますか？

n8n の Webhook ノードが Meta からメッセージを受け取った後、次の 3 つを順に呼び出します。

crm.duplicate.findbycomm に type として PHONE と送信者の電話番号を渡すと、その番号を持つリード、連絡先、会社の ID が返ります。3 種類を一度に検索でき、テキスト項目ではなく連絡先情報での照合を目的に作られているため、この検索に適しています。

何も返らなかった場合は、crm.lead.add で WhatsApp のプロフィール名をタイトルに、電話番号を電話項目に入れたリードを作成します。続いて crm.timeline.comment.add に ENTITY_TYPE、ENTITY_ID、COMMENT を渡し、メッセージ本文をレコードへのコメントとして書き込みます。コメントは通話やメールと並んでタイムラインに表示されるので、営業担当者がいつも見ている場所で確認できます。

POST https://yourcompany.bitrix24.com/rest/1/<secret>/crm.duplicate.findbycomm.json
{ "type": "PHONE", "values": ["14155550188"] }

POST .../crm.lead.add.json
{ "fields": { "TITLE": "WhatsApp: Maria", "PHONE": [{ "VALUE": "14155550188", "VALUE_TYPE": "MOBILE" }] } }

POST .../crm.timeline.comment.add.json
{ "fields": { "ENTITY_TYPE": "lead", "ENTITY_ID": 4211, "COMMENT": "do you have anything friday?" } }

レート制限はワークフローの設計にどう影響しますか？

Bitrix24 は REST 呼び出しをリーキーバケット方式で制限しています。リクエストのたびにカウンターが加算され、カウンターは毎秒一定量ずつ減り、しきい値を超えると次のリクエストには 503 と QUERY_LIMIT_EXCEEDED が返ります。Enterprise プランではカウンターが毎秒 5 ずつ減り、しきい値は 250 です。それ以外のプランでは毎秒 2 ずつ減り、しきい値は 50 です。

受信メッセージ 1 件につき呼び出しは 2、3 回なので、一定のペースで届く間はしきい値に近づきません。問題になるのはバーストです。同じメッセージテンプレートに 1 分以内に 50 人のお客様が返信すると、最大 150 回の呼び出しになります。HTTP Request ノードは失敗時に短い待機を挟んで再試行する設定にし、ワークフローの実行は 1 件ずつ処理するようにしてください。そうすれば、バーストが弾かれることなく Bitrix24 へ順に流れ込みます。

スマートフォンで入力した返信も Bitrix24 に届きますか？

届けられます。Coexistence の番号では WhatsApp Business アプリが引き続き使えます。アプリから返信すると、Meta は送信メッセージのエコーを smb_message_echoes フィールドとして、同じ Webhook の送信先に送ります。

ワークフローに 2 つ目の分岐を設け、このエコーも受信メッセージと同じ方法で処理し、コメントには送信メッセージであることを示す印を付けます。これでレコードには、お客様の発言と店舗側の返信が順番に並んだ会話全体が残ります。

ワークフロー自身が Cloud API で送る返信は、送信する時点ですでにワークフローの手元にあります。Webhook が戻ってくるのを待たず、送信と同時に記録してください。

よくある間違い

• 受信 Webhook の URL をクライアント側のコードや共有ドキュメントに貼り付けること。URL に含まれる秘密コードで、その Webhook に付与したすべてのスコープが使えてしまいます。
• すべてのリードを見られないユーザーで Webhook を作成すること。検索で既存のレコードを見落とし、ワークフローが重複を作ってしまいます。
• 再試行なしでバースト的に呼び出しを送ること。Bitrix24 が 503 QUERY_LIMIT_EXCEEDED を返し、そのメッセージはタイムラインに届きません。

よくある質問

続きを読む