Skip to main content

​
Overview

Send SMS messages using pre-defined templates with dynamic parameters. Templates allow you to create reusable message formats with placeholders that can be filled with specific values for each recipient.

​
Endpoint

curl --request POST \
  "https://sms.lamah.com/api/sms/messages/template" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "template_id": "property_viewing",
    "sender": "RealEstate",
    "payment_type": "wallet",
    "receiver": "00218912345678",
    "params": [
      { "name": "أحمد محمد" },
      { "date": "2024-01-15" },
      { "time": "17:00" },
      { "area": "قرقارش" }
    ]
  }'

​
Request Parameters

ParameterTypeRequiredDescription
template_idstring✅The short name/ID of the template to use
senderstring✅The sender ID (up to 11 characters)
payment_typestring✅Payment method: wallet or subscription
receiverstring✅The recipient’s phone number in international format
paramsarray✅Array of objects mapping placeholder names to values

​
Parameter Details

The unique identifier of the template you want to use.
  • Format: String identifier created when template was defined
  • Examples: welcome_template_123, otp_verification, order_confirmation
  • Management: Templates are managed through your dashboard
The sender ID that will appear on the recipient’s device.
  • Length: Maximum 11 characters
  • Format: Alphanumeric characters only
  • Examples: Lamah, MyCompany, Alert123
Specifies how the SMS cost will be charged.
  • wallet: Deduct from your account balance
  • subscription: Use your subscription plan credits
The recipient’s phone number in international format.
  • Format: Must include country code (e.g., +218912345678 or 00218912345678)
  • Validation: Number will be validated before sending
Array of objects to replace named placeholders in the template.
  • Format: [{ "name": "..." }, { "date": "..." }]
  • Placeholders: Use {{name}}, {{date}} style in templates
  • Type: All values are strings
  • Required: Must include all placeholders present in the template

​
Template Format

Templates use named placeholders with double curly braces:

​
Example Template

مرحباً {{name}}، تم تأكيد معاينتك للعقار يوم {{date}} الساعة {{time}} في منطقة {{area}}.

​
With Parameters

{
  "params": [
    { "name": "أحمد محمد" },
    { "date": "2024-01-15" },
    { "time": "17:00" },
    { "area": "قرقارش" }
  ]
}

​
Resulting Message

مرحباً أحمد محمد، تم تأكيد معاينتك للعقار يوم 2024-01-15 الساعة 17:00 في منطقة قرقارش.

​
Response

​
Success Response (200 OK)

{
  "message_id": "msg_123456789",
  "cost": 1
}

​
Response Fields

FieldTypeDescription
message_idstringUnique identifier for the sent message
message_idstringUnique identifier for the sent message
costnumberNumber of SMS parts charged for this send

​
Error Responses

​
400 Bad Request - Invalid Template

{ "message": "Template not found" }

​
400 Bad Request - Parameter Mismatch

{ "message": "Missing parameter: name" }

​
401 Unauthorized

{
  "error": "Invalid API token",
  "code": "UNAUTHORIZED"
}

​
402 Payment Required

{
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": 0.05,
    "available": 0.02
  }
}

​
Template Management

Templates are created and managed through your Lamah dashboard. You cannot create templates via the API.

​
Creating Templates

  1. Log into Dashboard: Visit https://sms.lamah.com
  2. Navigate to Templates: Go to the Templates section
  3. Create New Template: Click “Create Template”
  4. Define Content: Write your message with placeholders like {1}, {2}, etc.
  5. Save Template: Give it a unique ID and save

​
Template Best Practices

Use Clear Placeholders

Use numbered placeholders {1}, {2} in logical order

Keep It Concise

Templates should be concise to minimize SMS costs

Test Thoroughly

Test templates with various parameter combinations

Document Parameters

Document what each parameter represents for your team

​
Common Use Cases

​
Welcome Messages

Welcome {1}! Your {2} account is now active. 
Login at: {3}

​
OTP Verification

Your verification code is: {1}
This code expires in {2} minutes.

​
Order Confirmations

Order #{1} confirmed! 
Total: ${2}
Delivery: {3}
Track: {4}

​
Appointment Reminders

Hi {1}, reminder: {2} appointment on {3} at {4}.
Location: {5}

​
Error Handling Example

const sendTemplateMessage = async (templateData) => {
  try {
    const response = await fetch('https://sms.lamah.com/api/sms/messages/template', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(templateData)
    });

    if (!response.ok) {
      const error = await response.json();
      
      if (error.code === 'TEMPLATE_NOT_FOUND') {
        console.error('Template does not exist:', error.details.template_id);
      } else if (error.code === 'PARAMETER_MISMATCH') {
        console.error(`Expected ${error.details.expected} parameters, got ${error.details.provided}`);
      } else {
        console.error('Template SMS failed:', error.error);
      }
      return null;
    }

    const result = await response.json();
    console.log('Template SMS sent:', result.message_id);
    return result;
    
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
};