Royal Indigo Engine
Processing Request...
Developer Documentation

API Integration Reference

Integrate our high-speed OTP SMS gateway using simple JSON REST payloads. Configure failover routes and query wallet balances instantly.

Your Vendor ID (sender_id) YOUR_VENDOR_ID
Active API Authorization Token Sign in to view credentials
Login

AI-Powered 1-Click Integration Assistant

Auto-Detect Features

Copy this Master Prompt into ChatGPT, Claude, Cursor, Copilot, or Antigravity to automatically audit your project and generate full GoSMS integration code.

Step 1: Deep Codebase Audit

AI scans your code for OTP, Subscriptions, Form Tokens, PDF Invoices & Orders.

Step 2: PDF & Template Binding

Maps dynamic templates & automatically attaches generated PDF invoices to WhatsApp.

Step 3: Production Code Gen

Generates clean, resilient Notification Services with retry logic & env variables.

You are an expert full-stack developer and software architect. Your objective is to integrate the GoSMS WhatsApp & SMS Notification Gateway API into this codebase.

## PHASE 1: REPOSITORY & NOTIFICATION FEATURE DISCOVERY
Before generating code, first scan the entire repository/codebase and catalog all user-facing notification events:
1. Authentication & Security:
   - Registration OTP, Login OTP, Two-Step Verification (2FA), Password Reset Code, New Device Login Alert.
2. Subscription & Membership Lifecycle:
   - Subscription purchased / activated confirmation (with plan name, amount, expiry date, invoice number).
   - Subscription expiring soon reminders (e.g. 3 or 7 days prior with days remaining).
   - Subscription expired notices.
   - Subscription renewal success.
3. Billing, Invoices & Receipts:
   - Payment confirmation & PDF Tax Invoice generation (locate where PDF invoices or receipts are generated/saved).
   - Wallet top-up / credit notifications.
4. Form Submission & Tracking Tokens:
   - Contact forms, KYC applications, service requests that generate a Token / Tracking ID.
   - Application Approved / Rejected status notifications.
5. E-Commerce & Deliveries:
   - Order confirmation, Out for Delivery (with Delivery PIN/OTP), Order Delivered.

## PHASE 2: GOSMS API SPECIFICATION
- Base URL: https://www.gosms.in/api/v1
- Auth Header: Authorization: Bearer {YOUR_API_KEY}
- Endpoints:
  1. WhatsApp Message / Template / PDF Media Attachment:
     POST https://www.gosms.in/api/v1/whatsapp/send
     Payload format:
     {
       "to": "10_DIGIT_MOBILE",
       "template_slug": "subscription-activated", // e.g. standard-otp, subscription-activated, subscription-expiring-soon, form-submitted, application-approved, payment-receipt, order-confirmed, out-for-delivery
       "variables": { "NAME": "...", "AMOUNT": "...", "EXPIRY_DATE": "...", "TOKEN_NO": "...", "LINK": "...", "BRAND_NAME": "..." },
       "media_url": "https://yourdomain.com/invoices/inv_123.pdf", // Optional: Attach PDF Invoice or document directly to WhatsApp
       "file_name": "Tax_Invoice_2026.pdf"
     }
  2. WhatsApp Priority OTP:
     POST https://www.gosms.in/api/v1/whatsapp/send-otp
     Payload: { "to": "10_DIGIT_MOBILE", "otp": "123456", "action": "two-step verification", "brand": "YourBrand" }
  3. General SMS:
     POST https://www.gosms.in/api/v1/sms/send
     Payload: { "to": "10_DIGIT_MOBILE", "message": "...", "sender_id": "YOUR_VENDOR_ID" }

## PHASE 3: IMPLEMENTATION
1. Create a reusable GoSMS notification service in this project with environment configuration (GOSMS_API_KEY, GOSMS_BASE_URL).
2. Attach listeners/hooks to all identified app events.
3. For invoice payments and subscription activations, ensure the generated PDF invoice URL is passed into media_url so the customer receives the invoice PDF directly on WhatsApp.
4. Provide comprehensive error logging, retry handling, and graceful fallbacks.

Global Settings

API Base URL https://www.gosms.in/api/v1
Content-Type application/json
Authentication Header Authorization: {YOUR_API_KEY}

Send SMS Endpoint

POST
https://www.gosms.in/api/v1/sms
Payload Parameters
Field Type Requirement Description
to / numbers string Required 10-digit recipient mobile number.
message / variables_values string Required The message text content or numeric OTP code.
sender_id string Optional Your Account Vendor ID or DLT Approved Header.
route / rout string Optional sms (default Non-DLT), otp, or dlt.
dlt_template_id string Optional Your operator registered DLT Template ID (for DLT route).
dlt_entity_id string Optional Your Principal Entity ID (for DLT route).

Instant Dual-Channel OTP (SMS + WhatsApp)

POST
https://www.gosms.in/api/v1/send-otp

Sends high-priority verification OTP simultaneously through SMS Gateway and WhatsApp Gateway for maximum delivery guarantee.

Payload Parameters
Field Type Requirement Description
to string Required Recipient 10-digit mobile number.
otp string Required Numeric OTP code (e.g. 492015).

Send Email (SMTP Gateway)

POST
https://www.gosms.in/api/v1/email/send
Request Parameters
Field Type Status Description
to string (email) Required Recipient email address.
subject string Required Email subject line.
message string (HTML) Required* HTML or plain text body (optional if `template_slug` provided).
template_slug string Optional Stock template slug (e.g. `otp_verification_clean_blue`).
variables object / array Optional Template placeholders e.g. {"otp_code": "58291"}.
from_name string Optional Custom sender display name.
reply_to string (email) Optional Reply-to destination address.
purpose string Optional Dedicated SMTP channel: otp, invoice, notification, campaign.

WhatsApp Message & OTP Endpoint

POST
https://www.gosms.in/api/v1/whatsapp/send
Aliases: /api/v1/whatsapp/send-otp, /api/v1/send-whatsapp
Payload Parameters
Field Type Status Description
to string Required Recipient 10-digit mobile number (e.g. 9876543210).
otp string Optional* Direct OTP code (e.g. 482910). Formats as priority auth message.
action string Optional Verification action: login, two-step verification, registration, password reset, transaction. (Defaults to verification).
brand string Optional Custom brand / business name to display in the message.
template_slug string Optional Pre-built template ID or custom template slug: standard-otp, secure-2fa-otp, password-reset-otp, subscription-activated, subscription-expiring-soon, subscription-expired, subscription-renewed, form-submitted, application-approved, application-rejected, service-status-update, payment-receipt, invoice-generated, wallet-credited, order-confirmed, out-for-delivery, order-delivered, appointment-confirmed, promo-discount, feedback-request.
variables object / array Optional Placeholder values: {"OTP": "482910", "ACTION": "login", "PLAN_NAME": "Pro Plan", "AMOUNT": "999", "EXPIRY_DATE": "31/12/2026", "DAYS_LEFT": "3"}.
message string Optional* Direct message body (if not using template_slug or otp).
type string Optional otp (default) or promotional.
Example 1 – Send Dynamic OTP Verification
OTP / 2FA / Reset
{
  "to": "9876543210",
  "otp": "482910",
  "action": "two-step verification",
  "brand": "MyBrand"
}
Example 2 – Subscription Activated Notification
Subscription & Plans
{
  "to": "9876543210",
  "template_slug": "subscription-activated",
  "variables": {
    "NAME": "Deep Biswas",
    "PLAN_NAME": "Gold VIP Membership",
    "AMOUNT": "1499.00",
    "EXPIRY_DATE": "24/09/2026",
    "INVOICE_NO": "SUB-20260824",
    "LINK": "https://example.com/account/subscription",
    "BRAND_NAME": "MyBrand"
  }
}
Example 3 – Subscription Expiring Soon Alert
Renewal Alert
{
  "to": "9876543210",
  "template_slug": "subscription-expiring-soon",
  "variables": {
    "NAME": "Deep Biswas",
    "PLAN_NAME": "Gold VIP Membership",
    "DAYS_LEFT": "3",
    "EXPIRY_DATE": "27/08/2026",
    "AMOUNT": "1499.00",
    "LINK": "https://example.com/renew",
    "BRAND_NAME": "MyBrand"
  }
}
Example 4 – Form Submission / Tracking Token
Token Lifecycle
{
  "to": "9876543210",
  "template_slug": "form-submitted",
  "variables": {
    "NAME": "Rahul Roy",
    "SERVICE_NAME": "KYC Merchant Verification",
    "TOKEN_NO": "TOKEN-88391",
    "LINK": "https://example.com/track/TOKEN-88391",
    "BRAND_NAME": "MyBrand"
  }
}
Example 5 – Form Approved / Status Update
Status Update
{
  "to": "9876543210",
  "template_slug": "application-approved",
  "variables": {
    "NAME": "Rahul Roy",
    "TOKEN_NO": "TOKEN-88391",
    "SERVICE_NAME": "KYC Merchant Verification",
    "LINK": "https://example.com/certificate/TOKEN-88391",
    "BRAND_NAME": "MyBrand"
  }
}

WhatsApp Invoice / PDF & Media Notification

POST
https://www.gosms.in/api/v1/whatsapp/send

Send PDF tax invoices, receipts, payment confirmations, approval certificates, or any media file (image/document) directly to WhatsApp. Simply provide the media_url field with a publicly accessible URL to your file.

Extended Parameters for Media / Invoice
Field Type Status Description
to string Required Recipient 10-digit mobile (e.g. 9876543210).
message string Optional Caption text shown below the document/image. Use for payment details, order summary, etc.
media_url string (URL) For Media Public HTTPS URL of the PDF/image file to attach. Eg: https://www.gosms.in/invoices/inv_1234.pdf
file_name string Optional Display name for the file (e.g. Tax_Invoice_2024.pdf). Defaults to Document.pdf.
type string Optional otp (default) or promotional. Invoice/notification use otp (transactional rate).
Example 4 – Send PDF Tax Invoice / Certificate
{
  "to": "9876543210",
  "message": "✅ Payment Successful!\nRef: INV-20241024\nAmount: ₹1,500.00\nYour tax invoice is attached below.",
  "media_url": "https://www.gosms.in/invoices/sample_invoice.pdf",
  "file_name": "Tax_Invoice_Oct2024.pdf",
  "type": "otp"
}

Wallet Balance

GET
https://www.gosms.in/api/v1/balance

Retrieve your client account name, wallet balance sum, and currency info.

Master AI Assistant Prompt Flutter (Dart) Setup Kotlin (Android) Setup Node.js (Axios) Code PHP (cURL) Code Python (Requests) Code Java (OkHttp) Code Go (net/http) Code C# (HttpClient) Code
How AI Assistant Integration Works

1. Copy this Master Prompt and paste it into your AI coding tool (ChatGPT, Claude, Cursor, Copilot, or Antigravity).
2. The AI will first scan your repository to detect all events (Registration OTP, Subscriptions, Form Tokens, PDF Invoices).
3. It will generate a tailored, production-ready GoSMS integration service for your specific tech stack.

You are an expert full-stack developer and software architect. Your objective is to integrate the GoSMS WhatsApp & SMS Notification Gateway API into this codebase.

## PHASE 1: REPOSITORY & NOTIFICATION FEATURE DISCOVERY
Before generating code, first scan the entire repository/codebase and catalog all user-facing notification events:
1. Authentication & Security:
   - Registration OTP, Login OTP, Two-Step Verification (2FA), Password Reset Code, New Device Login Alert.
2. Subscription & Membership Lifecycle:
   - Subscription purchased / activated confirmation (with plan name, amount, expiry date, invoice number).
   - Subscription expiring soon reminders (e.g. 3 or 7 days prior with days remaining).
   - Subscription expired notices.
   - Subscription renewal success.
3. Billing, Invoices & Receipts:
   - Payment confirmation & PDF Tax Invoice generation (locate where PDF invoices or receipts are generated/saved).
   - Wallet top-up / credit notifications.
4. Form Submission & Tracking Tokens:
   - Contact forms, KYC applications, service requests that generate a Token / Tracking ID.
   - Application Approved / Rejected status notifications.
5. E-Commerce & Deliveries:
   - Order confirmation, Out for Delivery (with Delivery PIN/OTP), Order Delivered.

## PHASE 2: GOSMS API SPECIFICATION
- Base URL: https://www.gosms.in/api/v1
- Auth Header: Authorization: Bearer {YOUR_API_KEY}
- Endpoints:
  1. WhatsApp Message / Template / PDF Media Attachment:
     POST https://www.gosms.in/api/v1/whatsapp/send
     Payload format:
     {
       "to": "10_DIGIT_MOBILE",
       "template_slug": "subscription-activated", // e.g. standard-otp, subscription-activated, subscription-expiring-soon, form-submitted, application-approved, payment-receipt, order-confirmed, out-for-delivery
       "variables": { "NAME": "...", "AMOUNT": "...", "EXPIRY_DATE": "...", "TOKEN_NO": "...", "LINK": "...", "BRAND_NAME": "..." },
       "media_url": "https://yourdomain.com/invoices/inv_123.pdf", // Optional: Attach PDF Invoice or document directly to WhatsApp
       "file_name": "Tax_Invoice_2026.pdf"
     }
  2. WhatsApp Priority OTP:
     POST https://www.gosms.in/api/v1/whatsapp/send-otp
     Payload: { "to": "10_DIGIT_MOBILE", "otp": "123456", "action": "two-step verification", "brand": "YourBrand" }
  3. General SMS:
     POST https://www.gosms.in/api/v1/sms/send
     Payload: { "to": "10_DIGIT_MOBILE", "message": "...", "sender_id": "YOUR_VENDOR_ID" }

## PHASE 3: IMPLEMENTATION
1. Create a reusable GoSMS notification service in this project with environment configuration (GOSMS_API_KEY, GOSMS_BASE_URL).
2. Attach listeners/hooks to all identified app events.
3. For invoice payments and subscription activations, ensure the generated PDF invoice URL is passed into media_url so the customer receives the invoice PDF directly on WhatsApp.
4. Provide comprehensive error logging, retry handling, and graceful fallbacks.
How Flutter Works

1. Add the http package to your Flutter project's pubspec.yaml file:

dependencies: http: ^1.2.0

2. Import the HTTP library and execute the asynchronous request payload as shown below.

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> sendSMS() async {
  final url = Uri.parse('https://www.gosms.in/api/v1/sms');
  final headers = {
    'Authorization': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json',
  };
  final body = jsonEncode({
    'sender_id': 'YOUR_VENDOR_ID',
    'numbers': '9876543210',
    'rout': 'sms',
    'variables_values': '123456',
  });

  try {
    final response = await http.post(url, headers: headers, body: body);
    if (response.statusCode == 200) {
      print('Response: ${response.body}');
    } else {
      print('Failed: ${response.statusCode}');
    }
  } catch (e) {
    print('Error: $e');
  }
}
How Kotlin Works

1. Add the OkHttp dependency to your Android app's build.gradle file:

dependencies { implementation("com.squareup.okhttp3:okhttp:4.12.0") }

2. Create the request payload, pass authorization header, and run the client call asynchronously.

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException

fun sendSMS() {
    val client = OkHttpClient()
    val mediaType = "application/json; charset=utf-8".toMediaType()
    val json = """
        {
            "sender_id": "YOUR_VENDOR_ID",
            "numbers": "9876543210",
            "rout": "sms",
            "variables_values": "123456"
        }
    """.trimIndent()
    val body = json.toRequestBody(mediaType)
    val request = Request.Builder()
        .url("https://www.gosms.in/api/v1/sms")
        .post(body)
        .addHeader("Authorization", "YOUR_API_KEY_HERE")
        .addHeader("Content-Type", "application/json")
        .build()

    client.newCall(request).enqueue(object : okhttp3.Callback {
        override fun onFailure(call: okhttp3.Call, e: java.io.IOException) {
            e.printStackTrace()
        }

        override fun onResponse(call: okhttp3.Call, response: okhttp3.Response) {
            response.use {
                if (!response.isSuccessful) throw java.io.IOException("Unexpected code ${response}")
                println(response.body?.string())
            }
        }
    })
}
const axios = require('axios');

const data = {
    sender_id: "YOUR_VENDOR_ID",
    numbers: "9876543210",
    rout: "sms",
    variables_values: "123456"
};

axios.post('https://www.gosms.in/api/v1/sms', data, {
    headers: {
        'Authorization': 'YOUR_API_KEY_HERE',
        'Content-Type': 'application/json'
    }
}).then(response => {
    console.log(response.data);
}).catch(error => {
    console.error(error);
});
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://www.gosms.in/api/v1/sms',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: YOUR_API_KEY_HERE',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'sender_id' => 'YOUR_VENDOR_ID',
        'numbers' => '9876543210',
        'rout' => 'sms',
        'variables_values' => '123456'
    ])
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests
import json

url = "https://www.gosms.in/api/v1/sms"
headers = {
    "Authorization": "YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "sender_id": "YOUR_VENDOR_ID",
    "numbers": "9876543210",
    "rout": "sms",
    "variables_values": "123456"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
import okhttp3.*;
import java.io.IOException;

public class SmsSender {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, 
            "{\"sender_id\":\"YOUR_VENDOR_ID\",\"numbers\":\"9876543210\",\"rout\":\"sms\",\"variables_values\":\"123456\"}");
        
        Request request = new Request.Builder()
            .url("https://www.gosms.in/api/v1/sms")
            .post(body)
            .addHeader("Authorization", "YOUR_API_KEY_HERE")
            .addHeader("Content-Type", "application/json")
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://www.gosms.in/api/v1/sms"
	payload := map[string]string{
		"sender_id":        "YOUR_VENDOR_ID",
		"numbers":          "9876543210",
		"rout":             "sms",
		"variables_values": "123456",
	}
	jsonVal, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonVal))
	req.Header.Set("Authorization", "YOUR_API_KEY_HERE")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        var client = new HttpClient();
        var url = "https://www.gosms.in/api/v1/sms";
        
        client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_KEY_HERE");
        
        var json = "{\"sender_id\":\"YOUR_VENDOR_ID\",\"numbers\":\"9876543210\",\"rout\":\"sms\",\"variables_values\":\"123456\"}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync(url, content);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}