Inbound webhooks

Inkomende Webhooks

Wanneer een inkomende oproep aankomt, kan Finn uw server in real time vragen met welk middel te beantwoorden, welke variabelen te injecteren, en welke kennisbasis te laden. Hiermee kunt u dynamisch routeren door beller nummer, account tier, tijd van de dag, A / B cohort, of een logica uw backend geeft om.

Als een vaste agent genoeg is, sla dit dan over. Als je wilt dynamische per-call routing, dit is de pagina.

Hoe het werkt

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

De handshake voegt ~100 Uw eindpunt moet reageren in onder 500ms of Finn valt terug naar de standaard agent.

Instellen

1. Stel de inkomende webhook URL in

Dashboard → Instellingen → Telefoonnummers → [nummer] → Inkomende Webhook URL.

Plak je HTTPS eindpunt. Opslaan. Finn pings het eenmaal met een {"ping": true} lichaam om de bereikbaarheid te controleren.

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. Stel een terugvalmiddel in

Configureren van een standaard Finn voor dat nummer gebruikt als uw webhook timeout, fouten, of geeft een ongeldig antwoord.

Verzoek lading

Finn POSTs naar uw URL met:

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

Voor WhatsApp-aanroepen gebruikt het from-blok WhatsApp-specifieke velden:

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

Respons

Geef een JSON-lichaam binnen 500m terug waarin wordt beschreven hoe de oproep moet worden doorgestuurd:

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

Veldreferentie

Veld vereist

Ja** Welke agent antwoordt. Moet van je org zijn De standaardtaal van de overrideagent. en-US, hi-IN, es-ES, enz Gratis sleutel/waarde zak. Verkrijgbaar in de prompt als {variable_name} | knowledge_base_ids | No | Override which KBs are loaded for this call. | Gebruik voor je eigen analytics tagging. Wat | recording_enabled | No | Override the agent default. | Hard cap. Standaard is 1800 (30 min)

De oproep weigeren

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

Finn eindigt de oproep met een geconfigureerd uitgaand bericht ("Dit nummer is niet langer in gebruik"). Gebruik voor DNC handhaving, geblokkeerde accounts, of na-uren ophangen.

Onmiddellijk overbrengen

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

Skip de AI agent volledig route direct naar een mens. Nuttig voor VIP / escalatie niveaus.

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

Controle van de handtekening

Zelfde schema als post-call webhooks HMAC-SHA256 over het ruwe lichaam, 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");

Zie Post-call Webhooks voor de volledige verificatieuitvoering.

Prestatievoorschriften

Dit is op het hot pad De beller hoort ringtone tijdens het wachten op uw reactie.

Metrisch doel |---|---| Response time *** < 500ms** (p99) Tijdslimiet 1000ms Fallback op timeout Standaard agent geconfigureerd op het telefoonnummer Fallback op 5xx Terugval op ongeldige JSON Standaardagent + fout geregistreerd

Tips voor het raken van < 500ms

• Cache CRM opzoeken per telefoonnummer gedurende 5 minuten
• Gebruik een gecolokaliseerde database
• Pre-compute routing decisions
• Skip niet-essentiële verrijking op de inkomende hop

Beller pre-screening

De meeste apps gebruiken de inkomende webhook voor een van deze patronen:

Testen

Gebruik de Finn CLI om inkomende gesprekken te simuleren zonder een echte PSTN ring:

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

Output toont uw eindpunt respons, latentie, en de opgelost agent + variabelen. CI-vriendelijk.

Gemeenschappelijke gotcha's

Symptoom Fix |---|---| Je eindpunt is > 500ms. Controleer Finn's webhook log voor de timing. Wat De beller hoort 2-3s stilte voordat agent spreekt... Je eindpunt is langzaam maar onder timeout. Optimaliseer tot < 200ms Gebruik slang case beide kanten Je eindpunt gaf een finn_id terug die tot een andere org behoort. Controleer eigendom Controle reason is een string, antwoord JSON is geldig. Ongeldige reacties → terugval

Gerelateerd

• API Referentie →
• Post-call Webhooks →
• Telefoonnummers →
• WhatsApp Business Calling →
• Inkomende vs uitgaande →