SMS API Guide

Send text messages to students, parents, and staff using our reliable SMS delivery platform. Our SMS API provides high deliverability, real-time status updates, and seamless integration with education management systems.

Quick Start

Basic SMS Request

POST /api/SendMessage_V3/SMS
Host: m5api.groupcall.com
Content-Type: application/json

{
  "messageData": [
    {
      "CustomerId": "your-customer-id",
      "Password": "your-api-key",
      "Recipients": ["+447700900123"],
      "SMSMessage": "Welcome to our school! Your account has been activated.",
      "CallbackUrl": "https://your-app.com/sms-callback"
    }
  ]
}

Authentication

The SMS API uses credential-based authentication through the payload. No Authorization header is required. Authentication is handled via the CustomerId and Password fields in the request payload.

Response

[
  {
    "WarningMessages": [],
    "errorMsg": "OK 1 messages queued for sending",
    "MessageSentId": 0,
    "MessageId": "1469.20250704.02516506506657265717-e0684dbcb71f402ab39d4d6b86d44cbb",
    "statusMsg": "In Queue",
    "transmitDateTime": "2025-07-04T17:28:54.5859378Z",
    "ClientRef": null
  }
]

Key Response Fields:

• errorMsg: "OK X messages queued for sending" indicates success
• MessageId: Unique identifier for tracking the message (present on success)
• statusMsg: Current status of the message ("In Queue", etc.)
• transmitDateTime: When the message was queued for sending
• MessageSentId: Internal identifier (may be 0 even for successful messages)

Message Structure

Required Fields

Field	Type	Description
messageData	array	Array of message objects
CustomerId	string	Your customer identifier
Password	string	Your API key
Recipients	array	Array of recipient objects (see Recipients Reference)
SMSMessage	string	SMS content (max 918 characters)

Optional Fields

Field	Type	Description
CallbackUrl	string	URL for delivery status updates
ClientRef	string	Your internal reference ID
SMSSender	string	Custom sender ID that appears on recipient's handset

Payload Structure

The messageData field is an array of message objects, not a single object. Each object in the array should contain CustomerId, Password, Recipients, SMSMessage, and optional fields.

Message Content

Character Limits

• Single SMS: Up to 160 characters
• Concatenated SMS: Up to 918 characters (6 parts max)
• Unicode Support: Full Unicode support for international characters

Best Practices

Content Guidelines

// ✅ Good - Clear and concise
"Parent Evening: Tue 15th Nov, 6-8pm. Book at: school.com/booking"

// ❌ Avoid - Too verbose
"Dear Parent/Guardian, We would like to inform you that we are holding a parent evening event..."

Personalization

{
  "message": "Hi {firstName}, your child {childName} has an appointment at {time}",
  "recipients": [
    {
      "number": "+447700900123",
      "personalisation": {
        "firstName": "Sarah",
        "childName": "Emma",
        "time": "2:30pm"
      }
    }
  ]
}

Custom Sender ID

Use the SMSSender field to customize how your messages appear on recipients' handsets:

{
  "messageData": [
    {
      "CustomerId": "your-customer-id",
      "Password": "your-api-key",
      "Recipients": [
        {
          "MobileNumber": "+447700900123"
        }
      ],
      "SMSMessage": "Your appointment is confirmed for tomorrow at 2:30pm.",
      "SMSSender": "SchoolName",
      "CallbackUrl": "https://your-app.com/sms-callback",
      "ClientRef": "APPT-001"
    }
  ]
}

Sender ID Guidelines:

• Length: Maximum 11 characters (alphanumeric) or 15 digits (numeric)
• Characters: Letters, numbers, and spaces only
• Restrictions: Cannot start with a number if using alphanumeric
• Examples: "SchoolName", "Library", "441234567890"

Sender ID Approval

Some sender IDs may require pre-approval depending on your region and mobile network requirements. Contact support if you experience delivery issues with custom sender IDs.

Bulk Messaging

Sending to Multiple Recipients

{
  "messageData": [
    {
      "CustomerId": "your-customer-id",
      "Password": "your-api-key",
      "Recipients": [
        {
          "MobileNumber": "+447700900123"
        },
        {
          "MobileNumber": "+447700900124"
        },
        {
          "MobileNumber": "+447700900125"
        }
      ],
      "SMSMessage": "School will be closed tomorrow due to weather conditions.",
      "CallbackUrl": "https://your-app.com/sms-callback"
    }
  ]
}

Rate Limiting

• Default Limit: 100 messages per second
• Burst Capacity: Up to 1000 messages in burst
• Enterprise: Higher limits available on request

Delivery Status Tracking

Callback Configuration

When you provide a callbackUrl, we'll send delivery updates:

{
  "messageId": "msg_abc123_001",
  "status": "delivered",
  "timestamp": "2024-07-04T10:30:00Z",
  "recipient": "+447700900123",
  "units": 1,
  "reference": "your-ref-123"
}

Callback Payload

The exact callback payload structure needs to be verified with the latest API documentation. The payload format and field names may differ from what's shown above.

Status Values

Status	Description
queued	Message accepted and queued for delivery
sent	Message sent to carrier
delivered	Message delivered to recipient
failed	Delivery failed (permanent)
expired	Message expired before delivery

Handling Callbacks

// Express.js example
app.post('/sms-callback', (req, res) => {
  const { messageId, status, recipient } = req.body;
  
  // Update your database
  await updateMessageStatus(messageId, status);
  
  // Acknowledge receipt
  res.status(200).send('OK');
});

Detailed Callback Implementation

For comprehensive callback handling examples, see our Message Status Callbacks guide.

Error Handling

For detailed error handling patterns and troubleshooting, see our Error Handling Guide and API Errors Reference.

Testing

Testing Information

Sandbox test numbers and testing procedures need to be verified with the latest API documentation. Contact support for current testing guidelines.

Testing Best Practices

• Test with small batches before bulk sending
• Verify callback URL handling in your staging environment
• Validate phone number formats before sending
• Monitor delivery rates and callback responses

Postman Collection

A Postman collection may be available for testing. Contact support for the latest testing resources and documentation.

Recipients for SMS

The Recipients array contains objects that identify who should receive the SMS message. Each recipient object can use various identification methods and personalization options.

Basic SMS Recipients

{
  "Recipients": [
    {
      "MobileNumber": "+447700900123"
    },
    {
      "MobileNumber": "+447700900124"
    }
  ]
}

Advanced Recipients with Personalization

{
  "Recipients": [
    {
      "MobileNumber": "+447700900123",
      "Forename": "Sarah",
      "Surname": "Johnson",
      "DynamicTokens": {
        "studentName": "Emma",
        "appointmentTime": "2:30 PM"
      }
    }
  ]
}

Student Context Messages

Send SMS to parents about their children:

{
  "Recipients": [
    {
      "ExternalId": "PARENT_001",
      "SendTo": 1,
      "StudentExternalId": "STUDENT_001",
      "DynamicTokens": {
        "studentName": "Emma Johnson",
        "subject": "Mathematics"
      }
    }
  ]
}

Complete Recipients Guide

For comprehensive documentation on all recipient identification methods, personalization options, and advanced features, see the Recipients Reference guide.

---

Next Steps:

• Learn about Recipients Reference for advanced targeting
• Learn about Email API for rich HTML messaging
• Explore Authentication methods
• Set up Delivery Tracking with callbacks
• Review Error Handling best practices