What This Skill Does
The Azure Communication SMS Java skill enables AI agents to send text messages programmatically using Microsoft's Azure Communication Services. This skill provides a comprehensive interface for sending SMS messages to single or multiple recipients, tracking delivery status, and managing bulk messaging campaigns.
Built on the official Azure Communication SMS SDK for Java, this skill handles everything from basic one-time password delivery to complex multi-recipient marketing campaigns. It includes robust error handling, delivery reporting via Event Grid integration, and support for both synchronous and asynchronous operations.
Whether you need to send authentication codes, shipping notifications, appointment reminders, or emergency alerts, this skill provides the infrastructure to deliver messages reliably at scale while maintaining detailed tracking and reporting capabilities.
Getting Started
Before using this skill, you'll need an Azure Communication Services resource with an active phone number. The skill supports three authentication methods: DefaultAzureCredential for managed identities, connection strings for quick setup, or AzureKeyCredential for explicit access keys.
Add the dependency to your Maven project to access the SMS client functionality. The skill initializes with your resource endpoint and credentials, creating either a synchronous client for straightforward operations or an async client for high-throughput scenarios.
Environment variables help manage configuration across development and production environments. Store your endpoint URL, connection string, and sender phone number in environment variables rather than hardcoding them in your application logic.
The SDK handles phone number formatting validation, rate limiting responses, and network retry logic automatically. Your application code focuses on message content and recipient management while the underlying client handles protocol details.
Key Features
Single and Bulk Messaging — Send messages to individual recipients with simple method calls, or dispatch to multiple phone numbers in a single request. Bulk operations return individual results for each recipient, allowing granular success tracking even when some deliveries fail.
Delivery Reporting — Enable delivery reports through SmsSendOptions to receive real-time status updates via Azure Event Grid. Track when messages are delivered, failed, or queued, correlating events back to your original send requests using message IDs and custom tags.
Custom Tagging — Attach metadata tags to messages for campaign tracking, correlation with business transactions, or analytics grouping. Tags flow through to delivery reports, enabling sophisticated tracking across your messaging infrastructure.
Error Handling — Individual message failures return structured error information without throwing exceptions, allowing your code to process successful sends while handling failures gracefully. Request-level errors like authentication failures or network issues throw HttpResponseException for appropriate catch handling.
Async Operations — Process high message volumes without blocking threads using the async client. Chain reactive operations, handle backpressure naturally, and integrate with reactive frameworks for scalable messaging architectures.
Usage Examples
Sending a verification code demonstrates the simplest use case. Provide your ACS phone number as sender, the recipient's number in E.164 format, and your message content. The result object indicates success and provides a unique message ID for tracking.
Multi-recipient campaigns use the batch send method with a list of phone numbers. Enable delivery reports and add campaign tags to track performance. Iterate through results to identify which recipients received messages successfully and which require retry or alternative contact methods.
Async clients support reactive programming patterns. Subscribe to send operations with success and error handlers, allowing your application to continue processing while messages dispatch in the background. Chain multiple async operations together for complex workflows.
Response handling extracts HTTP status codes and headers when you need detailed protocol information. Check individual SmsSendResult objects for per-recipient success status, error messages, and HTTP status codes specific to each delivery attempt.
Best Practices
Always format phone numbers in E.164 international format with country code prefix. Invalid formats cause delivery failures that waste quota and create poor user experiences. Validate numbers before sending or handle format errors gracefully in your error handling code.
Enable delivery reports for critical messages like authentication codes or transaction confirmations. The small overhead of Event Grid processing ensures you can track successful delivery and retry failures appropriately. Less critical bulk messages can skip delivery reports to reduce processing costs.
Use custom tags to correlate messages with business context. Tag messages with order IDs, campaign identifiers, or user session tokens so delivery reports and analytics tie back to your application's business logic. This enables sophisticated tracking without maintaining separate correlation databases.
Implement exponential backoff for rate limit responses. When you receive HTTP 429 status codes, wait before retrying rather than immediately resending. This prevents cascading failures and respects service quotas while ensuring messages eventually deliver.
Batch multiple recipients into single requests rather than sending individual messages in loops. Batch operations reduce network overhead, improve throughput, and provide more efficient quota usage. Process results individually to maintain granular error handling benefits.
When to Use This Skill
Use this skill when your Java application needs reliable SMS delivery with detailed tracking. Authentication systems sending one-time passwords, e-commerce platforms dispatching shipping notifications, or appointment scheduling systems sending reminders all benefit from programmatic SMS capabilities.
Marketing campaigns targeting mobile audiences leverage bulk send capabilities for efficient multi-recipient messaging. Customer service systems use SMS for proactive updates about service issues, account changes, or billing notifications.
Time-sensitive alerts like security notifications, emergency warnings, or critical system status updates benefit from SMS's high engagement rates compared to email. Most users read text messages within minutes of receipt, making SMS ideal for urgent communications.
When NOT to Use This Skill
Avoid SMS for long-form content or detailed instructions that exceed character limits. Email or push notifications serve better for content-rich communications. SMS works best for brief, actionable messages that users can read and respond to quickly.
Don't use SMS as your only communication channel for important information. Users may change phone numbers, experience service disruptions, or have messaging disabled. Implement fallback channels and preference management for robust communication strategies.
Skip delivery reports for high-volume, low-criticality messages like general announcements or promotional blasts where individual delivery tracking doesn't justify the processing overhead. Monitor aggregate delivery rates instead of per-message status.
Related Skills
Explore azure-communication-email-java for sending formatted email messages with attachments when SMS's character limits prove too restrictive.
Check azure-eventgrid-java for processing delivery report events and integrating SMS status updates into your application's event-driven architecture.
Consider azure-identity-java for managing authentication credentials securely across your Azure services, including Communication Services resources.
Source
Provider: Microsoft
Category: Cloud & Azure
Package: com.azure:azure-communication-sms
Official Documentation: Azure Communication SMS SDK for Java