SenderLand API

The Senderland API provides a set of endpoints for managing WhatsApp accounts, sending messages, and handling application settings and databases. It also includes tools for containerized deployment and management via Docker Compose, making it easy to set up and run.

Table of Contents

• Getting Started
  • Startup Script
  • Environment Setup
• Authentication
• Endpoints
  • Add WhatsApp Account
  • Get Settings
  • Download Database
  • Send WhatsApp Message
• Swagger Documentation

To interact with the Senderland API, visit the Swagger UI for detailed documentation and try out the endpoints:

• Swagger UI: http://localhost:1321/apidocs

---

Getting Started

Startup Script

The project includes a startup script (start.sh) designed to simplify the initialization and management of the Senderland environment. The script handles setting up necessary directories, creating environment files, and managing Docker containers.

File Location: Ensure the script is in the root directory of the project.

Key Features:

1. Automatic Setup:
   • Ensures required directories (config, data) exist.
   • Creates or updates an .env file with essential variables.
2. Main Menu:
   • Options to start the project in different environments (e.g., production, development).
   • Utilities for listing and stopping running containers.
3. Profiles:
   • Profiles for prod, prod-c (console mode), and dev.
4. Docker Management:
   • Starts, stops, or runs containers interactively based on user input.

Running the Script:

Make the script executable:

chmod +x start.sh

Run the script:

./start.sh

---

Environment Setup

The script ensures an environment file (os_general.env) exists and populates it with necessary variables. Key variables include:

Variable	Description	Default Value
SENDERLAND_PATH	The root path of the Senderland project	Populated dynamically
OS_HOST	The operating system host type	Populated dynamically
UID	Current user ID	Populated dynamically
GID	Current group ID	Populated dynamically
USERNAME	Default API username	senderland
PASSWORD	Default API password	senderland
NAME_FILE_SETTINGS	Settings file name	settings.ini
NAME_FILE_SECRETS	Secrets file name	secrets.ini

---

Authentication

All API endpoints require Basic Authentication. The credentials are defined in the secrets.ini file under the api_secret_admin section.

Example Credentials:

• Username: senderland
• Password: senderland

Include these credentials in the Authorization header of your API requests.

---

Endpoints

1. POST /add_account_whatsapp

Description: Adds a new WhatsApp account to the system. This operation initializes the account with the provided phone number and country.

• Authentication: Required (Basic Auth)

• Request Parameters:

  • country_name (string): The name of the country (e.g., Argentina).
  • phone_number (integer): The phone number for the WhatsApp account (e.g., 1234567890).

• Responses:

  • 200 OK: Successfully added the account.

    {
      "status": "success",
      "account": {
        "type": "WHATSAPP",
        "phone_number": 1234567890,
        "country": "Argentina",
        "session_code": "ABC123",
        "notification": "The session code was created successfully..."
      }
    }

  • 400 Bad Request: Invalid input provided.
  • 500 Internal Server Error: Error during account creation.

---

2. GET /get_settings

Description: Retrieves all the application settings from the configuration file.

• Authentication: Required (Basic Auth)
• Responses:
  • 200 OK: Successfully retrieved settings.

    {
      "settings": {
        "section_name": {
          "key": "value"
        }
      }
    }

  • 401 Unauthorized: Authentication failed.
  • 500 Internal Server Error: Error while fetching settings.

---

3. GET /download_database/<db_name>

Description: Downloads the specified database file.

• Authentication: Required (Basic Auth)

• Path Parameter:

  • db_name (string): The name of the database file (e.g., account_data.sqlite).

• Responses:

  • 200 OK: File is successfully sent as a download.
  • 400 Bad Request: Invalid database name provided.
  • 404 Not Found: Database file not found.
  • 500 Internal Server Error: Error during the file retrieval process.

---

4. POST /send_message_whatsapp

Description: Sends messages from a specific WhatsApp account. Messages are queued for delivery.

• Authentication: Required (Basic Auth)

• Request Body:

  • phone_number_source (integer): The phone number of the sender's WhatsApp account (e.g., 1234567890).
  • messages (array): A list of messages to send, each with:
    • foreign_id (string): A unique identifier for the message.
    • message_text (string): The text of the message.
    • destination (integer): The destination phone number, including the country code (e.g., +5491123456789).

  Example:

  {
    "phone_number_source": 1234567890,
    "messages": [
      {
        "foreign_id": "message-001",
        "message_text": "Hello!",
        "destination": 5491123456789
      }
    ]
  }

• Responses:

  • 200 OK: Messages successfully queued for sending.

    {
      "status": "success",
      "sent_messages": [
        {"foreign_id": "message-001", "status": "IN_QUEUE"}
      ]
    }

  • 400 Bad Request: Invalid input provided.
  • 404 Not Found: Source account not found.
  • 500 Internal Server Error: Error during message processing.

---

Swagger Documentation

The Senderland API includes an interactive Swagger UI to explore and test the available endpoints. Access it at:

• Swagger UI: http://localhost:1321/apidocs
• OpenAPI Specification: /apispec.json

---