# AlphaSMS

> Messaging platform: SMS, Viber, RCS, voice calls, plus number lookup via HLR and MNP.
> Works over HTTP: one endpoint, JSON in and JSON out. There is a synchronous mode
> (answer right away) and an asynchronous one (queued).

Documentation: https://docs.alphasms.net
Synchronous API: https://alphasms.net/api/json.php

## Sending your first message

The key is issued in your personal cabinet: Settings → API → Add. It is shown once.

The request is a POST with the header `Content-Type: application/json`:

```json
{
  "auth": "YOUR_KEY",
  "data": [
    { "type": "sms", "id": 1, "phone": "380671234567", "sms_signature": "ALPHA", "sms_message": "Your code is 1234" }
  ]
}
```

`data` is always an array, even for a single message. The `type` field picks the channel.

## Request types

- `sms` — send an SMS
- `viber` — send a Viber message
- `rcs` — send an RCS message
- `voice` — voice call
- `status` — status of a message sent earlier
- `balance` — account balance
- `sender` — list of registered sender names
- `verify` — send a verification code
- `hlr` — check the number in the operator network
- `mnp` — check whether the number was ported between operators
- `pipeline` — one recipient, several channels one after another (this is the only way to reach WhatsApp)

## What to know before the first call

- **The sender name is registered in advance.** An operator will not pass an arbitrary
  signature. Registration takes 7–14 business days. Format: 3–11 Latin characters.
- **Message length drives the price.** The first SMS holds 160 Latin characters or 70
  Cyrillic ones. Anything longer is split into parts, each charged separately.
  A single Cyrillic letter in Latin text moves the whole message into the expensive mode.
- **The key expires.** A sudden "it stopped sending" usually means an expired key rather
  than a platform failure.
- **IP allow list.** If it is filled in, requests from other addresses are refused.
  It understands single addresses, ranges with a dash and CIDR subnets.

## Error codes

- `200` unknown error · `201` request format · `202` sender or authorization
- `203` recipient · `204` text length · `205` user disabled · `206` billing
- `207` limit exceeded · `208` duplicate · `209` API disabled in the cabinet
- `210` IP not in the allow list · `211` deletion error · `212` requests too frequent

## Delivery statuses

Only "delivered", "read" and "replied" count as delivery. "Sent" means the message left
for the operator but the report has not come back yet — an operator may return it with a
delay of several hours.

## Delivery status webhooks

Pass `hook` when sending and the platform will POST the status to that address. Up to three
attempts, with pauses of 10 and 60 seconds; a repeat happens only on a broken connection,
a timeout, a 5xx or a 429. Only HTTP 200 counts as success. Timeouts: 5 seconds to connect,
5 seconds in total. Make the handler idempotent: the same status may arrive more than once.

## Documentation sections

- [Getting started](https://docs.alphasms.net/)
- [API method reference](https://docs.alphasms.net/api_methods/)
- [JSON API](https://docs.alphasms.net/api/json/) — the recommended way
- [HTTP API](https://docs.alphasms.net/api/http/)
- [XML API](https://docs.alphasms.net/api/xml/)
- [Send SMS](https://docs.alphasms.net/api/json/send_sms/)
- [Message status](https://docs.alphasms.net/api/json/message_status/)
- [Balance](https://docs.alphasms.net/api/json/balance/)
- [Sender names](https://docs.alphasms.net/api/json/sender/)
- [HLR number lookup](https://docs.alphasms.net/api/json/hlr/)
- [Status webhooks](https://docs.alphasms.net/api/json/webhook/)
- [Multichannel sending (pipeline)](https://docs.alphasms.net/api/json/multi_channel/)

## Documentation languages

- en (default): https://docs.alphasms.net/