Inkommande webhooks

Inkommande webhooks

När ett inkommande samtal kommer in kan Finn i realtid fråga din server vilken agent som ska svara, vilka variabler som ska injiceras och vilken kunskapsbas som ska laddas. Det gör att du kan dirigera dynamiskt – efter uppringarens nummer, kontonivå, tid på dygnet, A/B-kohort eller någon annan logik i din backend.

Räcker det med en fast agent kan du hoppa över det här. Vill du ha dynamisk dirigering per samtal är det den här sidan som gäller.

Så fungerar det

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

Handskakningen lägger till cirka 100–200 ms latens. Din endpoint måste svara på under 500 ms, annars faller Finn tillbaka på standardagenten.

Konfigurera

1. Ange URL för inkommande webhook

Dashboard → Inställningar → Telefonnummer → [nummer] → URL för inkommande webhook.

Klistra in din HTTPS-endpoint. Spara. Finn pingar den en gång med en {"ping": true}-body för att verifiera att den går att nå.

Via 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. Ange en reservagent

Konfigurera en standard-Finn för numret – används om din webhook får timeout, ger fel eller returnerar ett ogiltigt svar.

Begärans payload

Finn skickar POST till din URL med:

{
  "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": {}
}

För WhatsApp-samtal använder from-blocket WhatsApp-specifika fält:

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

Svar

Returnera en JSON-body inom 500 ms som beskriver hur samtalet ska dirigeras:

{
  "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
}

Fältreferens

Avvisa samtalet

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

Finn avslutar samtalet med ett konfigurerat utgående meddelande ("Detta nummer är inte längre i bruk"). Använd för DNC-efterlevnad, blockerade konton eller avslut utanför öppettiderna.

Koppla vidare direkt

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

Hoppa över AI-agenten helt – koppla direkt till en människa. Användbart för VIP- eller eskaleringsnivåer.

Implementationsexempel (Node)

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);

Signaturverifiering

Samma metod som för webhooks efter samtal – HMAC-SHA256 över den råa bodyn, header X-Finn-Signature.

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");

Se Webhooks efter samtal för den fullständiga verifieringsimplementationen.

Prestandakrav

Detta ligger på den kritiska vägen – den som ringer hör ringsignalen medan svaret inväntas.

Tips för att klara < 500 ms

• Cachea CRM-uppslag per telefonnummer i 5 minuter
• Använd en samlokaliserad databas – webhook från us-east, DB i us-west = 80 ms åt varje håll
• Förberäkna routningsbeslut – lagra svaret på kundposten, avgör det inte i realtid
• Hoppa över icke-nödvändig anrikning i det inkommande steget – lägg det arbetet i webhooken efter samtal

Förhandsgranskning av uppringare

De flesta appar använder den inkommande webhooken för något av dessa mönster:

Testning

Använd Finn CLI för att simulera inkommande samtal utan en riktig PSTN-signal:

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

Utdata visar din endpoint-respons, latens samt den upplösta agenten + variablerna. CI-vänligt.

Vanliga fallgropar

Relaterat

• API-referens →
• Webhooks efter samtal →
• Telefonnummer →
• WhatsApp Business Calling →
• Inkommande vs utgående →