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

# Python SDK

The official g-tateth SDK for Python.

## Installation

```bash theme={null}
pip install gtateth-sdk
```

Or from source:

```bash theme={null}
git clone https://github.com/g-tateth/sdk-python.git
cd sdk-python
pip install -e .
```

## Quick Start

```python theme={null}
from gtateth import GtatethClient

client = GtatethClient(
    api_key='sk_live_your_api_key_here',
    base_url='https://api.g-tateth.com'  # Optional, defaults to production
)

# List conversations
conversations = client.conversations.list()

# Get a conversation
conversation = client.conversations.get('conversation_id')

# List customers
customers = client.customers.list()

# Create a customer
new_customer = client.customers.create({
    'profile': {
        'firstName': 'John',
        'lastName': 'Doe',
        'email': 'john@example.com'
    }
})
```

## Configuration

### Options

```python theme={null}
client = GtatethClient(
    api_key='sk_live_your_api_key',
    base_url='https://api.g-tateth.com',  # Optional
    timeout=30,  # Optional, default: 30 seconds
    retries=3  # Optional, default: 3
)
```

### Environment Variables

You can also configure the client using environment variables:

```bash theme={null}
export G_TATETH_API_KEY=sk_live_your_api_key
export G_TATETH_BASE_URL=https://api.g-tateth.com
```

```python theme={null}
client = GtatethClient()  # Uses environment variables
```

## API Methods

### Conversations

```python theme={null}
# List conversations
conversations = client.conversations.list(
    status='open',
    page=1,
    limit=50
)

# Get conversation
conversation = client.conversations.get('conversation_id')

# Create conversation
new_conversation = client.conversations.create({
    'subject': 'Customer inquiry',
    'customerId': 'customer_id',
    'channel': 'email'
})

# Update conversation
client.conversations.update('conversation_id', {
    'status': 'closed'
})

# Delete conversation
client.conversations.delete('conversation_id')
```

### Customers

```python theme={null}
# List customers
customers = client.customers.list(
    search='john',
    page=1,
    limit=50
)

# Get customer
customer = client.customers.get('customer_id')

# Create customer
new_customer = client.customers.create({
    'profile': {
        'firstName': 'John',
        'lastName': 'Doe',
        'email': 'john@example.com'
    }
})

# Update customer
client.customers.update('customer_id', {
    'profile': {
        'company': 'Acme Corp'
    }
})

# Delete customer
client.customers.delete('customer_id')
```

### Webhooks

```python theme={null}
# List webhooks
webhooks = client.webhooks.list()

# Create webhook
webhook = client.webhooks.create({
    'name': 'My Webhook',
    'url': 'https://myapp.com/webhooks',
    'events': ['conversation.created', 'customer.updated']
})

# Get webhook
webhook = client.webhooks.get('webhook_id')

# Update webhook
client.webhooks.update('webhook_id', {
    'isActive': False
})

# Delete webhook
client.webhooks.delete('webhook_id')
```

### Analytics

```python theme={null}
# Get usage statistics
usage = client.analytics.get_usage(
    start_date='2024-01-01',
    end_date='2024-01-31'
)

# Get performance metrics
metrics = client.analytics.get_metrics(days=7)
```

## Error Handling

The SDK raises custom exception types:

```python theme={null}
from gtateth.exceptions import (
    GtatethError,
    RateLimitError,
    AuthenticationError
)

try:
    conversations = client.conversations.list()
except RateLimitError as e:
    print(f'Rate limit exceeded. Retry after: {e.retry_after}')
except AuthenticationError as e:
    print(f'Authentication failed: {e.message}')
except GtatethError as e:
    print(f'API error: {e.code} - {e.message}')
```

## Retry Logic

The SDK automatically retries failed requests with exponential backoff:

```python theme={null}
client = GtatethClient(
    api_key='sk_live_your_api_key',
    retries=3  # Number of retry attempts
)
```

## Examples

### Pagination

```python theme={null}
def get_all_conversations():
    page = 1
    all_conversations = []
    
    while True:
        response = client.conversations.list(page=page, limit=50)
        all_conversations.extend(response['data'])
        
        if page >= response['pagination']['totalPages']:
            break
        page += 1
    
    return all_conversations
```

### Error Handling

```python theme={null}
def safe_get_conversation(conversation_id):
    try:
        return client.conversations.get(conversation_id)
    except GtatethError as e:
        print(f'API Error: {e.code} - {e.message}')
        raise
```

## Resources

* [GitHub Repository](https://github.com/g-tateth/sdk-python)
* [PyPI Package](https://pypi.org/project/gtateth-sdk/)
* [API Reference](/guides/authentication)