> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# टूल इंटीग्रेशन (API) बनाएं

> अपने एजेंट को बातचीत के दौरान आपके APIs कॉल करने दें — डेटाबेस खोजें, टिकट बनाएं, ऑर्डर देखें।

एक **टूल इंटीग्रेशन** एक पुन: उपयोग योग्य HTTP एंडपॉइंट है जिसे एजेंट
कॉल के दौरान इनवोक कर सकता है। आप ThunderPhone को टूल का JSON-स्कीमा विवरण
और एक एंडपॉइंट URL देते हैं; एजेंट बातचीत के आधार पर तय करता है कि इसे कब कॉल करना है,
और ThunderPhone अपने सर्वर से आउटबाउंड HTTP रिक्वेस्ट करता है और रिस्पॉन्स एजेंट को लौटाता है।

<Note>
  इस API के बिना भी डैशबोर्ड अधिकांश टूल आवश्यकताओं को कवर करता है: **कनेक्शंस
  → ऐप्स** कुछ OAuth क्लिक्स में Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets, और Cal.com को कनेक्ट करता है; **कनेक्शंस →
  APIs** किसी भी HTTP API को एजेंट एक्शन में बदलता है (एक cURL कमांड पेस्ट करें
  और एक AI विज़ार्ड टूल का ड्राफ्ट तैयार करता है, जिसमें बिल्ट-इन टेस्ट रिक्वेस्ट होता है); और
  **कनेक्शंस → MCP** MCP सर्वर जोड़ता है। देखें
  [कनेक्शंस](/hi/guides/concepts)। यह गाइड APIs इंटरफ़ेस के नीचे मौजूद
  रॉ API के बारे में है।
</Note>

यह गाइड एक वेदर-लुकअप टूल को शुरू से अंत तक बनाने की प्रक्रिया बताती है।

## टूल की संरचना

दो हिस्से:

1. **स्कीमा** — एक OpenAI-स्टाइल फ़ंक्शन डेफिनिशन
   (`{type: "function", function: {name, description, parameters}}`)
   जो LLM को बताती है कि टूल क्या करता है और वह कौन से आर्ग्युमेंट लेता है।
2. **एंडपॉइंट** — वह URL जिसे ThunderPhone के सर्वर तब कॉल करते हैं जब
   LLM टूल का उपयोग करने का निर्णय लेता है। रिक्वेस्ट JSON POST होती है, जिसमें
   LLM द्वारा चुने गए आर्ग्युमेंट बॉडी के रूप में होते हैं।

## 1. स्टोरेज स्ट्रैटेजी चुनें

<CardGroup cols={2}>
  <Card title="एजेंट पर इनलाइन" icon="paperclip">
    एजेंट के `tools` ऐरे में एक वन-ऑफ टूल अटैच करें। सरल है, लेकिन
    पुन: उपयोग योग्य नहीं है।
  </Card>

  <Card title="सेव्ड इंटीग्रेशन" icon="plug">
    टूल को पुन: उपयोग योग्य [इंटीग्रेशन](/api-reference/integrations) के रूप में स्टोर करें
    और इसे कई एजेंटों से लिंक करें। किसी भी ऐसी चीज़ के लिए अनुशंसित है जिसका उपयोग
    एक से अधिक बार होता है।
  </Card>
</CardGroup>

यह गाइड सेव्ड-इंटीग्रेशन पाथ का उपयोग करती है।

## 2. इंटीग्रेशन बनाएं

```bash theme={null}
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>

## 3. एंडपॉइंट का सैंडबॉक्स-टेस्ट करें

इंटीग्रेशन को किसी एजेंट से लिंक करने से पहले, कनेक्टिविटी की पुष्टि के लिए
ThunderPhone के सर्वर से एक साइन किया हुआ रिक्वेस्ट भेजें:

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
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-..."]
  }'
```

आप एक एजेंट से कई इंटीग्रेशन लिंक कर सकते हैं। एजेंट का प्रॉम्प्ट
उन्हें नाम से रेफर कर सकता है — "जब कॉलर परिस्थितियों के बारे में पूछे
तो `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"}
```

आपका सर्वर JSON के साथ प्रतिक्रिया देता है, जो LLM को वापस भेज दिया जाता है:

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

LLM उस प्रतिक्रिया को इनजेस्ट करता है और कॉलर को एक मानवीय सारांश बोलता है।

<Warning>
  सिग्नेचर को आपके webhook एंडपॉइंट के समान `secret` का उपयोग करके रॉ
  रिक्वेस्ट बॉडी पर कंप्यूट किया जाता है। **इसे वेरिफ़ाई करें** — टूल एंडपॉइंट
  इंटरनेट-फेसिंग होते हैं और webhooks जैसी ही स्पूफिंग संबंधी चिंताओं के अधीन होते हैं।
  [Webhook सिग्नेचर वेरिफ़ाई करें](/hi/guides/verify-webhook-signatures) देखें।
</Warning>

## 6. लूप टेस्ट करें

एजेंट के विरुद्ध एक [mic session](/api-reference/mic-sessions) चलाएँ
और वह प्रश्न पूछें जिसे आपका टूल हैंडल करता है ("94110 में मौसम
कैसा है?")। कॉल का ट्रांसक्रिप्ट पूरा राउंड ट्रिप दिखाता है:

```json theme={null}
{
  "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 टूल के विवरण के आधार पर निर्णय लेता है। अगर कॉलर का
    प्रश्न विवरण से मेल नहीं खाता, तो मॉडल टूल को इनवोक नहीं करेगा।
    विवरण को अधिक सटीक बनाएँ (सामान्य समानार्थी शब्द और वाक्यांश जोड़ें)
    या एजेंट प्रॉम्प्ट में इसका स्पष्ट उल्लेख करें ("जब
    कॉलर मौसम के बारे में पूछे, तो `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="Function Tools स्पेसिफिकेशन" icon="screwdriver-wrench" href="/hi/tools/overview">
    पूरा JSON स्कीमा ग्रामर और साइन किए गए एंडपॉइंट कॉन्ट्रैक्ट।
  </Card>

  <Card title="सिग्नेचर सत्यापित करें" icon="shield-check" href="/hi/guides/verify-webhook-signatures">
    टूल एंडपॉइंट पर वेबहुक-सिग्नेचर पैटर्न लागू करें।
  </Card>

  <Card title="ट्रांसक्रिप्ट + हिस्ट्री API" icon="phone" href="/api-reference/calls">
    टूल कॉल के पूरे राउंड-ट्रिप की जांच करें।
  </Card>
</CardGroup>