image

HTTP SMS API Documentation

Welcome to the HTTP SMS API documentation. This API enables you to send SMS messages via simple HTTP POST requests. Below you will find the necessary information to efficiently integrate and use our SMS sending service.

Base URL
                            
https://api.harisma-sms.com/v1/sms
Authentication

All requests must include an API key for authentication, provided during the registration process.

Authentication Header

Include the following header in each request

                            
Authorization: Bearer YOUR_API_KEY
Endpoints
Send SMS

All requests must include an API key for authentication, provided during the registration process.

  • Endpoint: /send

  • Method: POST

Request Parameters

  • to - (string, required): Recipient's phone number in international format (e.g., +1234567890).

  • message - (string, required): The content of the SMS message.

  • from - (string, optional): Sender ID as it should appear on the recipient's phone. If not specified, a default sender ID will be used.

Example Request

                            
POST /send HTTP/1.1
Host: api.yourcompany.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "to": "+1234567890",
  "message": "Hello, this is a test message.",
  "from": "YourBrand"
}
Response

  • Code: 200 OK on success

  • Code: status (string): success if the message is accepted for delivery

  • messageId (string): Unique ID for the sent message.

  • error (string, optional): Error message if the message could not be processed.

Example Response

                            
{
  "status": "success",
  "messageId": "abc1234567890",
  "error": null
}
Error Handling

  • 200 OK - The request was successful.

  • 400 Bad Request - The request was invalid. Check input parameters.

  • 401 Unauthorized - Missing or invalid API key.

  • 403 Forbidden - API key is not permitted to perform this operation.

  • 500 Internal Server Error - An error occurred on the server. Try again later.

Support

For assistance or further inquiries, please contact our support team at support@harisma-sms.com.

SMPP API Documentation

This detailed guide covers how to connect to our SMPP server for sending and receiving SMS messages using the SMPP protocol. SMPP (Short Message Peer-to-Peer) is a protocol used by telecommunications and mobile network operators to send and receive SMS.

Prerequisites

To connect to our SMPP server, you will need the following:

  • SMPP Gateway URL

    Provided to you upon registration

  • Port

    5000

  • System ID and Password

    Credentials supplied upon account creation

  • Bind Type

    Transceiver (allows both sending and receiving messages)

Establishing a Connection

TCP/IP Connection

Initiate a socket connection to our SMPP server using the server URL and port. This is the foundational step before sending any SMPP commands.

SMPP Bind

Authenticate your connection by sending a Bind request. For most operations, you’ll use bind_Transceiver.

                            
{
  "System_ID": "your_system_id",
  "Password": "your_password",
  "Interface_Version": "0x34",
  "Address_TON": "0x00",
  "Address_NPI": "0x00",
  "Address_Range": null
}
Response Handling
On successful binding, expect Bind_Transceiver_RESP with status ESME_ROK (0x00000000).

Sending Messages

Use the Submit_SM PDU to send SMS.

                            
Submit_SM {
  Service_Type = "",
  Source_Addr_TON = 0x01,     // International
  Source_Addr_NPI = 0x01,     // ISDN (E.164)
  Source_Addr = "SenderID",
  Dest_Addr_TON = 0x01,
  Dest_Addr_NPI = 0x01,
  Destination_Addr = "+1234567890",
  ESM_Class = 0x00,
  Protocol_ID = 0x00,
  Priority_Flag = 0x00,
  Schedule_Delivery_Time = null,
  Validity_Period = null,
  Registered_Delivery = 0x01, // Delivery receipt requested
  Replace_If_Present_Flag = 0x00,
  Data_Coding = 0x00,         // SMSC Default Alphabet
  SM_Default_MSGLen = length_of_message,
  Short_Message = "Hello, this is a test message!"
}
Data Coding

0x00: SMSC Default Alphabet (ASCII)

0x08: UCS2 encoding for Unicode messages

Response Handling

Upon submitting, expect a submit_sm_resp with a unique message ID for tracking.

Receiving Messages (MO & Delivery Receipts)

Upon successful sending, your SMPP client can receive two types of deliver_sm

Mobile Originated (MO) Messages

Messages sent from mobile subscribers to your application. Check service_type for identifiers or routing logic.

Delivery Receipts

Indications from the network about message delivery status to the recipient

esm_class = 0x04 signifies a delivery receipt.

Example of Delivery Receipt format (check SMSC specifications)

                            
id:12345 sub:001 dlvrd:001 submit date:YYMMDDHHMM done date:YYMMDDHHMM stat:DELIVRD err:000 text:}

Keeping Connection Alive

To maintain an active connection use enquire_link PDU every 30-60 seconds of inactivity

Unbinding and Closing Connection

When finished, gracefully close the connection

1. Send unbind PDU.

2. Close the socket after receiving an unbind_resp.