gRPC Messaging

SMS Service

Messaging service responsible for SMS submission and message lifecycle management.

For authentication details (JWT tokens, metadata headers, error codes), see gRPC Authentication.

Service name:

sms.v1.SmsService

SendMessage

Sends a single SMS message (unary RPC).

rpc SendMessage(SmsRequest) returns (SmsResponse)

Request Fields

{
  "task_id": 11,
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "app_id": 1,
  "esme": 1000,
  "ston": 0,
  "snpi": 5,
  "saddr": "MYBRAND",
  "dnpi": 1,
  "dton": 1,
  "daddr": "998901234567",
  "message": "Hello World",
  "sent_at": 1937082918,
  "strategy": "cp1"
}

Response Fields

{
  "success": true,
  "error": "",
  "esme": 1000,
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "submitted",
  "sms_ids": [
    "smsc-seg-001"
  ],
  "task_id": 11
}

Processing Pipeline

This method performs the full SMS processing pipeline:

1. Authentication — validates JWT token and app_id
2. Rate limiting — checks L1 (in-process) and L2 (Redis) limits
3. Contact policy — validates against MCP strategy (if specified)
4. SMPP routing — selects target link or load-balances across pool
5. Submission — sends message to SMSC over SMPP v3.4
6. Persistence — stores message state in Aerospike for delivery tracking

grpcurl Example

grpcurl \
  -plaintext \
  -H 'authorization: Bearer <jwt-token>' \
  -H 'app_id: 1' \
  -d '{
    "app_id": 1,
    "esme": 1000,
    "saddr": "MYBRAND",
    "daddr": "998901234567",
    "message": "Hello from gRPC",
    "strategy": "cp1"
  }' \
  127.0.0.1:44044 \
  sms.v1.SmsService/SendMessage

SendMessageStream

Bidirectional streaming interface for high-throughput message submission.

rpc SendMessageStream(stream SmsRequest) returns (stream SmsResponse)

Description

Allows clients to maintain a persistent gRPC connection and send multiple SMS messages over a single stream. Each incoming SmsRequest produces a corresponding SmsResponse.

This is the recommended method for high-volume integrations because it eliminates the overhead of establishing a new connection for each message.

When to Use Streaming

Request and Response

The request and response messages are the same as SendMessage — SmsRequest and SmsResponse. The only difference is the transport: messages flow continuously in both directions over a single connection.

Example: Go Client

// Establish a streaming connection
stream, err := client.SendMessageStream(ctx)
if err != nil {
    log.Fatal(err)
}

// Send messages
for _, msg := range messages {
    err := stream.Send(&pb.SmsRequest{
        AppId:         1,
        Esme:          1000,
        Saddr:         "MYBRAND",
        Daddr:         msg.Phone,
        Message:       msg.Text,
        TransactionId: msg.TxID,
        Strategy:      "cp1",
    })
    if err != nil {
        log.Printf("send error: %v", err)
        break
    }

    // Receive response for each sent message
    resp, err := stream.Recv()
    if err != nil {
        log.Printf("recv error: %v", err)
        break
    }
    log.Printf("message %s: %s", resp.TransactionId, resp.Status)
}

stream.CloseSend()

Example: Python Client

import grpc
import sms_pb2, sms_pb2_grpc

channel = grpc.insecure_channel("127.0.0.1:44044")
stub = sms_pb2_grpc.SmsServiceStub(channel)

metadata = [
    ("authorization", "Bearer <jwt-token>"),
    ("app_id", "1"),
]

def message_generator():
    for phone, text in messages:
        yield sms_pb2.SmsRequest(
            app_id=1,
            esme=1000,
            saddr="MYBRAND",
            daddr=phone,
            message=text,
            strategy="cp1",
        )

responses = stub.SendMessageStream(message_generator(), metadata=metadata)
for resp in responses:
    print(f"{resp.transaction_id}: {resp.status}")

CheckESME

Checks the availability of a specific SMPP link.

rpc CheckESME(CheckESMERequest) returns (CheckESMEResponse)

Request Fields

{
  "esme": 101
}

Response Fields

{
  "persist": true,
  "system_id": "smpp-client-1"
}

Use this endpoint to verify SMPP connectivity before sending messages. A persist: false response indicates the link is disconnected — the proxy will automatically reconnect when the SMSC becomes available.

CheckTextLen

Analyzes SMS text and calculates encoding and segmentation.

rpc CheckTextLen(CheckTextLenRequest) returns (CheckTextLenResponse)

Request Fields

{
  "text": "Hello World"
}

Response Fields

{
  "error": "",
  "encode": "GSM7",
  "symbols": 11,
  "parts": 1
}

Segmentation Rules

SMS messages have character limits that depend on encoding:

When a message exceeds the single SMS limit, it is automatically split into segments. The reduced per-segment limit accounts for the User Data Header (UDH) used for reassembly.

Use this endpoint to preview segmentation before sending — for example, to estimate costs or warn users about multipart messages in a UI.

SmsInfo

Returns delivery information about a previously sent message.

rpc SmsInfo(SmsStatusRequest) returns (SmsStatusResponse)

Request Fields

{
  "esme": 100,
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

{
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "single",
  "parts": {
    "1": "DELIVERED"
  },
  "delivered_count": 1,
  "sent_at": 1937082918,
  "updated_at": 1937082925,
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": 11,
  "status": "DELIVERED",
  "error": ""
}

Message Status Values

gRPC Request Lifecycle

A typical gRPC request follows the same processing pipeline as REST:

Client
 ↓
Authentication Interceptor (JWT + app_id validation)
 ↓
L1 Rate Limiter (in-process)
 ↓
L2 Distributed Rate Limiter (Redis)
 ↓
Contact Policy (MCP, if strategy is specified)
 ↓
SMPP Router (link selection or pool load balancing)
 ↓
SMSC

Each stage validates and processes the message before forwarding it to the next component. If any stage rejects the message, the response is returned immediately with the appropriate error.

Service Summary