@airhornjs/azure

Azure Communication Services and Notification Hubs provider for Airhorn.

How to Contribute
Licensing and Copyright

Installation

npm install airhorn @airhornjs/azure

Features

SMS sending via Azure Communication Services
Email sending via Azure Communication Services
Mobile push notifications to iOS and Android devices via Azure Notification Hubs
Automatic error handling and retry support
Integration with Airhorn's notification system
Support for multiple connection strings

Usage

SMS with Azure Communication Services

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornAzure } from '@airhornjs/azure';

// Create Azure provider for SMS
const azureProvider = new AirhornAzure({
  connectionString: 'endpoint=https://your-service.communication.azure.com/;accesskey=your-key',
});

// Create Airhorn instance with Azure provider
const airhorn = new Airhorn({
  providers: [azureProvider],
});

const data = {
  orderId: '12345',
  customerName: 'John',
};

// The template is the content of the message
const template = {
  content: 'Hello <%= customerName %>!, your order #<%= orderId %> has been shipped!',
};

// Send SMS — the sender is part of the send call
const result = await airhorn.send(
  '+0987654321', // to
  template,
  data,
  AirhornSendType.SMS,
  { from: '+1234567890' }, // Your sender phone number (must be provisioned in Azure)
);

Email with Azure Communication Services

import { Airhorn } from 'airhorn';
import { AirhornAzure } from '@airhornjs/azure';

// Create Azure provider with email support
const azureProvider = new AirhornAzure({
  connectionString: 'endpoint=https://your-service.communication.azure.com/;accesskey=your-key',
});

// Create Airhorn instance
const airhorn = new Airhorn({
  providers: [azureProvider],
});

const data = {
  orderId: '656565',
  customerName: 'John',
};

// Send Email
const template = {
  subject: 'Order Confirmation: <%= orderId %>',
  content: 'Hi <%= customerName %>, your order #<%= orderId %> has been confirmed!',
};

const result = await airhorn.send(
  '[email protected]', // to
  template,
  data,
  AirhornSendType.Email,
  { from: '[email protected]' }, // Must be verified domain in Azure
);

The sender can also be set on the template itself (template.from) — options.from on the send call takes precedence.

Mobile Push Notifications with Azure Notification Hubs

import { Airhorn } from 'airhorn';
import { AirhornAzure } from '@airhornjs/azure';

const azureProvider = new AirhornAzure({
  notificationHubConnectionString: 'Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=DefaultFullSharedAccessSignature;SharedAccessKey=your-key',
  notificationHubName: 'your-hub-name',
});

const airhorn = new Airhorn({
  providers: [azureProvider],
});

const data = {
  orderId: '12345',
  customerName: 'John',
};

// Send to iOS device via APNs — the template is the content of the notification
const template = {
  content: JSON.stringify({
    aps: {
      alert: {
        title: 'New Order',
        body: 'Hi <%= customerName %>, you have a new order #<%= orderId %>',
      },
      badge: 1,
      sound: 'default',
    },
    // Custom data
    orderId: '12345',
  }),
};

// Send using tag expression
await airhorn.send(
  'user:john-doe', // Tag expression
  template,
  data,
  AirhornSendType.MobilePush,
  {
    from: 'YourApp',
    platform: 'apple',
    tags: 'user:john-doe && ios',
  },
);

Custom Capabilities

You can specify which services to enable using the capabilities option:

// SMS only
const smsProvider = new AirhornAzure({
  connectionString: 'your-connection-string',
  capabilities: [AirhornSendType.SMS],
});

// Email only
const emailProvider = new AirhornAzure({
  connectionString: 'your-connection-string',
  capabilities: [AirhornSendType.Email],
});

// Mobile Push only
const pushProvider = new AirhornAzure({
  notificationHubConnectionString: 'your-hub-connection-string',
  notificationHubName: 'your-hub-name',
  capabilities: [AirhornSendType.MobilePush],
});

// All capabilities (explicit)
const allProvider = new AirhornAzure({
  connectionString: 'your-communication-services-connection-string',
  notificationHubConnectionString: 'your-hub-connection-string',
  notificationHubName: 'your-hub-name',
  capabilities: [AirhornSendType.SMS, AirhornSendType.Email, AirhornSendType.MobilePush],
});

Configuration

AirhornAzureOptions

connectionString (optional): Azure Communication Services connection string (used for both SMS and Email if specific strings not provided)
emailConnectionString (optional): Specific connection string for Email service
smsConnectionString (optional): Specific connection string for SMS service
notificationHubConnectionString (optional): Azure Notification Hub connection string
notificationHubName (optional): Azure Notification Hub name
capabilities (optional): Array of AirhornSendType values to specify which services to enable (defaults to SMS, MobilePush, and Email)

Additional Options

For provider-specific options, call the provider directly with a message — the second parameter is passed through to Azure:

SMS Options

await azureProvider.send(message, {
  // Additional SMS options from Azure Communication Services
  deliveryReportTimeoutInSeconds: 300,
  tag: 'custom-tag',
});

Prerequisites

Azure Communication Services

Create an Azure Communication Services resource in Azure Portal
Get your connection string from the resource
For SMS: Provision a phone number through the Azure Portal
For Email: Verify your sending domain

Azure Notification Hubs

Create a Notification Hub namespace and hub in Azure Portal
Configure platform credentials (APNs for iOS, FCM for Android)
Get your connection string and hub name
Implement device registration in your mobile apps

Azure RBAC Permissions

Minimum required permissions for the service principal or managed identity:

For Communication Services:

Azure Communication Services Contributor role
Or specific permissions:
- Microsoft.Communication/CommunicationServices/read
- Microsoft.Communication/CommunicationServices/write

For Notification Hubs:

Azure Notification Hubs Contributor role
Or specific permissions:
- Microsoft.NotificationHubs/Namespaces/NotificationHubs/read
- Microsoft.NotificationHubs/Namespaces/NotificationHubs/write

Testing

pnpm test

How to Contribute

Now that you've set up your workspace, you're ready to contribute changes to the airhorn repository you can refer to the CONTRIBUTING guide. If you have any questions please feel free to ask by creating an issue and label it question.