API Documentation

Introduction

Welcome to our Communication API documentation. This API provides a unified interface to send messages across multiple channels including RCS, SMS, Email, and WhatsApp.

Base URL

Getting Started

To get started, you'll need an API key. Sign up for an account and generate your API key from the dashboard.

1. Sign up for a developer account
2. Verify your email address
3. Generate your API key from the dashboard
4. Start making requests to the API

Rate Limits

API requests are limited to 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Authentication

All API requests must be authenticated using a Bearer token included in the Authorization header.

How to Authenticate

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Getting Your API Key

You can generate API keys from your account dashboard. We recommend using different keys for different environments (development, staging, production).

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Error Response Format

{
    "error": {
        "code": "invalid_request",
        "message": "The request was invalid",
        "details": {
            "param": "email",
            "reason": "invalid_format"
        }
    }
}

Create SMS Template

This endpoint allows you to create and save a new SMS template. Templates include details like template name, entity ID, template ID, content, and sender ID. Each template is associated with a user and cost is calculated automatically based on SMS parts.

HTTP Request

Request Parameters

Request Payload

{
  "template_name": "otp_alert",
  "entity_id": "1234567890",
  "template_id": "DLT12345",
  "content": "Hello { name }, your OTP is { otp }.",
  "sender_id": "ABCDEF"
}

Send SMS

This endpoint allows you to send SMS messages to one or more recipients. It supports both non-personalized (bulk) and personalized (customized per recipient) messages. Unicode messages (e.g., Hindi, Tamil) are also supported.

HTTP Request

Request Parameters

Request Payload Examples

{
  "senderid": "ABCDEF",
  "message": "Hello! This is a bulk test message.",
  "unicode": 0,
  "personalized": 0,
  "numbers": ["9876543210", "9123456780"]
}

{
  "senderid": "ABCDEF",
  "message": "Hello {{ name }}, your OTP is {{ otp }}.",
  "unicode": 0,
  "personalized": 1,
  "numbers": [
    { "number": "9876543210", "name": "Sanjay", "otp": "123456" },
    { "number": "9123456780", "name": "Amit", "otp": "654321" }
  ]
}

SMS List Report

This endpoint retrieves the delivery report of a previously sent SMS batch. You must provide the gateway_ref_id (returned when sending SMS) to fetch the associated logs for each recipient.

HTTP Request

Path Parameter

Example Request

curl -X GET 'https://multichannel.insignsms.com/api/sms/reports/GATEWAY_REF_12345' \
--header 'Authorization: Bearer YOUR_API_KEY'

Create RCS Template

This endpoint allows you to create a new Rich Communication Services (RCS) template. Supported types include: plain text, standalone card, and carousel. Templates must be approved before use.

HTTP Request

Request Parameters

Request Payload Example (Plain Text)

{
  "template_name": "welcome_text_01",
  "template_type": "plain_text",
  "data": {
    "content": {
      "plainText": "Welcome to our service! Enjoy your experience."
    }
  }
}

Request Payload Example (Standalone)

{
  "template_name": "promo_card_01",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardTitle": "Big Sale!",
            "cardDescription": "Up to 70% off electronics.",
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/sale.png"
              }
            },
            "suggestions": [
              { "type": "REPLY", "text": "Shop Now" },
              { "type": "URL", "url": "https://example.com/store" }
            ]
          }
        }
      }
    }
  }
}

Request Payload Example (Carousel)

{
  "template_name": "carousel_offer_01",
  "template_type": "carousel",
  "data": {
    "content": {
      "richCardDetails": {
        "carousel": {
          "cardWidth": "MEDIUM",
          "contents": [
            {
              "cardTitle": "Item 1",
              "cardDescription": "Best gadget at best price.",
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://example.com/item1.png"
                }
              },
              "suggestions": [
                { "type": "URL", "url": "https://example.com/item1" }
              ]
            },
            {
              "cardTitle": "Item 2",
              "cardDescription": "Don’t miss this deal!",
              "cardMedia": {
                "mediaHeight": "SHORT",
                "contentInfo": {
                  "fileUrl": "https://example.com/item2.png"
                }
              },
              "suggestions": [
                { "type": "URL", "url": "https://example.com/item2" }
              ]
            }
          ]
        }
      }
    }
  }
}

List Templates

This endpoint retrieves stored Rich Communication Services (RCS) templates. You can fetch all templates or a specific template by passing its {id}. Supported types include plain_text, standalone, and carousel.

HTTP Request

{id} is optional. If provided → returns single template. If omitted → returns list of templates.

Response Fields

Example Response – Plain Text

{
  "success": true,
  "data": {
    "template_id": 101,
    "template_name": "welcome_msg",
    "template_type": "plain_text",
    "status": "approved",
    "data": {
      "content": {
        "plainText": "Hello {{ name }}, welcome aboard!",
        "suggestions": [
          { "type": "REPLY", "text": "Thanks" }
        ]
      }
    }
  }
}

Example Response – Standalone

{
  "success": true,
  "data": {
    "template_id": 102,
    "template_name": "promo_card",
    "template_type": "standalone",
    "status": "approved",
    "data": {
      "content": {
        "richCardDetails": {
          "standalone": {
            "cardOrientation": "VERTICAL",
            "content": {
              "cardTitle": "Big Sale!",
              "cardDescription": "Up to 70% off electronics.",
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://example.com/sale.png"
                }
              },
              "suggestions": [
                { "type": "REPLY", "text": "Shop Now" },
                { "type": "URL", "url": "https://example.com/store" }
              ]
            }
          }
        }
      }
    }
  }
}

Example Response – Carousel

{
  "success": true,
  "data": {
    "template_id": 103,
    "template_name": "product_carousel",
    "template_type": "carousel",
    "status": "approved",
    "data": {
      "content": {
        "richCardDetails": {
          "carousel": {
            "cardWidth": "MEDIUM",
            "contents": [
              {
                "cardTitle": "Laptop",
                "cardDescription": "Powerful and portable.",
                "cardMedia": {
                  "mediaHeight": "MEDIUM",
                  "contentInfo": {
                    "fileUrl": "https://example.com/laptop.png"
                  }
                },
                "suggestions": [
                  { "type": "URL", "url": "https://example.com/laptop" }
                ]
              },
              {
                "cardTitle": "Smartphone",
                "cardDescription": "Latest Android device.",
                "cardMedia": {
                  "mediaHeight": "MEDIUM",
                  "contentInfo": {
                    "fileUrl": "https://example.com/phone.png"
                  }
                },
                "suggestions": [
                  { "type": "URL", "url": "https://example.com/phone" }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

Send RCS Message

This endpoint allows you to send an RCS message using an approved template. Messages can be sent to multiple contacts (up to 50 numbers per request).

HTTP Request

Request Parameters

Request Payload

{
    "templateId": 123,
    "messageId": "msg_001",
    "contacts": ["9876543210", "9123456780"]
}