ThunderPhone v3 હવે લાઇવ છે.સેલ્ફ-સર્વ, 2¢/મિનિટથી.જાહેરાત વાંચો

Developer cookbook

દરેક કૉલ માટે ગતિશીલ કૉન્ફિગરેશન

તમે નિયંત્રિત કરતા webhookમાં કસ્ટમ લોજિકના આધારે, દરેક આવનારા કૉલ માટે અલગથી જવાબ આપતો એજન્ટ પસંદ કરો — અથવા તેનો prompt અને સેટિંગ્સ ફરીથી લખો.

ડિફૉલ્ટ રીતે દરેક ફોન નંબર અને publishable key માટે એક સ્થિર એજન્ટ સોંપાયેલ હોય છે. જ્યારે તમને દરેક કૉલર માટે અથવા દરેક વિઝિટર માટે કસ્ટમાઇઝેશનની જરૂર હોય — VIP રાઉટિંગ, લૉગ-ઇન થયેલા વપરાશકર્તાનો સંદર્ભ, A/B prompt પરીક્ષણો — ત્યારે webhook-mode પર સ્વિચ કરો અને તમારા સર્વરને નિર્ણય લેવા દો.

તે કેવી રીતે કાર્ય કરે છે

  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. webhook ગંતવ્ય કૉન્ફિગર કરો

ફોન નંબરો માટે, તમારા endpointને 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 શામેલ હોય છે — તેને સાચવો; તમે તેનો ઉપયોગ signature verification માટે કરશો.

widget સત્રો માટે, તમારા endpoint URL સાથે સમાવિષ્ટ mode="webhook"માં publishable key બનાવો:

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

દરેક સત્ર શરૂ થાય ત્યારે widget આ 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 પ્લેસહોલ્ડરના ડિફૉલ્ટનો ઉપયોગ કરે છે, અથવા કોઈ આપવામાં ન હોય તો ખાલી ટેક્સ્ટનો. અંતિમ મૂલ્યો અને ઉકેલાયા ન હોય તેવા નામો કૉલ વિગતો અને પૂર્ણતા વેબહૂક્સમાં દેખાય છે. એજન્ટને આ કૉલ માટે સંક્ષિપ્ત માહિતી આપવા context, વધુમાં વધુ 20,000 અક્ષરોની મુક્ત-રૂપી સ્ટ્રિંગ, ઉમેરો (તમારા 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માં ટાઇમસ્ટેમ્પને બદલે ઝોન મોકલો: કૉલ દરમિયાન એજન્ટની ઘડિયાળ ચાલુ રહે છે, અને તમે મોકલેલો સમય જૂનો થઈ જાય છે. IANA ઝોન ન હોય તેવી કિંમત અવગણવામાં આવે છે અને કૉલ એજન્ટના ઝોનમાં કનેક્ટ થાય છે.

પ્રતિ કૉલ ભાષા સેટ કરો

એક એજન્ટ તેની દરેક ભાષામાં જવાબ આપી શકે છે. agent_idની બાજુમાં language, સમર્થિત ભાષા કોડ જેમ કે es (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 પ્રોમ્પ્ટ રોલઆઉટ

તમે આ જાતે બનાવો તે પહેલાં, નોંધો કે ThunderPhone પાસે મૂળભૂત પ્રયોગો સુવિધા છે (/dashboard/experiments અને એજન્ટ બિલ્ડરના A/B ટૅબમાં), જે વેરિઅન્ટ્સ વ્યાખ્યાયિત કરે છે, ટ્રાફિક વહેંચે છે અને દરેક વેરિઅન્ટના પરિણામોની તુલના કરે છે — વેબહૂકની જરૂર નથી.

જો તમને તેમ છતાં વેબહૂક-બાજુનું નિયંત્રણ જોઈએ: call_id હૅશ કરો → બકેટ; 0..49 માટે પ્રોમ્પ્ટ A અને 50..99 માટે પ્રોમ્પ્ટ B આપો. તમે પસંદ કરેલો બકેટ તમારા પોતાના DBમાં રેકોર્ડ કરો અને પછી પૂર્ણ થયેલા કૉલના ગ્રેડ સાથે તેનો સંબંધ સ્થાપિત કરો.

સમય-આધારિત રૂટિંગ

વ્યવસાયિક સમય → "લાઇવ સપોર્ટ" એજન્ટ; કામકાજ પછીનો સમય → "સંદેશ લો" એજન્ટ. તમારા હેન્ડલરમાં new Date().getUTCHours() પર સીધું સ્વિચ કરો.


આગળનાં પગલાં