> ## 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.

# React कंपोनेंट

> ThunderPhone वॉइस विजेट को React एप्लिकेशन में एम्बेड करें

`ThunderPhoneWidget` कंपोनेंट म्यूट करने, कॉल समाप्त करने और कनेक्शन स्टेटस दिखाने के लिए बिल्ट-इन कंट्रोल्स के साथ एक ग्लासमॉर्फिक कॉल बार रेंडर करता है। React ऐप में वॉइस AI जोड़ने का यह सबसे तेज़ तरीका है।

## इंस्टॉलेशन

```bash theme={null}
npm install @thunderphone/widget
```

## बुनियादी उपयोग

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  विजेट को सही ढंग से रेंडर करने के लिए आपको CSS फ़ाइल **ज़रूर** इंपोर्ट करनी होगी। इसके बिना, विजेट बिना स्टाइल के होगा।
</Warning>

***

## प्रॉप्स

कंपोनेंट `ThunderPhoneWidgetProps` के माध्यम से निम्न प्रॉप्स स्वीकार करता है:

| प्रॉप            | टाइप                                                           | आवश्यक | डिफ़ॉल्ट                                 | विवरण                                                                                                                                                                                  |
| ---------------- | -------------------------------------------------------------- | ------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | हाँ    | --                                       | Developers सेटिंग्स से पब्लिशेबल API key (`pk_live_...`)। एजेंट को key के विजेट कॉन्फ़िगरेशन से स्वचालित रूप से रिज़ॉल्व किया जाता है।                                                 |
| `theme`          | `'light' \| 'dark'`                                            | नहीं   | `'light'`                                | कलर स्कीम। विजेट रूट पर `tp--light` या `tp--dark` क्लास लागू करता है।                                                                                                                  |
| `primaryColor`   | `string`                                                       | नहीं   | `'#000000'` (लाइट) / `'#ffffff'` (डार्क) | एक्सेंट रंग के रूप में उपयोग की जाने वाली CSS कलर स्ट्रिंग (कॉल बटन, वेवफॉर्म, सक्रिय इंडिकेटर)।                                                                                       |
| `title`          | `string`                                                       | नहीं   | `'Voice assistant'`                      | विजेट बार में दिखाया जाने वाला टेक्स्ट।                                                                                                                                                |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | नहीं   | `'bottom-right'`                         | विजेट के लिए फिक्स्ड व्यूपोर्ट पोज़िशन।                                                                                                                                                |
| `apiBase`        | `string`                                                       | नहीं   | `'https://api.thunderphone.com/v1'`      | API बेस URL ओवरराइड।                                                                                                                                                                   |
| `language`       | `string`                                                       | नहीं   | --                                       | प्रति-सेशन भाषा ओवरराइड -- भाषा कोड या लोकेल, जैसे `en`, `es`, या `fr-FR`। सेट न होने पर, एजेंट की कॉन्फ़िगर की गई भाषा लागू होती है।                                                  |
| `voice`          | `string`                                                       | नहीं   | --                                       | प्रति-सेशन वॉइस ओवरराइड -- वॉइस नाम, जैसे `maria`। सेट न होने पर, एजेंट की कॉन्फ़िगर की गई वॉइस लागू होती है।                                                                          |
| `context`        | `string`                                                       | नहीं   | --                                       | एजेंट को दिया जाने वाला प्रति-सेशन तथ्यात्मक पेज या साइट कॉन्टेक्स्ट (उदाहरण के लिए, विज़िटर जिस पेज को देख रहा है उसका विवरण)। सर्वर-साइड पर 12,000 कैरेक्टर तक ट्रंकेट किया जाता है। |
| `onConnect`      | `() => void`                                                   | नहीं   | --                                       | वॉइस सेशन के सफलतापूर्वक कनेक्ट होने पर कॉल किया जाता है।                                                                                                                              |
| `onDisconnect`   | `() => void`                                                   | नहीं   | --                                       | सेशन समाप्त होने पर कॉल किया जाता है।                                                                                                                                                  |
| `onError`        | `(error) => void`                                              | नहीं   | --                                       | एरर होने पर कॉल किया जाता है। `error` ऑब्जेक्ट में `error` (कोड) और `message` फ़ील्ड होते हैं।                                                                                         |
| `className`      | `string`                                                       | नहीं   | --                                       | विजेट कंटेनर पर लागू किया जाने वाला अतिरिक्त CSS क्लास नाम।                                                                                                                            |
| `ringtone`       | `boolean \| string`                                            | नहीं   | `false`                                  | कनेक्ट करते समय रिंगटोन चलाएँ। डिफ़ॉल्ट रिंगटोन के लिए `true`, या कस्टम ऑडियो के लिए URL स्ट्रिंग।                                                                                     |

***

## उदाहरण

### कस्टम रंग के साथ डार्क थीम

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}
```

### कस्टम पोज़िशन

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### प्रति-सेशन भाषा, वॉइस और कॉन्टेक्स्ट

कॉल शुरू होने पर `language`, `voice`, और `context` props को सेशन रिक्वेस्ट (`POST /widget/session`) में फॉरवर्ड किया जाता है, जिससे उस सेशन के लिए एजेंट के कॉन्फ़िगर किए गए डिफ़ॉल्ट ओवरराइड हो जाते हैं:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

विज़िटर जिस पेज पर है, उसके बारे में एजेंट को तथ्यात्मक नॉलेज देने के लिए `context` का उपयोग करें -- प्रोडक्ट विवरण, मूल्य निर्धारण या पेज-विशिष्ट FAQs। इसे सर्वर-साइड पर 12,000 कैरेक्टर तक ट्रंकेट किया जाता है।

### इवेंट कॉलबैक के साथ

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### कस्टम स्टाइलिंग के साथ

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

सभी उपलब्ध CSS क्लास और कस्टम प्रॉपर्टी के लिए [स्टाइलिंग गाइड](/hi/widget/styling) देखें।

### रिंगटोन के साथ

कनेक्शन स्थापित होने के दौरान फ़ोन की घंटी बजने की आवाज़ चलाएं:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

ऑडियो फ़ाइल URL पास करके कस्टम रिंगटोन का उपयोग करें:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

विजेट `connecting` स्टेट में होने पर रिंगटोन लूप होती है और एजेंट के कनेक्ट होने पर धीरे-धीरे फेड आउट हो जाती है।

### कस्टम API बेस के साथ

<Tip>
  आपको `apiBase` केवल तब सेट करना होगा जब आप सेल्फ़-होस्टेड या प्रॉक्सी API एंडपॉइंट का उपयोग कर रहे हों। डिफ़ॉल्ट रूप से यह `https://api.thunderphone.com/v1` पर पॉइंट करता है।
</Tip>

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

***

## एरर हैंडलिंग

जब `onError` कॉलबैक फायर होता है, तो उसे दो फ़ील्ड वाला एक एरर ऑब्जेक्ट मिलता है:

| फ़ील्ड    | टाइप     | विवरण                |
| --------- | -------- | -------------------- |
| `error`   | `string` | मशीन-रीडेबल एरर कोड  |
| `message` | `string` | मानव-पठनीय एरर विवरण |

सामान्य एरर कोड में डोमेन की अनुमति नहीं है, एजेंट नहीं मिला, और अमान्य API key शामिल हैं।

***

## अगले चरण

<CardGroup cols={2}>
  <Card title="हेडलेस हुक" icon="code" href="/hi/widget/headless-hook">
    UI पर पूरा नियंत्रण चाहिए? इसके बजाय `useThunderPhone` हुक का उपयोग करें।
  </Card>

  <Card title="स्टाइलिंग" icon="palette" href="/hi/widget/styling">
    CSS कस्टम प्रॉपर्टीज़ के साथ रंग, आकार और लेआउट कस्टमाइज़ करें।
  </Card>
</CardGroup>