> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xerobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS API FAQ

> Frequently asked questions about the Xerobi SMS Gateway API

## Getting Started with SMS

### Basic SMS Sending

> [accordion] How do I send a single SMS?
>
> Send a POST request to `/sms/send` with the recipient and message:
>
> ```bash theme={null}
> curl -X POST "https://api.hixbe.com/sms/send" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-Version: 2026-01-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "to": "+1234567890",
>     "message": "Hello from Xerobi!",
>     "from": "YourSender"
>   }'
> ```

> [accordion] What's the maximum SMS length?
>
> Standard SMS allows 160 characters. Longer messages are automatically split into multiple parts (concatenated SMS).

> [accordion] How do I send SMS to multiple recipients?
>
> Use the bulk SMS endpoint `/sms/send-bulk` with an array of recipients:
>
> ```json theme={null}
> {
>   "recipients": [
>     {"to": "+1234567890", "message": "Personal message 1"},
>     {"to": "+1234567891", "message": "Personal message 2"}
>   ],
>   "from": "YourSender"
> }
> ```

### Sender IDs and Branding

> [accordion] 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).

> [accordion] 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.

> [accordion] 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

> [accordion] Why use SMS templates?
>
> Templates ensure consistent messaging, reduce errors, and can be pre-approved for better deliverability in regulated markets.

> [accordion] How do I create a template?
>
> ```bash theme={null}
> curl -X POST "https://api.hixbe.com/sms/templates" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-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"]
>   }'
> ```

> [accordion] How do I use templates in messages?
>
> Reference templates by ID and provide variable values:
>
> ```json theme={null}
> {
>   "to": "+1234567890",
>   "template_id": "tmpl_123",
>   "template_variables": {
>     "order_id": "ORD-12345",
>     "tracking_url": "https://track.example.com/12345"
>   }
> }
> ```

## Delivery and Status

### Message Delivery

> [accordion] 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.

> [accordion] What delivery statuses are available?
>
> * `sent` - Message accepted by carrier
> * `delivered` - Message delivered to recipient
> * `failed` - Delivery failed
> * `undelivered` - Message expired or blocked

> [accordion] 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

> [accordion] Why do messages fail?
>
> Common reasons: invalid phone numbers, recipient opted out, insufficient credits, sender ID restrictions, or carrier blocks.

> [accordion] 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.

> [accordion] 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

> [accordion] How do I check my SMS balance?
>
> ```bash theme={null}
> curl -X GET "https://api.hixbe.com/sms/balance" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-Version: 2026-01-01"
> ```

> [accordion] How are SMS messages billed?
>
> Billing is per message segment. Standard messages (160 chars) = 1 segment. Longer messages are split into multiple segments.

> [accordion] 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

> [accordion] Can I send SMS internationally?
>
> Yes, Xerobi supports SMS delivery to over 200 countries. Pricing varies by destination country.

> [accordion] 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.

> [accordion] 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

> [accordion] What are TCPA regulations?
>
> In the US, the TCPA requires prior express consent for marketing SMS. Include opt-out instructions in all messages.

> [accordion] How do I handle opt-outs?
>
> Always include "Reply STOP to unsubscribe" in marketing messages. Honor opt-out requests immediately and maintain suppression lists.

> [accordion] What content is restricted?
>
> Avoid spam, phishing, fraudulent content, and restricted materials. Some countries prohibit political or religious content.

## Webhooks and Integration

### SMS Webhooks

> [accordion] How do I set up delivery webhooks?
>
> Register a webhook endpoint to receive delivery notifications:
>
> ```bash theme={null}
> curl -X POST "https://api.hixbe.com/sms/webhooks" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-Version: 2026-01-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "url": "https://yourapp.com/webhooks/sms",
>     "events": ["message.delivered", "message.failed"]
>   }'
> ```

> [accordion] 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

> [accordion] 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [accordion] What are the rate limits?
>
> SMS API allows 50 requests per minute per API key. Bulk SMS endpoints have higher limits for large sends.

> [accordion] How do I handle rate limiting?
>
> Implement exponential backoff and monitor the rate limit headers in responses.

> [accordion] 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

> [accordion] INSUFFICIENT\_BALANCE
>
> Top up your account balance. Set up balance monitoring to avoid this error.

> [accordion] INVALID\_RECIPIENT
>
> Check phone number format. Ensure it includes country code and is valid for the destination country.

> [accordion] SENDER\_ID\_UNAVAILABLE
>
> Your sender ID is not approved or blocked. Contact support to resolve sender ID issues.

## Pricing and Billing

### SMS Costs

> [accordion] How much does SMS cost?
>
> Pricing varies by destination country, typically $0.01-$0.10 per message. Check your dashboard for current rates.

> [accordion] Are there setup fees?
>
> No setup fees. You only pay for messages sent. Different pricing tiers available for high-volume users.

> [accordion] 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?

> [card] [SMS API Docs](https://docs.xerobi.com/sms-api/introduction.md)
>
> Complete API reference

> [card] [Webhooks](https://docs.xerobi.com/faq-guides/webhooks.md)
>
> Set up SMS delivery notifications

> [card] [Error Handling](https://docs.xerobi.com/faq-guides/error-handling.md)
>
> Handle SMS errors

> [card] [Best Practices](https://docs.xerobi.com/faq-guides/best-practices.md)
>
> SMS integration best practices

> [card] [Troubleshooting](https://docs.xerobi.com/faq-guides/troubleshooting)
>
> SMS-specific issues

> [card] [Support](mailto:support@xerobi.com)
>
> Contact our support team


## Related topics

- [Xerobi SMS Gateway API Introduction](https://docs.xerobi.com/sms-api/introduction.md)
- [Certification API FAQ](https://docs.xerobi.com/faq-guides/certification-api-faq.md)
- [Payment API FAQ](https://docs.xerobi.com/faq-guides/payment-api-faq.md)
- [API Versioning](https://docs.xerobi.com/faq-guides/versioning.md)
- [Xerobi Developer Documentation](https://docs.xerobi.com/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.