Kotlin quickstart

Learn how to integrate Novu into your Kotlin project on the fly and send notifications across different channels (SMS, Email, Chat, Push).

Let’s get started! 💪

​

Requirements

To be able to use this Quickstart, you would need to have the following:

• A Novu account, if you don’t have one yet, sign up for free.
• A working Kotlin project running version 1.6.0+ and Kotlin compiler 1.8.0+.

The completed code for this quick start is available on GitHub. Check it out here.

​

Install and Set up the Novu Kotlin SDK in your project

First, you need to import the library into your application.

If you use Maven, add the dependency to the pom.xml file;

<dependency>
  <groupId>co.novu</groupId>
  <artifactId>novu-kotlin</artifactId>
  <version>{use-latest-version}</version>
</dependency>

The latest version can be found on GitHub.

If you use Gradle, add the dependency to the build.gradle file;

implementation 'co.novu:novu-kotlin:{use-latest-version}' //Groovy

implementation ("co.novu:novu-kotlin:{use-latest-version}") //Kotlin

Sync your project, and you should have the artifacts downloaded.

To use the SDK, you need to have your API key handy, it can be gotten from the settings page of the web portal.

To initialize the library, you can create an instance of Novu.kt class using any of the following constructors:

//Using the API Key only
val novu = Novu(apiKey = "API_KEY")

//Using the API Key plus an instance of NovuConfig
val novuConfig = NovuConfig(backendUrl = "URL")
val novu = Novu(apiKey = "API_KEY", config = novuConfig)

Once that is done successfully, head over to the web portal for the next steps.

​

Set up a Channel Provider

A channel provider is a service that provides one or more notification functionality such as sending an email, SMS, push notification, etc. Our integration store includes four channels: Email, SMS, Chat, and Push. These channels have multiple providers associated with them.

Only one provider can be active per channel. Connect any of your favourite providers to get started. The email channel comes with Novu’s email provider, which is active by default and includes 300 credits.

​

Create a Workflow

A workflow is a blueprint for the notifications that will be sent. It holds the entire flow of messages sent to the subscriber. This is where all the different channels are tied together under a single entity.

The workflow includes the following:

• Workflow name and Identifier.
• Channel-tailored content:

Please proceed to create a workflow.

1. Click Workflows on the left sidebar of your Novu dashboard.
2. Click the Create Workflow button on the top right.

3. The name of the new workflow is currently Untitled, rename it to a more suitable title.

4. Select Email as the channel you want to add, by dragging it from the right sidebar.

5. Click on the Email in the workflow and edit it as per this image. Don’t forget to add the fields in the editor which is supposed to be updated with dynamic values that will be sent when calling the API.

6. Also, add the variables in the Variables section in the test tab and try testing it by sending the email to your email address using the Send Test Email button at the bottom right.

You should get an email within seconds! 👌

Great, you have successfully sent your first notification via the Novu dashboard! Now, let’s take a step further to trigger notifications via code.

​

Create a Subscriber and Update a Subscriber’s information

The recipients of a triggered notification are called subscribers.

Click Subscribers on the left sidebar of the Novu dashboard to see all subscribers. By default, the dashboard will display a subscriber, as you were added automatically during sign-up.

Now, let’s create a subscriber on Novu. Copy and paste the following code to do so:

suspend fun createSubscriber(): ResponseWrapper<SubscriberResponse>? {
        val novu = Novu(apiKey = "API_KEY")
        val subscriberRequest = SubscriberRequest(
            email = "email@sample.com",
            firstName = "John",//optional
            lastName = "Doe",//optional
            phone = "123456789",//optional
            avatar = "sample-avatar",//optional
            subscriberId = "12345"//optional
        )
        return CoroutineScope(Dispatchers.IO).async {
            novu.createSubscriber(subscriberRequest)
        }.await()
    }

When you run this code snippet, you should see the subscriber on your Novu dashboard. 👤

Now, let’s assume you want to modify the email address of the Subscriber you just created, you can do that with the following code:

suspend fun updateSubscriber(): ResponseWrapper<SubscriberResponse>? {
        val novu = Novu(apiKey = "API_KEY")
        val subscriberRequest = UpdateSubscriberRequest(
            email = "validemail@sample.com",
            firstName = "John",//optional
            lastName = "Doe",//optional
            phone = "123456789",//optional
            avatar = "sample-avatar"//optional
        )
        val subscriberId = "12345"
        return CoroutineScope(Dispatchers.IO).async {
            novu.updateSubscriber(subscriberId, subscriberRequest)
        }.await()
    }

Other valid fields that can be updated are phone, avatar, and data. The data field can accept an Object or a Map with the info you want to attach to the subscriber.

​

Trigger a Notification

Copy and paste the following code into your app to trigger a notification to a Subscriber:

suspend fun triggerNotification(): Any? {
        val novu = Novu(apiKey = "API_KEY")
        val triggerEventRequest = TriggerEventRequest(
            name = "test",
            to = SubscriberRequest(
                subscriberId = "12345",
                email = "email@email.com",
                firstName = "John",
                lastName = "Doe"
            ),
            payload = mapOf("customVariables" to "Hello")
        )

        return CoroutineScope(Dispatchers.IO).async {
            novu.trigger(triggerEventRequest)
        }.await()
    }

Before running the code, make sure you understand the following:

• The value of payload is an array of the data that you want to be dynamically injected into the workflow content.
• The value of subscriberId is the ID of the subscriber on Novu. Replace 12345 with your subscriber ID.

Run the code to trigger a notification! 📧

​

Topics

Novu provides a simple API that offers an easy interface for triggering notifications to multiple subscribers at once. This API is called Topics and allows users to manage their bulk notifications without having to implement complex loops. A topic is identified by a custom key that is provided by the user, and this key will be the identifier used in the Topics API.

A topic can have multiple subscribers who will receive a notification whenever a message is sent to the topic.

​

Create a Topic

Copy and paste the following code into your app to create a topic:

suspend fun createTopic(): Any? {
        val novu = Novu(apiKey = "API_KEY")
        val createTopicRequest = CreateTopicRequest(
            key = "key",
            name = "name"
        )
        return CoroutineScope(Dispatchers.IO).async {
            novu.createTopic(createTopicRequest)
        }.await()
    }

Before running the code, make sure you understand the following:

• When creating a key, ensure it is unique and accurately identifies the topic. Document naming conventions and communicate them to team members to avoid confusion and ensure a smooth workflow.
• The value of name should be a descriptive topic name.

​

Add subscribers to a Topic

Copy and paste the following code into your app to add subscribers a topic:

suspend fun addSubscriberToTopic(): Any? {
        val novu = Novu(apiKey = "API_KEY")
        val topicKey = "key"
        val requestBody = SubscriberList(listOf("name"))
        return CoroutineScope(Dispatchers.IO).async {
            novu.addSubscribers(topicKey, requestBody)
        }.await()
    }

On the other hand, if you want to remove subscribers from a topic, do the following:

suspend fun removeSubscriberFromTopic(): Any? {
        val novu = Novu(apiKey = "API_KEY")
        val topicKey = "key"
        val requestBody = SubscriberList(listOf("name"))
        return CoroutineScope(Dispatchers.IO).async {
            novu.removeSubscriber(topicKey, requestBody)
        }.await()
    }

​

Sending a Notification to a Topic

Thanks to the topics feature, it is possible to trigger a notification to all subscribers assigned to a topic. This helps avoid listing all subscriber identifiers in the to field of the notification trigger.

To trigger a notification to all subscribers of a topic, copy and paste the code below:

suspend fun triggerNotificationToTopic(): Any? {
        val novu = Novu(apiKey = "NOVU_API_KEY")
        val triggerEventRequest = TriggerEventRequest(
                name = "test",
                to = listOf(
                        Topic(
                                type = "Topic",
                                topicKey = "posts:comment:12345"
                        )
                ),
                payload = mapOf("customVariables" to "Hello")
        )

        return CoroutineScope(Dispatchers.IO).async {
            novu.trigger(triggerEventRequest)
        }.await()
    }

​

Conclusion

Great job! 👏 If you’ve reached this point, you should have successfully created a subscriber, workflow, configured a channel provider, triggered a single notification, created a topic, and added a subscriber to a topic in your application.