SMS API FAQ

Frequently asked questions about the Hixbe SMS Gateway API

Getting Started with SMS

Basic SMS Sending

How do I send a single SMS?

Send a POST request to /sms/send with the recipient and message:

curl -X POST "https://api.hixbe.com/sms/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[phone]",
    "message": "Hello from Hixbe!",
    "from": "YourSender"
  }'

What's the maximum SMS length?

Standard SMS allows 160 characters. Longer messages are automatically split into multiple parts (concatenated SMS).

How do I send SMS to multiple recipients?

Use the bulk SMS endpoint /sms/send-bulk with an array of recipients:

{
  "recipients": [
    {"to": "[phone]", "message": "Personal message 1"},
    {"to": "[phone]", "message": "Personal message 2"}
  ],
  "from": "YourSender"
}

Sender IDs and Branding

What is a sender ID?

A sender ID is the name or number that appears as the sender of your SMS messages (e.g., “YourBrand” instead of a phone number).

How do I get a custom sender ID?

Submit a sender ID request through the API or dashboard. Approval typically takes 1-2 business days and requires valid business documentation.

Can I use any sender ID?

Sender IDs must be alphanumeric (up to 11 characters) and approved by carriers. Some countries restrict numeric-only sender IDs.

Message Templates

Template Management

Why use SMS templates?

Templates ensure consistent messaging, reduce errors, and can be pre-approved for better deliverability in regulated markets.

How do I create a template?

curl -X POST "https://api.hixbe.com/sms/templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "content": "Your order {{order_id}} has been confirmed. Track at {{tracking_url}}",
    "variables": ["order_id", "tracking_url"]
  }'

How do I use templates in messages?

Reference templates by ID and provide variable values:

{
  "to": "[phone]",
  "template_id": "tmpl_123",
  "template_variables": {
    "order_id": "ORD-12345",
    "tracking_url": "https://track.example.com/12345"
  }
}

Delivery and Status

Message Delivery

How do I track message delivery?

Use webhooks to receive delivery status updates. Register a webhook endpoint to get real-time notifications for sent, delivered, and failed messages.

What delivery statuses are available?

• sent - Message accepted by carrier
• delivered - Message delivered to recipient
• failed - Delivery failed
• undelivered - Message expired or blocked

How long do messages take to deliver?

Most messages deliver within seconds, but delivery can take up to 24 hours in some regions due to carrier routing.

Handling Failures

Why do messages fail?

Common reasons: invalid phone numbers, recipient opted out, insufficient credits, sender ID restrictions, or carrier blocks.

How do I handle delivery failures?

Implement proper error handling and retry logic. Use webhooks to track failures and notify users when messages can’t be delivered.

Can I resend failed messages?

Yes, but implement a retry limit (max 3 attempts) and respect user opt-out preferences.

Account Management

Balance and Billing

How do I check my SMS balance?

curl -X GET "https://api.hixbe.com/sms/balance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01"

How are SMS messages billed?

Billing is per message segment. Standard messages (160 chars) = 1 segment. Longer messages are split into multiple segments.

What happens when I run out of credits?

API calls will return INSUFFICIENT_BALANCE errors. Set up balance alerts via webhooks to avoid service interruption.

International SMS

Global Messaging

Can I send SMS internationally?

Yes, Hixbe supports SMS delivery to over 200 countries. Pricing varies by destination country.

How do phone number formats work?

Use international format with country code: +1 for US/Canada, +44 for UK, +91 for India, etc. Do not include spaces, dashes, or parentheses.

Are there country-specific restrictions?

Some countries require pre-registration of sender IDs, have content restrictions, or require local entity registration. Check our coverage documentation.

Compliance and Regulations

SMS Regulations

What are TCPA regulations?

In the US, the TCPA requires prior express consent for marketing SMS. Include opt-out instructions in all messages.

How do I handle opt-outs?

Always include “Reply STOP to unsubscribe” in marketing messages. Honor opt-out requests immediately and maintain suppression lists.

What content is restricted?

Avoid spam, phishing, fraudulent content, and restricted materials. Some countries prohibit political or religious content.

Webhooks and Integration

SMS Webhooks

How do I set up delivery webhooks?

Register a webhook endpoint to receive delivery notifications:

curl -X POST "https://api.hixbe.com/sms/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/sms",
    "events": ["message.delivered", "message.failed"]
  }'

What webhook events are available?

• message.sent - Message sent to carrier
• message.delivered - Delivered to recipient
• message.failed - Delivery failed
• balance.low - Account balance low

How do I secure my webhooks?

Always verify webhook signatures and use HTTPS endpoints. Implement idempotency to handle duplicate events.

Testing and Development

SMS Testing

How do I test SMS without sending real messages?

Use our sandbox environment with test phone numbers. Messages won’t be delivered but you’ll receive success responses for testing.

What test phone numbers can I use?

Use any valid phone number format in sandbox. For testing failures, use specific test numbers that trigger different error conditions.

How do I test webhooks locally?

Use tools like ngrok to expose local endpoints or use webhook testing services like RequestBin for initial testing.

Performance and Reliability

Rate Limits and Throttling

What are the rate limits?

SMS API allows 50 requests per minute per API key. Bulk SMS endpoints have higher limits for large sends.

How do I handle rate limiting?

Implement exponential backoff and monitor the rate limit headers in responses.

Can I send high-volume SMS?

For high-volume messaging, use the bulk SMS endpoints and consider our enterprise plans for higher throughput.

Error Handling

Common SMS Errors

INSUFFICIENT_BALANCE

Top up your account balance. Set up balance monitoring to avoid this error.

INVALID_RECIPIENT

Check phone number format. Ensure it includes country code and is valid for the destination country.

SENDER_ID_UNAVAILABLE

Your sender ID is not approved or blocked. Contact support to resolve sender ID issues.

Pricing and Billing

SMS Costs

How much does SMS cost?

Pricing varies by destination country, typically $0.01-$0.10 per message. Check your dashboard for current rates.

Are there setup fees?

No setup fees. You only pay for messages sent. Different pricing tiers available for high-volume users.

How do I monitor my spending?

Use the dashboard to track message volume, delivery rates, and costs. Set up spending alerts and limits.

Need More Help?

SMS API Docs

Complete API reference

Webhooks

Set up SMS delivery notifications

Error Handling

Handle SMS errors

Best Practices

SMS integration best practices

Troubleshooting

SMS-specific issues

Support

Contact our support team