Open in
telephony.incoming / web.incoming
ਬਲਾਕਿੰਗ webhook ਜੋ ਇਨਬਾਊਂਡ ਕਾਲ ਦੀ ਸੰਰਚਨਾ ਨੂੰ ਰੀਅਲ ਟਾਈਮ ਵਿੱਚ ਢਾਲਦਾ ਹੈ।
ਜਦੋਂ ਕਿਸੇ ਇਨਬਾਊਂਡ ਫ਼ੋਨ ਕਾਲ ਦਾ ਨੰਬਰ ਕਿਸੇ ਨਿਰਧਾਰਤ
ਏਜੰਟ ਨਾਲ ਸੰਬੰਧਿਤ ਨਹੀਂ ਹੁੰਦਾ, ਜਾਂ ਵੈੱਬ ਵਿਜਿਟ ਸੈਸ਼ਨ ਕਿਸੇ ਪਬਲਿਸ਼ੇਬਲ ਕੀ ਨਾਲ
mode="webhook" ਵਿੱਚ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ, ਤਾਂ ThunderPhone ਤੁਹਾਡੇ
ਲੇਗੇਸੀ webhook URL
ਨੂੰ ਇੱਕ ਬਲਾਕਿੰਗ
telephony.incoming / web.incoming ਬੇਨਤੀ ਭੇਜਦਾ ਹੈ ਅਤੇ ਕਨਫ਼ਿਗਰੇਸ਼ਨ ਜਵਾਬ ਲਈ
ਵੱਧ ਤੋਂ ਵੱਧ 10 ਸਕਿੰਟਾਂ ਤੱਕ ਉਡੀਕ ਕਰਦਾ ਹੈ। ਹਰ ਕਾਲ ਲਈ prompt, ਵੌਇਸ ਅਤੇ ਟੂਲਜ਼
ਨੂੰ ਡਾਇਨਾਮਿਕ ਤੌਰ 'ਤੇ ਚੁਣਨ ਲਈ ਇਸ ਐਕਸਚੇਂਜ ਦੀ ਵਰਤੋਂ ਕਰੋ —
ਪੂਰੇ ਪੈਟਰਨ ਲਈ ਡਾਇਨਾਮਿਕ ਕਾਲ ਕਨਫ਼ਿਗਰੇਸ਼ਨ ਗਾਈਡ
ਵੇਖੋ।
ਇਸ ਬਲਾਕਿੰਗ ਐਕਸਚੇਂਜ ਦਾ ਕੋਈ ਫਾਲਬੈਕ ਨਹੀਂ ਹੈ: ਜੇ ਤੁਹਾਡਾ ਹੈਂਡਲਰ
ਗੈਰ-2xx ਸਟੇਟਸ ਵਾਪਸ ਕਰਦਾ ਹੈ, ਸਮਾਂ ਸਮਾਪਤ ਹੋ ਜਾਂਦਾ ਹੈ, ਜਾਂ ਅਜਿਹੀ ਕਨਫ਼ਿਗ ਵਾਪਸ ਕਰਦਾ ਹੈ
ਜੋ ਵੈਲੀਡੇਸ਼ਨ ਵਿੱਚ ਅਸਫਲ ਹੁੰਦੀ ਹੈ, ਤਾਂ ਕਾਲ ਰੱਦ ਕਰ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ (ਫ਼ੋਨ ਕਾਲ
ਕਨੈਕਟ ਨਹੀਂ ਹੁੰਦੀ; ਵਿਜਿਟ ਸੈਸ਼ਨ ਬੇਨਤੀ 502/422 ਨਾਲ ਅਸਫਲ ਹੁੰਦੀ ਹੈ)। ਜਲਦੀ
ਜਵਾਬ ਦਿਓ — ਜਦੋਂ ਤੁਸੀਂ ਫ਼ੈਸਲਾ ਕਰ ਰਹੇ ਹੁੰਦੇ ਹੋ, ਕਾਲਰ ਰਿੰਗਬੈਕ ਸੁਣ ਰਿਹਾ ਹੁੰਦਾ ਹੈ।
ਬੇਨਤੀ ਪੇਲੋਡ
ਫ਼ੋਨ ਕਾਲਾਂ ਲਈ (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| ਫ਼ੀਲਡ | ਕਿਸਮ | ਵੇਰਵਾ |
|---|---|---|
call_id | integer | ਕਾਲ id — ਇਸ ਕਾਲ ਦੇ ਸਾਰੇ ਇਵੈਂਟਾਂ ਵਿੱਚ ਸਥਿਰ |
from_number | string | E.164 ਕਾਲਰ ਨੰਬਰ |
to_number | string | E.164 ਮੰਜ਼ਿਲ (ਤੁਹਾਡੇ ThunderPhone ਨੰਬਰਾਂ ਵਿੱਚੋਂ ਇੱਕ) |
ਵੈੱਬ ਵਿਜਿਟ ਸੈਸ਼ਨਾਂ ਲਈ (web.incoming), data ਫ਼ੋਨ ਨੰਬਰਾਂ ਦੀ ਬਜਾਏ
ਏਮਬੈਡਿੰਗ ਪੇਜ ਦੀ ਪਛਾਣ ਕਰਦਾ ਹੈ:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| ਫ਼ੀਲਡ | ਕਿਸਮ | ਵੇਰਵਾ |
|---|---|---|
call_id | integer | ਕਾਲ id |
origin_domain | string | ਵਿਜਿਟ ਨੂੰ ਹੋਸਟ ਕਰਨ ਵਾਲੇ ਪੇਜ ਦਾ ਔਰਿਜਿਨ |
publishable_key_prefix | string | ਸੈਸ਼ਨ ਖੋਲ੍ਹਣ ਵਾਲੀ ਪਬਲਿਸ਼ੇਬਲ ਕੀ ਦੇ ਪਹਿਲੇ ਅੱਖਰ |
language, primary_language | string | ਜਦੋਂ ਵਿਜਿਟ ਸੈਸ਼ਨ ਨੇ ਭਾਸ਼ਾ ਓਵਰਰਾਈਡ ਦੀ ਬੇਨਤੀ ਕੀਤੀ ਹੋਵੇ ਤਾਂ ਮੌਜੂਦ |
voice | string | ਜਦੋਂ ਵਿਜਿਟ ਸੈਸ਼ਨ ਨੇ ਵੌਇਸ ਓਵਰਰਾਈਡ ਦੀ ਬੇਨਤੀ ਕੀਤੀ ਹੋਵੇ ਤਾਂ ਮੌਜੂਦ |
website_context | string | ਜਦੋਂ ਵਿਜਿਟ ਨੇ ਹਰ-ਸੈਸ਼ਨ ਪੇਜ ਸੰਦਰਭ ਪਾਸ ਕੀਤਾ ਹੋਵੇ ਤਾਂ ਮੌਜੂਦ |
ਜਵਾਬ ਸਕੀਮਾ
ਇਸ ਕਾਲ ਲਈ ਏਜੰਟ ਸੰਰਚਨਾ ਦਾ ਵਰਣਨ ਕਰਨ ਵਾਲਾ JSON ਆਬਜੈਕਟ ਵਾਪਸ ਕਰੋ।
prompt ਅਤੇ voice ਲਾਜ਼ਮੀ ਹਨ; ਬਾਕੀ ਸਭ ਕੁਝ ਵਿਕਲਪਿਕ ਹੈ।
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| ਫੀਲਡ | ਕਿਸਮ | ਲਾਜ਼ਮੀ | ਵੇਰਵਾ |
|---|---|---|---|
prompt | ਸਟ੍ਰਿੰਗ | ਹਾਂ | ਏਜੰਟ ਨੂੰ ਚਲਾਉਣ ਵਾਲਾ ਸਿਸਟਮ prompt |
voice | ਸਟ੍ਰਿੰਗ | ਹਾਂ | GET /v1/voices ਤੋਂ ਵੌਇਸ id, ਜਿਵੇਂ john। voice_name ਨੂੰ ਉਪਨਾਮ ਵਜੋਂ ਸਵੀਕਾਰਿਆ ਜਾਂਦਾ ਹੈ। ਅਣਜਾਣ ਵੌਇਸਾਂ ਪ੍ਰਮਾਣਿਕਤਾ ਵਿੱਚ ਅਸਫਲ ਹੁੰਦੀਆਂ ਹਨ ਅਤੇ ਕਾਲ ਰੱਦ ਕਰਦੀਆਂ ਹਨ |
product | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਡਿਫਾਲਟ spark ਹੈ। ਮਨਜ਼ੂਰਸ਼ੁਦਾ: spark, bolt, storm-base, storm-base-with-ack, storm-extra, storm-extra-with-ack |
thinking_level | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | minimal, base (ਡਿਫਾਲਟ), ਜਾਂ extra। Storm ਉਤਪਾਦਾਂ ਲਈ ਓਵਰਰਾਈਡ ਹੁੰਦਾ ਹੈ: storm-extra* extra ਲਾਗੂ ਕਰਦਾ ਹੈ, ਹੋਰ storm-* base ਲਾਗੂ ਕਰਦੇ ਹਨ |
audio_context_mode | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | full (ਡਿਫਾਲਟ) ਜਾਂ reduced |
watchdog_enabled | ਬੂਲੀਅਨ | ਨਹੀਂ | ਇਸ ਕਾਲ ਲਈ ਨਿਗਰਾਨੀ ਯੋਗ ਕਰੋ। ਡਿਫਾਲਟ false |
additional_audio_context | ਬੂਲੀਅਨ | ਨਲ | ਨਹੀਂ | ਸਿਰਫ਼ ਸਭ ਤੋਂ ਹਾਲੀਆ ਵਾਰੀ ਦੀ ਬਜਾਏ ਕਾਲਰ ਆਡੀਓ ਦੀਆਂ ਪਿਛਲੀਆਂ ਕੁਝ ਵਾਰੀਆਂ ਸ਼ਾਮਲ ਕਰੋ, ਜਿਸ ਨਾਲ ਥੋੜ੍ਹੀ ਲੇਟੈਂਸੀ/ਲਾਗਤ ਵਧਣ ਦੇ ਬਦਲੇ ਸੁਧਾਰਾਂ ਅਤੇ ਸਪੈਲਿੰਗ/ਨੰਬਰ-ਭਾਰੀ ਡਾਟਾ ਇਕੱਤਰ ਕਰਨ ਵਿੱਚ ਸੁਧਾਰ ਹੁੰਦਾ ਹੈ। ਇਨਬਾਊਂਡ ਸੈਸ਼ਨਾਂ ਲਈ ਡਿਫਾਲਟ ਤੌਰ ਤੇ ਚਾਲੂ ਅਤੇ ਆਊਟਬਾਊਂਡ ਫ਼ੋਨ ਕਾਲਾਂ ਲਈ ਬੰਦ ਹੈ; null ਡਿਫਾਲਟ ਬਰਕਰਾਰ ਰੱਖਦਾ ਹੈ |
storm_feedback_mode | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | none, acknowledgement (ਡਿਫਾਲਟ), ਜਾਂ tick |
language | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | primary_language ਲਈ ਸੰਖੇਪ ਰੂਪ |
primary_language | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਭਾਸ਼ਾ ਕੋਡ, ਸਧਾਰਨ ਕੀਤਾ ਗਿਆ (ਡਿਫਾਲਟ en)। ਹੱਲ ਨਾ ਹੋਣ ਵਾਲੇ ਕੋਡ ਕਾਲ ਰੱਦ ਕਰਦੇ ਹਨ |
has_additional_languages | ਬੂਲੀਅਨ | ਨਹੀਂ | ਡਿਫਾਲਟ false |
additional_languages | ਸਟ੍ਰਿੰਗ ਦੀ ਐਰੇ | ਨਹੀਂ | ਵਾਧੂ ਭਾਸ਼ਾਵਾਂ ਜਿਨ੍ਹਾਂ ਵਿੱਚ ਏਜੰਟ ਬਦਲ ਸਕਦਾ ਹੈ |
native_voice_switching | ਬੂਲੀਅਨ | ਨਹੀਂ | ਡਿਫਾਲਟ false। ਜਦੋਂ ਕਾਲ ਕਿਸੇ ਹੋਰ ਭਾਸ਼ਾ ਵਿੱਚ ਬਦਲਦੀ ਹੈ, ਤਾਂ ਸੰਰਚਿਤ ਵੌਇਸ ਰੱਖਣ ਦੀ ਬਜਾਏ ਉਸ ਭਾਸ਼ਾ ਦੀ ਮੂਲ ਵੌਇਸ ਨਾਲ ਬਦਲੋ (ਲਿੰਗ ਅਨੁਸਾਰ ਮੇਲ ਕੀਤੀ ਹੋਈ) |
background_track | ਸਟ੍ਰਿੰਗ | ਨਲ | ਨਹੀਂ | ਐਂਬੀਅਂਟ ਆਡੀਓ id ਜਾਂ null |
acknowledgement_prompt_mode | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | auto (ਡਿਫਾਲਟ) ਜਾਂ manual (Storm-with-ack ਉਤਪਾਦ) |
acknowledgement_prompt | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਜਦੋਂ acknowledgement_prompt_mode="manual" ਹੋਵੇ ਤਾਂ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ |
silence_interval_seconds | ਪੂਰਨ ਅੰਕ | ਨਲ | ਨਹੀਂ | 5–120। ਜਾਂਚ ਤੋਂ ਪਹਿਲਾਂ ਕਾਲਰ ਦੀ ਚੁੱਪੀ ਦੇ ਸਕਿੰਟ |
silence_max_checkins | ਪੂਰਨ ਅੰਕ | ਨਲ | ਨਹੀਂ | 1–10 |
silence_checkins_enabled | ਬੂਲੀਅਨ | ਨਹੀਂ | ਡਿਫਾਲਟ true |
connect_tone_enabled | ਬੂਲੀਅਨ | ਨਹੀਂ | ਡਿਫਾਲਟ false |
voicemail_action | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | prompt (ਡਿਫਾਲਟ), hangup, ਜਾਂ message |
voicemail_message | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਜਦੋਂ voicemail_action="message" ਹੋਵੇ ਤਾਂ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ |
agent_name | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਡੈਸ਼ਬੋਰਡਾਂ ਅਤੇ ਵਿਜਿਟ ਲਈ ਦਰਸਾਇਆ ਜਾਣ ਵਾਲਾ ਨਾਮ |
org_name | ਸਟ੍ਰਿੰਗ | ਨਹੀਂ | ਏਜੰਟ ਦੇ ਪਰਸੋਨਾ ਲਈ ਸੰਗਠਨ ਦਾ ਡਿਸਪਲੇ ਨਾਮ |
tools | ਐਰੇ | ਨਹੀਂ | ਇਨਲਾਈਨ ਫੰਕਸ਼ਨ-ਟੂਲ ਸਕੀਮੇ (Function Tools ਵੇਖੋ) |
call_id | ਪੂਰਨ ਅੰਕ | ਨਹੀਂ | ਬੇਨਤੀ ਦੀ ਕਾਲ id ਦੀ ਵਿਕਲਪਿਕ ਗੂੰਜ; ਅਣਡਿੱਠੀ ਕੀਤੀ ਜਾਂਦੀ ਹੈ |
ਕਿਉਂਕਿ prompt ਅਤੇ voice ਲਾਜ਼ਮੀ ਹਨ, {} ਜਾਂ ਪ੍ਰਮਾਣਿਕਤਾ ਵਿੱਚ ਅਸਫਲ ਹੋਣ ਵਾਲਾ ਕੋਈ ਵੀ
ਜਵਾਬ ਕਾਲ ਨੂੰ 422 ਨਾਲ ਰੱਦ ਕਰ ਦਿੰਦਾ ਹੈ — ਇਸ ਪਾਥ ਉੱਤੇ ਕੋਈ static-agent ਫਾਲਬੈਕ ਨਹੀਂ ਹੈ
(ਵੈੱਬਹੁੱਕ ਮੋਡ ਵਿੱਚ ਕਿਸੇ ਨੰਬਰ ਜਾਂ ਕੁੰਜੀ ਲਈ ਕੋਈ ਏਜੰਟ ਨਿਰਧਾਰਤ ਨਹੀਂ ਹੁੰਦਾ)।
ਜਵਾਬ ਦੇ ਆਕਾਰ ਦੀ ਸੀਮਾ
ਉਦਾਹਰਨ ਹੈਂਡਲਰ
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, signature: str) -> bool:
expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
body = await request.body()
if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
raise HTTPException(status_code=401)
event = json.loads(body)
if event["type"] == "telephony.incoming":
caller = event["data"]["from_number"]
prompt = (
"Greet the caller as a San Francisco local…"
if caller.startswith("+1415")
else "You are a friendly customer support agent…"
)
return {
"prompt": prompt,
"voice": "john",
"product": "spark",
}
if event["type"] == "web.incoming":
return {
"prompt": "You are the website's helpful voice assistant…",
"voice": "john",
"product": "spark",
}
return {}import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
function verify(body, signature) {
const expected = crypto
.createHmac("sha256", SECRET)
.update(body)
.digest("hex");
return signature &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
app.post(
"/thunderphone-webhook",
express.raw({ type: "application/json" }),
(req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (event.type === "telephony.incoming" || event.type === "web.incoming") {
const caller = event.data.from_number || "web";
const prompt = caller.startsWith("+1415")
? "Greet the caller as a San Francisco local…"
: "You are a friendly customer support agent…";
return res.json({
prompt,
voice: "john",
product: "spark",
});
}
res.json({});
},
);ਫੰਕਸ਼ਨ ਟੂਲਾਂ ਨਾਲ ਜਵਾਬ
ਟੂਲ ਜੋੜੋ ਤਾਂ ਜੋ AI ਗੱਲਬਾਤ ਦੌਰਾਨ ਤੁਹਾਡੀਆਂ API ਨੂੰ ਕਾਲ ਕਰ ਸਕੇ:
{
"prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.",
"voice": "john",
"product": "spark",
"tools": [
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"service": { "type": "string" }
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-key"
}
}
}
]
}ਉਤਪਾਦ ਟੀਅਰ ਚੀਟ ਸ਼ੀਟ
| ਉਤਪਾਦ | ਲੇਟੈਂਸੀ | ਤਰਕ | ਸਵੀਕ੍ਰਿਤੀ |
|---|---|---|---|
spark | ਸਭ ਤੋਂ ਘੱਟ | ਬੁਨਿਆਦੀ | — |
bolt | ਘੱਟ | ਸੁਧਾਰਿਆ ਹੋਇਆ | — |
storm-base | ਦਰਮਿਆਨਾ | ਮਜ਼ਬੂਤ | — |
storm-base-with-ack | ਦਰਮਿਆਨਾ | ਮਜ਼ਬੂਤ | ਸੋਚਦੇ ਸਮੇਂ ਆਟੋ ਫਿਲਰ |
storm-extra | ਵੱਧ | ਡੂੰਘਾ | — |
storm-extra-with-ack | ਵੱਧ | ਡੂੰਘਾ | ਸੋਚਦੇ ਸਮੇਂ ਆਟੋ ਫਿਲਰ |