Skip to content

Send Message

Send messages through SMSBAT API using the /bat/messagelist endpoint.

Endpoint

POST /bat/messagelist

Request Structure

The request body is a JSON array of message objects:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Parameters

Required Parameters

Parameter Type Description
from string Alphanumeric sender ID
to string Recipient phone number in E.164 format (e.g., +380XXXXXXXXX)
type string Message type: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
text string Message content (required for most types, optional for some)

Optional Parameters

Parameter Type Description
customerMessageId string Your internal identifier for tracking
ttl integer Time-to-live in seconds
messageData object Type-specific configuration (varies by message type)

Authentication

Choose one of three authentication methods:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

Response

Success Response

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Response Fields

Field Type Description
messagelistId integer Unique identifier for the message list
messageId string Unique identifier for each message
status string Message status: accepted, rejected, failed
parts integer Number of message parts (for SMS)
customerMessageId string Your internal identifier (if provided)
to string Recipient phone number

Message Types

SMS

Simple text messages:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Viber Promo

Promotional messages with rich media:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber Transactional

Transaction notifications:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

One-time password notifications:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Error Handling

HTTP Status Codes

Code Description
200 Request successful
400 Bad request - invalid parameters
401 Unauthorized - authentication failed
429 Too many requests - rate limit exceeded
500 Internal server error

Error Response

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Best Practices

Phone Number Format

Always use E.164 format for phone numbers:

  • ✅ Correct: +380XXXXXXXXX
  • ❌ Incorrect: 380XXXXXXXXX, 0XXXXXXXXX

Message Text

  • Keep SMS under 160 characters to avoid multiple parts
  • Use UTF-8 encoding for international characters
  • Test special characters before bulk sending

TTL (Time-to-Live)

  • Set appropriate TTL for time-sensitive messages
  • OTP messages: 300-600 seconds (5-10 minutes)
  • Promotional messages: 3600-86400 seconds (1-24 hours)

Customer Message ID

  • Use unique identifiers for each message
  • Helps with tracking and debugging
  • Useful for correlating with your system's records

Rate Limits

Contact your account manager for information about:

  • Messages per second
  • Messages per day
  • Concurrent connections

Next Steps