Open in
ఫంక్షన్ టూల్స్
మీ AI ఏజెంట్లకు సంభాషణ మధ్యలో బాహ్య APIలను కాల్ చేసే ఫంక్షన్ టూల్స్ను ఇవ్వండి — కస్టమర్ డేటాను పొందండి, అపాయింట్మెంట్లను బుక్ చేయండి, రికార్డులను అప్డేట్ చేయండి — టైప్ చేయబడిన పారామీటర్లతో.
ఫంక్షన్ టూల్స్ మీ AI ఏజెంట్లు ఫోన్ కాల్ల సమయంలో బాహ్య APIలను పిలవడానికి అనుమతిస్తాయి. కస్టమర్ డేటాను వెతకడానికి, అందుబాటును తనిఖీ చేయడానికి, అపాయింట్మెంట్లను బుక్ చేయడానికి లేదా మీ బ్యాకెండ్ మద్దతిచ్చే ఏదైనా చర్యను నిర్వహించడానికి వాటిని ఉపయోగించండి.
ఇది ఎలా పనిచేస్తుంది
- మీరు ఒక స్కీమాతో టూల్స్ను నిర్వచిస్తారు (టూల్ అంగీకరించే ఆర్గ్యుమెంట్లు)
- మీరు ఒక
endpointకాన్ఫిగరేషన్ను అందిస్తారు (ThunderPhone మీ APIని ఎక్కడ పిలుస్తుంది) — లేదా మీ సంస్థ వెబ్హుక్లో టూల్ కాల్లను స్వీకరించడానికి దానిని వదిలివేయండి - కాల్ సమయంలో, సంభాషణ ఆధారంగా టూల్ను ఎప్పుడు ఉపయోగించాలో AI నిర్ణయిస్తుంది
- ThunderPhone టూల్ ఆర్గ్యుమెంట్లతో మీ endpointను పిలుస్తుంది
- సంభాషణను కొనసాగించడానికి మీ API ప్రతిస్పందన AIకి తిరిగి పంపబడుతుంది
| సామర్థ్యం | ఇది ఎక్కడ నడుస్తుంది | సెటప్ |
|---|---|---|
| అంతర్నిర్మిత టూల్స్ | ThunderPhone | Prompt సూచనలు; కొన్ని టూల్స్కు ఏజెంట్ సెట్టింగ్ కూడా అవసరం |
| యాప్ కనెక్షన్లు | ThunderPhone మరియు కనెక్ట్ చేసిన ప్రొవైడర్ | ఖాతాను కనెక్ట్ చేసి, ఆమోదించబడిన చర్యలను జత చేయండి |
| API కనెక్షన్లు మరియు ఫంక్షన్ టూల్స్ | మీ HTTP API | endpoint మరియు స్కీమాను నిర్వచించండి లేదా వెబ్హుక్ ద్వారా ఫంక్షన్ కాల్లను స్వీకరించండి |
| MCP సర్వర్లు | రిమోట్ MCP సర్వర్ | సర్వర్ను జోడించి, దాని టూల్స్ను కనుగొని, దానిని ఏజెంట్కు జత చేయండి |
టూల్ స్కీమా
ప్రతి టూల్ ఈ నిర్మాణాన్ని అనుసరిస్తుంది:
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots for a given date",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"service": {
"type": "string",
"description": "Type of service (e.g., 'consultation', 'follow-up')"
}
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-api-key"
}
},
"timeout": 120
}టూల్ కాన్ఫిగరేషన్
| ఫీల్డ్ | రకం | అవసరం | వివరణ |
|---|---|---|---|
timeout | సంఖ్య | కాదు | సెకన్లలో గరిష్ట అమలు సమయం (డిఫాల్ట్: 20, గరిష్టం: 180, లేదా wait_mode: "hold"తో 600) |
wait_mode | స్ట్రింగ్ | కాదు | టూల్ అమలవుతున్నప్పుడు కాలర్ వినేది: updates (డిఫాల్ట్), చిన్న మౌఖిక నవీకరణలు; లేదా hold, హోల్డ్ సంగీతం. ఎక్కువసేపు వేచి ఉండటం: హోల్డ్ మోడ్ మరియు తర్వాత సమాధానం ఇవ్వడం చూడండి |
call_start | ఆబ్జెక్ట్ | కాదు | ప్రతి ఫోన్ కాల్ ప్రారంభంలో, అభివాదానికి ముందు, టూల్ను స్వయంచాలకంగా కూడా అమలు చేయండి. కాల్ ప్రారంభంలో టూల్ను అమలు చేయండి చూడండి |
ఫంక్షన్ నిర్వచనం
| ఫీల్డ్ | రకం | అవసరం | వివరణ |
|---|---|---|---|
name | స్ట్రింగ్ | అవును | టూల్కు ఐడెంటిఫైయర్; ఒక కాల్లోని టూల్లలో ప్రత్యేకంగా ఉండాలి. వేర్వేరు ఏజెంట్లు ఒకే పేరుతో తమ స్వంత టూల్ను కలిగి ఉండవచ్చు |
description | స్ట్రింగ్ | అవును | ఈ టూల్ను ఎప్పుడు ఉపయోగించాలో AIకి వివరిస్తుంది |
parameters | ఆబ్జెక్ట్ | అవును | టూల్ ఆర్గ్యుమెంట్ల కోసం JSON Schema |
Endpoint కాన్ఫిగరేషన్
| ఫీల్డ్ | రకం | అవసరం | వివరణ |
|---|---|---|---|
url | స్ట్రింగ్ | అవును | మీ API endpoint URL |
method | స్ట్రింగ్ | లేదు | HTTP పద్ధతి (డిఫాల్ట్: POST) |
headers | ఆబ్జెక్ట్ | లేదు | చేర్చాల్సిన అనుకూల హెడర్లు |
రెండు ఇన్వొకేషన్ మార్గాలు
మీ సర్వర్ స్వీకరించే అభ్యర్థన టూల్కు
endpoint ఉందా అనే దానిపై ఆధారపడి ఉంటుంది:
endpoint ఉన్న టూల్ | endpoint లేని టూల్ | |
|---|---|---|
| అభ్యర్థన వెళ్లే స్థానం | నేరుగా endpoint.urlకు | మీ సంస్థ యొక్క లెగసీ వెబ్హుక్ URLకు |
| బాడీ | ఎంచుకున్న అభ్యర్థన ఫార్మాట్ (డిఫాల్ట్గా కేవలం ఆర్గ్యుమెంట్లు) | telephony.tool / web.tool ఎన్వలప్ |
| హెడర్లు | మీ endpoint.headers + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature, అలాగే ఫోన్ కాల్లలో కాల్ నంబర్లు | Content-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature |
| సంతకం కీ | సంస్థ వెబ్హుక్ సీక్రెట్ | సంస్థ వెబ్హుక్ సీక్రెట్ |
రెండు మార్గాలు బ్లాకింగ్ — ఫలితం కోసం AI వాక్యం మధ్యలో వేచి ఉంటుంది. డిఫాల్ట్ టైమ్అవుట్ 20 s; గరిష్ఠంగా ప్లాట్ఫారమ్ అనుమతించే 180 s వరకు ఎక్కువ సమయం అమలుకు అనుమతించడానికి టూల్ టాప్-లెవల్ timeout సెట్ చేయండి. హ్యాండ్లర్లను వేగంగా ఉంచండి. వ్యక్తి లేదా నెమ్మదైన జాబ్ కోసం వేచి ఉండాల్సి వస్తే, హోల్డ్ మోడ్ ఉపయోగించండి. రెండింటి మిశ్రమం కూడా సరే: వెబ్హుక్ URL ఉన్న సంస్థ కాల్లో, endpoint ఉన్న టూల్లను నేరుగా కాల్ చేస్తారు మరియు మిగిలినవి వెబ్హుక్కు ఫాల్బ్యాక్ అవుతాయి.
ప్రత్యక్ష ఎండ్పాయింట్ కాల్లు
AI ఒక endpoint ఉన్న టూల్ను అమలు చేసినప్పుడు, ThunderPhone మీ URLకు
రిక్వెస్ట్ను పంపుతుంది:
రిక్వెస్ట్ హెడర్లు
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-keyమీ endpoint.headers నుంచి అనుకూల హెడర్లు ఎల్లప్పుడూ యథాతథంగా చేర్చబడతాయి,
అదనంగా ఈ ThunderPhone-నేమ్స్పేస్ హెడర్లు ఉంటాయి:
X-ThunderPhone-Signature-V2— మెథడ్, పాత్, క్వెరీ మరియు బాడీపై టైమ్స్టాంప్తో కూడిన HMAC-SHA256, మీ సంస్థ వెబ్హుక్ రహస్యంతో కీ చేయబడింది. దీన్ని ధృవీకరించి, 5 నిమిషాల కంటే పాత అభ్యర్థనలను తిరస్కరించండి; చూడండి వెబ్హుక్ సంతకాలను ధృవీకరించండిX-ThunderPhone-Signature— ఖచ్చితమైన అభ్యర్థన-బాడీ బైట్లకు సంబంధించిన లెగసీ HMAC-SHA256, అదే కీతో, ఇప్పటికే ఉన్న వెరిఫైయర్ల కోసం ఇప్పటికీ పంపబడుతుందిX-ThunderPhone-Call-ID— ప్రస్తుత కాల్ IDX-ThunderPhone-From-NumberమరియుX-ThunderPhone-To-Number— కాల్కు సంబంధించిన E.164లోని From మరియు To నంబర్లు. ఇవిtelephony.completeలోనిfrom_numberమరియుto_numberతో అదే అర్థాన్ని కలిగి ఉంటాయి: అవుట్బౌండ్ కాల్లో, From మీ ఏజెంట్ నంబర్ మరియు To కాల్ చేసిన వ్యక్తి. కాలర్ ID దాచబడినప్పుడు లేదా అది ఫోన్ నంబర్ కానప్పుడు నంబర్ చేర్చబడదుX-ThunderPhone-Call-Direction—inboundలేదాoutbound, కాబట్టి కస్టమర్ నంబర్ ఏదో మీరు గుర్తించవచ్చు
కాల్-నంబర్ హెడర్లు ఫోన్ కాల్లలో మాత్రమే పంపబడతాయి. వెబ్, విజెట్,
రియల్టైమ్ మరియు బ్రౌజర్ Talk పరీక్షల్లో ఫోన్ నంబర్ ఉండదు కాబట్టి అవి చేర్చబడవు. ఏజెంట్ ఎడిటర్ మరియు AI సిమ్యులేషన్లలోని పరీక్ష కాల్లు సిమ్యులేట్ చేసిన కాలర్ నంబర్ను కలిగి ఉంటాయి. సంతకాలు హెడర్లను
కవర్ చేయవు: V2 టైమ్స్టాంప్, మెథడ్, పాత్, క్వెరీ మరియు బాడీపై సంతకం చేస్తుంది. నంబర్లు కూడా సంతకంలో ఉండాలంటే, బదులుగా వాటిని బాడీ నుండి చదవండి:
retell అభ్యర్థన ఫార్మాట్ మూడింటినీ కలిగి ఉంటుంది మరియు vapi కస్టమర్ నంబర్ను కలిగి ఉంటుంది.
మీ endpoint.headers దానిని ఓవర్రైడ్ చేయనంత వరకు Content-Type: application/json
సెట్ చేయబడుతుంది — కస్టమ్ Content-Typeకే ప్రాధాన్యం ఉంటుంది.
అభ్యర్థన ఫార్మాట్
ప్రతి API కనెక్షన్లో request_format సెట్టింగ్ ఉంటుంది. దిగుమతి చేసిన టూల్ ఆ ప్లాట్ఫారమ్ కోసం రూపొందించిన ఎండ్పాయింట్ను కాల్ చేస్తూనే ఉండాలంటే vapi లేదా
retell ఎంచుకోండి. కొత్త మరియు ఇప్పటికే ఉన్న కనెక్షన్లు డిఫాల్ట్గా standardను ఉపయోగిస్తాయి.
POST / PUT / PATCH కోసం, ThunderPhone ఎంచుకున్న
ఎన్వలప్ను కానానికల్గా సీరియలైజ్ చేస్తుంది (క్రమబద్ధీకరించిన కీలు, కాంపాక్ట్ సెపరేటర్లు). రెండు సంతకాలు ఈ ఖచ్చితమైన బైట్లను కవర్ చేస్తాయి.
ప్రామాణికం
standard ఎలాంటి ర్యాపర్ లేకుండా టూల్ ఆర్గ్యుమెంట్లను మాత్రమే పంపుతుంది. ఇది
డిఫాల్ట్ ఎంపిక మరియు ThunderPhone యొక్క అసలు రిక్వెస్ట్ బాడీని బైట్కు బైట్గా యథాతథంగా ఉంచుతుంది:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi, Vapi డాక్యుమెంట్ చేసిన ఆకృతిలో Vapi యొక్క tool-calls server messageను పంపుతుంది.
call.id అనేది ThunderPhone కాల్ ID.
ఫోన్ కాల్లలో, Vapi కాల్ ఆబ్జెక్ట్లో ఉన్నట్లుగా call.customer.number అనేది ఇతర పక్షం నంబర్: ఇన్బౌండ్ కాల్లో కాల్ చేసిన వ్యక్తి, అవుట్బౌండ్ కాల్లో కాల్ అందుకునే వ్యక్తి నంబర్. ఆ నంబర్ దాచబడినప్పుడు లేదా అది ఫోన్ నంబర్ కానప్పుడు ఇది చేర్చబడదు. టూల్-కాల్ id ఆ అమలుకు ప్రత్యేకమైనది మరియు ఎండ్పాయింట్ ఫలితంతో సరిపోల్చడానికి మళ్లీ ఉపయోగించబడుతుంది. function.argumentsను JSON ఆబ్జెక్ట్గా ఉంచి, కాల్ toolCallList మరియు
toolWithToolCallList రెండింటిలోనూ కనిపిస్తుంది:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}assistant, artifact మరియు పూర్తి call ఆబ్జెక్ట్ వంటి Vapi-ప్రత్యేక ఫీల్డ్లు
పంపబడవు.
సరిపోలే టూల్-కాల్ IDతో Vapi ప్రతిస్పందన ఎన్వలప్ను తిరిగి ఇవ్వండి:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone ర్యాప్ చేయని result స్ట్రింగ్ను AIకి అందిస్తుంది. ఇప్పటికే JSON విలువను తిరిగి ఇచ్చే ఎండ్పాయింట్లతో అనుకూలత కోసం
అది JSON విలువను కూడా స్వీకరిస్తుంది. result స్థానంలో ఉన్న errorను AIకి టూల్ లోపంగా తిరిగి ఇస్తుంది. ఎండ్పాయింట్ తప్పుగా రూపొందించిన లేదా సరిపోలని Vapi ఎన్వలప్ను తిరిగి ఇస్తే, ThunderPhone
హెచ్చరికను లాగ్ చేసి, కాల్ విఫలమయ్యేలా చేయకుండా దాని ప్రామాణిక ప్రతిస్పందన పార్సింగ్కు తిరిగి మారుతుంది.
Retell
retell, Retell కస్టమ్
ఫంక్షన్ కోసం డాక్యుమెంట్ చేసిన అభ్యర్థనను పంపుతుంది:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}ఫోన్ కాల్లలో, call ఆబ్జెక్ట్లో Retell ఫోన్ కాల్ ఆబ్జెక్ట్ ఉపయోగించే ఫీల్డ్ పేర్లైన call_id, from_number,
to_number మరియు direction (inbound లేదా outbound) ఉంటాయి. అవి కాల్-నంబర్ హెడర్లకు సరిపోతాయి,
మరియు హెడర్లకు భిన్నంగా, అవి రెండు సంతకాల పరిధిలో ఉంటాయి. గోప్యంగా ఉంచిన లేదా ఫోన్ నంబర్ కాని నంబర్ను చేర్చరు. వెబ్, విడ్జెట్,
రియల్టైమ్ మరియు బ్రౌజర్ Talk పరీక్షల్లో ఇందులో call_id మాత్రమే ఉంటుంది. ThunderPhone
పంపిణీ సమయంలో వాస్తవంగా అందించలేని agent_id, transcript, transcript_object, metadata లేదా డైనమిక్
వేరియబుల్స్ వంటి Retell-నిర్దిష్ట ఫీల్డ్లను చేర్చదు. Retell ఏదైనా ప్రతిస్పందన బాడీని అంగీకరిస్తుంది; ThunderPhone దానిని ప్రామాణిక ప్రతిస్పందన నిర్వహణను ఉపయోగించి పంపిస్తుంది.
GET / DELETE కోసం, request_formatతో సంబంధం లేకుండా ఆర్గ్యుమెంట్లు క్వెరీ పారామీటర్లుగా
పంపబడతాయి మరియు బాడీ ఖాళీగా ఉంటుంది. V2 సంతకం పంపినట్లుగానే క్వెరీ స్ట్రింగ్ను కవర్ చేస్తుంది; లెగసీ సంతకం
ఖాళీ బైట్ స్ట్రింగ్పై లెక్కించబడుతుంది. చూడండి
వెబ్హుక్ సంతకాలను ధృవీకరించండి.
రెస్పాన్స్
టూల్ ఫలితంతో JSON రెస్పాన్స్ను తిరిగి ఇవ్వండి:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}రెస్పాన్స్ను ఫార్మాట్ చేసి, సంభాషణను కొనసాగించడానికి AIకి అందిస్తారు.
JSON కాని రెస్పాన్స్లు {"data": "<text>"}గా ర్యాప్ చేయబడతాయి; టైమ్అవుట్లు
మరియు కనెక్షన్ వైఫల్యాలు AIకి ఎర్రర్లుగా నివేదించబడతాయి, కాబట్టి ఏజెంట్
ఆలస్యం కాకుండా క్షమాపణ చెప్పి ముందుకు సాగగలదు.
వెబ్హుక్-మోడ్ డిస్పాచ్
endpoint లేని టూల్లు మీ సంస్థ లెగసీ వెబ్హుక్ URLకు సంతకం చేయబడిన
telephony.tool (ఫోన్ కాల్లు) లేదా web.tool (వెబ్ కాల్లు) రిక్వెస్ట్గా
డిస్పాచ్ చేయబడతాయి. అమలు తర్వాత వెబ్హుక్ ఎండ్పాయింట్లకు పంపబడే
ఆడిట్ నోటిఫికేషన్లుకు భిన్నంగా, ఈ రిక్వెస్ట్యే అమలు —
మీ HTTP రెస్పాన్స్ టూల్ ఫలితం.
{
"type": "telephony.tool",
"data": {
"call_id": 987654321,
"tool_name": "search_appointments",
"arguments": { "date": "2026-04-21" },
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}web.tool, from_number /
to_number బదులుగా origin_domainను కలిగి ఉంటుంది. డైరెక్ట్ endpoint కాల్లకు వర్తించే అదే ప్రతిస్పందన
ఒప్పందంతో, సాధన ఫలితాన్ని JSONగా పంపండి. ఇతర ప్రతి webhook లాగానే, ఈ అభ్యర్థనకు రెండు సిగ్నేచర్ headerలతో పాటు సంస్థ
webhook రహస్యాన్ని ఉపయోగించి సంతకం చేయబడుతుంది.
దీర్ఘ నిరీక్షణలు: హోల్డ్ మోడ్ మరియు తర్వాత సమాధానం ఇవ్వడం
కొన్ని టూల్స్ వ్యక్తి కోసం వేచి ఉంటాయి: డిస్కౌంట్ను ఆమోదించే మేనేజర్, Slackలో ప్రశ్నకు సమాధానం ఇచ్చే యజమాని. అలాంటి టూల్స్లో wait_modeని "hold"గా సెట్ చేయండి.
wait_mode: "updates" (డిఫాల్ట్) | wait_mode: "hold" | |
|---|---|---|
| కాలర్ వినేది | టూల్-ప్రారంభ లైన్, తర్వాత సుమారు 12 సెకన్లకు ఒక చిన్న "ఇంకా పని చేస్తోంది" లైన్ మరియు దాదాపు ప్రతి 15 సెకన్లకు మరొకటి | టూల్-ప్రారంభ లైన్, ఆపై ఫలితం వచ్చే వరకు హోల్డ్ సంగీతం |
timeout గరిష్ఠం | 180 సె | 600 సె |
| పెండింగ్ సమాధానాలు | ఫలితంగా ఏజెంట్కు పంపబడతాయి | మీరు ఫలితాన్ని అందించే వరకు టూల్ తెరిచి ఉంటుంది |
హోల్డ్ మోడ్లో టూల్ ప్రారంభమైనప్పుడు ఏజెంట్ ఒక లైన్ చెబుతుంది (దాని స్వంత మాటల్లో లేదా ఏజెంట్పై సెట్ చేసిన టూల్-ప్రారంభ లైన్), తర్వాత కాలర్ హోల్డ్ సంగీతం వింటారు. ఏజెంట్ ఫలితం చెప్పే ముందు సంగీతం నెమ్మదిగా తగ్గుతుంది. ఒకటి లేదా రెండు సెకన్లలో సమాధానం ఇచ్చే టూల్కు సంగీతం ఉండదు. ఏజెంట్ ఫోన్ మెను లేదా వాయిస్మెయిల్ బాక్స్తో మాట్లాడుతున్నప్పుడు, సంగీతాన్ని సమాధానంగా వినే అవకాశం ఉన్నందున అది బదులుగా మాట్లాడే నవీకరణలను ఉపయోగిస్తుంది. హోల్డ్ మధ్యలో మెను లేదా మెయిల్బాక్స్గా గుర్తించిన కాల్ కూడా ఇందులో ఉంటుంది: సంగీతం ఆగిపోతుంది మరియు మాట్లాడే నవీకరణలు ప్రారంభమవుతాయి. సంగీతం ప్లే చేయలేని కాల్కు కూడా ఇదే వర్తిస్తుంది.
హోల్డ్ సమయంలో కాలర్ మాట్లాడితే, సంగీతం కొనసాగుతుంది మరియు ఏజెంట్ ఇంకా సమాధానం ఇవ్వదు. కాలర్ చెప్పినది విని, ఫలితంతో పాటు దానికి స్పందిస్తుంది. కాల్ను ముగిస్తే కాల్ మరియు తెరిచి ఉన్న టూల్ ముగుస్తాయి.
తర్వాత సమాధానం ఇవ్వడం
మీ ఎండ్పాయింట్ స్వంత ప్రతిస్పందన ఇప్పటికీ 180 సె లోపు రావాలి. కాలర్ను ఎక్కువసేపు హోల్డ్లో ఉంచడానికి, పెండింగ్ ఫలితంతో వెంటనే సమాధానం ఇవ్వండి:
{ "status": "pending", "request_id": "ask-4471" }request_id అనేది మీ వైపు ఈ అభ్యర్థనను గుర్తించే గరిష్ఠంగా 200 అక్షరాల ఏదైనా స్ట్రింగ్. మీరు దాని ఫలితాన్ని
POST /v1/calls/{call_id}/tool-resultsతో అందించే వరకు కాలర్ హోల్డ్లోనే ఉంటారు.
call_id అనేది టూల్ అభ్యర్థనలోని X-ThunderPhone-Call-ID హెడర్.
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'మీ ఎండ్పాయింట్ దానిని తిరిగి ఇచ్చినట్లే, ఏజెంట్ resultను టూల్ సమాధానంగా చదువుతుంది. టూల్ను పిలిచినప్పటి నుండి లెక్కించే టూల్ timeoutకు ముందు ఫలితం రాకపోతే, సమాధానం తిరిగి రాలేదని ఏజెంట్కు తెలియజేయబడుతుంది మరియు సందేశం తీసుకోవడం వంటి తదుపరి చర్యలను కాలర్కు సూచిస్తుంది.
మీ పెండింగ్ ప్రతిస్పందన ThunderPhoneకు చేరకముందే కూడా, మీకు నచ్చిన వెంటనే ఫలితాన్ని పోస్ట్ చేయవచ్చు. 202 అంటే కాల్ దానిని అంగీకరించిందని అర్థం: తెరిచి ఉన్న అభ్యర్థన దానిని తీసుకుంది లేదా టూల్ స్వంత అభ్యర్థన ఇంకా ప్రాసెస్లో ఉంది మరియు దాని పెండింగ్ సమాధానం దానిని స్వీకరిస్తుంది. ఏ అభ్యర్థన కూడా స్వీకరించని ఫలితం (ఆ request_id కోసం మీ ఎండ్పాయింట్ తర్వాత పెండింగ్ కాకుండా వేరే సమాధానం ఇచ్చినప్పుడు) విస్మరించబడుతుంది.
కనెక్షన్కు రెస్పాన్స్ ట్రాన్స్ఫార్మ్ ఉంటే (ఏజెంట్ చూడకముందు మీ ఎండ్పాయింట్ సమాధానాన్ని మళ్లీ రాసే కోడ్), ThunderPhone పెండింగ్ సమాధానం కోసం తనిఖీ చేయకముందే ట్రాన్స్ఫార్మ్ మీ ఎండ్పాయింట్ స్వంత సమాధానంపై అమలవుతుంది, కాబట్టి పెండింగ్ సమాధానంలో అది status మరియు request_idను ఉంచాలి. మీరు తర్వాత పోస్ట్ చేసే ఫలితంపై అది అమలుకాదు: మీరు పంపినట్లుగానే ఏజెంట్ ఆ ఫలితాన్ని పొందుతుంది.
ఫుల్-డ్యూప్లెక్స్ ఏజెంట్కు హోల్డ్ సంగీతం లేదా నవీకరణ లైన్లు ఉండవు, కాబట్టి దాని కాల్లలో హోల్డ్ టూల్ updates టూల్లా ప్రవర్తిస్తుంది: పెండింగ్ సమాధానం టూల్ ఫలితంగా ఏజెంట్కు చేరుతుంది.
updates మోడ్లోని టూల్ నుండి వచ్చే పెండింగ్ ప్రతిస్పందన తెరిచి ఉంచబడదు: ఏజెంట్ దానిని టూల్ ఫలితంగా అందుకుంటుంది.
సంతకం ధృవీకరణ
డైరెక్ట్ టూల్ కాల్లు వెబ్హుక్ల మాదిరిగానే సంతకం చేయబడతాయి; ఇవి మీ సంస్థ వెబ్హుక్ సీక్రెట్తో కీ చేయబడతాయి:
X-ThunderPhone-Signature-V2పంపిన విధంగానే టైమ్స్టాంప్, మెథడ్, పాత్, క్వెరీ, అలాగే ఖచ్చితమైన బాడీ బైట్లపై సంతకం చేస్తుంది. మీ గడియారం సమయం కంటే 5 నిమిషాల కంటే ఎక్కువ వ్యత్యాసం ఉన్న టైమ్స్టాంప్లతో వచ్చిన రిక్వెస్ట్లను తిరస్కరించండి.X-ThunderPhone-Signature(లెగసీ) బాడీ బైట్లపై మాత్రమే సంతకం చేస్తుంది;GET/DELETEకోసం ఖాళీ బైట్ స్ట్రింగ్ను ఉపయోగిస్తుంది. ఇది ఇప్పటికీ మార్పులేకుండా పంపబడుతుంది.
SDK హెల్పర్లు 5 నిమిషాల వ్యవధితో సహా V2 హెడర్ను తనిఖీ చేస్తాయి:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
raise HTTPException(status_code=401)
data = json.loads(body)
date = data["date"]
# Look up availability
slots = await get_available_slots(date)
return {"available_slots": slots}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) return res.status(401).send('Invalid signature');
const { date, service } = JSON.parse(req.body);
// Look up availability
const slots = getAvailableSlots(date, service);
res.json({ available_slots: slots });
});పూర్తి రెసిపీలు — సంతకం చేసిన స్ట్రింగ్, ఒక పనిచేసే ఉదాహరణ, SDK లేకుండా కోడ్,
GET / DELETE సందర్భం, అలాగే సీక్రెట్ లేనప్పుడు వర్తించే హెచ్చరిక — వెబ్హుక్ సంతకాలను ధృవీకరించండిలో ఉన్నాయి.
ఉదాహరణ: పూర్తి బుకింగ్ ఫ్లో
పూర్తి అపాయింట్మెంట్ బుకింగ్ సిస్టమ్ కోసం టూల్ల సమితి ఇది:
{
"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": "key" }
}
},
{
"type": "function",
"function": {
"name": "book_appointment",
"description": "Book an appointment at a specific time",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "HH:MM format" },
"customer_name": { "type": "string" },
"customer_phone": { "type": "string" }
},
"required": ["date", "time", "customer_name"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/book",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "cancel_appointment",
"description": "Cancel an existing appointment",
"parameters": {
"type": "object",
"properties": {
"confirmation_number": { "type": "string" }
},
"required": ["confirmation_number"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/cancel",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
}
]
}కాల్ ప్రారంభంలో టూల్ను అమలు చేయండి
ఏజెంట్ తన మొదటి మాట చెప్పే ముందు, ప్రతి ఫోన్ కాల్ ప్రారంభంలో కూడా టూల్ స్వయంచాలకంగా అమలు కావచ్చు, తద్వారా అభివాదం ఫలితాన్ని ఉపయోగించగలదు. సాధారణంగా కాలర్ నంబర్ ద్వారా CRM శోధన చేస్తారు: "తిరిగి స్వాగతం, ఆర్తి! మీ సాధారణ ఆర్డర్ కావాలా?"
డ్యాష్బోర్డ్లో API కనెక్షన్ను తెరిచి, ఇది అమలయ్యే సమయంను
ప్రతి ఫోన్ కాల్ ప్రారంభంలోగా సెట్ చేయండి, ఆపై ప్రతి పారామీటర్కు వచ్చే విలువను నమోదు చేయండి. API ద్వారా, ఇంటిగ్రేషన్లోని triggerను
call_startగా మరియు దాని call_start_argumentsను
(API కనెక్షన్లు) సెట్ చేయండి లేదా ఇన్లైన్ టూల్కు call_start
బ్లాక్ను జోడించండి:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}కాల్ ప్రారంభంలో ఎవరూ ఏదీ నమోదు చేయరు కాబట్టి, ప్రతి అవసరమైన పారామీటర్కు ఆర్గ్యుమెంట్లలో ఒక విలువ ఉండాలి. విలువలు స్ట్రింగ్లు, సంఖ్యలు లేదా బూలియన్లు కావచ్చు. అవి సాధారణ టెక్స్ట్గా నిల్వ చేసి తిరిగి అందిస్తారు, ఏజెంట్ వాటిని చూడగలదు కాబట్టి API కీలు వంటి రహస్యాలను ఇక్కడ కాకుండా కనెక్షన్ హెడ్డర్లలో ఉంచండి. స్ట్రింగ్లు ఈ ప్లేస్హోల్డర్లను ఉపయోగించవచ్చు:
| ప్లేస్హోల్డర్ | విలువ |
|---|---|
{{caller_number}} | E.164 ఫార్మాట్లో కాల్లోని అవతలి వ్యక్తి నంబర్, ఉదా. +61402122887: ఇన్బౌండ్ కాల్లో కాలర్, అవుట్బౌండ్ కాల్లో కాల్ చేసిన వ్యక్తి |
{{caller_number_national}} | ఖాళీలు లేకుండా ఆ దేశ జాతీయ ఫార్మాట్లో అదే నంబర్, ఉదా. 0402122887 |
{{agent_number}} | ఏజెంట్ సొంత నంబర్ |
ఇది ఎలా పనిచేస్తుంది:
- అభ్యర్థన ఏజెంట్ స్వంత టూల్ కాల్లు పంపే అభ్యర్థనే అవుతుంది (అదే ఎండ్పాయింట్, హెడ్డర్లు, అభ్యర్థన ఫార్మాట్ మరియు సిగ్నేచర్).
- కాల్ ప్రారంభమైనప్పుడు టూల్ ప్రారంభమవుతుంది మరియు కనెక్ట్ టోన్, పరిచయం లేదా రికార్డింగ్ నోటీసు ప్లే అవుతున్నప్పుడు అమలవుతుంది. ఆ సమయం నుంచి అభివాదం దాని కోసం సుమారు 3 సెకన్ల వరకు వేచి ఉంటుంది. నెమ్మదిగా వచ్చే ఫలితం అందగానే, మిగతా కాల్ కోసం ఏజెంట్కు ఇవ్వబడుతుంది. అవుట్బౌండ్ కాల్లో కాల్ చేసినప్పుడు ఇది ప్రారంభమవుతుంది, కాబట్టి ఎవరూ సమాధానం ఇవ్వని ప్రయత్నాలతో సహా ప్రతి ప్రయత్నంలో అమలవుతుంది.
- కాలర్ ముందుగా మాట్లాడే ఏజెంట్లో వేచి ఉండేందుకు అభివాదం ఉండదు; ఫలితం అందగానే ఏజెంట్కు అందుతుంది.
- ఫలితం మొత్తం కాల్కు సందర్భంగా ఏజెంట్కు ఇవ్వబడుతుంది. దాన్ని ఎలా ఉపయోగించాలో మీ promptలో ఏజెంట్కు చెప్పండి; లేకపోతే అది చదివి వినిపించబడదు.
- టూల్ విఫలమైనా లేదా సమయం ముగిసినా, ఏజెంట్ సాధారణంగా చేసే విధంగానే కాలర్ను అభివాదం చేస్తుంది మరియు దాని గురించి ఏమీ చెప్పదు.
- కాల్లో తర్వాత కూడా ఏజెంట్ స్వయంగా టూల్ను కాల్ చేయగలదు.
- ఇది మీ ఫోన్కు చేసే డ్యాష్బోర్డ్ పరీక్షా కాల్లతో సహా ఫోన్ కాల్లలో, అలాగే అనుకరించిన కాలర్ నంబర్ను మీ ఎండ్పాయింట్కు పంపే AI సిమ్యులేషన్లలో అమలవుతుంది. కాలర్ నంబర్ లేని బ్రౌజర్ టాక్ పరీక్షలు లేదా వెబ్ విడ్జెట్ సెషన్లలో, కాలర్ ID దాచిన కాల్లలో లేదా దశలున్న ఏజెంట్లలో ఇది అమలవదు.
- ఒక ఏజెంట్ ఒకేసారి గరిష్ఠంగా మూడు కాల్-ప్రారంభ టూల్లను అమలు చేస్తుంది.
ఫలితాన్ని ఏజెంట్ ఎలా ఉపయోగించాలో తెలుసుకునేలా మీ promptలో దాని గురించి ప్రస్తావించండి, ఉదాహరణకు: "కాల్ ప్రారంభ శోధనలో కాలర్ కనిపిస్తే, వారిని వారి మొదటి పేరుతో అభివాదం చేయండి."
ఉత్తమ పద్ధతులు
స్పష్టమైన వివరణలు రాయండి
description ఫీల్డ్ టూల్ను ఎప్పుడు ఉపయోగించాలో AIకి అర్థం చేసుకోవడంలో సహాయపడుతుంది. అది ఏమి చేస్తుందో, ఎప్పుడు ఉపయోగించడం సముచితమో నిర్దిష్టంగా వివరించండి.
ఎర్రర్లను సులభంగా నిర్వహించండి
సాధారణ 500 ఎర్రర్లకు బదులుగా AI అర్థం చేసుకోగల ఎర్రర్ సందేశాలను తిరిగి పంపండి: {"error": "No slots available for that date"}.
ప్రతిస్పందనలను సంక్షిప్తంగా ఉంచండి
సంభాషణను కొనసాగించడానికి AIకి అవసరమైనదాన్ని మాత్రమే తిరిగి ఇవ్వండి. టూల్ ఫలితం సంభాషణలోనే ఉంటుంది మరియు ప్రతి తదుపరి దశలో మళ్లీ చదవబడుతుంది, కాబట్టి పెద్ద ఫలితం మిగిలిన కాల్కు ఖర్చు మరియు ఆలస్యాన్ని పెంచుతుంది. 100,000 అక్షరాలకు మించిన ఫలితాలు అసంపూర్ణమని AIకి తెలిసే ప్రివ్యూకు కుదించబడతాయి, మరియు చాలా సుదీర్ఘ కాల్లో పాత ఫలితాలు తొలగించబడవచ్చు (AI టూల్ను మళ్లీ కాల్ చేయగలదు). AI ఒకేసారి ఒక అంశం లేదా వర్గాన్ని చూడగలిగేలా ఒక పరామితిని జోడించండి, మరియు మెనూలు లేదా కేటలాగ్ల వంటి పెద్ద రిఫరెన్స్ కంటెంట్ను నాలెడ్జ్ బేస్లో ఉంచండి. డాష్బోర్డ్లోని పరీక్ష అభ్యర్థన పంపు ప్రతి ఫలితం పరిమాణాన్ని చూపిస్తుంది మరియు అది పెద్దదిగా ఉన్నప్పుడు హెచ్చరిస్తుంది.
అవసరమైన ఫీల్డ్లను వివేకంగా ఉపయోగించండి
నిజంగా అవసరమైనప్పుడు మాత్రమే ఫీల్డ్లను requiredగా గుర్తించండి. టూల్ను కాల్ చేయడానికి ముందు AI అవసరమైన సమాచారాన్ని వినియోగదారుని అడుగుతుంది.
సంబంధితవి
endpoint నిర్వచించకుండా ప్లాట్ఫారమ్ నిర్వహించే కాల్ చర్యలను prompt చేయండి.
HubSpot, Salesforce, Google Calendar, Google Sheets మరియు Cal.com కోసం ప్లాట్ఫారమ్ నిర్వహించే టూల్స్ — endpoint అవసరం లేదు.
MCP సర్వర్ను జతచేసి, దాని టూల్స్ను ఏజెంట్ కాల్ చేయనివ్వండి.
ఏజెంట్లకు జతచేయగల పునర్వినియోగించదగిన REST ఇంటిగ్రేషన్లు.
వెబ్హుక్లు మరియు టూల్ కాల్ల కోసం ఒక ధృవీకరణ సహాయకం.