@airhornjs/twilio


tests codecov license npm npm

@airhornjs/twilio

Twilio SMS and SendGrid Email provider for the Airhorn notification system.

Installation

npm install airhorn @airhornjs/twilio
    

Features

  • SMS sending via Twilio API
  • Email sending via SendGrid API
  • Automatic error handling and retry support
  • Integration with Airhorn's notification system

Usage

SMS with Twilio

import { Airhorn } from 'airhorn';
    import { AirhornTwilio } from '@airhornjs/twilio';
    
    // Create Twilio provider for SMS only
    const twilioProvider = new AirhornTwilio({
      accountSid: 'your-account-sid',
      authToken: 'your-auth-token',
    });
    
    // Create Airhorn instance with Twilio provider
    const airhorn = new Airhorn({
      providers: [twilioProvider],
    });
    
    // Send SMS
    const message = {
      from: '+1234567890',
      content: 'Hello John!, your order #12345 has been shipped!',
      type: AirhornProviderType.SMS,
    };
    
    const result = await airhorn.send(
      '+0987654321', // to
      message,
    );
    

Email with SendGrid

import { Airhorn } from 'airhorn';
    import { TwilioProvider } from '@airhornjs/twilio';
    
    // Create Twilio provider with SendGrid support
    const twilioProvider = new TwilioProvider({
      accountSid: 'your-account-sid',
      authToken: 'your-auth-token',
      sendGridApiKey: 'your-sendgrid-api-key', // Enables email support
    });
    
    // Create Airhorn instance
    const airhorn = new Airhorn({
      providers: [twilioProvider],
    });
    
    // Send Email
    const message = {
      from: '[email protected]',
      subject: 'Order Confirmation',
      content: '

Hello John

Your order #656565 has been confirmed!

'
, type: AirhornProviderType.Email, }; const result = await airhorn.send( '[email protected]', // to message, );

Both SMS and Email

When configured with both Twilio and SendGrid credentials, the provider supports both SMS and email notifications:

const provider = new TwilioProvider({
      // Twilio SMS configuration
      accountSid: 'your-account-sid',
      authToken: 'your-auth-token',
      
      // SendGrid Email configuration
      sendGridApiKey: 'your-sendgrid-api-key',
      
      // Optional Twilio configuration
      region: 'sydney',
      edge: 'sydney',
    });
    
    // Provider capabilities will include both 'sms' and 'email'
    console.log(provider.capabilities); // ['sms', 'email']
    

Configuration

AirhornTwilioOptions

  • accountSid (required): Your Twilio Account SID
  • authToken (required): Your Twilio Auth Token
  • sendGridApiKey (optional): Your SendGrid API key (enables email support)
  • region (optional): Twilio region
  • edge (optional): Twilio edge location

Additional Options

You can pass additional provider-specific options as the second parameter to the send method:

Twilio SMS Options

await airhorn.send(to, message, {
      statusCallback: 'https://example.com/callback',
      maxPrice: '0.50',
      validityPeriod: 14400,
      // ... other Twilio message options
    });
    

SendGrid Email Options

await airhorn.send(to, message, {
      replyTo: '[email protected]',
      categories: ['transactional', 'order-confirmation'],
      trackingSettings: {
        clickTracking: { enable: true },
        openTracking: { enable: true },
      },
      // ... other SendGrid mail options
    });
    

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.

Licensing and Copyright

This project is MIT License © Jared Wray