---
title: "ટૂલ ઇન્ટિગ્રેશન (API) બનાવો"
description: "તમારા એજન્ટને વાતચીત દરમિયાન તમારા 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 સર્વર્સ ઉમેરે છે. જુઓ
  [કનેક્શન્સ](/gu/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` મળે છે, જે તેને કૉલર સાથે જોડણીની પુષ્ટિ કરવા અને શાબ્દિક સરનામું ફરી મોકલવા કહે છે.

છોડી દેવાયેલ વૈકલ્પિક ઈમેઇલને અસ્પૃશ્ય રાખવામાં આવે છે. પ્રોપર્ટી વૈકલ્પિક અથવા 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"}
```

તમારું સર્વર JSON સાથે પ્રતિસાદ આપે છે, જે LLM ને પાછો આપવામાં આવે છે:

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

LLM તે પ્રતિસાદને ગ્રહણ કરે છે અને કૉલરને માનવીય સારાંશ કહી સંભળાવે છે.

<Warning>
  સહી તમારા વેબહૂક એન્ડપૉઇન્ટના સમાન `secret` નો ઉપયોગ કરીને કાચા
  વિનંતી બૉડી પર ગણવામાં આવે છે. **તે ચકાસો** — ટૂલ એન્ડપૉઇન્ટ
  ઇન્ટરનેટ-સામે હોય છે અને વેબહૂક જેવી જ સ્પૂફિંગ સંબંધિત ચિંતાઓને
  આધીન હોય છે. જુઓ
  [વેબહૂક સહી ચકાસો](/gu/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="Function Tools સ્પેક" icon="screwdriver-wrench" href="/gu/tools/overview">
    સંપૂર્ણ JSON સ્કીમા વ્યાકરણ અને સહી કરેલ એન્ડપોઇન્ટ કરાર.
  </Card>
  <Card title="સિગ્નેચર ચકાસો" icon="shield-check" href="/gu/guides/verify-webhook-signatures">
    ટૂલ એન્ડપોઇન્ટ્સ પર વેબહૂક-સિગ્નેચર પેટર્ન લાગુ કરો.
  </Card>
  <Card title="ટ્રાન્સક્રિપ્ટ + ઇતિહાસ API" icon="phone" href="/api-reference/calls">
    ટૂલ કૉલની સંપૂર્ણ રાઉન્ડ-ટ્રિપ તપાસો.
  </Card>
</CardGroup>