telnyx-numbers-python

Name: telnyx-numbers-python
Author: team-telnyx

187stars18forks

How to install telnyx-numbers-python?

team-telnyx/ai/telnyx-numbers-python

$npx -y skills add team-telnyx/ai --skill telnyx-numbers-python

Installs into the current project.

Summary

Search, order, and manage phone numbers by location, features, and coverage.

Files · 1

View on GitHub

SKILL.md

1	<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
2
3	# Telnyx Numbers - Python
4
5	## Installation
6
7	```bash
8	pip install telnyx
9	```
10
11	## Setup
12
13	```python
14	import os
15	from telnyx import Telnyx
16
17	client = Telnyx(
18	api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
19	)
20	```
21
22	All examples below assume `client` is already initialized as shown above.
23
24	## Error Handling
25
26	All API calls can fail with network errors, rate limits (429), validation errors (422),
27	or authentication errors (401). Always handle errors in production code:
28
29	```python
30	import telnyx
31
32	try:
33	available_phone_numbers = client.available_phone_numbers.list()
34	except telnyx.APIConnectionError:
35	print("Network error — check connectivity and retry")
36	except telnyx.RateLimitError:
37	import time
38	time.sleep(1) # Check Retry-After header for actual delay
39	except telnyx.APIStatusError as e:
40	print(f"API error {e.status_code}: {e.message}")
41	if e.status_code == 422:
42	print("Validation error — check required fields and formats")
43	```
44
45	Common error codes: `401` invalid API key, `403` insufficient permissions,
46	`404` resource not found, `422` validation error (check field formats),
47	`429` rate limited (retry with exponential backoff).
48
49	## Important Notes
50
51	- Phone numbers must be in E.164 format (e.g., `+13125550001`). Include the `+` prefix and country code. No spaces, dashes, or parentheses.
52	- Pagination: List methods return an auto-paginating iterator. Use `for item in page_result:` to iterate through all pages automatically.
53
54	## Reference Use Rules
55
56	Do not invent Telnyx parameters, enums, response fields, or webhook fields.
57
58	- If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
59	- Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).
60
61	## Core Tasks
62
63	### Search available phone numbers
64
65	Number search is the entrypoint for provisioning. Agents need the search method, key query filters, and the fields returned for candidate numbers.
66
67	`client.available_phone_numbers.list()` — `GET /available_phone_numbers`
68
69	\| Parameter \| Type \| Required \| Description \|
70	\|-----------\|------\|----------\|-------------\|
71	\| `filter` \| object \| No \| Consolidated filter parameter (deepObject style). \|
72
73	```python
74	available_phone_numbers = client.available_phone_numbers.list()
75	print(available_phone_numbers.data)
76	```
77
78	Response wrapper:
79	- items: `available_phone_numbers.data`
80	- pagination: `available_phone_numbers.meta`
81
82	Primary item fields:
83	- `phone_number`
84	- `record_type`
85	- `quickship`
86	- `reservable`
87	- `best_effort`
88	- `cost_information`
89
90	### Create a number order
91
92	Number ordering is the production provisioning step after number selection.
93
94	`client.number_orders.create()` — `POST /number_orders`
95
96	\| Parameter \| Type \| Required \| Description \|
97	\|-----------\|------\|----------\|-------------\|
98	\| `phone_numbers` \| array[object] \| Yes \| \|
99	\| `connection_id` \| string (UUID) \| No \| Identifies the connection associated with this phone number. \|
100	\| `messaging_profile_id` \| string (UUID) \| No \| Identifies the messaging profile associated with the phone n... \|
101	\| `billing_group_id` \| string (UUID) \| No \| Identifies the billing group associated with the phone numbe... \|
102	\| ... \| \| \| +1 optional params in [references/api-details.md](references/api-details.md) \|
103
104	```python
105	number_order = client.number_orders.create(
106	phone_numbers=[{"phone_number": "+18005550101"}],
107	)
108	print(number_order.data)
109	```
110
111	Primary response fields:
112	- `number_order.data.id`
113	- `number_order.data.status`
114	- `number_order.data.phone_numbers_count`
115	- `number_order.data.requirements_met`
116	- `number_order.data.messaging_profile_id`
117	- `number_order.data.connection_id`
118
119	### Check number order status
120
121	Order status determines whether provisioning completed or additional requirements are still blocking fulfillment.
122
123	`client.number_orders.retrieve()` — `GET /number_orders/{number_order_id}`
124
125	\| Parameter \| Type \| Required \| Description \|
126	\|-----------\|------\|----------\|-------------\|
127	\| `number_order_id` \| string (UUID) \| Yes \| The number order ID. \|
128
129	```python
130	number_order = client.number_orders.retrieve(
131	"number_order_id",
132	)
133	print(number_order.data)
134	```
135
136	Primary response fields:
137	- `number_order.data.id`
138	- `number_order.data.status`
139	- `number_order.data.requirements_met`
140	- `number_order.data.phone_numbers_count`
141	- `number_order.data.phone_numbers`
142	- `number_order.data.connection_id`
143
144	---
145
146	## Important Supporting Operations
147
148	Use these when the core

People who liked this also viewed

6 picks

Type

telnyx-numbers-python

187stars18forks

View on GitHub

How to install telnyx-numbers-python?

team-telnyx/ai/telnyx-numbers-python

$npx -y skills add team-telnyx/ai --skill telnyx-numbers-python

Installs into the current project.

Summary

Search, order, and manage phone numbers by location, features, and coverage.

Files · 1

View on GitHub

SKILL.md

1	<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
2
3	# Telnyx Numbers - Python
4
5	## Installation
6
7	```bash
8	pip install telnyx
9	```
10
11	## Setup
12
13	```python
14	import os
15	from telnyx import Telnyx
16
17	client = Telnyx(
18	api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
19	)
20	```
21
22	All examples below assume `client` is already initialized as shown above.
23
24	## Error Handling
25
26	All API calls can fail with network errors, rate limits (429), validation errors (422),
27	or authentication errors (401). Always handle errors in production code:
28
29	```python
30	import telnyx
31
32	try:
33	available_phone_numbers = client.available_phone_numbers.list()
34	except telnyx.APIConnectionError:
35	print("Network error — check connectivity and retry")
36	except telnyx.RateLimitError:
37	import time
38	time.sleep(1) # Check Retry-After header for actual delay
39	except telnyx.APIStatusError as e:
40	print(f"API error {e.status_code}: {e.message}")
41	if e.status_code == 422:
42	print("Validation error — check required fields and formats")
43	```
44
45	Common error codes: `401` invalid API key, `403` insufficient permissions,
46	`404` resource not found, `422` validation error (check field formats),
47	`429` rate limited (retry with exponential backoff).
48
49	## Important Notes
50
51	- Phone numbers must be in E.164 format (e.g., `+13125550001`). Include the `+` prefix and country code. No spaces, dashes, or parentheses.
52	- Pagination: List methods return an auto-paginating iterator. Use `for item in page_result:` to iterate through all pages automatically.
53
54	## Reference Use Rules
55
56	Do not invent Telnyx parameters, enums, response fields, or webhook fields.
57
58	- If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
59	- Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).
60
61	## Core Tasks
62
63	### Search available phone numbers
64
65	Number search is the entrypoint for provisioning. Agents need the search method, key query filters, and the fields returned for candidate numbers.
66
67	`client.available_phone_numbers.list()` — `GET /available_phone_numbers`
68
69	\| Parameter \| Type \| Required \| Description \|
70	\|-----------\|------\|----------\|-------------\|
71	\| `filter` \| object \| No \| Consolidated filter parameter (deepObject style). \|
72
73	```python
74	available_phone_numbers = client.available_phone_numbers.list()
75	print(available_phone_numbers.data)
76	```
77
78	Response wrapper:
79	- items: `available_phone_numbers.data`
80	- pagination: `available_phone_numbers.meta`
81
82	Primary item fields:
83	- `phone_number`
84	- `record_type`
85	- `quickship`
86	- `reservable`
87	- `best_effort`
88	- `cost_information`
89
90	### Create a number order
91
92	Number ordering is the production provisioning step after number selection.
93
94	`client.number_orders.create()` — `POST /number_orders`
95
96	\| Parameter \| Type \| Required \| Description \|
97	\|-----------\|------\|----------\|-------------\|
98	\| `phone_numbers` \| array[object] \| Yes \| \|
99	\| `connection_id` \| string (UUID) \| No \| Identifies the connection associated with this phone number. \|
100	\| `messaging_profile_id` \| string (UUID) \| No \| Identifies the messaging profile associated with the phone n... \|
101	\| `billing_group_id` \| string (UUID) \| No \| Identifies the billing group associated with the phone numbe... \|
102	\| ... \| \| \| +1 optional params in [references/api-details.md](references/api-details.md) \|
103
104	```python
105	number_order = client.number_orders.create(
106	phone_numbers=[{"phone_number": "+18005550101"}],
107	)
108	print(number_order.data)
109	```
110
111	Primary response fields:
112	- `number_order.data.id`
113	- `number_order.data.status`
114	- `number_order.data.phone_numbers_count`
115	- `number_order.data.requirements_met`
116	- `number_order.data.messaging_profile_id`
117	- `number_order.data.connection_id`
118
119	### Check number order status
120
121	Order status determines whether provisioning completed or additional requirements are still blocking fulfillment.
122
123	`client.number_orders.retrieve()` — `GET /number_orders/{number_order_id}`
124
125	\| Parameter \| Type \| Required \| Description \|
126	\|-----------\|------\|----------\|-------------\|
127	\| `number_order_id` \| string (UUID) \| Yes \| The number order ID. \|
128
129	```python
130	number_order = client.number_orders.retrieve(
131	"number_order_id",
132	)
133	print(number_order.data)
134	```
135
136	Primary response fields:
137	- `number_order.data.id`
138	- `number_order.data.status`
139	- `number_order.data.requirements_met`
140	- `number_order.data.phone_numbers_count`
141	- `number_order.data.phone_numbers`
142	- `number_order.data.connection_id`
143
144	---
145
146	## Important Supporting Operations
147
148	Use these when the core

People who liked this also viewed

6 picks

Type