Messaging API

The Lineserve Messaging API allows you to send SMS messages, manage campaigns, and track delivery status programmatically.

Base URL

https://api.lineserve.com/v1

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Send SMS

Send Single SMS

Send an SMS message to a single recipient.

Endpoint: POST /sms/send

Parameters:

• to (required): Recipient phone number in international format
• message (required): Message content (max 1600 characters)
• from (optional): Sender ID (must be registered)
• callback_url (optional): Webhook URL for delivery status

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+254700123456",
    "message": "Hello from Lineserve!",
    "from": "YourBrand",
    "callback_url": "https://yourapp.com/webhooks/sms"
  }' \
  https://api.lineserve.com/v1/sms/send

Example Response:

{
  "message_id": "msg_123456789",
  "to": "+254700123456",
  "message": "Hello from Lineserve!",
  "from": "YourBrand",
  "status": "sent",
  "cost": 0.05,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

Send Bulk SMS

Send SMS messages to multiple recipients.

Endpoint: POST /sms/bulk

Parameters:

• recipients (required): Array of phone numbers
• message (required): Message content
• from (optional): Sender ID
• campaign_name (optional): Campaign identifier
• callback_url (optional): Webhook URL for delivery status

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+254700123456", "+254700123457", "+254700123458"],
    "message": "Bulk message from Lineserve!",
    "from": "YourBrand",
    "campaign_name": "Monthly Newsletter"
  }' \
  https://api.lineserve.com/v1/sms/bulk

Example Response:

{
  "campaign_id": "camp_123456",
  "campaign_name": "Monthly Newsletter",
  "total_messages": 3,
  "total_cost": 0.15,
  "currency": "USD",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "messages": [
    {
      "message_id": "msg_123456789",
      "to": "+254700123456",
      "status": "sent"
    },
    {
      "message_id": "msg_123456790",
      "to": "+254700123457",
      "status": "sent"
    },
    {
      "message_id": "msg_123456791",
      "to": "+254700123458",
      "status": "sent"
    }
  ]
}

Message Status

Get Message Status

Check the delivery status of a specific message.

Endpoint: GET /sms/status/{message_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/sms/status/msg_123456789

Example Response:

{
  "message_id": "msg_123456789",
  "to": "+254700123456",
  "message": "Hello from Lineserve!",
  "from": "YourBrand",
  "status": "delivered",
  "cost": 0.05,
  "currency": "USD",
  "sent_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:15Z",
  "delivery_report": {
    "network": "Safaricom",
    "country": "Kenya",
    "error_code": null,
    "error_message": null
  }
}

Message Status Values

• sent: Message sent to carrier
• delivered: Message delivered to recipient
• failed: Message delivery failed
• pending: Message queued for delivery
• expired: Message expired before delivery
• rejected: Message rejected by carrier

Message History

List Messages

Get a list of sent messages with optional filtering.

Endpoint: GET /sms/messages

Parameters:

• from_date (optional): Start date (ISO 8601 format)
• to_date (optional): End date (ISO 8601 format)
• status (optional): Filter by status
• to (optional): Filter by recipient
• from (optional): Filter by sender ID
• page (optional): Page number
• per_page (optional): Results per page (max 100)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/sms/messages?status=delivered&page=1&per_page=50"

Example Response:

{
  "messages": [
    {
      "message_id": "msg_123456789",
      "to": "+254700123456",
      "message": "Hello from Lineserve!",
      "from": "YourBrand",
      "status": "delivered",
      "cost": 0.05,
      "currency": "USD",
      "sent_at": "2024-01-15T10:30:00Z",
      "delivered_at": "2024-01-15T10:30:15Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 50,
    "pages": 3
  }
}

Campaign Management

List Campaigns

Get a list of SMS campaigns.

Endpoint: GET /sms/campaigns

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/sms/campaigns

Example Response:

{
  "campaigns": [
    {
      "campaign_id": "camp_123456",
      "campaign_name": "Monthly Newsletter",
      "total_messages": 1000,
      "delivered_messages": 985,
      "failed_messages": 15,
      "total_cost": 50.00,
      "currency": "USD",
      "status": "completed",
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:45:00Z"
    }
  ]
}

Get Campaign Details

Get detailed information about a specific campaign.

Endpoint: GET /sms/campaigns/{campaign_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/sms/campaigns/camp_123456

Sender ID Management

List Sender IDs

Get a list of registered sender IDs.

Endpoint: GET /messaging/sender-ids

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/messaging/sender-ids

Example Response:

{
  "sender_ids": [
    {
      "sender_id": "YourBrand",
      "type": "alphanumeric",
      "status": "approved",
      "countries": ["KE", "UG", "TZ"],
      "created_at": "2024-01-01T00:00:00Z",
      "approved_at": "2024-01-05T00:00:00Z"
    }
  ]
}

Register Sender ID

Register a new sender ID for approval.

Endpoint: POST /messaging/sender-ids

Parameters:

• sender_id (required): Desired sender ID
• type (required): Type (alphanumeric, numeric)
• countries (required): Array of country codes
• use_case (required): Description of use case
• business_name (required): Business name

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "NewBrand",
    "type": "alphanumeric",
    "countries": ["KE", "UG"],
    "use_case": "Marketing and transactional messages",
    "business_name": "New Brand Ltd"
  }' \
  https://api.lineserve.com/v1/messaging/sender-ids

Templates

List Message Templates

Get a list of saved message templates.

Endpoint: GET /messaging/templates

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/messaging/templates

Create Template

Create a new message template.

Endpoint: POST /messaging/templates

Parameters:

• name (required): Template name
• content (required): Template content with placeholders
• category (optional): Template category

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Message",
    "content": "Welcome {{name}}! Your account has been created.",
    "category": "onboarding"
  }' \
  https://api.lineserve.com/v1/messaging/templates

Send Template Message

Send a message using a template with variable substitution.

Endpoint: POST /sms/send-template

Parameters:

• to (required): Recipient phone number
• template_id (required): Template ID
• variables (required): Object with variable values
• from (optional): Sender ID

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+254700123456",
    "template_id": "tpl_123456",
    "variables": {
      "name": "John Doe",
      "code": "ABC123"
    },
    "from": "YourBrand"
  }' \
  https://api.lineserve.com/v1/sms/send-template

Contact Lists

List Contact Lists

Get a list of contact lists.

Endpoint: GET /messaging/contacts/lists

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/messaging/contacts/lists

Create Contact List

Create a new contact list.

Endpoint: POST /messaging/contacts/lists

Parameters:

• name (required): List name
• description (optional): List description

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter recipients"
  }' \
  https://api.lineserve.com/v1/messaging/contacts/lists

Add Contacts to List

Add contacts to a specific list.

Endpoint: POST /messaging/contacts/lists/{list_id}/contacts

Parameters:

• contacts (required): Array of contact objects

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone": "+254700123456",
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "phone": "+254700123457",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ]
  }' \
  https://api.lineserve.com/v1/messaging/contacts/lists/list_123/contacts

Opt-out Management

List Opt-outs

Get a list of opted-out phone numbers.

Endpoint: GET /messaging/opt-outs

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/messaging/opt-outs

Add Opt-out

Add a phone number to the opt-out list.

Endpoint: POST /messaging/opt-outs

Parameters:

• phone (required): Phone number to opt out

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+254700123456"
  }' \
  https://api.lineserve.com/v1/messaging/opt-outs

Webhooks

Configure Webhooks

Set up webhooks to receive real-time delivery status updates.

Endpoint: POST /messaging/webhooks

Parameters:

• url (required): Webhook endpoint URL
• events (required): Array of events to subscribe to
• secret (optional): Secret for signature verification

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/sms",
    "events": ["sms.delivered", "sms.failed"],
    "secret": "your-webhook-secret"
  }' \
  https://api.lineserve.com/v1/messaging/webhooks

Webhook Events

Available webhook events:

• sms.sent: Message sent to carrier
• sms.delivered: Message delivered to recipient
• sms.failed: Message delivery failed
• sms.expired: Message expired
• sms.rejected: Message rejected by carrier

Webhook Payload

{
  "event": "sms.delivered",
  "timestamp": "2024-01-15T10:30:15Z",
  "data": {
    "message_id": "msg_123456789",
    "to": "+254700123456",
    "from": "YourBrand",
    "status": "delivered",
    "delivered_at": "2024-01-15T10:30:15Z",
    "network": "Safaricom",
    "country": "Kenya"
  }
}

Analytics

Get Delivery Statistics

Get delivery statistics for your messages.

Endpoint: GET /messaging/analytics/delivery

Parameters:

• from_date (optional): Start date
• to_date (optional): End date
• group_by (optional): Group by (day, week, month)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/messaging/analytics/delivery?from_date=2024-01-01&to_date=2024-01-31&group_by=day"

Example Response:

{
  "analytics": [
    {
      "date": "2024-01-15",
      "total_messages": 1000,
      "delivered": 985,
      "failed": 15,
      "delivery_rate": 98.5,
      "total_cost": 50.00
    }
  ],
  "summary": {
    "total_messages": 30000,
    "total_delivered": 29550,
    "total_failed": 450,
    "average_delivery_rate": 98.5,
    "total_cost": 1500.00
  }
}

Error Handling

HTTP Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 422 - Unprocessable Entity
• 429 - Rate Limited
• 500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number format is invalid",
    "details": {
      "field": "to",
      "value": "invalid-number"
    }
  }
}

Common Error Codes

• invalid_phone_number: Phone number format is invalid
• sender_id_not_approved: Sender ID not approved for target country
• insufficient_balance: Account balance too low
• message_too_long: Message exceeds character limit
• rate_limit_exceeded: Too many requests
• invalid_template: Template not found or invalid

Rate Limiting

• Rate Limit: 1000 requests per hour per API key
• Burst Limit: 100 requests per minute
• SMS Limit: 10,000 messages per hour

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000
X-SMS-Limit: 10000
X-SMS-Remaining: 9999

SDKs and Libraries

Official SDKs available for:

• Node.js: npm install @lineserve/node
• Python: pip install lineserve
• PHP: composer require lineserve/php
• Go: go get github.com/lineserve/go

Testing

Test Mode

Use test mode to send messages without actual delivery:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Test-Mode: true" \
  -d '{
    "to": "+254700123456",
    "message": "Test message",
    "from": "YourBrand"
  }' \
  https://api.lineserve.com/v1/sms/send

Test Phone Numbers

Use these numbers for testing (no actual SMS sent):

• +254700000001 - Always succeeds
• +254700000002 - Always fails
• +254700000003 - Random success/failure

Next Steps

• Compute API
• Storage API
• Billing & Projects API
• SMS Tutorial