Skip to content
Open
Show file tree
Hide file tree
Changes from 13 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 94 additions & 41 deletions content/docs/platform/integrations/sms/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,76 @@ description: "Configure and manage SMS notification providers like Twilio, Nexmo
icon: 'circle-info'
---

Novu makes SMS notifications simple, scalable, and reliable, enabling seamless integration with your communication stack. Whether you're sending OTPs, updates, or transactional messages, Novu ensures your SMS notifications are delivered efficiently and effectively.
The SMS channel delivers messages to your subscribers’ mobile devices through your configured SMS provider integrations.

With the SMS channel, you can:
## How SMS delivery works in Novu

- **Switch Providers Effortlessly:** Integrate popular services like Twilio, Nexmo, or a custom provider
- **Deliver at Scale:** Handle high-volume messaging with confidence
- **Customize and Track:** Tailor SMS content dynamically and monitor delivery status in real time
Here’s the typical flow for sending an email notification through Novu:

## Key Features
<Steps>
<Step>

- **Dynamic Messaging:** Inject user-specific data into messages for personalization
- **Multi-Provider Support:** Switch or combine providers to maximize reliability
- **Delivery Insights:** Track message delivery, failures, and user engagement
- **Fallback Mechanisms:** Ensure reliable messaging with backup providers
- **Template Management:** Simplify content creation with reusable SMS templates
- **Streamlined API Integration:** Easily connect your backend for automated messaging workflows
### Add an email provider

## Common Use Cases
Start by adding an SMS provider in the **Integration Store** on your Novu dashboard. You can connect one or more integrations for the different or the same providers.

- **Transactional Notifications:** Send OTPs, receipts, or order updates instantly
- **Marketing Campaigns:** Deliver promotional offers and updates to your audience
- **Critical Alerts:** Notify users of urgent events, like security breaches or system outages
- **Reminders and Scheduling:** Automate reminders for appointments, events, or deadlines
To learn [how to add an SMS provider](/platform/integrations/sms#supported-providers), refer to the guide for that provider.

</Step>
<Step>
### Add the email channel to your workflow

Next, include an [SMS step in your workflow](/platform/workflow/build-a-workflow). This step defines when and how an SMS should be sent as part of your notification workflow.
</Step>
<Step>
### Define the SMS content

## Sending SMS overrides
Within the Email step editor, write the message body. The editor supports dynamic data for personalized content.

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.
</Step>
<Step>
### Store subscriber phone number

Novu automatically sends the notification to the phone number stored on the subscriber's profile . You must ensure that this field is set for any subscriber who needs to receive emails. You can store subscribers phone number using the Novu API, or SDK.
</Step>
<Step>
### Trigger the workflow

[Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu.
Novu automatically:
- Resolves the subscriber.
- Selects the correct provider.
- Renders the email template.
- Delivers the message through the configured email integration.
</Step>
</Steps>
Comment on lines +8 to +50
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix systematic copy-paste errors: "email" should be "SMS" throughout the workflow steps.

The step-by-step workflow structure is excellent, but multiple instances incorrectly reference "email" instead of "SMS." These appear to be copy-paste errors from email integration documentation:

  • Line 12: "sending an email notification" → should be "SMS notification"
  • Line 17: "Add an email provider" → should be "SMS provider"
  • Line 25: "Add the email channel" → should be "SMS channel"
  • Line 32: "Within the Email step editor" → should be "SMS step editor"
  • Line 38: "receive emails" → should be "receive SMS"
  • Line 47: "Renders the email template" → should be "SMS template"
  • Line 48: "through the configured email integration" → should be "SMS integration"

Apply this diff to correct all references:

-Here's the typical flow for sending an email notification through Novu:
+Here's the typical flow for sending an SMS notification through Novu:

-### Add an email provider
+### Add an SMS provider

-### Add the email channel to your workflow
+### Add the SMS channel to your workflow

-Within the Email step editor, write the message body.
+Within the SMS step editor, write the message body.

-Novu automatically sends the notification to the phone number stored on the subscriber's profile . You must ensure that this field is set for any subscriber who needs to receive emails.
+Novu automatically sends the notification to the phone number stored on the subscriber's profile. You must ensure that this field is set for any subscriber who needs to receive SMS.

-Renders the email template.
-Delivers the message through the configured email integration.
+Renders the SMS template.
+Delivers the message through the configured SMS integration.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The SMS channel delivers messages to your subscribers’ mobile devices through your configured SMS provider integrations.
With the SMS channel, you can:
## How SMS delivery works in Novu
- **Switch Providers Effortlessly:** Integrate popular services like Twilio, Nexmo, or a custom provider
- **Deliver at Scale:** Handle high-volume messaging with confidence
- **Customize and Track:** Tailor SMS content dynamically and monitor delivery status in real time
Here’s the typical flow for sending an email notification through Novu:
## Key Features
<Steps>
<Step>
- **Dynamic Messaging:** Inject user-specific data into messages for personalization
- **Multi-Provider Support:** Switch or combine providers to maximize reliability
- **Delivery Insights:** Track message delivery, failures, and user engagement
- **Fallback Mechanisms:** Ensure reliable messaging with backup providers
- **Template Management:** Simplify content creation with reusable SMS templates
- **Streamlined API Integration:** Easily connect your backend for automated messaging workflows
### Add an email provider
## Common Use Cases
Start by adding an SMS provider in the **Integration Store** on your Novu dashboard. You can connect one or more integrations for the different or the same providers.
- **Transactional Notifications:** Send OTPs, receipts, or order updates instantly
- **Marketing Campaigns:** Deliver promotional offers and updates to your audience
- **Critical Alerts:** Notify users of urgent events, like security breaches or system outages
- **Reminders and Scheduling:** Automate reminders for appointments, events, or deadlines
To learn [how to add an SMS provider](/platform/integrations/sms#supported-providers), refer to the guide for that provider.
</Step>
<Step>
### Add the email channel to your workflow
Next, include an [SMS step in your workflow](/platform/workflow/build-a-workflow). This step defines when and how an SMS should be sent as part of your notification workflow.
</Step>
<Step>
### Define the SMS content
## Sending SMS overrides
Within the Email step editor, write the message body. The editor supports dynamic data for personalized content.
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.
</Step>
<Step>
### Store subscriber phone number
Novu automatically sends the notification to the phone number stored on the subscriber's profile . You must ensure that this field is set for any subscriber who needs to receive emails. You can store subscribers phone number using the Novu API, or SDK.
</Step>
<Step>
### Trigger the workflow
[Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu.
Novu automatically:
- Resolves the subscriber.
- Selects the correct provider.
- Renders the email template.
- Delivers the message through the configured email integration.
</Step>
</Steps>
The SMS channel delivers messages to your subscribers’ mobile devices through your configured SMS provider integrations.
## How SMS delivery works in Novu
Here’s the typical flow for sending an SMS notification through Novu:
<Steps>
<Step>
### Add an SMS provider
Start by adding an SMS provider in the **Integration Store** on your Novu dashboard. You can connect one or more integrations for the different or the same providers.
To learn [how to add an SMS provider](/platform/integrations/sms#supported-providers), refer to the guide for that provider.
</Step>
<Step>
### Add the SMS channel to your workflow
Next, include an [SMS step in your workflow](/platform/workflow/build-a-workflow). This step defines when and how an SMS should be sent as part of your notification workflow.
</Step>
<Step>
### Define the SMS content
Within the SMS step editor, write the message body. The editor supports dynamic data for personalized content.
</Step>
<Step>
### Store subscriber phone number
Novu automatically sends the notification to the phone number stored on the subscriber's profile. You must ensure that this field is set for any subscriber who needs to receive SMS. You can store subscribers phone number using the Novu API, or SDK.
</Step>
<Step>
### Trigger the workflow
[Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu.
Novu automatically:
- Resolves the subscriber.
- Selects the correct provider.
- Renders the SMS template.
- Delivers the message through the configured SMS integration.
</Step>
</Steps>
🤖 Prompt for AI Agents
In content/docs/platform/integrations/sms/index.mdx around lines 8 to 50,
multiple copy-paste references to "email" should be replaced with "SMS": change
"sending an email notification" to "sending an SMS notification", "Add an email
provider" to "Add an SMS provider", "Add the email channel" to "Add the SMS
channel", "Within the Email step editor" to "Within the SMS step editor",
"receive emails" to "receive SMS", "Renders the email template" to "Renders the
SMS template", and "through the configured email integration" to "through the
configured SMS integration" so all step text consistently refers to SMS rather
than email.


<Callout type="info">Some countries restrict using verified `from` sender IDs (name). Kindly check the country- and provider-specific requirements first.</Callout>

## Configuring SMS providers

To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that email providers.

### Default sender settings

The **From** field, which is displayed as the sender of the SMS, is a required default setting for any email provider that you connect. You can override this field during trigger if necessary.

### Provider authentication

You must provide credentials specific to your email provider, such as:
- API key
- Auth token
- Account SID
- Username
- Password.

Each provider has different requirements.

<Callout type="info"> Refer to the [supported SMS providers](/platform/integrations/sms#supported-providers) list for detailed setup guides for each provider integration.</Callout>
Comment on lines +54 to +73
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix copy-paste errors in configuration section: "email" should be "SMS".

Additional instances of "email" incorrectly used in the configuration section:

  • Line 56: "specific to that email providers" → should be "SMS providers"
  • Line 60: "any email provider that you connect" → should be "SMS provider"
  • Line 64: "your email provider" → should be "SMS provider"

Apply this diff:

-To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that email providers.
+To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that SMS provider.

-The **From** field, which is displayed as the sender of the SMS, is a required default setting for any email provider that you connect.
+The **From** field, which is displayed as the sender of the SMS, is a required default setting for any SMS provider that you connect.

-You must provide credentials specific to your email provider, such as:
+You must provide credentials specific to your SMS provider, such as:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Configuring SMS providers
To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that email providers.
### Default sender settings
The **From** field, which is displayed as the sender of the SMS, is a required default setting for any email provider that you connect. You can override this field during trigger if necessary.
### Provider authentication
You must provide credentials specific to your email provider, such as:
- API key
- Auth token
- Account SID
- Username
- Password.
Each provider has different requirements.
<Callout type="info"> Refer to the [supported SMS providers](/platform/integrations/sms#supported-providers) list for detailed setup guides for each provider integration.</Callout>
## Configuring SMS providers
To add an SMS provider from the **Integration Store**, you must configure settings and credentials that are specific to that SMS provider.
### Default sender settings
The **From** field, which is displayed as the sender of the SMS, is a required default setting for any SMS provider that you connect. You can override this field during trigger if necessary.
### Provider authentication
You must provide credentials specific to your SMS provider, such as:
- API key
- Auth token
- Account SID
- Username
- Password.
Each provider has different requirements.
<Callout type="info"> Refer to the [supported SMS providers](/platform/integrations/sms#supported-providers) list for detailed setup guides for each provider integration.</Callout>
🤖 Prompt for AI Agents
In content/docs/platform/integrations/sms/index.mdx around lines 54 to 73, there
are copy-paste errors using "email" instead of "SMS"; update the text to read:
"specific to that SMS provider" (line ~56), "any SMS provider that you connect"
(line ~60), and "your SMS provider" (line ~64), and adjust surrounding wording
for correct singular/plural agreement if needed.


## Override SMS settings

You can override the SMS settings when triggerring a notification by passing the `overrides` object. The overrides object field supports an `sms` property and `from`, `to`, and `content` field overrides. This lets you send a message to a different recipient, from a different sender, or with a different content.

```javascript
import { Novu } from '@novu/api';
Expand All @@ -49,7 +90,7 @@ await novu.trigger({
to: {
subscriberId: "subscriberId",
},
overrides: {
overrides: { // [!code ++:7]
sms: {
to: '+123012345678',
from: 'Novu Team',
Expand All @@ -59,18 +100,11 @@ await novu.trigger({
});
```

## 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.
## Target a specific provider

If there are 4 active SMS integrations with these identifiers:-
By default, Novu uses your primary SMS provider. If you want to bypass this and force a specific, active integration for a trigger, then use the `integrationIdentifier`.

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:-
This is useful if you have multiple active integrations for different purposes. For example, you might have one integration for transactional SMS and one for security SMS. You can find the `integrationIdentifier` in the **Integration Store** of the Novu dashboard.

<Tabs items={['Node.js']}>
<Tab value="Node.js">
Expand All @@ -89,7 +123,7 @@ await novu.trigger({
to: {
subscriberId: "subscriberId",
},
overrides: {
overrides: { // [!code ++:3]
sms: { integrationIdentifier: 'infobip-abcdef', },
},
});
Expand All @@ -98,13 +132,32 @@ await novu.trigger({
</Tab>
</Tabs>

<Callout type="info">
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.
</Callout>

## 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.
## Supported providers

Here are the SMS providers that are currently supported by Novu. Select any provider to see its detailed setup guide.

<Cards>
<Card title="46elks" href="/platform/integrations/sms/46elks"> Learn how to use the 46elks provider to send SMS notifications using Novu.</Card>
<Card title="Africa's Talking" href="/platform/integrations/sms/africas-talking"> Learn how to use the Africa's Talking provider to send SMS notifications using Novu.</Card>
<Card title="AWS SNS" href="/platform/integrations/sms/aws-sns"> Learn how to use the AWS SNS provider to send SMS notifications using Novu.</Card>
<Card title="Azure SMS" href="/platform/integrations/sms/azure-sms"> Learn how to use the Azure SMS provider to send SMS notifications using Novu.</Card>
<Card title="BulkSMS" href="/platform/integrations/sms/bulksms"> Learn how to use the BulkSMS provider to send SMS notifications using Novu.</Card>
<Card title="Clickatell" href="/platform/integrations/sms/clickatell"> Learn how to use the Clickatell provider to send SMS notifications using Novu.</Card>
<Card title="Clicksend" href="/platform/integrations/sms/clicksend"> Learn how to use the Clicksend provider to send SMS notifications using Novu.</Card>
<Card title="Firetext" href="/platform/integrations/sms/firetext"> Learn how to use the Firetext provider to send SMS notifications using Novu.</Card>
<Card title="Gupshup" href="/platform/integrations/sms/gupshup"> Learn how to use the Gupshup provider to send SMS notifications using Novu.</Card>
<Card title="Infobip - SMS" href="/platform/integrations/sms/infobip"> Learn how to use the Infobip - SMS provider to send SMS notifications using Novu.</Card>
<Card title="Kannel" href="/platform/integrations/sms/kannel"> Learn how to use the Kannel provider to send SMS notifications using Novu.</Card>
<Card title="Kudosity" href="/platform/integrations/sms/kudosity"> Learn how to use the Kudosity provider to send SMS notifications using Novu.</Card>
<Card title="MessageBird" href="/platform/integrations/sms/messagebird"> Learn how to use the MessageBird provider to send SMS notifications using Novu.</Card>
<Card title="Nexmo" href="/platform/integrations/sms/nexmo"> Learn how to use the Nexmo provider to send SMS notifications using Novu.</Card>
<Card title="Plivo" href="/platform/integrations/sms/plivo"> Learn how to use the Plivo provider to send SMS notifications using Novu.</Card>
<Card title="Sendchamp" href="/platform/integrations/sms/sendchamp"> Learn how to use the Sendchamp provider to send SMS notifications using Novu.</Card>
<Card title="SimpleTexting" href="/platform/integrations/sms/simpletexting"> Learn how to use the SimpleTexting provider to send SMS notifications using Novu.</Card>
<Card title="SMS Central" href="/platform/integrations/sms/sms-central"> Learn how to use the SMS Central provider to send SMS notifications using Novu.</Card>
<Card title="SMS77" href="/platform/integrations/sms/sms77"> Learn how to use the SMS77 provider to send SMS notifications using Novu.</Card>
<Card title="SNS" href="/platform/integrations/sms/sns"> Learn how to use the SNS provider to send SMS notifications using Novu.</Card>
<Card title="Telnyx" href="/platform/integrations/sms/telnyx"> Learn how to use the Telnyx provider to send SMS notifications using Novu.</Card>
<Card title="Termii" href="/platform/integrations/sms/termii"> Learn how to use the Termii provider to send SMS notifications using Novu.</Card>
<Card title="Twilio" href="/platform/integrations/sms/twilio"> Learn how to use the Twilio provider to send SMS notifications using Novu.</Card>
</Cards>
Comment on lines +135 to +163
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Supported providers gallery is comprehensive and well-organized.

The Cards component provides an excellent visual showcase of 25+ SMS providers with clear navigation. The consistent description format and href links create a usable provider directory.

Verify that all provider documentation pages linked in the href attributes (e.g., /platform/integrations/sms/46elks, /platform/integrations/sms/twilio) exist and are correctly named.


🏁 Script executed:

#!/bin/bash
# Description: Verify that all SMS provider documentation pages exist

# Extract all hrefs from the Supported providers section
provider_paths=$(grep -oP '(?<=href="/platform/integrations/sms/)[^"]+' content/docs/platform/integrations/sms/index.mdx)

# Check which provider pages exist
echo "Checking provider documentation pages..."
for provider in $provider_paths; do
  provider_file="content/docs/platform/integrations/sms/${provider}.mdx"
  if [ -f "$provider_file" ]; then
    echo "✓ Found: $provider"
  else
    echo "✗ Missing: $provider"
  fi
done

Length of output: 495


Looking at the verification results, I need to check if the provider documentation pages exist under a different directory structure or naming convention before finalizing the assessment.

Critical issue: All 23 SMS provider documentation pages are missing from the repository.

The Novu documentation includes all listed providers (46elks, Africa's Talking, AWS SNS, Azure SMS, BulkSMS, Clickatell, Clicksend, Firetext, Gupshup, Kannel, MessageBird, Nexmo, Plivo, Sendchamp, SimpleTexting, SMS Central, SMS77, SNS, Telnyx, Termii, Twilio, and others), however the corresponding .mdx source files do not exist in the content/docs/platform/integrations/sms/ directory. The index page contains href links to these provider pages, but the pages themselves need to be created or sourced from the main documentation repository.

Either:

  1. Create all missing provider documentation files, OR
  2. Remove the provider cards from index.mdx until the documentation pages are ready, OR
  3. Confirm these files are built/generated separately in the CI/CD pipeline

🏁 Script executed:

#!/bin/bash
# Search for any SMS provider documentation files in the codebase
# Check different possible locations and naming patterns

echo "Searching for provider documentation files..."
echo ""

# Check if provider pages exist in content/docs/platform/integrations/sms/ directory
echo "Files in content/docs/platform/integrations/sms/:"
if [ -d "content/docs/platform/integrations/sms/" ]; then
  find content/docs/platform/integrations/sms/ -type f -name "*.mdx" | sort
else
  echo "Directory not found"
fi

echo ""
echo "Searching for any files with provider names (case-insensitive):"
# Search for files containing provider names
for provider in "twilio" "nexmo" "aws-sns" "plivo"; do
  echo "Searching for '$provider'..."
  find content/docs -type f -name "*${provider}*" 2>/dev/null || echo "  (no matches)"
done

Length of output: 2078


Looking at the new results, the provider files exist in a (providers) subdirectory. I need to verify if the href links in index.mdx correctly match the actual provider filenames.


🏁 Script executed:

#!/bin/bash
# Extract all hrefs from index.mdx and compare with actual provider filenames

echo "Comparing index.mdx href links with actual provider files..."
echo ""

# Get hrefs from index.mdx
echo "href links from index.mdx:"
grep -oP '(?<=href="/platform/integrations/sms/)[^"]+' content/docs/platform/integrations/sms/index.mdx > /tmp/hrefs.txt
cat /tmp/hrefs.txt

echo ""
echo "Actual provider filenames (without .mdx extension):"
find content/docs/platform/integrations/sms/\(providers\)/ -type f -name "*.mdx" -exec basename {} .mdx \; | sort > /tmp/files.txt
cat /tmp/files.txt

echo ""
echo "Mismatches between href links and filenames:"
# Compare the two lists
comm -23 <(sort /tmp/hrefs.txt) <(sort /tmp/files.txt) | sed 's/^/  href link not found: /'
comm -13 <(sort /tmp/hrefs.txt) <(sort /tmp/files.txt) | sed 's/^/  file exists but not linked: /'

Length of output: 676


Fix 2 broken provider links in the Cards component.

Two href links in the index.mdx file do not match the actual provider documentation filenames:

  1. Line ~145 – Change href="/platform/integrations/sms/azure-sms" to href="/platform/integrations/sms/azure" (file is azure.mdx, not azure-sms.mdx)
  2. Line ~148 – Change href="/platform/integrations/sms/bulksms" to href="/platform/integrations/sms/bulk-sms" (file is bulk-sms.mdx, not bulksms.mdx)

All other 21 provider links match their corresponding .mdx files correctly.

🤖 Prompt for AI Agents
In content/docs/platform/integrations/sms/index.mdx around lines 135–163, two
Card hrefs point to incorrect filenames: update the Card with title "Azure SMS"
to use href="/platform/integrations/sms/azure" (file is azure.mdx) and update
the Card with title "BulkSMS" to use href="/platform/integrations/sms/bulk-sms"
(file is bulk-sms.mdx); change those two href attributes accordingly and leave
the other Card links unchanged.

2 changes: 1 addition & 1 deletion content/docs/platform/integrations/sms/meta.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"icon": "MessageCircle",
"pages": ["adding-sms", "..."]
"pages": ["(providers)"]
}