Inkommande webhooks

Inkommande Webhooks

När ett inkommande samtal anländer kan Finn fråga ** din server** i realtid som agent att svara med, vilka variabler att injicera och vilken kunskapsbas att ladda. Detta låter dig dirigera dynamiskt - genom ringnummer, kontonivå, tid på dagen, A / B-kohort eller någon logik som din backend bryr sig om.

Om en fast agent är tillräckligt, hoppa över detta. Om du vill *dynamisk per-call routing, är detta sidan.

Hur det fungerar

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

Handskakan lägger till ~ 100-200ms latens. Din slutpunkt måste svara i ** under 500ms ** eller Finn faller tillbaka till standardagenten.

Konfigurera

1. Ställ in den inkommande webhook URL

Dashboard → Inställningar → Telefonnummer → [nummer] → Inbound Webhook URL.

Klistra på din HTTPS endpoint. Spara. Finn pingar det en gång med ett {"ping": true}-organ för att verifiera räckvidden.

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

Ställ en fallback agent

Konfigurera en standard Finn för det numret - används om din webhook time out, fel eller returnerar ett ogiltigt svar.

Begär payload

Finn 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-kropp inom 500ms som beskriver hur man dirigerar samtalet:

{
  "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ält referens

| Fält | Krävs? | Anteckningar | |---------- | finn_id | *Ja | Vilken agent svarar. Måste tillhöra din org | language | Nej | Override agentens standardspråk. en-US, hi-IN, es-ES, etc. | | variables | No | Free-form key/value bag. Finns i prompten som {variable_name}. | | knowledge_base_ids | Nej | Överskridande vilka KB som är laddade för detta samtal. | | metadata | Nej | Bifogad till call record och post-call webhook. Använd för din egen analys tagging. | | recording_enabled | Nej | åsidosätta agentens standard. | | max_call_duration_seconds | Nej | Hårt lock. Standard är 1800 (30 min)

Avvisa samtalet

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

Finn avslutar samtalet med ett konfigurerat utgående meddelande ("Detta nummer är inte längre i tjänst"). Använd för DNC verkställighet, blockerade konton eller eftertimmars hangups.

Överför omedelbart

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

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

Implementeringsexempel (nod)

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 system som post-call webhooks - HMAC-SHA256 över den råa kroppen, rubrik 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 Post-call Webhooks för full kontroll.

Prestandakrav

Detta är på den ** heta vägen ** - kallaren hör ring ton medan du väntar på ditt svar.

Metric | Mål | |-------- | Svarstid | < 500ms (p99) | | Timeout | 1000ms | Fallback på timeout | Standard agent konfigurerad på telefonnumret | Fallback på 5xx | Standard agent Fallback på ogiltig JSON | Standard agent + fel inloggad |

Tips för att träffa < 500ms

• Cache CRM lookups med telefonnummer i 5 minuter
• ** Använd en sammanflätad databas* — webhook from us-east, DB in us-west = 80ms varje sätt
• Pre-compute routing beslut - lagra svaret på kundrekordet, besluta inte live
• Skip icke-essentiella anrikning på den inkommande hopen – driva det arbetet till post-call webhook

Caller pre-screening

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

| Mönster | Använd fall | |-------- | Lookup + personifiera | Pull kundrekord, passnamn + nivå som variabler | | ** DNC verkställighet | Avvisa samtal från blockerade nummer | VIP routing | Skip agent, överför direkt till mänskligt skrivbord | | ** språkdetektering** | Välj hi-IN för Indien, en-US för amerikanska uppringar | A/B-testning* | Rutt 50% av samtalen till en ny agentversion | Efter timmars routing | Olika agenter (eller röstbrevlåda) utanför arbetstid | Campaign tracking | Tag samtal från specifika spårningsnummer med ett kampanj-ID | | *Multi-tenant SaaS | Vägen till hyresgästen vars antal uppringdes |

Testning

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

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

Utgång visar ditt endpoint-svar, latens och den lösta agenten + variabler. CI-vänlig.

Vanliga gotchas

Symptom | Fix | |-------- Ringar faller alltid tillbaka till standardagent | Din slutpunkt är > 500ms. Kontrollera Finns webhook log för tidpunkten. | Caller hör 2-3s tystnad innan agenten talar | Din slutpunkt är långsam men under timeout. Optimera till < 200ms. | Variabler som inte förekommer i agenttal | Mismatch mellan prompt placeholder {customer_name} och webhook key customerName. Använd snake case båda sidor Fel agent svarade | Din slutpunkt returnerade en finn_id som tillhör en annan org. Verifiera ägande. | | action: reject inte hedrad | Kontroll reason är en sträng, svar JSON är giltig. Ogiltiga svar → nedgång. |

Relaterad

• API Referens ](/academy/api)
• Post-call Webhooks Ḳ]
• [Phone Numbers |0]
• WhatsApp Business Calling →]
• [Inbound vs Outbound |0]