---
title: "టూల్ ఇంటిగ్రేషన్‌ను రూపొందించండి (API)"
description: "సంభాషణ మధ్యలో మీ ఏజెంట్ మీ APIలను కాల్ చేయనివ్వండి — డేటాబేస్‌ను శోధించండి, టికెట్‌ను సృష్టించండి, ఆర్డర్‌ను చూడండి."
---

**టూల్ ఇంటిగ్రేషన్** అనేది ఏజెంట్ కాల్ సమయంలో
ఇన్వోక్ చేయగల పునర్వినియోగ HTTP ఎండ్‌పాయింట్. మీరు ThunderPhoneకు టూల్ యొక్క JSON-స్కీమా వివరణతో పాటు
ఎండ్‌పాయింట్ URL ఇస్తారు; సంభాషణ ఆధారంగా దాన్ని ఎప్పుడు కాల్ చేయాలో ఏజెంట్ నిర్ణయిస్తుంది, మరియు ThunderPhone తన సర్వర్‌ల నుంచి అవుట్‌బౌండ్ HTTP
రిక్వెస్ట్ చేసి స్పందనను ఏజెంట్‌కు తిరిగి అందిస్తుంది.

<Note>
  ఈ API లేకుండానే డ్యాష్‌బోర్డ్ చాలా టూల్ అవసరాలను కవర్ చేస్తుంది: **కనెక్షన్లు
  → యాప్‌లు** కొన్ని OAuth క్లిక్‌లలో Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets, మరియు Cal.comలను కనెక్ట్ చేస్తుంది; **కనెక్షన్లు →
  APIలు** ఏదైనా HTTP APIని ఏజెంట్ చర్యగా మారుస్తుంది (ఒక cURL కమాండ్‌ను పేస్ట్ చేస్తే
  AI విజార్డ్ టూల్‌ను డ్రాఫ్ట్ చేస్తుంది, ఇందులో అంతర్నిర్మిత టెస్ట్ రిక్వెస్ట్ ఉంటుంది); మరియు
  **కనెక్షన్లు → MCP** MCP సర్వర్‌లను జోడిస్తుంది. చూడండి
  [కనెక్షన్లు](/te/guides/concepts). ఈ గైడ్ APIల ఉపరితలం కింద ఉన్న
  ప్రాథమిక API గురించి వివరిస్తుంది.
</Note>

ఈ గైడ్ వాతావరణాన్ని చూసే టూల్‌ను ప్రారంభం నుంచి ముగింపు వరకు రూపొందించడం గురించి వివరిస్తుంది.

## టూల్ నిర్మాణం

రెండు భాగాలు:

1. **స్కీమా** — OpenAI-శైలి ఫంక్షన్ నిర్వచనం
   (`{type: "function", function: {name, description, parameters}}`)
   ఇది టూల్ ఏమి చేస్తుందో, ఏ ఆర్గ్యుమెంట్‌లను తీసుకుంటుందో LLMకు తెలియజేస్తుంది.
2. **ఎండ్‌పాయింట్** — టూల్‌ను ఉపయోగించాలని LLM నిర్ణయించినప్పుడు ThunderPhone సర్వర్‌లు కాల్ చేసే
   URL. రిక్వెస్ట్ JSON POST రూపంలో ఉంటుంది; బాడీలో LLM ఎంచుకున్న ఆర్గ్యుమెంట్‌లు ఉంటాయి.

## 1. ఎడిటర్‌ను ఎంచుకోండి

<CardGroup cols={2}>
  <Card title="డ్యాష్‌బోర్డ్" icon="window-maximize">
    **కనెక్షన్లు → APIలు** తెరిచి, API కనెక్షన్‌ను సృష్టించండి లేదా సవరించండి,
    పారామీటర్ ఎడిటర్‌ను **JSON**కు మార్చి, అక్కడ ఫార్మాట్‌ను జోడించండి.
  </Card>
  <Card title="ఇంటిగ్రేషన్స్ API" icon="plug">
    `POST /v1/integrations`తో స్పెక్‌ను సృష్టించండి లేదా
    `PATCH /v1/integrations/{id}`తో దాన్ని అప్‌డేట్ చేయండి.
  </Card>
</CardGroup>

రెండు మార్గాలూ సేవ్ చేసిన ఇంటిగ్రేషన్‌ను సృష్టిస్తాయి. సేవ్ చేసిన తర్వాత ఆ ఇంటిగ్రేషన్‌ను
ఏజెంట్‌కు జతచేయండి. ఏజెంట్స్ APIలో వ్రాయగల ఇన్‌లైన్ `tools`
ఫీల్డ్ లేదు. ఈ గైడ్ ఇంటిగ్రేషన్స్ API మార్గాన్ని ఉపయోగిస్తుంది.

## 2. ఇంటిగ్రేషన్‌ను సృష్టించండి

```bash
curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'
```

తిరిగి వచ్చిన `id`ను (ఒక UUID) సేవ్ చేయండి.

<Tip>
  టూల్ యొక్క `description`కు మరియు ప్రతి పరామీటర్ యొక్క వివరణకు తగిన శ్రద్ధ వహించండి. టూల్‌ను ఎప్పుడు, ఎలా కాల్ చేయాలో నిర్ణయించడానికి LLM రన్‌టైమ్‌లో ఈ స్ట్రింగ్‌లను ఉపయోగిస్తుంది. అస్పష్టమైన వివరణలు → అస్పష్టమైన టూల్ కాల్‌లు.
</Tip>

### చిరునామా పరామీటర్‌లపై `format: "email"`ను ప్రకటించండి

ఇమెయిల్ చిరునామాను స్వీకరించే పరామీటర్ దాని స్కీమాలో అలా పేర్కొనాలి:

```json
"email": { "type": "string", "format": "email", "description": "The caller's email address" }
```

`format` కేవలం సూచన కంటే ఎక్కువ. పరిష్కరించబడిన ఇమెయిల్ స్కీమా కోసం, మీ ఎండ్‌పాయింట్‌ను కాల్ చేయడానికి ముందు ThunderPhone విలువలోని అదనపు ఖాళీలను తొలగిస్తుంది, డొమైన్‌ను లోయర్‌కేస్‌గా మారుస్తుంది, స్వతంత్ర ఆంగ్ల పదాలైన `at`, `dot`, `underscore`, `dash`, మరియు `hyphen`లను వాటి అక్షరాలుగా మారుస్తుంది, అలాగే `@`, `.`, `_`, మరియు `-` చుట్టూ నేరుగా ఉన్న ఖాళీలను తొలగిస్తుంది. ట్రాన్స్‌క్రిప్ట్‌లో ఇప్పటికే అక్షరాలా `@` ఉన్నా లేకపోయినా ఈ పదాలకు ఒకే అర్థం ఉంటుంది:
`"john dot smith at gmail dot com"` ఇలా మారుతుంది
`john.smith@gmail.com`.

ఇతర అంతర్గత ఖాళీలను నిశ్శబ్దంగా కలపకుండా తిరస్కరిస్తుంది. పలికే విభజన పదాలు ఆంగ్లానికి మాత్రమే వర్తిస్తాయి; ఆంగ్లేతర లేదా గుర్తించబడని ఖాళీలతో ఉన్న రూపాలు సురక్షితంగా విఫలమవుతాయి. చెల్లుబాటు అయ్యే అంతర్జాతీయీకరించిన డొమైన్‌లు మరియు SMTPUTF8 లోకల్ పార్ట్‌లు ఆమోదించబడతాయి. పార్సర్ సాధారణీకరణ తర్వాత Punycode ఇన్‌పుట్ Punycodeగానే, Unicode డొమైన్ ఇన్‌పుట్ Unicodeగానే ఉంటుంది; కాబట్టి మీ APIకి కాలర్ అందించిన సాంప్రదాయిక రూపమే అందుతుంది. తుది విలువ చెల్లనిది అయితే, టూల్‌ను **కాల్ చేయరు**. స్పెల్లింగ్‌ను కాలర్‌తో నిర్ధారించి అక్షరాలా ఉన్న చిరునామాను మళ్లీ పంపమని ఏజెంట్‌కు తెలిపే `invalid_email_argument` అందుతుంది.

వదిలివేయబడిన ఐచ్ఛిక ఇమెయిల్‌లో ఎలాంటి మార్పు ఉండదు. ప్రాపర్టీ ఐచ్ఛికం లేదా nullable అయినప్పుడు `null`, ఖాళీ స్ట్రింగ్ లేదా ఖాళీలతో మాత్రమే ఉన్న స్ట్రింగ్ కూడా మార్పు లేకుండానే ఉంటుంది; అవసరమైన, non-nullable ఇమెయిల్‌కు అదే విలువలు తిరస్కరించబడతాయి.

`#/$defs/email`, `#/definitions/email` వంటి స్థానిక స్కీమా రిఫరెన్స్‌లతో పాటు `anyOf`, `oneOf`, మరియు `allOf`లను సైకిల్ మరియు డెప్త్ పరిమితులతో పరిశీలిస్తారు. స్థానికం కాని లేదా పరిష్కరించలేని `$ref` తెలిసిన అమలు పరిమితి; ఉపయోగించదగిన స్కీమా లేని టూల్ స్నాప్‌షాట్‌తో చేసే కాల్‌ల మాదిరిగానే దానిని మార్పులేకుండా పంపుతారు. ఈ గేట్ వర్తించాల్సి ఉన్నప్పుడు ఇమెయిల్ స్కీమాలను స్థానికంగానే ఉంచండి.

అమలు చేయబడిన ఇమెయిల్ ఫార్మాట్ లేని పరామీటర్‌లను మోడల్ రూపొందించిన విధంగానే మార్పులేకుండా పంపుతారు.

మద్దతు ఉన్న ఫార్మాట్‌లు `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, మరియు `uuid`; ప్రస్తుతం `email` మాత్రమే సాధారణీకరించబడి అమలు చేయబడుతుంది.

## 3. ఎండ్‌పాయింట్‌ను సాండ్‌బాక్స్‌లో పరీక్షించండి

ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు లింక్ చేసే ముందు, కనెక్టివిటీని నిర్ధారించడానికి ThunderPhone సర్వర్‌ల నుండి సంతకం చేసిన రిక్వెస్ట్‌ను పంపండి:

```bash
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'
```

```json Response
{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}
```

ఈ పరీక్ష ThunderPhone యొక్క SSRF రక్షణలను కూడా బలోపేతం చేస్తుంది — localhost లేదా ప్రైవేట్ IP పరిధులకు చేసే రిక్వెస్ట్‌లు `400 code=url_not_allowed`ను అందిస్తాయి.

## 4. ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు లింక్ చేయండి

ఏజెంట్‌ను సృష్టించినప్పుడు లేదా అప్‌డేట్ చేసినప్పుడు `integration_ids` ద్వారా జతచేయండి:

```bash
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'
```

మీరు ఒక ఏజెంట్‌కు అనేక ఇంటిగ్రేషన్‌లను లింక్ చేయవచ్చు. ఏజెంట్ prompt
వాటిని పేరు ద్వారా సూచించవచ్చు — కాలర్ పరిస్థితుల గురించి అడిగినప్పుడు
`get_weather` ఉపయోగించండి — లేదా స్కీమా వివరణల నుంచి వాటిని
సూచ్యంగా గుర్తించవచ్చు.

## 5. ఎండ్‌పాయింట్‌ను అమలు చేయండి

ఏజెంట్ టూల్‌ను ఇన్‌వోక్ చేసినప్పుడు, ThunderPhone మీ
`endpoint_url`కు సంతకం చేసిన POST‌ను పంపుతుంది:

```
POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}
```

మీ సర్వర్ LLMకు తిరిగి అందించబడే JSONతో ప్రతిస్పందిస్తుంది:

```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```

LLM ఆ ప్రతిస్పందనను స్వీకరించి, కాలర్‌కు మానవీయ సారాంశాన్ని చెబుతుంది.

<Warning>
  మీ webhook ఎండ్‌పాయింట్‌కు ఉపయోగించిన అదే `secret`తో ముడి రిక్వెస్ట్
  బాడీపై సంతకాన్ని గణిస్తారు. **దాన్ని ధృవీకరించండి** — టూల్ ఎండ్‌పాయింట్‌లు
  ఇంటర్నెట్‌కు బహిరంగంగా ఉంటాయి మరియు webhookల మాదిరిగానే స్పూఫింగ్
  సమస్యలకు లోబడతాయి. చూడండి
  [webhook సంతకాలను ధృవీకరించండి](/te/guides/verify-webhook-signatures).
</Warning>

## 6. లూప్‌ను పరీక్షించండి

ఏజెంట్‌పై ఒక [మైక్ సెషన్](/api-reference/mic-sessions)ను నడిపి,
మీ టూల్ నిర్వహించే ప్రశ్నను అడగండి ("94110లో వాతావరణం ఎలా ఉంది?").
కాల్ ట్రాన్స్‌క్రిప్ట్ పూర్తి రౌండ్ ట్రిప్‌ను చూపిస్తుంది:

```json
{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}
```

మీరు దీన్ని
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript) ద్వారా పొందవచ్చు;
ప్రతి ఎంట్రీ సమయం మరియు ఆడియో ఆఫ్‌సెట్‌లతో కూడిన ముడి ఈవెంట్ స్ట్రీమ్
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history)లో ఉంటుంది.

## సాధారణ సమస్యలు

<AccordionGroup>
  <Accordion title="ఏజెంట్ టూల్‌ను ఎప్పుడూ కాల్ చేయదు">
    LLM టూల్ వివరణ ఆధారంగా నిర్ణయిస్తుంది. కాలర్ ప్రశ్న వివరణతో
    సరిపోలకపోతే, మోడల్ టూల్‌ను ఇన్‌వోక్ చేయదు. వివరణను మరింత స్పష్టంగా
    చేయండి (సాధారణ పర్యాయపదాలు మరియు పదబంధాలను జోడించండి) లేదా ఏజెంట్
    promptలో స్పష్టంగా పేర్కొనండి (కాలర్ వాతావరణం గురించి అడిగినప్పుడు,
    `get_weather` ఉపయోగించండి.).
  </Accordion>

  <Accordion title="టూల్ చాలా ఎక్కువ డేటాను తిరిగి ఇస్తుంది">
    6 kB కంటే పెద్ద ప్రతిస్పందనలు ట్రాన్స్‌క్రిప్ట్ ప్రివ్యూలో కత్తిరించబడతాయి.
    LLMకు అవసరమైన ఫీల్డ్‌లను మాత్రమే తిరిగి ఇవ్వండి — మీ పూర్తి వరుసను కాదు.
  </Accordion>

  <Accordion title="టైమ్‌అవుట్‌లు">
    టూల్ ఎండ్‌పాయింట్‌లకు డిఫాల్ట్‌గా 10-సెకన్ల టైమ్‌అవుట్ ఉంటుంది. మీకు
    ఎక్కువ సమయం అవసరమైతే, దాన్ని అసింక్రోనస్‌గా నిర్వహించండి: `{"status": "pending", "request_id": "..."}`
    తిరిగి ఇచ్చి, వేరే టూల్ కాల్ ద్వారా ఫలితాన్ని అందించండి.
  </Accordion>

  <Accordion title="వెర్షనింగ్">
    ప్రతి ఇంటిగ్రేషన్ `PATCH` కొత్త రివిజన్‌ను సృష్టిస్తుంది.
    ఎవరు ఏమి మార్చారో చూడటానికి
    [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)ను పరిశీలించండి.
    మీరు టూల్ స్కీమాను దెబ్బతీస్తే, పాత స్నాప్‌షాట్‌ను తిరిగి PATCH చేయడం ద్వారా
    మాన్యువల్‌గా రోల్‌బ్యాక్ చేయవచ్చు.
  </Accordion>
</AccordionGroup>

---

## తదుపరి దశలు

<CardGroup cols={2}>
  <Card title="ఇంటిగ్రేషన్ల సూచిక" icon="plug" href="/api-reference/integrations">
    CRUD, బదిలీ, వెర్షన్ చరిత్ర.
  </Card>
  <Card title="ఫంక్షన్ టూల్స్ స్పెసిఫికేషన్" icon="screwdriver-wrench" href="/te/tools/overview">
    పూర్తి JSON స్కీమా వ్యాకరణం మరియు సంతకం చేసిన ఎండ్‌పాయింట్ ఒప్పందం.
  </Card>
  <Card title="సంతకాలను ధృవీకరించండి" icon="shield-check" href="/te/guides/verify-webhook-signatures">
    టూల్ ఎండ్‌పాయింట్‌లకు webhook-సంతకం నమూనాను వర్తింపజేయండి.
  </Card>
  <Card title="ట్రాన్స్క్రిప్ట్ + చరిత్ర API" icon="phone" href="/api-reference/calls">
    టూల్ కాల్ యొక్క పూర్తి రౌండ్-ట్రిప్‌ను పరిశీలించండి.
  </Card>
</CardGroup>