ਹਰ ਕਾਲ ਲਈ ਡਾਇਨਾਮਿਕ ਸੰਰਚਨਾ

ਤੁਹਾਡੇ ਨਿਯੰਤਰਣ ਹੇਠਲੇ webhook ਵਿੱਚ ਕਸਟਮ ਤਰਕ ਦੇ ਆਧਾਰ

ਮੂਲ ਰੂਪ ਵਿੱਚ ਹਰ ਫ਼ੋਨ ਨੰਬਰ ਅਤੇ ਪ੍ਰਕਾਸ਼ਯੋਗ ਕੀ ਨਾਲ ਇੱਕ ਸਥਿਰ ਏਜੰਟ ਨਿਰਧਾਰਤ ਹੁੰਦਾ ਹੈ। ਜਦੋਂ ਤੁਹਾਨੂੰ ਹਰ ਕਾਲਰ ਲਈ ਜਾਂ ਹਰ ਵਿਜ਼ਟਰ ਲਈ ਕਸਟਮਾਈਜ਼ੇਸ਼ਨ ਚਾਹੀਦੀ ਹੋਵੇ — VIP ਰੂਟਿੰਗ, ਲੌਗ-ਇਨ ਵਰਤੋਂਕਾਰ ਸੰਦਰਭ, A/B prompt ਟੈਸਟ — ਤਾਂ ਵੈੱਬਹੁੱਕ ਮੋਡ ਵਰਤੋ ਅਤੇ ਆਪਣੇ ਸਰਵਰ ਨੂੰ ਫ਼ੈਸਲਾ ਕਰਨ ਦਿਓ।

ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ#

1. ਤੁਸੀਂ telephony.incoming (ਫੋਨ) ਜਾਂ web.incoming (ਵਿਜਟ) ਇਵੈਂਟ ਨੂੰ ਸਬਸਕ੍ਰਾਈਬ ਕਰਦੇ ਹੋ। ਦੋਵੇਂ ਬਲਾਕਿੰਗ ਵੈੱਬਹੁੱਕ ਹਨ: ThunderPhone ਕਾਲ ਜਾਰੀ ਰੱਖਣ ਤੋਂ ਪਹਿਲਾਂ ਤੁਹਾਡੇ ਜਵਾਬ ਦੀ ਉਡੀਕ ਕਰਦਾ ਹੈ, ਫੋਨ ਕਾਲ ਲਈ ਵੱਧ ਤੋਂ ਵੱਧ 13 ਸਕਿੰਟ (ਇੱਕ ਦੁਬਾਰਾ ਕੋਸ਼ਿਸ਼ ਸਮੇਤ) ਅਤੇ ਵਿਜਟ ਸੈਸ਼ਨ ਲਈ 10 ਸਕਿੰਟ।
2. ThunderPhone ਤੁਹਾਨੂੰ {call_id, from_number, to_number} ਭੇਜਦਾ ਹੈ (ਵਿਜਟ ਸੈਸ਼ਨਾਂ ਵਿੱਚ ਨੰਬਰਾਂ ਦੀ ਬਜਾਏ ਵਿਜਟ-ਵਿਸ਼ੇਸ਼ ਫੀਲਡ ਹੁੰਦੇ ਹਨ — ਬੇਨਤੀ ਸਕੀਮਾ ਦੇਖੋ)।
3. ਤੁਹਾਡਾ ਸਰਵਰ ਏਜੰਟ ਸੰਰਚਨਾ ਨਾਲ ਜਵਾਬ ਦਿੰਦਾ ਹੈ (prompt, ਆਵਾਜ਼, ਉਤਪਾਦ, ਟੂਲ)। ThunderPhone ਕਾਲ ਲਈ ਉਸ ਸੰਰਚਨਾ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ।
4. ਕੋਈ ਫਾਲਬੈਕ ਏਜੰਟ ਨਹੀਂ ਹੈ। ਜੇ ਤੁਸੀਂ {} ਜਾਂ ਅਵੈਧ ਸੰਰਚਨਾ ਵਾਪਸ ਕਰਦੇ ਹੋ, ਜਾਂ ਬੇਨਤੀ ਆਪਣੀ ਦੁਬਾਰਾ ਕੋਸ਼ਿਸ਼ ਤੋਂ ਬਾਅਦ ਵੀ ਅਸਫਲ ਰਹਿੰਦੀ ਹੈ, ਤਾਂ ਫੋਨ ਕਾਲ ਤੁਰੰਤ ਖਤਮ ਕਰ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ ਅਤੇ end_reason inbound_config_webhook_failed ਨਾਲ ਰਿਕਾਰਡ ਕੀਤੀ ਜਾਂਦੀ ਹੈ; ਵਿਜਟ ਸੈਸ਼ਨ ਦੀ ਬੇਨਤੀ ਅਸਫਲ ਹੋ ਜਾਂਦੀ ਹੈ।

1. ਵੈੱਬਹੁੱਕ ਟਿਕਾਣਾ ਕੌਂਫਿਗਰ ਕਰੋ#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod call-incoming",
    "url":    "https://example.com/thunderphone/incoming",
    "events": ["telephony.incoming"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Dynamic widget",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-incoming",
    "allowed_domains": ["example.com"]
  }'

2. ਹੈਂਡਲਰ ਲਾਗੂ ਕਰੋ#

ਤਿੰਨ ਮੁੱਢਲੇ ਨਿਯਮ:

• ਹਰ ਬੇਨਤੀ ਉੱਤੇ ਦਸਤਖਤ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ (ਵੇਖੋ ਵੈੱਬਹੁੱਕ ਦਸਤਖਤਾਂ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ)। dev ਵਿੱਚ ਇਸਨੂੰ ਨਾ ਛੱਡੋ — ਇੱਕ ਵਾਰ ਸਹੀ ਕਰੋ ਅਤੇ ਦੁਬਾਰਾ ਵਰਤੋ।
• ਤੁਰੰਤ ਜਵਾਬ ਦਿਓ। ਫੋਨ ਕਾਲ ਦੀ ਪਹਿਲੀ ਕੋਸ਼ਿਸ਼ 10 ਸਕਿੰਟਾਂ ਉੱਤੇ ਕੱਟ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ ਅਤੇ ਪੂਰੀ ਗੱਲਬਾਤ 13 ਸਕਿੰਟਾਂ ਉੱਤੇ, ਅਤੇ ਹਰ ਸਕਿੰਟ ਕਾਲਰ ਲਈ ਖਾਮੋਸ਼ੀ ਹੁੰਦਾ ਹੈ। ਲੋੜ ਹੋਵੇ ਤਾਂ ਡਾਟਾਬੇਸ ਲੁੱਕਅੱਪ ਕਰੋ, ਪਰ ਡਾਊਨਸਟ੍ਰੀਮ LLMs ਨੂੰ ਸਮਕਾਲੀ ਤੌਰ ਉੱਤੇ ਕਾਲ ਨਾ ਕਰੋ — ਜੇ ਤੁਹਾਨੂੰ ਡਾਇਨਾਮਿਕ prompt ਬਣਾਉਣਾ ਹੈ, ਤਾਂ ਪਹਿਲਾਂ ਤੋਂ ਗਣਨਾ ਕਰਕੇ ਕੈਸ਼ ਕਰੋ।
• ਸਾਫ਼ ਤਰੀਕੇ ਨਾਲ ਫਾਲਬੈਕ ਕਰੋ। ਕਿਸੇ ਵੀ ਅਣਅਪੇਖਿਤ ਸਥਿਤੀ ਲਈ, ਡਿਫਾਲਟ prompt ਅਤੇ voice (ਜਾਂ ਸੁਰੱਖਿਅਤ ਕੀਤਾ agent_id) ਨਾਲ ਜਵਾਬ ਦਿਓ। {} ਜਾਂ ਗਲਤੀ ਸਥਿਤੀ ਵਾਪਸ ਕਰਨ ਨਾਲ ਕਾਲ ਸਮਾਪਤ ਹੋ ਜਾਂਦੀ ਹੈ।

import hashlib
import hmac
import json
import os
 
from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
 
def verify(body: bytes, sig: str) -> bool:
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig or "")
 
@app.post("/thunderphone/incoming")
async def incoming(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(401)
 
    event = json.loads(body)
    if event["type"] not in ("telephony.incoming", "web.incoming"):
        return {}  # fall back to default
 
    caller = event["data"]["from_number"]
    # Cheap DB lookup: is this a known VIP?
    customer = lookup_customer(caller)
    if customer and customer.tier == "vip":
        return {
            "prompt":  f"You are a VIP concierge for {customer.name}. Be proactive…",
            "voice":   "john",
            "product": "storm-base",
        }
    return {}  # default agent handles non-VIPs
 
def lookup_customer(phone: str):
    # ... your CRM integration ...
    pass

import crypto from "node:crypto";
import express from "express";
 
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
 
function verify(body, sig) {
  const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
  return sig &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}
 
app.post(
  "/thunderphone/incoming",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
 
    const IMPORTANT_TYPES = new Set([
      "telephony.incoming",
      "web.incoming",
    ]);
    if (!IMPORTANT_TYPES.has(event.type)) return res.json({});
 
    const customer = await lookupCustomer(event.data.from_number);
    if (customer?.tier === "vip") {
      return res.json({
        prompt:  `You are a VIP concierge for ${customer.name}. Be proactive…`,
        voice:   "john",
        product: "storm-base",
      });
    }
    res.json({}); // fall back to default agent
  },
);

3. ਜਵਾਬ ਸਕੀਮਾ#

ਜਵਾਬ ਦਾ ਬਾਡੀ ਇਨਕਮਿੰਗ-ਕਾਲ ਜਵਾਬ ਸਕੀਮਾ ਨਾਲ ਬਿਲਕੁਲ ਮੇਲ ਖਾਂਦਾ ਹੈ। ਆਮ ਤੌਰ 'ਤੇ ਵਰਤੇ ਜਾਣ ਵਾਲੇ ਫੀਲਡ:

ਸੇਵ ਕੀਤਾ ਏਜੰਟ ਰੱਖੋ ਅਤੇ ਵੇਰੀਏਬਲ ਦਿਓ#

ਉਸ ਸੰਸਥਾ ਦੇ ਸੁਰੱਖਿਅਤ ਏਜੰਟ ਨੂੰ ਹਰ-ਕਾਲ ਡਾਟੇ ਨਾਲ ਵਰਤਣ ਲਈ {"agent_id": 12, "variables": {"name": "Ada"}} ਵਾਪਸ ਕਰੋ। ਇਸ ਦੇ prompt ਵਿੱਚ {{name}} ਜਾਂ {{name|Friend}} ਹੋ ਸਕਦਾ ਹੈ। ਵੈੱਬਹੁੱਕ ਵੇਰੀਏਬਲ ਬੇਨਤੀ-ਪੱਧਰ ਦੇ ਵੇਰੀਏਬਲਾਂ ਉੱਤੇ ਮਿਲਾਏ ਜਾਂਦੇ ਹਨ; null ਪਲੇਸਹੋਲਡਰ ਦਾ ਡਿਫਾਲਟ ਵਰਤਦਾ ਹੈ, ਜਾਂ ਜੇ ਕੋਈ ਦਿੱਤਾ ਨਾ ਹੋਵੇ ਤਾਂ ਖਾਲੀ ਟੈਕਸਟ ਵਰਤਦਾ ਹੈ। ਅੰਤਿਮ ਮੁੱਲ ਅਤੇ ਅਣਸੁਲਝੇ ਨਾਮ ਕਾਲ ਵੇਰਵਿਆਂ ਅਤੇ ਪੂਰਤੀ ਵੈੱਬਹੁੱਕਾਂ ਵਿੱਚ ਦਿਖਾਈ ਦਿੰਦੇ ਹਨ। ਸੁਰੱਖਿਅਤ-ਏਜੰਟ ਜਵਾਬ ਸਿਰਫ਼ agent_id, variables ਅਤੇ timezone ਸਵੀਕਾਰ ਕਰਦੇ ਹਨ। ਜੇ prompt ਮੌਜੂਦ ਹੋਵੇ, ਤਾਂ ਜਵਾਬ ਇਨਲਾਈਨ ਕੌਂਫਿਗਰੇਸ਼ਨ ਵਰਤਦਾ ਹੈ ਅਤੇ agent_id ਨੂੰ ਅਣਡਿੱਠਾ ਕਰਦਾ ਹੈ (ਜਿਸ ਵਿੱਚ null ਜਾਂ ਗੈਰ-ਪੂਰਨ ਅੰਕ ਮੈਟਾਡਾਟਾ ਵੀ ਸ਼ਾਮਲ ਹੈ); ਇਨਲਾਈਨ prompt ਫਿਰ ਵੀ ਵੈਧ ਹੋਣਾ ਲਾਜ਼ਮੀ ਹੈ। ਇਨਲਾਈਨ ਕੌਂਫਿਗਰੇਸ਼ਨ ਜਵਾਬਾਂ ਵਿੱਚ variables ਵੀ ਸ਼ਾਮਲ ਹੋ ਸਕਦੇ ਹਨ। ਸੁਰੱਖਿਅਤ-ਏਜੰਟ ਜਵਾਬ ਫੋਨ ਅਤੇ ਵਿਜਟ ਦੋਹਾਂ ਕਾਲਾਂ ਉੱਤੇ ਏਜੰਟ ਦਾ ਡਿਪਲੌਇ ਕੀਤਾ A/B ਵੰਡ ਵਰਤਦੇ ਹਨ, ਫਿਰ ਵੇਰੀਏਬਲ ਰੈਂਡਰ ਕਰਦੇ ਹਨ। ਸੀਮਾਵਾਂ ਅਤੇ ਸੈਸ਼ਨ API ਸਹਾਇਤਾ ਲਈ ਕਾਲ ਵੇਰੀਏਬਲ ਵੇਖੋ। ਬਲਾਕਿੰਗ ਕੌਂਫਿਗਰੇਸ਼ਨ ਲੈਗਸੀ ਫੋਨ-ਨੰਬਰ/ਸੰਸਥਾ URL ਜਾਂ ਵੈੱਬਹੁੱਕ-ਮੋਡ ਵਿਜਟ ਕੁੰਜੀ ਤੋਂ ਆਉਂਦੀ ਹੈ; ਐਂਡਪੌਇੰਟ-ਸਿਸਟਮ ਇਨਕਮਿੰਗ ਇਵੈਂਟ ਸਿਰਫ਼ ਸੂਚਨਾਵਾਂ ਹਨ।

ਹਰ ਕਾਲ ਲਈ ਸਮਾਂ ਖੇਤਰ ਸੈੱਟ ਕਰੋ#

ਇੱਕ ਏਜੰਟ ਵੱਖ-ਵੱਖ ਸਮਾਂ ਖੇਤਰਾਂ ਵਿੱਚ ਮੌਜੂਦ ਸੰਪਰਕਾਂ ਨੂੰ ਜਵਾਬ ਦੇ ਸਕਦਾ ਹੈ। ਸੰਭਾਲੇ ਹੋਏ ਏਜੰਟ ਜਾਂ ਇਨਲਾਈਨ ਜਵਾਬ ਵਿੱਚ IANA ਨਾਮ timezone ਸ਼ਾਮਲ ਕਰੋ, ਅਤੇ ਏਜੰਟ ਇਸ ਕਾਲ ਲਈ ਤਾਰੀਖ ਅਤੇ ਸਮਾਂ ਦੱਸੇਗਾ ਅਤੇ ਏਜੰਟ ਦੇ ਆਪਣੇ ਸਮਾਂ ਖੇਤਰ ਦੀ ਬਜਾਏ ਉਸ ਖੇਤਰ ਦੇ ਸਮੇਂ ਪੇਸ਼ ਕਰੇਗਾ:

{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}

variables ਵਿੱਚ ਟਾਈਮਸਟੈਂਪ ਦੀ ਬਜਾਏ ਸਮਾਂ ਖੇਤਰ ਭੇਜੋ: ਕਾਲ ਦੌਰਾਨ ਏਜੰਟ ਦੀ ਘੜੀ ਚਲਦੀ ਰਹਿੰਦੀ ਹੈ ਅਤੇ ਤੁਹਾਡੇ ਵੱਲੋਂ ਭੇਜਿਆ ਸਮਾਂ ਪੁਰਾਣਾ ਹੋ ਜਾਂਦਾ ਹੈ। ਜੋ ਮੁੱਲ IANA ਸਮਾਂ ਖੇਤਰ ਨਹੀਂ ਹੈ, ਉਸਨੂੰ ਅਣਡਿੱਠਾ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਅਤੇ ਕਾਲ ਏਜੰਟ ਦੇ ਸਮਾਂ ਖੇਤਰ ਵਿੱਚ ਕਨੈਕਟ ਹੁੰਦੀ ਹੈ।

ਪੈਟਰਨ#

ਲੌਗ-ਇਨ ਯੂਜ਼ਰ ਸੰਦਰਭ#

ਵੈੱਬਹੁੱਕ-ਮੋਡ ਵਿਜਿਟਾਂ ਵਿੱਚ, ਵਿਜ਼ਿਟਰ ਦੇ ਪੇਜ ਨੂੰ ਪਹਿਲਾਂ ਹੀ ਪਤਾ ਹੁੰਦਾ ਹੈ ਕਿ ਉਹ ਕੌਣ ਹਨ। ਆਪਣੇ ਵੈੱਬਹੁੱਕ ਨੂੰ ਉਸ ਕਵੇਰੀ ਸਟ੍ਰਿੰਗ ਪੈਰਾਮੀਟਰ ਨਾਲ ਕਾਲ ਕਰੋ ਜਿਸ ਨੂੰ ਵਿਜਿਟ SDK ਅੱਗੇ ਭੇਜਦਾ ਹੈ (?customer_id=123) ਅਤੇ ਸਰਵਰ-ਸਾਈਡ 'ਤੇ ਗਾਹਕ ਨੂੰ ਲੱਭੋ।

A/B prompt ਰੋਲਆਉਟ#

ਇਸ ਨੂੰ ਖੁਦ ਬਣਾਉਣ ਤੋਂ ਪਹਿਲਾਂ, ਧਿਆਨ ਦਿਓ ਕਿ ThunderPhone ਵਿੱਚ ਇੱਕ ਨੇਟਿਵ ਐਕਸਪੇਰੀਮੈਂਟਸ ਫੀਚਰ ਹੈ (/dashboard/experiments ਅਤੇ ਏਜੰਟ ਬਿਲਡਰ ਦੀ A/B ਟੈਬ) ਜੋ ਵੇਰੀਐਂਟ ਪਰਿਭਾਸ਼ਿਤ ਕਰਦਾ ਹੈ, ਟ੍ਰੈਫਿਕ ਵੰਡਦਾ ਹੈ, ਅਤੇ ਹਰ ਵੇਰੀਐਂਟ ਦੇ ਨਤੀਜਿਆਂ ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ — ਕਿਸੇ ਵੈੱਬਹੁੱਕ ਦੀ ਲੋੜ ਨਹੀਂ।

ਜੇ ਤੁਹਾਨੂੰ ਫਿਰ ਵੀ ਵੈੱਬਹੁੱਕ-ਸਾਈਡ ਕੰਟਰੋਲ ਚਾਹੀਦਾ ਹੈ: call_id ਨੂੰ ਹੈਸ਼ ਕਰਕੇ → ਬਕੇਟ ਬਣਾਓ; 0..49 ਲਈ prompt A ਅਤੇ 50..99 ਲਈ prompt B ਦਿਓ। ਆਪਣੀ DB ਵਿੱਚ ਤੁਹਾਡੇ ਦੁਆਰਾ ਚੁਣਿਆ ਬਕੇਟ ਰਿਕਾਰਡ ਕਰੋ ਅਤੇ ਬਾਅਦ ਵਿੱਚ ਇਸ ਨੂੰ ਪੂਰੀ ਹੋਈ ਕਾਲ ਦੇ ਗ੍ਰੇਡ ਨਾਲ ਜੋੜੋ।

ਸਮੇਂ-ਅਧਾਰਿਤ ਰਾਊਟਿੰਗ#

ਕਾਰੋਬਾਰੀ ਸਮਾਂ → "ਲਾਈਵ ਸਹਾਇਤਾ" ਏਜੰਟ; ਕਾਰੋਬਾਰੀ ਸਮੇਂ ਤੋਂ ਬਾਅਦ → "ਸੁਨੇਹਾ ਲਓ" ਏਜੰਟ। ਆਪਣੇ ਹੈਂਡਲਰ ਵਿੱਚ new Date().getUTCHours() 'ਤੇ ਸਿੱਧਾ ਸਵਿਚ ਕਰੋ।

ਅਗਲੇ ਕਦਮ#