Send your first SMS in 5 minutes

This guide takes you from an API key to a delivered message, with curl or the Node SDK.

1. Create an API key

In the portal: API → Keys → New key. Two kinds exist:

The full key is shown once. Keep it in an environment variable (BATLER_API_KEY), never in client-side code.

2. Make sure you have a verified sender

Every message is sent from an approved sender name: a shared name from the system list, or a name approved for your account. New names are requested in the portal (Sender names → request a new name): capital Latin letters, up to 10 characters, with a business certificate and an ID document. You get an answer within one business day. GET /senders returns the full list.

3. Send a message

curl -X POST https://smsprovider-web.vercel.app/api/v1/messages \
  -H "Authorization: Bearer $BATLER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "0501234567", "from": "MyBrand", "body": "Hi! Your order has shipped"}'

Or with the SDK:

import { BatlerSMS } from "@batler/sms";

const sms = new BatlerSMS({ apiKey: process.env.BATLER_API_KEY! });
const res = await sms.messages.send({ to: "0501234567", from: "MyBrand", body: "Hi! Your order has shipped" });
console.log(res.messages[0].id);

The response comes back immediately, before the actual send:

{
  "batch_id": "7d1c3c5e-2b1f-4c55-9a51-1f0b8f1b2a10",
  "accepted": 1,
  "rejected": [],
  "credits_reserved": 1,
  "messages": [{ "id": "0e9b2f0a-6c1d-4f43-8c33-6f3b3f0d9a11", "status": "queued", "to": "+972501234567", "segments": 1, "credits": 1 }]
}

4. Track delivery

• Webhook (recommended): register a URL and receive message.delivered / message.failed in real time — see Webhooks.
• Polling: GET https://smsprovider-web.vercel.app/api/v1/messages/{id}.

Message lifecycle: queued → sent → delivered / failed / expired. A cancelled scheduled message becomes cancelled and its credits are released.

Important rules

• Idempotency-Key is required on every send POST. The same key within 24 hours returns the same response without charging twice — safe to retry after a timeout.
• Phones are accepted as 05XXXXXXXX, 5XXXXXXXX, +972… or 972… and always returned in E.164.
• A delivery failure (handset off, number does not exist) does not refund the credit; a failure before sending releases it.