---
title: "टूल इंटिग्रेशन तयार करा (API)"
description: "तुमच्या एजंटला संभाषणादरम्यान तुमचे API कॉल करू द्या — डेटाबेस शोधा, तिकीट तयार करा, ऑर्डर शोधा."
---

**टूल इंटिग्रेशन** हा पुनर्वापरता येणारा HTTP एंडपॉइंट आहे, जो एजंट
कॉलदरम्यान invoke करू शकतो. तुम्ही ThunderPhone ला टूलचे JSON-स्कीमा वर्णन
आणि एंडपॉइंट URL देता; संभाषणाच्या आधारे एजंट ते कधी कॉल करायचे हे ठरवतो,
आणि ThunderPhone त्याच्या सर्व्हरवरून आउटबाउंड HTTP विनंती करून प्रतिसाद
एजंटकडे परत पाठवते.

<Note>
  या API शिवायही डॅशबोर्ड बहुतेक टूल गरजा पूर्ण करतो: **कनेक्शन्स
  → अॅप्स** द्वारे Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets आणि Cal.com काही OAuth क्लिकमध्ये जोडता येतात; **कनेक्शन्स →
  APIs** द्वारे कोणत्याही HTTP API ला एजंट कृतीमध्ये रूपांतरित करता येते (cURL कमांड
  पेस्ट करा आणि AI विझार्ड टूलचा मसुदा तयार करतो, अंगभूत चाचणी विनंतीसह); आणि
  **कनेक्शन्स → MCP** द्वारे MCP सर्व्हर जोडता येतात. पहा
  [कनेक्शन्स](/mr/guides/concepts). हे मार्गदर्शक APIs
  इंटरफेसच्या मागील मूलभूत 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">
    **कनेक्शन्स → APIs** उघडा, API कनेक्शन तयार करा किंवा संपादित करा,
    पॅरामीटर एडिटर **JSON** वर बदला आणि तेथे फॉरमॅट जोडा.
  </Card>
  <Card title="इंटिग्रेशन्स API" icon="plug">
    `POST /v1/integrations` वापरून स्पेसिफिकेशन तयार करा किंवा
    `PATCH /v1/integrations/{id}` वापरून ते अद्यतनित करा.
  </Card>
</CardGroup>

दोन्ही मार्ग जतन केलेले इंटिग्रेशन तयार करतात. ते जतन केल्यानंतर हे इंटिग्रेशन
एजंटला जोडा. Agents 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` मिळते, जे त्याला
कॉलरकडून स्पेलिंगची पुष्टी करून प्रत्यक्ष पत्ता पुन्हा पाठवण्यास सांगते.

वगळलेला पर्यायी ईमेल जसा आहे तसाच राहतो. प्रॉपर्टी पर्यायी किंवा नलेबल असल्यास `null`, रिकामी स्ट्रिंग किंवा केवळ रिकामी जागा असलेली स्ट्रिंगही जशी आहे तशीच राहते; आवश्यक, नॉन-नलेबल ईमेलसाठी हीच मूल्ये नाकारली जातात.

`#/$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` वापरा" — किंवा schema वर्णनांवरून एजंट त्यांना
अप्रत्यक्षपणे शोधू शकतो.

## 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` वापरून, कच्च्या विनंतीच्या
  बॉडीवर स्वाक्षरी तयार केली जाते. **त्याची पडताळणी करा** — टूल एंडपॉइंट
  इंटरनेटसमोर खुले असतात आणि webhooks प्रमाणेच स्पूफिंगच्या धोक्यांना
  सामोरे जातात. पहा
  [Webhook स्वाक्षरींची पडताळणी करा](/mr/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)
    तपासा. तुम्ही टूलचा schema बिघडवल्यास, जुना स्नॅपशॉट परत PATCH करून
    तुम्ही तो मॅन्युअली रोल बॅक करू शकता.
  </Accordion>
</AccordionGroup>

---

## पुढील पायऱ्या

<CardGroup cols={2}>
  <Card title="इंटिग्रेशन्स संदर्भ" icon="plug" href="/api-reference/integrations">
    CRUD, ट्रान्सफर, आवृत्ती इतिहास.
  </Card>
  <Card title="फंक्शन टूल्स तपशील" icon="screwdriver-wrench" href="/mr/tools/overview">
    संपूर्ण JSON स्कीमा व्याकरण आणि स्वाक्षरीत एंडपॉइंट करार.
  </Card>
  <Card title="स्वाक्षऱ्या पडताळा" icon="shield-check" href="/mr/guides/verify-webhook-signatures">
    टूल एंडपॉइंट्सना वेबहुक-स्वाक्षरी पॅटर्न लागू करा.
  </Card>
  <Card title="ट्रान्सक्रिप्ट + इतिहास API" icon="phone" href="/api-reference/calls">
    टूल कॉलचा संपूर्ण राउंड-ट्रिप तपासा.
  </Card>
</CardGroup>