Send messages from a CSV file using Kotlin

Table of contents

Introduction
Prerequisites
Set up a new Kotlin project
Add required dependencies
Create the CSV file
Create a file with the code
Replace the API token
Run the program
Conclusion

In this tutorial, you'll learn how to send messages to phone numbers stored in a CSV file using Kotlin and the Agent Connect API. We will read the phone numbers and messages from the CSV file, and then send them using the Agent Connect API.

This article is just a small taste of all the API features. Explore dozens of use cases and ready-to-use code examples here.

Prerequisites

Basic understanding of Kotlin
JDK 8 or higher installed on your computer
A text editor for writing code (e.g: IntelliJ IDEA, Visual Studio Code, Atom)
A Agent Connect API token (you can obtain this by signing up here)

Set up a new Kotlin project

Create a new Kotlin project using IntelliJ IDEA or your preferred text editor. For this tutorial, we will use a simple Kotlin script.

Add required dependencies

In your Kotlin project, create a new file named build.gradle.kts and add the following dependencies:

plugins {
    kotlin("jvm") version "1.6.0"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.github.kittinunf.fuel:fuel:2.3.1")
    implementation("com.github.tototoshi:scala-csv_2.13:1.3.6")
}

Sync your project with the Gradle configuration to download the necessary libraries.

Create the CSV file

Create a new file named numbers.csv in your project directory with two columns:

First column: phone number in E164 format with the country prefix.
Second column: text message to send to the target phone number.

The spreadsheet document should look like this:

Phone number	Message body
+1234567890	👋 Welcome to {{your-business-name}}! Thanks for signing up. We are just a message away!
+1234567890	💐 Your order has been shipped. Tracking number is {{tracking-number}}. Don't hesitate to reach out to if you need help! 🤗

The equivalent spreadsheet document exported as CSV should look like this:

+1234567890,"👋 Welcome to {{your-business-name}}! Thanks for signing up. We are just a message away!"
+1234567890,"💐 Your order has been shipped. Tracking number is {{tracking-number}}. Don't hesitate to reach out to if you need help! 🤗"

You can export any Office Excel or Google Sheets document as CSV file by following these instructions:

Create a file with the code

Create a new file named send_messages.kts in your project directory and add the following code:

import com.github.kittinunf.fuel.httpPost
import com.github.kittinunf.result.Result
import com.github.tototoshi.csv.CSVReader
import java.io.File

val csvFile = "numbers.csv"

// Replace this with your Agent Connect API token
val apiToken = "ENTER API KEY HERE"

// Optionally specify the target WhatsApp device ID connected to Agent Connect
// you want to use for messages delivery (24 characters hexadecimal value)
val device = "DEVICE ID GOES HERE" // or use null

val headers = mapOf(
    "Content-Type" to "application/json",
    "Authorization" to apiToken
)

val url = "https://api.agentconnect.chat/v1/messages"

fun send_message(phone: String, message: String) {
    val json = """
        {
            "phone": "$phone",
            "message": "$message",
            "device": "$device"
        }
    """.trimIndent()

    val (_, _, result) = url.httpPost()
        .body(json)
        .header(headers)
        .response()

    when (result) {
        is Result.Success -> println("=> Message created: $phone")
        is Result.Failure -> println("Failed to create message to $phone: ${result.error}")
    }
}

fun main() {
    val reader = CSVReader.open(File(csvFile))
    for (row in reader.all()) {
        val (phone, message) = row
        send_message(phone, message)
    }
    reader.close()
}

Play and run code in the cloud without installing any software in your computer. Create a free account in Replit and get started in minutes

Replace the API token

In the send_messages.kts file, make sure you have defined the API token of your actual Agent Connect account:

// Replace this with your Agent Connect API token
val apiToken = "ENTER API KEY HERE"

Optionally, if you have multiple WhatsApp numbers connected in your Agent Connect account, you can specify which WhatsApp number you want to use for the messages delivery by specifying the Agent Connect unique device ID (24 characters hexadecimal value) in the following line:

// Optionally specify the target WhatsApp device ID connected to Agent Connect
// you want to use for messages delivery (24 characters hexadecimal value)
val device = "DEVICE ID GOES HERE" // or use null

Run the program

Before running the program, if you plan to send hundreds of messages in a row, we recommend to define a lower messages delivery speed per minute no more than 2-3 messages per minute to prevent ban issues due to anti-spam policies by WhatsApp. Learn more about best practices and how to reduce risk here.

Open a terminal in your project directory and run the following command to execute the send_messages.kts script:

kotlinc -script send_messages.kts

If everything is set up correctly, you should see output indicating the messages have been created successfully:

=> Message created: +1234567890
=> Message created: +1234567890
=> Message created: +1234567890

Note messages will be added to your number's message delivery queue and delivered asynchronously in background over time based on your number's subscription message delivery speed per minute limit or the manually configured delivery speed you have defined in your number's settings.

Messages may take several minutes or hours, depending on how much you have created, to be effectively delivered to the target phone numbers via WhatsApp. You can monitor the progress fo the messages delivery in the web panel or automatically by using webhook events.

Conclusion

In this tutorial, you learned how to send messages to phone numbers stored in a CSV file using Kotlin and the Agent Connect API.

You can update numbers.csv file and run the program again anytime you want to send new messages through your Agent Connect connected WhatsApp number.

You can further customize the script to handle additional columns, create different types of messages, or integrate it with your own software as needed.