インバウンドウェブフック

動的なエージェントルーティング — インバウンド通話が着信するとFinnが御社のサーバーを呼び出します。

3 min read

インバウンド Webhooks

インバウンドコールが到着すると、 Finnは、エージェントが回答するリアルタイムで、インジェクトする変数、およびロードする知識ベースを尋ねることができます。これは、発信者番号、アカウントの階層、日の時刻、A/Bのコホート、またはバックエンドのケアに関する任意のロジックによって、動的にルートすることができます.

固定エージェントが十分な場合は、これをスキップします。 ダイナミックパーコールルーティングが必要な場合は、このページです.

お問い合わせ

作品紹介

caller dials → Finn answers ring → Finn POSTs to your URL → your server returns agent + vars → Finn streams the voice agent

ハンドシェイクはレイテンシーの100〜200msを追加します。エンドポイントは、デフォルトエージェントに500ms** または Finn が戻ってくる必要があります.

お問い合わせ

設定

1. インバウンドWebhook URLを設定する

ダッシュボード → 設定 → 電話番号 → [番号] → インバウンド Webhook URL.

HTTPS エンドポイントを貼り付けます。保存。 Finnは、リーダビリティを検証するために、{"ping": true}ボディで一度それをpingsをpings.

APIに従って

curl https://api.hirefinn.ai/v1/phone-numbers/ph_1234 \
  -X PATCH \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -d '{ "inbound_webhook_url": "https://your-app.com/finn/inbound" }'

2. フォールバックエージェントを設定する

デフォルトの Finn をその番号に設定します。Webhook のタイムアウト、エラー、または無効なレスポンスを返す場合に使用されます.

お問い合わせ

リクエストペイロード

Finn は URL への POST を次のようにします

{
  "session_id": "ws_2H4abc",
  "request_type": "inbound",
  "phone_number_id": "ph_1234",
  "channel": "pstn",
  "from": {
    "phone": "+919876543210",
    "country": "IN",
    "carrier": "Airtel"
  },
  "to": {
    "phone": "+918765432100",
    "country": "IN"
  },
  "received_at": "2026-05-22T14:30:00Z",
  "metadata": {}
}

WhatsAppコールの場合、fromブロックはWhatsApp固有のフィールドを使用します

"from": {
  "wa_id": "919876543210",
  "display_name": "Priya M",
  "profile_pic_url": "https://..."
},
"channel": "whatsapp"

お問い合わせ

フィードバック

コールをルーティングする方法を記述する500ms以内にJSONボディを返します

{
  "finn_id": "fn_def456",
  "language": "hi-IN",
  "variables": {
    "customer_name": "Priya M",
    "account_tier": "premium",
    "last_order_id": "ord_99831",
    "preferred_agent": "Aria"
  },
  "knowledge_base_ids": ["kb_general", "kb_premium_perks"],
  "metadata": {
    "campaign_tag": "premium-support-q2",
    "ab_cohort": "B"
  },
  "recording_enabled": true,
  "max_call_duration_seconds": 600
}

フィールド参照

| フィールド | 必須 | ノート | お問い合わせ | プライバシーポリシー | どの代理店が答えるか。あなたの所属する組織に所属しなければなりません。 | | language | いいえ | オーバーライドエージェントのデフォルト言語。 en-US、hi-IN、es-ES等 | | variables | いいえ | 自由フォームキー・値袋 {variable_name}``{variable_name}としてプロンプト内で使用可能です。 | | knowledge_base_ids | No | KB が読み込まれるオーバーライド | | metadata | ノー | コールレコード・ポストコールwebhookに添付独自の分析タグ作成に使用します。お問い合わせ | recording_enabled | いいえ | エージェントのデフォルトをオーバーライド | | max_call_duration_seconds | いいえ | ハードキャップデフォルトは1800(30分)です。 |

呼び出しを拒否する

{ "action": "reject", "reason": "blocked_caller" }

Finnは、設定された発信メッセージで呼び出しを終了します(「この番号はサービスにはありません」)。 DNCの執行、ブロックされたアカウント、またはアフター・タイムの集荷のために使用して下さい.

すぐに転送

{ "action": "transfer", "to": "+918888888888", "reason": "vip_route" }

AIエージェントを完全にスキップ — 直接人へ。 VIP/エスカレーションの層に便利な.

お問い合わせ

実装例(ノード)

import express from "express";

const app = express();
app.use(express.json());

app.post("/finn/inbound", async (req, res) => {
  const { from, to, channel } = req.body;

  // 1. Look up caller in CRM (must be fast — DB index by phone)
  const phone = from.phone ?? `+${from.wa_id}`;
  const customer = await crm.findByPhone(phone);

  // 2. Block known DNC
  if (customer?.dnc) {
    return res.json({ action: "reject", reason: "dnc" });
  }

  // 3. VIP → straight to human
  if (customer?.tier === "vip") {
    return res.json({
      action: "transfer",
      to: process.env.VIP_DESK_NUMBER!,
      reason: "vip_route",
    });
  }

  // 4. Localized agent based on caller country
  const language = from.country === "IN" ? "hi-IN" : "en-US";

  // 5. Pick agent + load context
  return res.json({
    finn_id: customer?.tier === "premium"
      ? "fn_premium_aria"
      : "fn_standard_aria",
    language,
    variables: {
      customer_name: customer?.name ?? "there",
      account_tier: customer?.tier ?? "standard",
      last_order_id: customer?.last_order_id ?? "",
    },
    knowledge_base_ids:
      customer?.tier === "premium" ? ["kb_general", "kb_premium"] : ["kb_general"],
    metadata: { ab_cohort: customer?.ab_cohort ?? "A" },
  });
});

app.listen(3000);

お問い合わせ

署名検証

生体上のHMAC-SHA256、ヘッダ X-Finn-Signature のポストコール webhooks と同じスキーム.

const sig = req.headers["x-finn-signature"] as string;
const ok = verifyFinnSignature(rawBody, sig, process.env.FINN_INBOUND_SECRET!);
if (!ok) return res.status(401).send("bad signature");

完全な検証実装の Post-call Webhooks] を参照してください.

お問い合わせ

性能要件

これは、*hot パス ** — 応答を待ちながら、呼び出し主は聴覚リングトーンです.

打つことのための先端 < 500ms

キャッシュCRMルックアップ 5分間の電話番号で
共同データベースを使用する-私たち東からwebhook、私たち西にあるDB = 80ms各方法
事前競争のルーティング決定 — 顧客の記録に答えを保存し、ライブを決定しないでください
Skip 非必須の濃縮 インバウンドホップ — ポストコールのwebhookに動作するプッシュ

お問い合わせ

ケーラー事前スクリーニング

ほとんどのアプリは、これらのパターンの1つにインバウンドWebhookを使用します

お問い合わせ

テスト

実際のPSTNリングなしでインバウンドコールをシミュレートするためにFinnCLIを使用してください

finn inbound simulate \
  --phone-number-id ph_1234 \
  --from +919876543210 \
  --webhook-url https://your-app.com/finn/inbound

出力はエンドポイント応答、レイテンシー、および解決されたエージェント+変数を示します。 CIフレンドリー.

お問い合わせ

普通のゴッチャ

| 症状 | 修正 | お問い合わせ | コールは常にデフォルトのエージェントに落ちる | エンドポイントは500msです。 Finnのwebhookログをタイミングでチェックします。お問い合わせ | コールアはエージェントが話す前に2〜3秒の沈黙を聞きます | エンドポイントは遅くてもタイムアウトです。 <200ms>を最適化 | エージェントスピーチで表示されていない変数 | プロンプトプレースホルダー{customer_name} と webhook のキー customerName間のMismatch。両側のヘビ caseを使用してください。 | | 間違ったエージェントが回答 | エンドポイントは、他の組織に所属するfinn_idを返しました。所有権の検証 | | action: reject 敬意を表していない | reasonは文字列であり、JSON は有効です。無効な応答→フォールバック。 |

お問い合わせ

Was this page helpful?

Still stuck or have feedback?

Email [email protected] or use the chat bubble in the bottom-right corner — it's a Finn that knows the Academy cold.

インバウンド Webhooks

作品紹介

設定

1. インバウンドWebhook URLを設定する

APIに従って

2. フォールバックエージェントを設定する

リクエストペイロード

フィードバック

フィールド参照

呼び出しを拒否する

すぐに転送

実装例(ノード)

署名検証

性能要件

打つことのための先端 < 500ms

ケーラー事前スクリーニング

テスト

普通のゴッチャ

関連記事