ThunderPhone v3 ഇപ്പോൾ ലൈവാണ്.സ്വയം തുടങ്ങാം — 2¢/മിനിറ്റ് മുതൽ.പ്രഖ്യാപനം വായിക്കുക

Developer cookbook

ഓരോ കോളിനുമുള്ള ഡൈനാമിക് കോൺഫിഗറേഷൻ

നിങ്ങൾ നിയന്ത്രിക്കുന്ന ഒരു webhook-ലെ കസ്റ്റം ലജിക് ഉപയോഗിച്ച്, ഓരോ ഇൻകമിംഗ് കോളിനും മറുപടി നൽകുന്ന ഏജന്റിനെ തിരഞ്ഞെടുക്കുക — അല്ലെങ്കിൽ അതിന്റെ prompt-ും ക്രമീകരണങ്ങളും പ്രത്യേകം പുനരാലേഖനം ചെയ്യുക.

സ്ഥിരസ്ഥിതിയായി ഓരോ ഫോൺ നമ്പറിനും പബ്ലിഷ് ചെയ്യാവുന്ന ഓരോ കീയ്ക്കും ഒരു സ്റ്റാറ്റിക് ഏജന്റിനെ നിയോഗിച്ചിരിക്കും. ഓരോ കോളറിനും അല്ലെങ്കിൽ ഓരോ സന്ദർശകനും ഇഷ്ടാനുസൃത ക്രമീകരണം ആവശ്യമാകുമ്പോൾ — VIP റൂട്ടിംഗ്, ലോഗിൻ ചെയ്ത ഉപയോക്തൃ സന്ദർഭം, A/B prompt പരിശോധനകൾ — വെബ്‌ഹുക്ക് മോഡിലേക്ക് മാറി തീരുമാനിക്കാൻ നിങ്ങളുടെ സെർവറിനെ അനുവദിക്കുക.

ഇത് എങ്ങനെ പ്രവർത്തിക്കുന്നു

  1. നിങ്ങൾ telephony.incoming (ഫോൺ) അല്ലെങ്കിൽ web.incoming (വിഡ്ജറ്റ്) ഇവന്റിലേക്ക് സബ്സ്ക്രൈബ് ചെയ്യുക. രണ്ടും തടയുന്ന വെബ്‌ഹുക്കുകളാണ്: കോൾ തുടരുന്നതിന് മുമ്പ് ThunderPhone നിങ്ങളുടെ പ്രതികരണത്തിനായി കാത്തിരിക്കും; ഫോൺ കോളിന് 13 സെക്കൻഡ് വരെ (ഒരു റീട്രൈ ഉൾപ്പെടെ), വിഡ്ജറ്റ് സെഷന് 10 സെക്കൻഡ് വരെ.
  2. ThunderPhone നിങ്ങൾക്ക് {call_id, from_number, to_number} അയയ്ക്കുന്നു (വിഡ്ജറ്റ് സെഷനുകൾ നമ്പറുകൾക്കു പകരം വിഡ്ജറ്റിന്-പ്രത്യേകമായ ഫീൽഡുകൾ വഹിക്കുന്നു — റിക്വസ്റ്റ് സ്കീമ കാണുക).
  3. നിങ്ങളുടെ സെർവർ ഒരു ഏജന്റ് കോൺഫിഗറേഷനുമായി പ്രതികരിക്കുന്നു (prompt, voice, product, tools, words). ThunderPhone കോളിനായി ആ കോൺഫിഗറേഷൻ ഉപയോഗിക്കുന്നു.
  4. ഫാൾബാക്ക് ഏജന്റ് ഇല്ല. നിങ്ങൾ {} അല്ലെങ്കിൽ അസാധുവായ ഒരു കോൺഫിഗറേഷൻ മടക്കിനൽകുകയോ, റീട്രൈ കഴിഞ്ഞിട്ടും റിക്വസ്റ്റ് പരാജയപ്പെടുകയോ ചെയ്താൽ, ഫോൺ കോൾ ഉടൻ അവസാനിപ്പിക്കുകയും inbound_config_webhook_failed എന്ന end_reason ഉപയോഗിച്ച് രേഖപ്പെടുത്തുകയും ചെയ്യും; വിഡ്ജറ്റ് സെഷൻ റിക്വസ്റ്റ് പരാജയപ്പെടും.

1. വെബ്‌ഹുക്ക് ലക്ഷ്യസ്ഥാനം കോൺഫിഗർ ചെയ്യുക

ഫോൺ നമ്പറുകൾക്കായി, നിങ്ങളുടെ എൻഡ്‌പോയിന്റിനെ telephony.incoming-ലേക്ക് സബ്സ്ക്രൈബ് ചെയ്യുക:

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

പ്രതികരണത്തിൽ ഒറ്റത്തവണ ഉപയോഗിക്കാവുന്ന secret ഉൾപ്പെടും — അത് സംരക്ഷിക്കുക; സിഗ്നേച്ചർ പരിശോധിക്കാൻ നിങ്ങൾ അത് ഉപയോഗിക്കും.

വിഡ്ജറ്റ് സെഷനുകൾക്കായി, നിങ്ങളുടെ എൻഡ്‌പോയിന്റ് URL ഉൾച്ചേർത്ത mode="webhook" ഉള്ള ഒരു പബ്ലിഷ് ചെയ്യാവുന്ന കീ സൃഷ്ടിക്കുക:

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

ഓരോ സെഷൻ ആരംഭത്തിലും വിഡ്ജറ്റ് ഈ URL-ലേക്ക് POST ചെയ്യും.

2. ഹാൻഡ്‌ലർ നടപ്പിലാക്കുക

മൂന്ന് പ്രായോഗിക നിയമങ്ങൾ:

  • ഓരോ അഭ്യർത്ഥനയിലും സിഗ്നേച്ചർ പരിശോധിക്കുക (കാണുക വെബ്ഹുക്ക് സിഗ്നേച്ചറുകൾ പരിശോധിക്കുക). dev-ൽ ഇത് ഒഴിവാക്കരുത് — ഒരിക്കൽ ശരിയായി നടപ്പാക്കി വീണ്ടും ഉപയോഗിക്കുക.
  • വേഗത്തിൽ പ്രതികരിക്കുക. ഒരു ഫോൺ കോളിന്റെ ആദ്യ ശ്രമം 10 സെക്കൻഡിൽ വിച്ഛേദിക്കപ്പെടും, മുഴുവൻ ഇടപെടൽ 13 സെക്കൻഡിലും; ഓരോ സെക്കൻഡും കോളർക്കുള്ള നിശ്ശബ്ദ സമയമാണ്. ആവശ്യമെങ്കിൽ ഡാറ്റാബേസ് ലുക്കപ്പുകൾ നടത്തുക, എന്നാൽ ഡൗൺസ്ട്രീം LLM-കളെ സിങ്ക്രണസായി വിളിക്കരുത് — ഡൈനാമിക് prompt ജനറേഷൻ വേണമെങ്കിൽ മുൻകൂട്ടി കണക്കാക്കി കാഷ് ചെയ്യുക.
  • ശുദ്ധമായി ഫാൾബാക്ക് ചെയ്യുക. പ്രതീക്ഷിക്കാത്ത ഏത് അവസ്ഥയ്ക്കും, ഡിഫോൾട്ട് prompt, voice (അല്ലെങ്കിൽ സേവ് ചെയ്ത agent_id) നൽകി പ്രതികരിക്കുക. {} അല്ലെങ്കിൽ ഒരു എറർ സ്റ്റാറ്റസ് മടക്കി നൽകുന്നത് കോൾ അവസാനിപ്പിക്കും.
FastAPI
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
Express
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. പ്രതികരണ സ്കീമ

പ്രതികരണ ബോഡി ഇൻകമിംഗ്-കോൾ പ്രതികരണ സ്കീമയുമായി കൃത്യമായി പൊരുത്തപ്പെടുന്നു. സാധാരണയായി ഉപയോഗിക്കുന്ന ഫീൽഡുകൾ:

ഫീൽഡ്തരംവിവരണം
promptസ്ട്രിംഗ് (ആവശ്യമാണ്)ഏജന്റിനായുള്ള സിസ്റ്റം prompt
voiceസ്ട്രിംഗ് (ആവശ്യമാണ്)GET /v1/voices-ൽ നിന്നുള്ള വോയ്സ് ഐഡി
productസ്ട്രിംഗ്bolt അയയ്ക്കുക. ഇപ്പോഴും അംഗീകരിക്കപ്പെടുന്ന പഴയ മൂല്യമായ spark ആണ് ഡിഫോൾട്ട്.
background_trackസ്ട്രിംഗ് | nullആംബിയന്റ് ഓഡിയോ ഐഡി
acknowledgement_prompt_modeസ്ട്രിംഗ്auto അല്ലെങ്കിൽ manual (പഴയ -with-ack ഉൽപ്പന്ന മൂല്യങ്ങൾക്ക് മാത്രം)
acknowledgement_promptസ്ട്രിംഗ്മോഡ് manual ആയിരിക്കുമ്പോൾ ആവശ്യമാണ്
language_switchingസ്ട്രിംഗ്ബഹുഭാഷാ ഏജന്റുകൾക്ക്, ask_first അല്ലെങ്കിൽ follow_caller
toolsഅറേഇൻലൈൻ ഫംഗ്ഷൻ-ടൂൾ സ്കീമകൾ — ഫംഗ്ഷൻ ടൂളുകൾ കാണുക

സംരക്ഷിച്ച ഏജന്റ് നിലനിർത്തി വേരിയബിളുകളോ കോൺടെക്സ്റ്റോ നൽകുക

ആ ഓർഗനൈസേഷന്റെ ഓരോ കോളിലെയും ഡാറ്റയോടെ സംരക്ഷിച്ച ഏജന്റ് ഉപയോഗിക്കാൻ {"agent_id": 12, "variables": {"name": "Ada"}} മടക്കിനൽകുക. അതിന്റെ prompt-ൽ {{name}} അല്ലെങ്കിൽ {{name|Friend}} ഉൾക്കൊള്ളാം. Webhook വേരിയബിളുകൾ request-തല വേരിയബിളുകളുമായി ലയിക്കുന്നു; നൾ പ്ലേസ്‌ഹോൾഡറിന്റെ ഡിഫോൾട്ട് ഉപയോഗിക്കും, അല്ലെങ്കിൽ ഒന്നും നൽകിയിട്ടില്ലെങ്കിൽ ശൂന്യ ടെക്സ്റ്റ് ഉപയോഗിക്കും. അന്തിമ മൂല്യങ്ങളും പരിഹരിക്കപ്പെടാത്ത പേരുകളും കോൾ വിവരങ്ങളിലും പൂർത്തീകരണ webhook-ുകളിലും ദൃശ്യമാകും. ഈ കോളിനായി ഏജന്റിന് ഒരു സംക്ഷിപ്ത നിർദ്ദേശം നൽകാൻ പരമാവധി 20,000 പ്രതീകങ്ങളുള്ള സ്വതന്ത്ര-രൂപത്തിലുള്ള സ്ട്രിങ്ങായ context ചേർക്കുക (നിങ്ങളുടെ CRM-ൽ നിന്നുള്ള കുറിപ്പുകൾ, നിങ്ങൾ കോൾ പ്രതീക്ഷിക്കുന്ന കാരണം); ഇത് prompt-ന് ശേഷം വിഭജകങ്ങളുള്ള ഒരു ബ്ലോക്കിൽ ചേർക്കപ്പെടും. സംരക്ഷിച്ച-ഏജന്റ് പ്രതികരണങ്ങൾ agent_id, variables, context, timezone, language എന്നിവ മാത്രം സ്വീകരിക്കും. prompt നിലവിലുണ്ടെങ്കിൽ, പ്രതികരണം ഇൻലൈൻ കോൺഫിഗറേഷൻ ഉപയോഗിക്കുകയും agent_id അവഗണിക്കുകയും ചെയ്യും; ഇൻലൈൻ prompt ഇപ്പോഴും സാധുവായിരിക്കണം. നിങ്ങളുടെ webhook നിയോഗിച്ച ഏജന്റിന്റെ സ്വന്തം കോൾ സജ്ജീകരണ webhook ആണെങ്കിൽ, കോളിനായി ആ നിയോഗിച്ച ഏജന്റിനെ (ഏതെങ്കിലും പതിപ്പ് നിശ്ചയിക്കൽ ഉൾപ്പെടെ) നിലനിർത്താൻ agent_id ഒഴിവാക്കി variables, context, timezone, language എന്നിവ മാത്രം മടക്കിനൽകാനും കഴിയും. ഇൻലൈൻ കോൺഫിഗറേഷൻ പ്രതികരണങ്ങളിൽ variables, context എന്നിവയും ഉൾപ്പെടുത്താം. സംരക്ഷിച്ച-ഏജന്റ് പ്രതികരണങ്ങൾ ഫോൺ, വിഡ്ജറ്റ് കോളുകൾ രണ്ടിലും ഏജന്റിന്റെ ഡിപ്ലോയ് ചെയ്ത A/B വിഭജനം ഉപയോഗിക്കുകയും തുടർന്ന് വേരിയബിളുകൾ റെൻഡർ ചെയ്യുകയും ചെയ്യും. പരിധികൾക്കും സെഷൻ API പിന്തുണയ്ക്കുമായി കോൾ വേരിയബിളുകൾ കാണുക. ബ്ലോക്കിംഗ് കോൺഫിഗറേഷൻ ലെഗസി ഫോൺ-നമ്പർ/ഓർഗനൈസേഷൻ URL-ൽ നിന്നോ webhook-മോഡ് വിഡ്ജറ്റ് കിയിൽ നിന്നോ ലഭിക്കുന്നു; എൻഡ്പോയിന്റ്-സിസ്റ്റം ഇൻകമിംഗ് ഇവന്റുകൾ അറിയിപ്പുകൾ മാത്രമാണ്.

ഓരോ കോളിനും സമയ മേഖല സജ്ജമാക്കുക

വ്യത്യസ്ത സമയ മേഖലകളിലുള്ള കോൺടാക്ടുകൾക്കായി ഒരു ഏജന്റിന് മറുപടി നൽകാനാകും. സംരക്ഷിച്ച ഏജന്റിലേക്കോ ഇൻലൈൻ പ്രതികരണത്തിലേക്കോ IANA പേരായ timezone ചേർക്കുക. അപ്പോൾ ഈ കോളിനായി ഏജന്റിന്റെ സ്വന്തം സമയ മേഖലയ്ക്ക് പകരം ആ മേഖലയിലെ തീയതിയും സമയവും ഏജന്റ് അറിയിക്കുകയും സമയങ്ങൾ നിർദ്ദേശിക്കുകയും ചെയ്യും:

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

variables-ൽ ടൈംസ്റ്റാമ്പിന് പകരം സമയ മേഖല അയയ്ക്കുക: കോളിനിടെ ഏജന്റിന്റെ ക്ലോക്ക് പ്രവർത്തിച്ചുകൊണ്ടിരിക്കും, നിങ്ങൾ നൽകുന്ന സമയം പഴകിപ്പോകും. IANA സമയ മേഖലയല്ലാത്ത മൂല്യം അവഗണിക്കപ്പെടും, കോൾ ഏജന്റിന്റെ സമയ മേഖലയിൽ കണക്റ്റ് ചെയ്യും.

ഓരോ കോളിനും ഭാഷ സജ്ജമാക്കുക

ഒരു ഏജന്റിന് അതിന്റെ ഓരോ ഭാഷയിലും മറുപടി നൽകാനാകും. agent_id-നൊപ്പം es പോലുള്ള പിന്തുണയ്ക്കുന്ന ഭാഷാ കോഡായ language ചേർക്കുക (es-MX എന്നത് es ആയി വായിക്കപ്പെടും), അപ്പോൾ കോൾ ആ ഭാഷയിൽ ആരംഭിക്കും:

{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}

ഏജന്റ് അതത് ഭാഷയ്ക്കുള്ള സ്വന്തം വോയ്‌സിൽ സംസാരിക്കുന്നു: അതിന്റെ language_voices എൻട്രി; അല്ലെങ്കിൽ, native_voice_switching ഓണായിരിക്കുമ്പോൾ, ആ ഭാഷയ്ക്കായി ഏജന്റ് മാറുന്ന നേറ്റീവ് വോയ്‌സ്; അല്ലെങ്കിൽ, ആ വോയ്‌സിന് ഭാഷ സംസാരിക്കാനാകുമ്പോൾ സ്വന്തം വോയ്‌സ്. റെക്കോർഡ് ചെയ്യാത്ത കോളുകളിൽ, ThunderPhone കോളിന്റെ ഭാഷയിൽ തത്സമയ-പ്രോസസ്സിംഗ് അറിയിപ്പും പ്ലേ ചെയ്യുന്നു. തുടർന്ന് ഏജന്റിന്റെ മറ്റ് ഭാഷകളും അതിന്റെ പ്രാഥമിക ഭാഷയും മാറ്റുന്നതിനായി ലഭ്യമായി തുടരും. ഇവയിലൊന്നിനും ആ ഭാഷ സംസാരിക്കാനാകില്ലെങ്കിൽ, കോൾ ഇപ്പോഴും ആ ഭാഷയിൽ തന്നെ ആരംഭിക്കും; ഭാഷയുടെ ഡിഫോൾട്ട് വോയ്‌സോടെയും (കസ്റ്റം വോയ്‌സുള്ള ഏജന്റ് അത് നിലനിർത്തും) മറ്റ് ഭാഷകളൊന്നുമില്ലാതെയും. പിന്നീട് കോൾ നടക്കുന്നതിനിടെ ഏജന്റിന്റെ മറ്റൊരു ഭാഷയിലേക്ക് മാറുകയാണെങ്കിൽ, രണ്ട് വോയ്‌സുകളും കാറ്റലോഗ് വോയ്‌സുകളായിരിക്കുമ്പോൾ അതത് ഭാഷയുടെ language_voices എൻട്രിയും ഉപയോഗിക്കുന്നു; അല്ലാത്തപക്ഷം സാധാരണ സ്വിച്ചിംഗ് നിയമങ്ങൾ ബാധകമാണ്. ഫുൾ ഡ്യൂപ്ലെക്സ് ഏജന്റുകൾ വ്യത്യസ്തമാണ്: പിന്തുണയ്ക്കുന്ന ഏത് ഭാഷയിലും, കോൾ ഏജന്റിന്റെ സ്വന്തം വോയ്‌സ് നിലനിർത്തുന്നു; language_voices ഉം നേറ്റീവ് വോയ്‌സ് സ്വിച്ചിംഗും ബാധകമല്ല. പിന്തുണയ്ക്കുന്ന ഭാഷയല്ലാത്ത ഒരു കോഡ് മാത്രമാണ് നിരസിക്കപ്പെടുന്നത്. വിഡ്ജറ്റും റിയൽടൈം സെഷനുകളും അതേ language ഫീൽഡ് സ്വീകരിക്കുന്നു.

പാറ്റേണുകൾ

ലോഗിൻ ചെയ്ത ഉപയോക്തൃ സന്ദർഭം

webhook-മോഡ് വിജറ്റുകളിൽ, സന്ദർശകന്റെ പേജിന് അവർ ആരാണെന്ന് ഇതിനകം അറിയാം. വിജറ്റ് SDK ഫോർവേഡ് ചെയ്യുന്ന ക്വറി സ്ട്രിംഗ് പാരാമീറ്റർ ഉപയോഗിച്ച് നിങ്ങളുടെ webhook വിളിക്കുക (?customer_id=123), തുടർന്ന് സെർവർ-സൈഡിൽ ഉപഭോക്താവിനെ തിരയുക.

A/B prompt റോൾഔട്ട്

നിങ്ങൾ ഇത് സ്വയം നിർമിക്കുന്നതിന് മുമ്പ്, ThunderPhone-ൽ നേറ്റീവ് പരീക്ഷണങ്ങൾ ഫീച്ചർ (/dashboard/experiments, ഏജന്റ് ബിൽഡറിലെ A/B ടാബ്) ഉണ്ടെന്ന് ശ്രദ്ധിക്കുക. ഇത് വേരിയന്റുകൾ നിർവചിക്കുകയും ട്രാഫിക് വിഭജിക്കുകയും ഓരോ വേരിയന്റിലെയും ഫലങ്ങൾ താരതമ്യം ചെയ്യുകയും ചെയ്യുന്നു — webhook ആവശ്യമില്ല.

നിങ്ങൾക്ക് എന്നിരുന്നാലും webhook-സൈഡ് നിയന്ത്രണം ആവശ്യമാണെങ്കിൽ: call_id → ബക്കറ്റ് ഹാഷ് ചെയ്യുക; 0..49-ന് prompt A-യും 50..99-ന് prompt B-യും നൽകുക. നിങ്ങൾ തിരഞ്ഞെടുത്ത ബക്കറ്റ് നിങ്ങളുടെ സ്വന്തം DB-യിൽ രേഖപ്പെടുത്തി, പിന്നീട് പൂർത്തിയായ കോളിന്റെ ഗ്രേഡുമായി ബന്ധിപ്പിക്കുക.

സമയാധിഷ്ഠിത റൂട്ടിംഗ്

ബിസിനസ് സമയം → "ലൈവ് സപ്പോർട്ട്" ഏജന്റ്; പ്രവൃത്തി സമയത്തിന് ശേഷം → "സന്ദേശം എടുക്കുക" ഏജന്റ്. നിങ്ങളുടെ ഹാൻഡ്‌ലറിലെ new Date().getUTCHours() അടിസ്ഥാനമാക്കിയുള്ള ലളിതമായ സ്വിച്ച്.


അടുത്ത ഘട്ടങ്ങൾ