--- name: telnyx-sip-integrations-python description: >- Manage call recordings, media storage, Dialogflow integration, and external connections for SIP trunking. This skill provides Python SDK examples. metadata: author: telnyx product: sip-integrations language: python generated_by: telnyx-ext-skills-generator --- # Telnyx Sip Integrations - Python ## Installation ```bash pip install telnyx ``` ## Setup ```python import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) ``` All examples below assume `client` is already initialized as shown above. ## Error Handling All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code: ```python import telnyx try: result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello") except telnyx.APIConnectionError: print("Network error — check connectivity and retry") except telnyx.RateLimitError: # 429: rate limited — wait and retry with exponential backoff import time time.sleep(1) # Check Retry-After header for actual delay except telnyx.APIStatusError as e: print(f"API error {e.status_code}: {e.message}") if e.status_code == 422: print("Validation error — check required fields and formats") ``` Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error (check field formats), `429` rate limited (retry with exponential backoff). ## Important Notes - **Pagination:** List methods return an auto-paginating iterator. Use `for item in page_result:` to iterate through all pages automatically. ## Retrieve a stored credential Returns the information about custom storage credentials. `GET /custom_storage_credentials/{connection_id}` ```python custom_storage_credential = client.custom_storage_credentials.retrieve( "connection_id", ) print(custom_storage_credential.connection_id) ``` Returns: `backend` (enum: gcs, s3, azure), `configuration` (object) ## Create a custom storage credential Creates a custom storage credentials configuration. `POST /custom_storage_credentials/{connection_id}` ```python custom_storage_credential = client.custom_storage_credentials.create( connection_id="550e8400-e29b-41d4-a716-446655440000", backend="gcs", configuration={ "backend": "gcs" }, ) print(custom_storage_credential.connection_id) ``` Returns: `backend` (enum: gcs, s3, azure), `configuration` (object) ## Update a stored credential Updates a stored custom credentials configuration. `PUT /custom_storage_credentials/{connection_id}` ```python custom_storage_credential = client.custom_storage_credentials.update( connection_id="550e8400-e29b-41d4-a716-446655440000", backend="gcs", configuration={ "backend": "gcs" }, ) print(custom_storage_credential.connection_id) ``` Returns: `backend` (enum: gcs, s3, azure), `configuration` (object) ## Delete a stored credential Deletes a stored custom credentials configuration. `DELETE /custom_storage_credentials/{connection_id}` ```python client.custom_storage_credentials.delete( "connection_id", ) ``` ## Retrieve stored Dialogflow Connection Return details of the Dialogflow connection associated with the given CallControl connection. `GET /dialogflow_connections/{connection_id}` ```python dialogflow_connection = client.dialogflow_connections.retrieve( "connection_id", ) print(dialogflow_connection.data) ``` Returns: `connection_id` (string), `conversation_profile_id` (string), `environment` (string), `record_type` (string), `service_account` (string) ## Create a Dialogflow Connection Save Dialogflow Credentiails to Telnyx, so it can be used with other Telnyx services. `POST /dialogflow_connections/{connection_id}` ```python dialogflow_connection = client.dialogflow_connections.create( connection_id="550e8400-e29b-41d4-a716-446655440000", service_account={ "type": "bar", "project_id": "bar", "private_key_id": "bar", "private_key": "bar", "client_email": "bar", "client_id": "bar", "auth_uri": "bar", "token_uri": "bar", "auth_provider_x509_cert_url": "bar", "client_x509_cert_url": "bar", }, ) print(dialogflow_connection.data) ``` Returns: `connection_id` (string), `conversation_profile_id` (string), `environment` (string), `record_type` (string), `service_account` (string) ## Update stored Dialogflow Connection Updates a stored Dialogflow Connection. `PUT /dialogflow_connections/{connection_id}` ```python dialogflow_connection = client.dialogflow_connections.update( connection_id="550e8400-e29b-41d4-a716-446655440000", service_account={ "type": "bar", "project_id": "bar", "private_key_id": "bar", "private_key": "bar", "client_email": "bar", "client_id": "bar", "auth_uri": "bar", "token_uri": "bar", "auth_provider_x509_cert_url": "bar", "client_x509_cert_url": "bar", }, ) print(dialogflow_connection.data) ``` Returns: `connection_id` (string), `conversation_profile_id` (string), `environment` (string), `record_type` (string), `service_account` (string) ## Delete stored Dialogflow Connection Deletes a stored Dialogflow Connection. `DELETE /dialogflow_connections/{connection_id}` ```python client.dialogflow_connections.delete( "connection_id", ) ``` ## List all External Connections This endpoint returns a list of your External Connections inside the 'data' attribute of the response. External Connections are used by Telnyx customers to seamless configure SIP trunking integrations with Telnyx Partners, through External Voice Integrations in Mission Control Portal. `GET /external_connections` ```python page = client.external_connections.list() page = page.data[0] print(page.id) ``` Returns: `active` (boolean), `created_at` (string), `credential_active` (boolean), `external_sip_connection` (enum: zoom, operator_connect), `id` (string), `inbound` (object), `outbound` (object), `record_type` (string), `tags` (array[string]), `updated_at` (string), `webhook_api_version` (enum: 1, 2), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ## Creates an External Connection Creates a new External Connection based on the parameters sent in the request. The external_sip_connection and outbound voice profile id are required. Once created, you can assign phone numbers to your application using the `/phone_numbers` endpoint. `POST /external_connections` — Required: `external_sip_connection`, `outbound` Optional: `active` (boolean), `inbound` (object), `tags` (array[string]), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ```python external_connection = client.external_connections.create( external_sip_connection="zoom", outbound={}, ) print(external_connection.data) ``` Returns: `active` (boolean), `created_at` (string), `credential_active` (boolean), `external_sip_connection` (enum: zoom, operator_connect), `id` (string), `inbound` (object), `outbound` (object), `record_type` (string), `tags` (array[string]), `updated_at` (string), `webhook_api_version` (enum: 1, 2), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ## List all log messages Retrieve a list of log messages for all external connections associated with your account. `GET /external_connections/log_messages` ```python page = client.external_connections.log_messages.list() page = page.log_messages[0] print(page.code) ``` Returns: `log_messages` (array[object]), `meta` (object) ## Retrieve a log message Retrieve a log message for an external connection associated with your account. `GET /external_connections/log_messages/{id}` ```python log_message = client.external_connections.log_messages.retrieve( "1293384261075731499", ) print(log_message.log_messages) ``` Returns: `log_messages` (array[object]) ## Dismiss a log message Dismiss a log message for an external connection associated with your account. `DELETE /external_connections/log_messages/{id}` ```python response = client.external_connections.log_messages.dismiss( "1293384261075731499", ) print(response.success) ``` Returns: `success` (boolean) ## Retrieve an External Connection Return the details of an existing External Connection inside the 'data' attribute of the response. `GET /external_connections/{id}` ```python external_connection = client.external_connections.retrieve( "1293384261075731499", ) print(external_connection.data) ``` Returns: `active` (boolean), `created_at` (string), `credential_active` (boolean), `external_sip_connection` (enum: zoom, operator_connect), `id` (string), `inbound` (object), `outbound` (object), `record_type` (string), `tags` (array[string]), `updated_at` (string), `webhook_api_version` (enum: 1, 2), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ## Update an External Connection Updates settings of an existing External Connection based on the parameters of the request. `PATCH /external_connections/{id}` — Required: `outbound` Optional: `active` (boolean), `inbound` (object), `tags` (array[string]), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ```python external_connection = client.external_connections.update( id="1293384261075731499", outbound={ "outbound_voice_profile_id": "1911630617284445511" }, ) print(external_connection.data) ``` Returns: `active` (boolean), `created_at` (string), `credential_active` (boolean), `external_sip_connection` (enum: zoom, operator_connect), `id` (string), `inbound` (object), `outbound` (object), `record_type` (string), `tags` (array[string]), `updated_at` (string), `webhook_api_version` (enum: 1, 2), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ## Deletes an External Connection Permanently deletes an External Connection. Deletion may be prevented if the application is in use by phone numbers, is active, or if it is an Operator Connect connection. To remove an Operator Connect integration please contact Telnyx support. `DELETE /external_connections/{id}` ```python external_connection = client.external_connections.delete( "1293384261075731499", ) print(external_connection.data) ``` Returns: `active` (boolean), `created_at` (string), `credential_active` (boolean), `external_sip_connection` (enum: zoom, operator_connect), `id` (string), `inbound` (object), `outbound` (object), `record_type` (string), `tags` (array[string]), `updated_at` (string), `webhook_api_version` (enum: 1, 2), `webhook_event_failover_url` (uri), `webhook_event_url` (uri), `webhook_timeout_secs` (integer | null) ## List all civic addresses and locations Returns the civic addresses and locations from Microsoft Teams. `GET /external_connections/{id}/civic_addresses` ```python civic_addresses = client.external_connections.civic_addresses.list( id="1293384261075731499", ) print(civic_addresses.data) ``` Returns: `city_or_town` (string), `city_or_town_alias` (string), `company_name` (string), `country` (string), `country_or_district` (string), `default_location_id` (uuid), `description` (string), `house_number` (string), `house_number_suffix` (string), `id` (uuid), `locations` (array[object]), `postal_or_zip_code` (string), `record_type` (string), `state_or_province` (string), `street_name` (string), `street_suffix` (string) ## Retrieve a Civic Address Return the details of an existing Civic Address with its Locations inside the 'data' attribute of the response. `GET /external_connections/{id}/civic_addresses/{address_id}` ```python civic_address = client.external_connections.civic_addresses.retrieve( address_id="318fb664-d341-44d2-8405-e6bfb9ced6d9", id="1293384261075731499", ) print(civic_address.data) ``` Returns: `city_or_town` (string), `city_or_town_alias` (string), `company_name` (string), `country` (string), `country_or_district` (string), `default_location_id` (uuid), `description` (string), `house_number` (string), `house_number_suffix` (string), `id` (uuid), `locations` (array[object]), `postal_or_zip_code` (string), `record_type` (string), `state_or_province` (string), `street_name` (string), `street_suffix` (string) ## Update a location's static emergency address `PATCH /external_connections/{id}/locations/{location_id}` — Required: `static_emergency_address_id` ```python response = client.external_connections.update_location( location_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", static_emergency_address_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response.data) ``` Returns: `accepted_address_suggestions` (boolean), `location_id` (uuid), `static_emergency_address_id` (uuid) ## List all phone numbers Returns a list of all active phone numbers associated with the given external connection. `GET /external_connections/{id}/phone_numbers` ```python page = client.external_connections.phone_numbers.list( id="1293384261075731499", ) page = page.data[0] print(page.civic_address_id) ``` Returns: `acquired_capabilities` (array[string]), `civic_address_id` (uuid), `displayed_country_code` (string), `location_id` (uuid), `number_id` (string), `telephone_number` (string), `ticket_id` (uuid) ## Retrieve a phone number Return the details of a phone number associated with the given external connection. `GET /external_connections/{id}/phone_numbers/{phone_number_id}` ```python phone_number = client.external_connections.phone_numbers.retrieve( phone_number_id="1234567889", id="1293384261075731499", ) print(phone_number.data) ``` Returns: `acquired_capabilities` (array[string]), `civic_address_id` (uuid), `displayed_country_code` (string), `location_id` (uuid), `number_id` (string), `telephone_number` (string), `ticket_id` (uuid) ## Update a phone number Asynchronously update settings of the phone number associated with the given external connection. `PATCH /external_connections/{id}/phone_numbers/{phone_number_id}` Optional: `location_id` (uuid) ```python phone_number = client.external_connections.phone_numbers.update( phone_number_id="1234567889", id="1293384261075731499", ) print(phone_number.data) ``` Returns: `acquired_capabilities` (array[string]), `civic_address_id` (uuid), `displayed_country_code` (string), `location_id` (uuid), `number_id` (string), `telephone_number` (string), `ticket_id` (uuid) ## List all Releases Returns a list of your Releases for the given external connection. These are automatically created when you change the `connection_id` of a phone number that is currently on Microsoft Teams. `GET /external_connections/{id}/releases` ```python page = client.external_connections.releases.list( id="1293384261075731499", ) page = page.data[0] print(page.tenant_id) ``` Returns: `created_at` (string), `error_message` (string), `status` (enum: pending_upload, pending, in_progress, complete, failed, expired, unknown), `telephone_numbers` (array[object]), `tenant_id` (uuid), `ticket_id` (uuid) ## Retrieve a Release request Return the details of a Release request and its phone numbers. `GET /external_connections/{id}/releases/{release_id}` ```python release = client.external_connections.releases.retrieve( release_id="7b6a6449-b055-45a6-81f6-f6f0dffa4cc6", id="1293384261075731499", ) print(release.data) ``` Returns: `created_at` (string), `error_message` (string), `status` (enum: pending_upload, pending, in_progress, complete, failed, expired, unknown), `telephone_numbers` (array[object]), `tenant_id` (uuid), `ticket_id` (uuid) ## List all Upload requests Returns a list of your Upload requests for the given external connection. `GET /external_connections/{id}/uploads` ```python page = client.external_connections.uploads.list( id="1293384261075731499", ) page = page.data[0] print(page.location_id) ``` Returns: `available_usages` (array[string]), `error_code` (string), `error_message` (string), `location_id` (uuid), `status` (enum: pending_upload, pending, in_progress, partial_success, success, error), `tenant_id` (uuid), `ticket_id` (uuid), `tn_upload_entries` (array[object]) ## Creates an Upload request Creates a new Upload request to Microsoft teams with the included phone numbers. Only one of civic_address_id or location_id must be provided, not both. The maximum allowed phone numbers for the numbers_ids array is 1000. `POST /external_connections/{id}/uploads` — Required: `number_ids` Optional: `additional_usages` (array[string]), `civic_address_id` (uuid), `location_id` (uuid), `usage` (enum: calling_user_assignment, first_party_app_assignment) ```python upload = client.external_connections.uploads.create( id="1293384261075731499", number_ids=["3920457616934164700", "3920457616934164701", "3920457616934164702", "3920457616934164703"], ) print(upload.ticket_id) ``` Returns: `success` (boolean), `ticket_id` (uuid) ## Refresh the status of all Upload requests Forces a recheck of the status of all pending Upload requests for the given external connection in the background. `POST /external_connections/{id}/uploads/refresh` ```python response = client.external_connections.uploads.refresh_status( "1293384261075731499", ) print(response.success) ``` Returns: `success` (boolean) ## Get the count of pending upload requests Returns the count of all pending upload requests for the given external connection. `GET /external_connections/{id}/uploads/status` ```python response = client.external_connections.uploads.pending_count( "1293384261075731499", ) print(response.data) ``` Returns: `pending_numbers_count` (integer), `pending_orders_count` (integer) ## Retrieve an Upload request Return the details of an Upload request and its phone numbers. `GET /external_connections/{id}/uploads/{ticket_id}` ```python upload = client.external_connections.uploads.retrieve( ticket_id="7b6a6449-b055-45a6-81f6-f6f0dffa4cc6", id="1293384261075731499", ) print(upload.data) ``` Returns: `available_usages` (array[string]), `error_code` (string), `error_message` (string), `location_id` (uuid), `status` (enum: pending_upload, pending, in_progress, partial_success, success, error), `tenant_id` (uuid), `ticket_id` (uuid), `tn_upload_entries` (array[object]) ## Retry an Upload request If there were any errors during the upload process, this endpoint will retry the upload request. In some cases this will reattempt the existing upload request, in other cases it may create a new upload request. Please check the ticket_id in the response to determine if a new upload request was created. `POST /external_connections/{id}/uploads/{ticket_id}/retry` ```python response = client.external_connections.uploads.retry( ticket_id="7b6a6449-b055-45a6-81f6-f6f0dffa4cc6", id="1293384261075731499", ) print(response.data) ``` Returns: `available_usages` (array[string]), `error_code` (string), `error_message` (string), `location_id` (uuid), `status` (enum: pending_upload, pending, in_progress, partial_success, success, error), `tenant_id` (uuid), `ticket_id` (uuid), `tn_upload_entries` (array[object]) ## List uploaded media Returns a list of stored media files. `GET /media` ```python media = client.media.list() print(media.data) ``` Returns: `content_type` (string), `created_at` (string), `expires_at` (string), `media_name` (string), `updated_at` (string) ## Upload media Upload media file to Telnyx so it can be used with other Telnyx services `POST /media` — Required: `media_url` Optional: `media_name` (string), `ttl_secs` (integer) ```python response = client.media.upload( media_url="http://www.example.com/audio.mp3", ) print(response.data) ``` Returns: `content_type` (string), `created_at` (string), `expires_at` (string), `media_name` (string), `updated_at` (string) ## Retrieve stored media Returns the information about a stored media file. `GET /media/{media_name}` ```python media = client.media.retrieve( "media_name", ) print(media.data) ``` Returns: `content_type` (string), `created_at` (string), `expires_at` (string), `media_name` (string), `updated_at` (string) ## Update stored media Updates a stored media file. `PUT /media/{media_name}` Optional: `media_url` (string), `ttl_secs` (integer) ```python media = client.media.update( media_name="media_name", ) print(media.data) ``` Returns: `content_type` (string), `created_at` (string), `expires_at` (string), `media_name` (string), `updated_at` (string) ## Deletes stored media Deletes a stored media file. `DELETE /media/{media_name}` ```python client.media.delete( "media_name", ) ``` ## Download stored media Downloads a stored media file. `GET /media/{media_name}/download` ```python response = client.media.download( "media_name", ) print(response) content = response.read() print(content) ``` ## Refresh Operator Connect integration This endpoint will make an asynchronous request to refresh the Operator Connect integration with Microsoft Teams for the current user. This will create new external connections on the user's account if needed, and/or report the integration results as [log messages](https://developers.telnyx.com/api-reference/external-connections/list-all-log-messages#list-all-log-messages). `POST /operator_connect/actions/refresh` ```python response = client.operator_connect.actions.refresh() print(response.message) ``` Returns: `message` (string), `success` (boolean) ## List all recording transcriptions Returns a list of your recording transcriptions. `GET /recording_transcriptions` ```python page = client.recording_transcriptions.list() page = page.data[0] print(page.id) ``` Returns: `created_at` (string), `duration_millis` (int32), `id` (string), `record_type` (enum: recording_transcription), `recording_id` (string), `status` (enum: in-progress, completed), `transcription_text` (string), `updated_at` (string) ## Retrieve a recording transcription Retrieves the details of an existing recording transcription. `GET /recording_transcriptions/{recording_transcription_id}` ```python recording_transcription = client.recording_transcriptions.retrieve( "6a09cdc3-8948-47f0-aa62-74ac943d6c58", ) print(recording_transcription.data) ``` Returns: `created_at` (string), `duration_millis` (int32), `id` (string), `record_type` (enum: recording_transcription), `recording_id` (string), `status` (enum: in-progress, completed), `transcription_text` (string), `updated_at` (string) ## Delete a recording transcription Permanently deletes a recording transcription. `DELETE /recording_transcriptions/{recording_transcription_id}` ```python recording_transcription = client.recording_transcriptions.delete( "6a09cdc3-8948-47f0-aa62-74ac943d6c58", ) print(recording_transcription.data) ``` Returns: `created_at` (string), `duration_millis` (int32), `id` (string), `record_type` (enum: recording_transcription), `recording_id` (string), `status` (enum: in-progress, completed), `transcription_text` (string), `updated_at` (string) ## List all call recordings Returns a list of your call recordings. `GET /recordings` ```python page = client.recordings.list() page = page.data[0] print(page.id) ``` Returns: `call_control_id` (string), `call_leg_id` (string), `call_session_id` (string), `channels` (enum: single, dual), `conference_id` (string), `connection_id` (string), `created_at` (string), `download_urls` (object), `duration_millis` (int32), `from` (string), `id` (string), `initiated_by` (string), `record_type` (enum: recording), `recording_ended_at` (string), `recording_started_at` (string), `source` (enum: conference, call), `status` (enum: completed), `to` (string), `updated_at` (string) ## Delete a list of call recordings Permanently deletes a list of call recordings. `POST /recordings/actions/delete` ```python action = client.recordings.actions.delete( ids=["428c31b6-7af4-4bcb-b7f5-5013ef9657c1", "428c31b6-7af4-4bcb-b7f5-5013ef9657c2"], ) print(action.status) ``` Returns: `status` (enum: ok) ## Retrieve a call recording Retrieves the details of an existing call recording. `GET /recordings/{recording_id}` ```python recording = client.recordings.retrieve( "recording_id", ) print(recording.data) ``` Returns: `call_control_id` (string), `call_leg_id` (string), `call_session_id` (string), `channels` (enum: single, dual), `conference_id` (string), `connection_id` (string), `created_at` (string), `download_urls` (object), `duration_millis` (int32), `from` (string), `id` (string), `initiated_by` (string), `record_type` (enum: recording), `recording_ended_at` (string), `recording_started_at` (string), `source` (enum: conference, call), `status` (enum: completed), `to` (string), `updated_at` (string) ## Delete a call recording Permanently deletes a call recording. `DELETE /recordings/{recording_id}` ```python recording = client.recordings.delete( "recording_id", ) print(recording.data) ``` Returns: `call_control_id` (string), `call_leg_id` (string), `call_session_id` (string), `channels` (enum: single, dual), `conference_id` (string), `connection_id` (string), `created_at` (string), `download_urls` (object), `duration_millis` (int32), `from` (string), `id` (string), `initiated_by` (string), `record_type` (enum: recording), `recording_ended_at` (string), `recording_started_at` (string), `source` (enum: conference, call), `status` (enum: completed), `to` (string), `updated_at` (string) ## Create a SIPREC connector Creates a new SIPREC connector configuration. `POST /siprec_connectors` ```python siprec_connector = client.siprec_connectors.create( host="siprec.telnyx.com", name="my-siprec-connector", port=5060, ) print(siprec_connector.data) ``` Returns: `app_subdomain` (string), `created_at` (string), `host` (string), `name` (string), `port` (integer), `record_type` (string), `updated_at` (string) ## Retrieve a SIPREC connector Returns details of a stored SIPREC connector. `GET /siprec_connectors/{connector_name}` ```python siprec_connector = client.siprec_connectors.retrieve( "connector_name", ) print(siprec_connector.data) ``` Returns: `app_subdomain` (string), `created_at` (string), `host` (string), `name` (string), `port` (integer), `record_type` (string), `updated_at` (string) ## Update a SIPREC connector Updates a stored SIPREC connector configuration. `PUT /siprec_connectors/{connector_name}` ```python siprec_connector = client.siprec_connectors.update( connector_name="connector_name", host="siprec.telnyx.com", name="my-siprec-connector", port=5060, ) print(siprec_connector.data) ``` Returns: `app_subdomain` (string), `created_at` (string), `host` (string), `name` (string), `port` (integer), `record_type` (string), `updated_at` (string) ## Delete a SIPREC connector Deletes a stored SIPREC connector. `DELETE /siprec_connectors/{connector_name}` ```python client.siprec_connectors.delete( "connector_name", ) ```