Adding SMS Channel

Learn how to add the SMS channel to your application

1. Enable SMS channel in Novu Dashboard

   The SMS channel is not enabled by default. To use it, configure a provider like Twilio, Nexmo, or others, and ensure compliance with country-specific restrictions for sender IDs (from).

   1. Go to the Novu Dashboard and click “Integrations” on the left sidebar
   2. Click “Add a provider”
   3. Locate the SMS channel and select the provider you want to use and click “Next”
   4. Select for which environment you want to add the Provider
   5. (Optional) Add Conditions to activate the provider only under certain conditions, useful for tenant-based providers
   6. Click “Create”
   7. Add your SMS provider credentials:
      • From: Displayed as the sender of the SMS (ensure compliance with local regulations)
      • Provider-specific credentials such as API key / Auth token, Account SID, username, or password
   8. Save the configuration by clicking “Update”
2. Setup workflow with SMS channel in Novu Dashboard

   1. Go to the Novu Dashboard and click “Workflows” on the left sidebar.
   2. Click the “Add a Workflow” button.
   3. Add a step and select “SMS” as the channel.
   4. Configure the SMS content:
      • Message body (e.g., {{userName}}, your order {{orderId}} has shipped.).
      • Dynamic placeholders for personalized content.
   5. Optionally, set fallback channels to ensure reliable delivery if SMS fails.
3. Add a workflow trigger to your backend

   Novu’s server-side SDKs make integrating Novu’s REST APIs straightforward, letting you focus on implementing workflows without dealing with repetitive code.

   Server-side SDKs
4. Test and verify SMS channel

   Ensure your SMS configuration is working correctly by testing the setup.

   1. Go to the Novu Dashboard, navigate to the “Workflows” section, and locate your configured workflow.
   2. Click “Test Workflow” and provide sample data, such as a phone number or dynamic variables.
   3. Verify delivery in the Novu Logs or your SMS provider’s dashboard.

Some countries have strict restriction of using verified from sender id (name). Kindly check country and provider specific requirements first.

Sending SMS overrides

The overrides field supports a sms property and from, to, content field overrides. This allows you to send a message to a different recipient, from a different sender, or with a different content.

import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  }
  overrides: {
    sms: {
      to: '[phone]',
      from: 'Novu Team',
      content: 'This SMS message is from overrides'
    },
  },
});

Using different SMS integration

In Novu integration store, multiple SMS channel type provider integrations can be active at the same time. But only one provider integration can be primary at a time. This primary integration will be used as a provider to deliver the SMS by default. If you want to use a different active provider integration then you can use the integrationIdentifier sms overrides field.

If there are 4 active SMS integrations with these identifiers:-

1. twilio-abcdef
2. twilio-ghijkl
3. firetext-abcdef
4. infobip-abcdef

Here, if twilio-abcdef is primary integration and you want to use infobip-abcdef with this trigger then you can use integrationIdentifier sms overrides field as below:-

Node.js

import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  overrides: {
    sms: {
      integrationIdentifier: 'infobip-abcdef',
    },
  },
});

import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  overrides: {
    sms: {
      integrationIdentifier: 'infobip-abcdef',
    },
  },
});

Integration identifier is similar to Provider identifier but it is different than Provider Id. It is unique for each integration. You can find the integrationIdentifier in the integration store page.

Common errors

Common errors and reason for these errors while sending sms messages using Novu.

1. Subscriber does not have a configured channel.
   • if the from field is missing / null / undefined.

Are we missing a provider you'd like to use for SMS channel? Please consider adding a new feature request on github or help us upvoting the existing ones on our public roadmap