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, குரல், தயாரிப்பு, கருவிகள், சொற்கள்). ThunderPhone அந்த உள்ளமைவை அழைப்பிற்குப் பயன்படுத்தும்.
  4. மாற்று ஏஜென்ட் இல்லை. நீங்கள் {} அல்லது செல்லாத உள்ளமைவைத் திருப்பி அனுப்பினால், அல்லது அதன் மறுமுயற்சிக்குப் பிறகும் கோரிக்கை தோல்வியடைந்தால், தொலைபேசி அழைப்பு உடனடியாக முடிக்கப்பட்டு end_reason inbound_config_webhook_failed எனப் பதிவு செய்யப்படும்; விட்ஜெட் அமர்வு கோரிக்கை தோல்வியடையும்.

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. ஹேண்ட்லரை செயல்படுத்துங்கள்

மூன்று வழிகாட்டும் விதிகள்:

  • ஒவ்வொரு கோரிக்கையிலும் கையொப்பத்தைச் சரிபார்க்கவும் (webhook கையொப்பங்களைச் சரிபார்க்கவும் என்பதைப் பார்க்கவும்). மேம்பாட்டு சூழலில் இதைத் தவிர்க்க வேண்டாம் — ஒருமுறை சரியாக அமைத்து மீண்டும் பயன்படுத்துங்கள்.
  • விரைவாகப் பதிலளிக்கவும். தொலைபேசி அழைப்பின் முதல் முயற்சி 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 இலிருந்து குரல் ID
productஸ்ட்ரிங்bolt அனுப்பவும். இயல்புநிலையாக spark பயன்படுத்தப்படும்; இது இன்னும் ஏற்கப்படும் பழைய மதிப்பாகும்.
background_trackஸ்ட்ரிங் | nullசூழல் ஆடியோ ID
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}} இருக்கலாம். வெப்ஹுக் மாறிகள் கோரிக்கை-நிலை மாறிகளுடன் இணைக்கப்படும்; null இடநிரப்பியின் இயல்புநிலையைப் பயன்படுத்தும், அல்லது எதுவும் வழங்கப்படாவிட்டால் வெற்று உரையைப் பயன்படுத்தும். இறுதி மதிப்புகளும் தீர்க்கப்படாத பெயர்களும் அழைப்பு விவரங்களிலும் நிறைவு வெப்ஹுக்குகளிலும் தோன்றும். இந்த அழைப்பிற்கான சுருக்கத்தை ஏஜென்ட்டுக்கு வழங்க, அதிகபட்சம் 20,000 எழுத்துகள் கொண்ட சுதந்திர வடிவச் சரமான context ஐச் சேர்க்கவும் (உங்கள் CRM-இலிருந்து குறிப்புகள், இந்த அழைப்பை நீங்கள் எதிர்பார்க்கும் காரணம்); அது prompt-க்குப் பிறகு வரையறுக்கப்பட்ட தொகுதியில் சேர்க்கப்படும். சேமித்த ஏஜென்ட் பதில்கள் agent_id, variables, context, timezone மற்றும் language ஆகியவற்றை மட்டுமே ஏற்கும். prompt இருந்தால், பதில் இன்லைன் கட்டமைப்பைப் பயன்படுத்தி agent_id ஐப் புறக்கணிக்கும்; இன்லைன் prompt இன்னும் செல்லுபடியாக இருக்க வேண்டும். உங்கள் வெப்ஹுக் ஒதுக்கப்பட்ட ஏஜென்ட்டின் சொந்த அழைப்பு அமைப்பு வெப்ஹுக்காக இருந்தால், அந்த ஒதுக்கப்பட்ட ஏஜென்ட்டை (எந்தப் பதிப்பு பூட்டும் உட்பட) அழைப்பிற்காகத் தக்கவைக்க agent_id ஐ விட்டுவிட்டு variables, context, timezone அல்லது language ஐ மட்டும் திருப்பியனுப்பலாம். இன்லைன் கட்டமைப்பு பதில்களில் variables மற்றும் context ஆகியவையும் இருக்கலாம். சேமித்த ஏஜென்ட் பதில்கள் தொலைபேசி மற்றும் விட்ஜெட் அழைப்புகள் இரண்டிலும் ஏஜென்ட்டின் வெளியிடப்பட்ட A/B பிரிப்பைப் பயன்படுத்தி, பின்னர் மாறிகளைக் காட்சிப்படுத்தும். வரம்புகள் மற்றும் அமர்வு API ஆதரவுக்கு அழைப்பு மாறிகள் பார்க்கவும். பிளாக்கிங் கட்டமைப்பு மரபு தொலைபேசி-எண்/நிறுவன URL அல்லது வெப்ஹுக்-முறை விட்ஜெட் விசையிலிருந்து வருகிறது; எண்ட்பாயிண்ட்-அமைப்பு உள்வரும் நிகழ்வுகள் அறிவிப்புகள் மட்டுமே.

ஒவ்வொரு அழைப்பிற்கும் நேர மண்டலத்தை அமைக்கவும்

ஒரு ஏஜென்ட் வெவ்வேறு நேர மண்டலங்களில் உள்ள தொடர்புகளுக்கு பதிலளிக்க முடியும். சேமித்த ஏஜென்ட் அல்லது இன்லைன் பதிலில் IANA பெயரான timezone-ஐச் சேர்க்கவும்; அப்போது இந்த அழைப்பிற்காக ஏஜென்ட் தேதி மற்றும் நேரத்தைக் கூறி, ஏஜென்ட்டின் சொந்த நேர மண்டலத்தை விட அந்த மண்டலத்தின் நேரங்களை வழங்கும்:

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

variables-இல் timestamp-க்கு பதிலாக மண்டலத்தை அனுப்பவும்: அழைப்பின் போது ஏஜென்ட்டின் கடிகாரம் தொடர்ந்து இயங்கும், நீங்கள் அனுப்பும் நேரம் காலாவதியாகிவிடும். 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 மற்றும் நேட்டிவ் குரல் மாறுதல் பொருந்தாது. ஆதரிக்கப்படும் மொழியாக இல்லாத குறியீடு மட்டுமே நிராகரிக்கப்படும். Widget மற்றும் realtime அமர்வுகள் அதே language புலத்தைப் பயன்படுத்தும்.

வடிவங்கள்

உள்நுழைந்த பயனர் சூழல்

வெப்ஹுக்-பயன்முறை விட்ஜெட்களில், பார்வையாளரின் பக்கத்திற்கு அவர்கள் யார் என்பது ஏற்கனவே தெரியும். விட்ஜெட் 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() அடிப்படையில் எளிய மாற்றம்.


அடுத்த படிகள்