ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Function Tools

Алатке функција

Омогућите својим AI агентима алатке функција које позивају спољне API-је усред разговора — преузимају податке о клијентима, заказују термине, ажурирају евиденцију — са типизираним параметрима.

Алатке функција омогућавају Вашим AI агентима да позивају спољне API-је током телефонских позива. Користите их за проналажење података о клијентима, проверу доступности, заказивање термина или извршавање било које радње коју подржава Ваш позадински систем.

Како функционише

  1. Дефинишете алатке помоћу шеме (које аргументе алатка прихвата)
  2. Наводите конфигурацију endpoint (где ThunderPhone позива Ваш API) — или је изостављате да бисте примали позиве алатки на webhook-у Ваше организације
  3. Током позива, AI одлучује када да користи алатку на основу разговора
  4. ThunderPhone позива Ваш endpoint са аргументима алатке
  5. Одговор Вашег API-ја се враћа AI-ју ради наставка разговора
МогућностГде се извршаваПодешавање
Уграђене алаткеThunderPhoneУпутства у prompt-у; неке алатке захтевају и подешавање агента
Повезивања са апликацијамаThunderPhone и повезани добављачПовежите налог и приложите одобрене радње
API повезивања и алатке функцијаВаш HTTP APIДефинишите endpoint и шему или примајте позиве функција преко webhook-а
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, или 600 са wait_mode: "hold")
wait_modeнискаНеШта позивалац чује док се алат извршава: updates (подразумевано), кратка говорна обавештења; или hold, музика на чекању. Погледајте Дуга чекања: режим чекања и каснији одговор
call_startобјекатНеАутоматски покрените алат и на почетку сваког телефонског позива, пре поздрава. Погледајте Покретање алата на почетку позива

Дефиниција функције

ПољеТипОбавезноОпис
nameнискаДаИдентификатор алата, јединствен међу алатима једног позива. Различити агенти могу имати сопствени алат са истим именом
descriptionнискаДаОбјашњава AI-ју када да користи овај алат
parametersобјекатДаJSON шема за аргументе алата

Конфигурација endpoint-а

ПољеТипОбавезноОпис
urlнискаДаURL endpoint-а Вашег API-ја
methodнискаНеHTTP метода (подразумевано: POST)
headersобјекатНеПрилагођена заглавља која треба укључити

Два пута позивања

Који захтев ће Ваш сервер примити зависи од тога да ли алатка има endpoint:

Алатка са endpointАлатка без endpoint
Куда се захтев шаљеДиректно на endpoint.urlНаслеђени Webhook 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
Кључ за потписивањеТајна за Webhook организацијеТајна за Webhook организације

Оба пута су блокирајућа — AI чека резултат усред реченице. Подразумевано временско ограничење је 20 s; подесите timeout на највишем нивоу алатке да бисте омогућили дуже извршавање, до максималних 180 s на платформи. Нека обрађивачи буду брзи. За чекање особе или спорог посла користите режим чекања. Комбинација је у реду: при позиву чија организација има 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 — ИД тренутног позива
  • X-ThunderPhone-From-Number и X-ThunderPhone-To-Number — бројеви пошиљаоца и примаоца позива у формату E.164. Имају исто значење као from_number и to_number у telephony.complete: код одлазног позива, број пошиљаоца је број вашег агента, а број примаоца је број позване особе. Број се изоставља када је идентификација позиваоца скривена или није телефонски број
  • X-ThunderPhone-Call-Direction — inbound или outbound, тако да можете одредити који је број корисников

Заглавља са бројевима позива шаљу се само за телефонске позиве. Тестови на вебу, у виџету, у реалном времену и у прегледачу Talk немају телефонски број и изостављају их. Пробни позиви из уређивача агента и AI симулације садрже број симулираног позиваоца. Потписи не обухватају заглавља: V2 потписује временску ознаку, метод, путању, упит и тело. Ако вам је потребно да бројеви буду потписани, уместо тога их прочитајте из тела: формат захтева retell садржи сва три, а vapi садржи број корисника.

Content-Type: application/json је постављен осим ако га Ваш endpoint.headers не замени — прилагођени Content-Type има предност.

Формат захтева

Свака API веза има подешавање request_format. Изаберите vapi или retell када увезени алат треба да настави да позива крајњу тачку направљену за ту платформу. Нове и постојеће везе подразумевано користе standard.

За POST / PUT / PATCH, ThunderPhone серијализује изабрани омотач канонски (сортирани кључеви, компактни раздвајачи). Оба потписа обухватају управо ове бајтове.

Standard

standard шаље само аргументе алата, без омотача. Ово је подразумевано понашање и чува оригинално тело захтева ThunderPhone-а бајт по бајт:

{"date":"2025-01-02","service":"consultation"}

Vapi

vapi шаље Vapi tool-calls серверску поруку у облику који Vapi документује. call.id је ID ThunderPhone позива. У телефонским позивима, call.customer.number је број друге стране, као у Vapi објекту позива: позивалац код долазног позива, а особа која се позива код одлазног позива. Изоставља се када је тај број сакривен или није телефонски број. id позива алатке је јединствен за позивање и поново се користи за повезивање са резултатом крајње тачке. Позив се појављује и у toolCallList и у toolWithToolCallList, при чему је function.arguments JSON објекат:

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

Поља која су само за Vapi, као што су assistant, artifact и цео објекат call, не шаљу се.

Вратите Vapi-јев омотач одговора са одговарајућим ID-јем позива алата:

{
  "results": [
    {
      "toolCallId": "call_00112233445566778899aabbccddeeff",
      "result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
    }
  ]
}

ThunderPhone прослеђује AI-ју распаковани ниску result. Прихвата и JSON вредност ради компатибилности са крајњим тачкама које је већ враћају. Ако је error враћен уместо result, 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 садржи call_id, from_number, to_number и direction (inbound или outbound), називе поља које користи Retell-ов објекат телефонског позива. Они одговарају заглављима броја позива и, за разлику од заглавља, обухваћени су обема потписима. Број који је сакривен или није телефонски број се изоставља. У веб, виџет, реалновременским и Talk тестовима у прегледачу садржи само call_id. ThunderPhone не укључује поља специфична за Retell која не може поуздано да достави при слању, као што су agent_id, transcript, transcript_object, metadata или динамичке променљиве. Retell прихвата било које тело одговора; ThunderPhone га прослеђује коришћењем стандардне обраде одговора.

За GET / DELETE, аргументи се шаљу као параметри упита а тело је празно без обзира на request_format. V2 потпис обухвата ниску упита онако како је послата; застарели потпис се израчунава над празном ниском бајтова. Погледајте Верификација потписа webhook-а.

Одговор

Вратите 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 садржи origin_domain уместо from_number / to_number. Одговорите резултатом алата у JSON формату — према истом уговору о одговору као код директних позива крајње тачке. Захтев је потписан тајном webhook вредношћу организације, са оба заглавља потписа, као и сваки други webhook.


Дуга чекања: режим чекања и накнадни одговор

Неки алати чекају на особу: менаџера који одобрава попуст, власника који одговара на питање у Slack-у. За те алате подесите wait_mode на "hold".

wait_mode: "updates" (подразумевано)wait_mode: "hold"
Шта позивалац чујеРед при покретању алата, затим кратак ред „и даље радим“ након око 12 с и још један отприлике сваких 15 сРед при покретању алата, затим музика на чекању док не стигне резултат
Максимално timeout180 с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 помоћне функције проверавају V2 заглавље, укључујући период од 5 минута:

Python
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}
Node.js
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 секунде од тог тренутка. Спорији резултат се прослеђује агенту чим стигне, за остатак позива. Код одлазног позива покреће се када се позив упути, па се извршава при сваком покушају, укључујући и оне на које нико не одговори.
  • Код агента код којег позивалац први говори нема поздрава који треба чекати; агент добија резултат чим стигне.
  • Резултат се даје агенту као контекст за цео позив. У упиту реците агенту како да га користи; у супротном се не чита наглас.
  • Ако алат не успе или прекорачи временско ограничење, агент поздравља позиваоца као и обично и не говори ништа о томе.
  • Агент и даље може сам да позове алат касније током позива.
  • Покреће се за телефонске позиве, укључујући пробне позиве са контролне табле на ваш телефон, и за AI симулације, које шаљу број симулираног позиваоца вашој крајњој тачки. Не покреће се у тестовима Разговор у прегледачу нити у сесијама веб виџета, које немају број позиваоца, код позива код којих је идентификација позиваоца сакривена или код агената са корацима.
  • Агент покреће највише три алата на почетку позива, све истовремено.

Помените резултат у свом упиту како би агент знао како да га користи, на пример: „Ако је претрага на почетку позива пронашла позиваоца, поздравите га именом.“


Најбоље праксе

Пишите јасне описе

Поље description помаже вештачкој интелигенцији да разуме када да користи алат. Наведите прецизно шта алат ради и када је прикладно да се користи.

Елегантно обрађујте грешке

Вратите поруке о грешци које вештачка интелигенција може да разуме: {"error": "No slots available for that date"} уместо генеричких грешака 500.

Нека одговори буду сажети

Вратите само оно што је AI потребно да настави разговор. Резултат алата остаје у разговору и поново се чита при сваком наредном потезу, па велики резултат повећава трошкове и кашњење до краја позива. Резултати дужи од 100.000 знакова скраћују се на преглед за који AI зна да је непотпун, а током веома дугог позива старији резултати могу бити одбачени (AI може поново да позове алат). Додајте параметар како би AI могао да потражи једну ставку или категорију одједном, а велики референтни садржај, као што су менији или каталози, ставите у базу знања. Пошаљите тест захтев на контролној табли приказује величину сваког резултата и упозорава када је велики.

Промишљено користите обавезна поља

Означите поља као required само када је то заиста неопходно. Вештачка интелигенција ће тражити од корисника обавезне информације пре позивања алата.


Повезано