Registry / azure / azure-communication-sms

azure-communication-sms

JSON →
library1.1.0pypypi✓ verified 85d ago

The Azure Communication SMS client library for Python allows developers to integrate SMS messaging capabilities into their applications. It provides functionalities to send 1:1 and 1:N SMS messages via Azure Communication Services. The library is currently at version 1.1.0 and is part of the Azure SDK for Python, which typically sees regular updates, including new features and bug fixes, often on a monthly or bi-monthly cadence, alongside public preview releases for upcoming functionalities.

pip install azure-communication-sms
INSTALL
IMPORT
SIG · AZURE-COMMUNICATIO
A
azure-communication-sms
azurepythonv1.1.0
Install
2.7s avg
Import
1091ms
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 1.157s · 26MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.7s · import 1.026s · 26MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SmsClient
from azure.communication.sms import SmsClient
DefaultAzureCredential
from azure.identity import DefaultAzureCredential
Required for Azure Active Directory (AAD) authentication.

This quickstart demonstrates how to initialize the `SmsClient` using a connection string and send a single SMS message. It is crucial to replace placeholder environment variables with your actual Azure Communication Services connection string, and SMS-enabled phone numbers in E.164 format. The `enable_delivery_report` flag is set to `True` to allow tracking message delivery status.

import os from azure.communication.sms import SmsClient # Retrieve the connection string from an environment variable # AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING is typically # 'endpoint=https://<your-resource-name>.communication.azure.com/;accesskey=<your-access-key>' connection_string = os.environ.get('AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING', 'YOUR_CONNECTION_STRING') # Replace with your SMS enabled phone numbers from_phone_number = os.environ.get('AZURE_COMMUNICATION_SERVICE_FROM_PHONE_NUMBER', '+1XXXXXXXXX') # E.164 format to_phone_number = os.environ.get('AZURE_COMMUNICATION_SERVICE_TO_PHONE_NUMBER', '+1YYYYYYYYY') # E.164 format if connection_string == 'YOUR_CONNECTION_STRING': raise ValueError("Please set the AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING environment variable.") if from_phone_number == '+1XXXXXXXXX': raise ValueError("Please set the AZURE_COMMUNICATION_SERVICE_FROM_PHONE_NUMBER environment variable.") if to_phone_number == '+1YYYYYYYYY': raise ValueError("Please set the AZURE_COMMUNICATION_SERVICE_TO_PHONE_NUMBER environment variable.") try: # Initialize the SmsClient with your connection string sms_client = SmsClient.from_connection_string(connection_string) # Send a 1:1 SMS message send_result = sms_client.send( from_=from_phone_number, to=[to_phone_number], message="Hello from Azure Communication Services!", enable_delivery_report=True ) print(f"SMS message sent. Results: {send_result}") for result in send_result: if result.successful: print(f" Message ID: {result.message_id}, To: {result.to}, Status: {result.http_status_code}") else: print(f" Failed to send to {result.to}. Error: {result.error_message}, Status: {result.http_status_code}") except Exception as ex: print(f"An error occurred: {ex}")
Debug
Known issues
gotchaPhone numbers must be provided in the E.164 international standard format (e.g., +14255550123) for both `from_` and `to` parameters. Incorrect formats will lead to delivery failures.
fix
Ensure all phone numbers adhere strictly to the E.164 format, including the '+' prefix.
affects: All versions
gotchaThe Azure Communication Services resource and the associated phone number must be properly configured for SMS capabilities and verified. Toll-free numbers, in particular, require verification to avoid messages being blocked by carriers.
fix
Verify SMS enablement and phone number status in the Azure Portal under your Communication Services resource. For toll-free numbers, ensure verification is complete.
affects: All versions
gotchaSending large volumes of SMS messages may encounter carrier throttling or Azure Communication Services throughput limits, resulting in delivery failures (e.g., '5000 Message failed to deliver').
fix
Implement retry logic with exponential backoff, send messages in batches, monitor ACS quotas, and validate phone numbers before sending to reduce delivery failures.
affects: All versions
gotchaAuthentication failures (e.g., `401 Unauthorized`, `403 Forbidden`) are common if the connection string is incorrect, environment variables for Azure Active Directory are missing, or the principal lacks sufficient permissions on the Communication Services resource.
fix
Double-check the connection string for accuracy, ensure required AAD environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) are set if using `DefaultAzureCredential`, and verify that the principal has the 'Azure Communication Services Contributor' role or equivalent permissions.
affects: All versions
Errors
Common errors & fixes
azure.core.exceptions.HttpResponseError: (Unauthorized) The request couldn't be authenticated.
The connection string or Azure Active Directory credentials provided are invalid, expired, or lack necessary permissions.
fix
Verify that the `AZURE_COMMUNICATION_SERVICE_CONNECTION_STRING` environment variable is correctly set and matches your Communication Services resource. If using AAD, ensure `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` are correct and the service principal has the 'Azure Communication Services Contributor' role.
azure.core.exceptions.HttpResponseError: (Forbidden) The request was authorized, but has insufficient permissions to carry out this operation.
The authenticated identity does not have the necessary role-based access control (RBAC) permissions to send SMS messages.
fix
Grant the appropriate permissions, such as 'Azure Communication Services Contributor', to the identity being used for authentication on your Azure Communication Services resource.
azure.core.exceptions.HttpResponseError: (InvalidInput) The request received couldn't be understood by the service. Double check the documentation and ensure you're sending everything required and in the correct format.
Typically caused by incorrect phone number formatting (not E.164) or unexpected/hidden characters in `from_`, `to`, or `message` fields.
fix
Ensure all phone numbers are in E.164 format (e.g., `+14255550123`). Trim and normalize all input strings to remove any invisible or non-printable characters.
SmsSendResult.successful is False, SmsSendResult.error_message contains '5000 Message failed to deliver'
A generic SMS delivery failure, often due to carrier throttling, Azure Communication Services throughput limits, temporary network issues, or sending to an invalid/inactive phone number.
fix
Review best practices: implement retry logic with exponential backoff, send messages in batches, monitor ACS quotas, and ensure `from_` and `to` numbers are valid, mobile, and SMS-capable. Check if the recipient has opted out.
Upgrade
Version history
1.1.0latest on PyPI · released Oct 3, 2024
Audit
Dependencies
PythonrequiredRequires Python 3.8 or later.
azure-identityoptionalRequired for Azure Active Directory (AAD) authentication (e.g., DefaultAzureCredential).
azure-corerequiredCore Azure SDK functionalities.
Agent activity
46 hits · last 30 days
node
36
OpenAI (training)
1
Resources