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

# Python SDK — telephony

> Python SDK reference for Kataven telephony — Twilio/Plivo/Vobiz credentials and phone-number management.

`TelephonyClient` is reachable on every Kataven client as `client.telephony`. Each method maps to one HTTP endpoint on the [Hub API](/api-reference/introduction); links to the underlying spec entry are inline below.

Carrier credentials (encrypted) and phone-number management. Pin a number to an agent so inbound calls route to that agent.

## Methods at a glance

| Method            | HTTP                                            | Summary                                 |
| ----------------- | ----------------------------------------------- | --------------------------------------- |
| `list_providers`  | `GET /api/telephony/providers`                  | List telephony provider credentials     |
| `create_provider` | `POST /api/telephony/providers`                 | Add a telephony provider credential     |
| `delete_provider` | `DELETE /api/telephony/providers/{provider_id}` | Delete a telephony provider credential  |
| `list_numbers`    | `GET /api/telephony/numbers`                    | List phone numbers                      |
| `create_number`   | `POST /api/telephony/numbers`                   | Register a phone number                 |
| `update_number`   | `PATCH /api/telephony/numbers/{number_id}`      | Pin or unpin a phone number to an agent |
| `delete_number`   | `DELETE /api/telephony/numbers/{number_id}`     | Delete a phone number                   |

## Reference

### `client.telephony.list_providers(...)`

List telephony provider credentials

**HTTP** — `GET /api/telephony/providers` · [API reference →](/api-reference/introduction#tag/Telephony/operation/getApiTelephonyProviders)

```python theme={null}
    def list_providers(self) -> Dict[str, Any]:
```

Returns metadata about every carrier credential configured for this account. Plaintext credentials are not returned.

### `client.telephony.create_provider(...)`

Add a telephony provider credential

**HTTP** — `POST /api/telephony/providers` · [API reference →](/api-reference/introduction#tag/Telephony/operation/postApiTelephonyProviders)

```python theme={null}
    def create_provider(
        self,
        provider: str,
        label: str,
        credentials: Dict[str, Any],
    ) -> Dict[str, Any]:
```

Required `credentials` keys per provider:

* twilio: account\_sid, auth\_token
* plivo:  auth\_id,    auth\_token
* vobiz:  auth\_id,    auth\_token

Encrypts the credentials JSON via the Secret Encryptor service, then inserts the row. Plaintext is never persisted.

### `client.telephony.delete_provider(...)`

Delete a telephony provider credential

**HTTP** — `DELETE /api/telephony/providers/{id}` · [API reference →](/api-reference/introduction#tag/Telephony/operation/deleteApiTelephonyProvidersById)

```python theme={null}
    def delete_provider(self, provider_id: str) -> None:
```

Refuses if any phone-number row still references this credential — detach numbers first.

### `client.telephony.list_numbers(...)`

List phone numbers

**HTTP** — `GET /api/telephony/numbers` · [API reference →](/api-reference/introduction#tag/Telephony/operation/getApiTelephonyNumbers)

```python theme={null}
    def list_numbers(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
```

### `client.telephony.create_number(...)`

Register a phone number

**HTTP** — `POST /api/telephony/numbers` · [API reference →](/api-reference/introduction#tag/Telephony/operation/postApiTelephonyNumbers)

```python theme={null}
    def create_number(
        self,
        e164: str,
        provider: str,
        credentials_id: str,
        agent_id: Optional[str] = None,
        inbound_enabled: bool = True,
        outbound_enabled: bool = True,
    ) -> Dict[str, Any]:
```

Binds an E.164 number to a carrier credential row and (optionally) pins it to one agent. Inbound + outbound default to enabled.

### `client.telephony.update_number(...)`

Pin or unpin a phone number to an agent

**HTTP** — `PATCH /api/telephony/numbers/{id}` · [API reference →](/api-reference/introduction#tag/Telephony/operation/patchApiTelephonyNumbersById)

```python theme={null}
    def update_number(self, number_id: str, agent_id: Optional[str]) -> None:
```

### `client.telephony.delete_number(...)`

Delete a phone number

**HTTP** — `DELETE /api/telephony/numbers/{id}` · [API reference →](/api-reference/introduction#tag/Telephony/operation/deleteApiTelephonyNumbersById)

```python theme={null}
    def delete_number(self, number_id: str) -> None:
```