Quick Start Guide

Get up and running with the Communications API in under 5 minutes. This guide covers the essential steps to send your first message.

Prerequisites

• API credentials (CustomerId and Password/API Key)
• Development environment with HTTP client capabilities
• Valid phone number for testing (international format)

Need API Access?

If you don't have API credentials yet, see our Partner Onboarding Guide to get started.

Step 1: Set Up Your Environment

Choose your preferred programming language and set up the basic HTTP client:

JavaScript/Node.js

// Install axios for HTTP requests (optional)
// npm install axios

const axios = require('axios');

const API_BASE = 'https://m5api.groupcall.com';
const customerId = 'your-customer-id';
const apiKey = 'your-api-key';

Python

import requests

API_BASE = 'https://m5api.groupcall.com'
customer_id = 'your-customer-id'
api_key = 'your-api-key'

C#

using System.Text.Json;
using System.Text;

public class CommunicationsClient
{
    private readonly HttpClient _client;
    private const string API_BASE = "https://m5api.groupcall.com";
    
    public CommunicationsClient()
    {
        _client = new HttpClient();
    }
}

Step 2: Send Your First SMS

Basic SMS Request

const sendSMS = async () => {
    const payload = {
        messageData: [{
            CustomerId: customerId,
            Password: apiKey,
            Recipients: [
                { MobileNumber: "+447700900123" } // Replace with your test number
            ],
            SMSMessage: "Hello from Communications API! 🚀"
        }]
    };

    try {
        const response = await fetch(`${API_BASE}/api/SendMessage_V3/SMS`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
        });

        const result = await response.json();
        console.log('Message sent:', result);
        
        return result;
    } catch (error) {
        console.error('Error:', error);
    }
};

// Send the message
sendSMS();

Expected Response

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

Success Indicators

• errorMsg starts with "OK" and shows message count
• MessageId is present (not null)
• statusMsg shows "In Queue"

Step 3: Handle the Response

function handleResponse(response) {
    if (!Array.isArray(response) || response.length === 0) {
        throw new Error('Invalid response format');
    }
    
    const result = response[0];
    
    // Check for success
    if (result.errorMsg && result.errorMsg.startsWith('OK') && result.MessageId) {
        console.log(`✅ Message sent successfully!`);
        console.log(`📧 Message ID: ${result.MessageId}`);
        console.log(`⏰ Queued at: ${result.transmitDateTime}`);
        return result;
    }
    
    // Handle errors
    const errorMsg = result.errorMsg || 
        (result.WarningMessages && result.WarningMessages[0]) ||
        'Unknown error';
    
    throw new Error(`❌ Failed to send message: ${errorMsg}`);
}

Step 4: Add Delivery Tracking (Optional)

To receive delivery status updates, add a callback URL:

const payload = {
    messageData: [{
        CustomerId: customerId,
        Password: apiKey,
        Recipients: [
            { MobileNumber: "+447700900123" }
        ],
        SMSMessage: "Hello with delivery tracking! 📱",
        CallbackUrl: "https://your-app.com/sms-callback" // Your webhook endpoint
    }]
};

Your webhook will receive delivery updates like:

{
    "MessageId": "1469.20250715.02516506506657265717-e0684dbcb71f402ab39d4d6b86d44cbb",
    "Status": "Delivered",
    "Timestamp": "2025-07-15T17:29:12.1234567Z",
    "Recipient": "+447700900123"
}

Common Issues & Quick Fixes

❌ "Data is not valid, no messages sent"

Solution: Check your CustomerId and Password are correct in the payload.

❌ "No recipients with valid addresses"

Solution: Ensure phone numbers are in international format (e.g., +447700900123).

❌ HTTP 500 Server Error

Solution: Retry the request after a short delay.

Next Steps

🎉 Congratulations! You've successfully sent your first message.

Continue Learning:

• SMS API Guide - Detailed SMS features and options
• Authentication Guide - Security best practices
• Error Handling - Comprehensive error management
• Callbacks & Webhooks - Real-time delivery tracking

Production Checklist:

• Set up proper error handling and retry logic
• Implement delivery status tracking
• Configure rate limiting for bulk messages
• Set up monitoring and logging
• Review security best practices

---

Need Help? Check our troubleshooting guides or contact support.