Twilio SMS Integration with Novu

You can utilize the Twilio API to communicate with your customers using SMS messaging. Let’s look at how you can do that:

Setting up Twilio

Create a Twilio Account

Go to Twilio and create an account, starting with their free trial.
You’ll be asked to verify your email and your phone number. Get them verified.

Get a Twilio Phone Number

Once verified, you’ll get an option to ‘get a Twilio phone number’ from your Twilio console.
Click on it to get your Twilio phone number.

When first using Twilio there should be an option to get a Twilio phone number in the main console. Otherwise, you may have to Buy a number to begin using it. For first-time users, utilize the free number provided.

For more detailed instructions, follow one of their many Tutorials within their docs.

Understand the Key Components

Irrespective of the language you use, the process requires:

Account SID and Auth token loaded into the code using secure environment variables
A Twilio client object that takes the SID and Token as variables
A message object containing:

Your Twilio phone number
- The recipient’s phone number
- The SMS message body

Creating a Twilio integration with Novu

Connect Twilio to Novu

Visit the Integrations Store on Novu
Click the “Add a provider” button
Locate Twilio and click on the Disabled button and mark it as Active
Click on the Connect button

Configure Twilio Credentials

Go to your Console on Twilio and access the Account Info section
Enter your:
- Account SID
- Authentication method — keep Auth token, or select API key to use a Twilio API key
- Auth Token
- Twilio Phone Number
- Data residency region (optional) — leave as US (default) unless your Twilio account uses EU data residency
Click on the Save button

Authenticate with an API key

Use a Twilio API key instead of your account Auth Token when you do not want to share the Auth Token with Novu. You can revoke an API key at any time without affecting other apps that use your Twilio account.

Create an API key in Twilio

In the Twilio Console, go to Account > API keys & tokens and create an API key. A Restricted key needs only permission to create messages. Copy the key’s SID (starts with SK) and Secret. Twilio shows the secret only once.

Select API key in Novu

In your Twilio integration, set Authentication method to API key, then enter your Account SID, API Key SID, and API Key Secret. Novu removes the stored Auth Token when you save.

API keys belong to a Twilio region. If you use EU (Ireland) as the data residency region, create the API key in the IE1 region.

To configure API key authentication through the Novu API, set authMethod to apiKey and send the key in apiKey (API Key SID) and secretKey (API Key Secret) inside credentials. Novu does not store token in this mode. To use the Auth Token, leave authMethod out.

Multi-region data residency

Twilio supports processing and storing SMS data in specific regions. Novu lets you choose the API region when connecting your Twilio integration.

Region	Twilio region	When to use
US (default)	US1	Existing Twilio accounts and US-based data residency
EU (Ireland)	IE1	EU data residency for SMS (phone numbers, message bodies, and related personal data processed in Ireland)

EU data residency requires IE1-specific credentials from the Twilio Console and senders configured for the IE1 region. See Twilio’s Messaging API with Twilio Regions guide for setup details.

Configure EU data residency

Create IE1 API credentials

In the Twilio Console, create API credentials for the IE1 region. Use those credentials in your Novu Twilio integration instead of your US credentials.

Configure senders for IE1

If you send with phone numbers, set each number’s active messaging region to IE1 in the Twilio Console under Numbers & Senders.

Select EU in Novu

When connecting or updating your Twilio integration in Novu, set Data residency region to EU (Ireland) and save your IE1 credentials.

Sending WhatsApp message

To send WhatsApp messages with Twilio integration, prefix the phone number of the subscriber with whatsapp: as shown below:

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

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "subscriberId",
    phone: "whatsapp:+14155238886", },
  payload: {},
  overrides: {
    "providers": {
        "twilio": {
            "_passthrough": {
                "body": {
                    "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                    "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                }
            }
        }
    }
},
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId", "phone": "whatsapp:+14155238886"},
        payload={},
        overrides={
        "providers": {
                "twilio": {
                        "_passthrough": {
                                "body": {
                                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                                }
                        }
                }
        }
},
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
            Phone: novugo.String("whatsapp:+14155238886"),
    }),
    Payload: map[string]any{},
    Overrides: map[string]any{
    "providers": {
        "twilio": {
            "_passthrough": {
                "body": {
                    "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                    "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                }
            }
        }
    }
},
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId', phone: 'whatsapp:+14155238886'),
        payload: {},
        overrides: {
        "providers": {
                "twilio": {
                        "_passthrough": {
                                "body": {
                                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                                }
                        }
                }
        }
},
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "subscriberId", Phone = "whatsapp:+14155238886" }),
    Payload = {},
    Overrides = {
    "providers": {
        "twilio": {
            "_passthrough": {
                "body": {
                    "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                    "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                }
            }
        }
    }
},
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").phone("whatsapp:+14155238886").build()))
        .payload({})
        .overrides({
        "providers": {
                "twilio": {
                        "_passthrough": {
                                "body": {
                                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                                }
                        }
                }
        }
})
        .build())
    .call();

curl --location 'https://api.novu.co/v1/events/trigger' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId",
        "phone": "whatsapp:+14155238886"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "twilio": {
                "_passthrough": {
                    "body": {
                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                    }
                }
            }
        }
    }
}'

Sending WhatsApp template message

To send WhatsApp template messages with Twilio integration, you can use the template field in the overrides object.

import { Novu } from "@novu/api";

const novu = new Novu({ 
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
    phone: "whatsapp:+14155238886",
  },
  payload: {},
  overrides: {
    providers: {
      twilio: {
        "_passthrough": {
          "body": {
            "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
            "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
          }
        }
      }
    }
  }
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId", "phone": "whatsapp:+14155238886"},
        payload={},
        overrides={
            "providers": {
                "twilio": {
                    "_passthrough": {
                        "body": {
                            "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                            "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                        }
                    }
                }
            }
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
        Phone: novugo.String("whatsapp:+14155238886"),
    }),
    Payload: map[string]any{},
    Overrides: map[string]any{
        "providers": map[string]any{
            "twilio": map[string]any{
                "_passthrough": map[string]any{
                    "body": map[string]any{
                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}",
                    },
                },
            },
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId', phone: 'whatsapp:+14155238886'),
        payload: [],
        overrides: [
            'providers' => [
                'twilio' => [
                    '_passthrough' => [
                        'body' => [
                            'contentSid' => 'HXb5b62575e6e4ff6129ad7c8efe1f983e',
                            'contentVariables' => '{"1":"12/1","2":"3pm"}',
                        ],
                    ],
                ],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "subscriberId", Phone = "whatsapp:+14155238886" }),
    Payload = new Dictionary<string, object>(),
    Overrides = new Overrides() {
        Providers = new Dictionary<string, Dictionary<string, object>>() {
            { "twilio", new Dictionary<string, object>() {
                { "_passthrough", new Dictionary<string, object>() {
                    { "body", new Dictionary<string, object>() {
                        { "contentSid", "HXb5b62575e6e4ff6129ad7c8efe1f983e" },
                        { "contentVariables", "{\"1\":\"12/1\",\"2\":\"3pm\"}" },
                    } },
                } },
            } },
        },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").phone("whatsapp:+14155238886").build()))
        .overrides(TriggerEventRequestDtoOverrides.builder()
            .additionalProperties(Map.of("providers", Map.of("twilio", Map.of(
                "_passthrough", Map.of("body", Map.of(
                    "contentSid", "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                    "contentVariables", "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                ))
            ))))
            .build())
        .build())
    .call();

curl --location 'https://api.novu.co/v1/events/trigger' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId",
        "phone": "whatsapp:+14155238886"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "twilio": {
                "_passthrough": {
                    "body": {
                        "contentSid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
                        "contentVariables": "{\"1\":\"12/1\",\"2\":\"3pm\"}"
                    }
                }
            }
        }
    }
}'

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Twilio SMS Integration with Novu

Setting up Twilio

Creating a Twilio integration with Novu

Authenticate with an API key

Multi-region data residency

Configure EU data residency

Sending WhatsApp message

Sending WhatsApp template message

​Setting up Twilio

​Creating a Twilio integration with Novu

​Authenticate with an API key

​Multi-region data residency

​Configure EU data residency

​Sending WhatsApp message

​Sending WhatsApp template message

Setting up Twilio

Creating a Twilio integration with Novu

Authenticate with an API key

Multi-region data residency

Configure EU data residency

Sending WhatsApp message

Sending WhatsApp template message