# VoidFix SMS API

> Send and receive SMS and MMS through Android phones connected to a VoidFix account: send single, bulk or scheduled messages, follow delivery status, read conversations and replies, manage contact lists and opt-outs, receive webhook events and run USSD codes. Plain HTTP + JSON.

- Interactive docs: https://sms.voidfix.com/api-docs.php
- OpenAPI 3.1 document: https://sms.voidfix.com/openapi.json

## Get the API key

The user finds it in their VoidFix dashboard:
1. Sign in at https://sms.voidfix.com
2. Left menu: API & Settings
3. API key section: click "Copy key"
Direct link: https://sms.voidfix.com/configuration.php#api

## Setup for an AI agent

1. Ask the user for their VoidFix API key (steps above). Store it as a secret, e.g. `VOIDFIX_API_KEY`. Never print it, log it or commit it.
2. Base URL: `https://sms.voidfix.com`
3. Authentication: add the API key as the `key` parameter on every request (query string for GET, form field for POST). There is no header-based authentication.
4. Test the key: `GET /services/v2/get-account.php?key=...`. `success: true` means it works.
5. List the phones that can send: `GET /services/get-devices.php?key=...`.

## Rules

- Requests: GET query parameters or POST form fields (`application/x-www-form-urlencoded`). Not a JSON body.
- Responses are always JSON with HTTP 200, even on errors: `{"success": true, "data": {...}, "error": null}` or `{"success": false, "data": null, "error": {"code": 401, "message": "..."}}`. Always check `success`.
- Error codes: 400 bad or missing parameter, 401 wrong API key, 403 not your resource, 404 nothing found, 500 server error.
- Phone numbers include the country code, e.g. `+15551234567`.
- SIM slots: `0` = SIM 1, `1` = SIM 2.
- Timestamps in parameters are Unix seconds; dates in responses are ISO 8601 (UTC).
- Paged lists return `page`, `limit`, `total`, `hasMore`. List messages pages by ID with `next.beforeId` / `next.afterId`.

## Endpoints

### Messages
- `POST /services/send.php` Send messages. Provide `number` + `message` (one or comma-separated numbers), or `messages` (JSON array string of `{"number","message"}`), or `listID` + `message` (a contact list; `%name%` = contact name). Optional: `devices` (device ID, or JSON array of "deviceID|simSlot"), `simSlot` (0/1 with one device), `option` (1 = all devices, 2 = all SIMs), `type` (`sms`|`mms`), `attachments` (comma-separated URLs, MMS), `schedule` (Unix time), `prioritize` (1). Returns `data.messages[]` with `ID`, `status`, `groupID`.
- `GET /services/send.php` with only `key`: balance. `data.credits` (`null` = unlimited).
- `GET /services/read-messages.php` Look up messages by `id`, `groupId`, `status`, `deviceID`, `simSlot`, `startTimestamp`, `endTimestamp`. Returns all matches (no paging).
- `GET /services/v2/list-messages.php` Paged history. Filters: `number`, `direction` (inbound|outbound), `status` (comma-separated), `groupId`, `deviceID`, `simSlot`, `startTimestamp`, `endTimestamp`. Paging: `beforeId`, `afterId`, `limit` (1-200, default 50). Newest first; with `afterId`, oldest first. Returns `data.messages[]` (each has `direction`), `hasMore`, `next`.
- `POST /services/resend.php` Resend messages matching the same filters as read-messages, e.g. `status=Failed&groupId=...`.
- `POST /services/v2/cancel-messages.php` Cancel not-yet-sent messages (Pending, Queued, Scheduled) by `id` or `groupId`. Returns `canceled`, `ids`.
- `GET /services/v2/get-message-stats.php` Counts per status, totals and `successRate` for `startTimestamp`..`endTimestamp` (default last 30 days); optional `deviceID`, `simSlot`.

### Conversations
- `GET /services/v2/get-conversations.php` One row per number, newest activity first: `number`, `messageCount`, `unreadCount`, `lastMessage`. Params: `page`, `limit` (1-100), `search`, `unread=1`.
- `POST /services/v2/mark-read.php` `number`, optional `lastId`. Marks the conversation read (shared with the dashboard chat).

### Devices
- `GET /services/get-devices.php` Connected phones: `id`, `name`, `model`, `androidVersion`, `appVersion`, `sims` (slot -> label with number).

### Contacts
- `GET /services/v2/get-contacts-lists.php` Lists with `ID`, `name`, `contacts`, `subscribed`.
- `POST /services/v2/add-contacts-list.php` `name`. Creates a list.
- `GET /services/v2/get-contacts.php` `listID` (required), `page`, `limit` (1-500), `search`, `subscribed` (0/1).
- `POST /services/manage-contacts.php` `listID`, `number`, optional `name`. Add `resubscribe=1` to re-subscribe, or `unsubscribe=1` to unsubscribe. Returns `data.contact`.

### Opt-outs (blacklist)
- `GET /services/v2/get-blacklist.php` Numbers you never send to. `page`, `limit`, `search`.
- `POST /services/v2/add-to-blacklist.php` `number` (comma-separated). Use when someone replies STOP.
- `POST /services/v2/remove-from-blacklist.php` `number` (comma-separated).

### Templates
- `GET /services/v2/get-templates.php` Saved templates: `ID`, `name`, `message`.

### Webhook settings
- `GET /services/v2/get-webhook.php` Current webhook URL or null.
- `POST /services/v2/set-webhook.php` `url` (http/https). Empty `url` removes it.

### USSD
- `POST /services/send-ussd-request.php` `request` (e.g. `*150#`), `device`, optional `sim` (0/1). The reply arrives later.
- `GET /services/read-ussd-requests.php` `id`, `request`, `deviceID`, `simSlot`, `startTimestamp`, `endTimestamp`. Each has `response` once it arrives.

### Account
- `GET /services/v2/get-account.php` `name`, `email`, `timeZone`, `credits`, `unlimitedCredits`, `expiryDate`, `connectedDevices`, `webhookEnabled`.

## Examples

```bash
# Check the key
curl "https://sms.voidfix.com/services/v2/get-account.php?key=$VOIDFIX_API_KEY"

# Send an SMS
curl -X POST https://sms.voidfix.com/services/send.php \
  -d key=$VOIDFIX_API_KEY -d number=+15551234567 -d message="Hello from VoidFix"

# Send from device 12, SIM 2
curl -X POST https://sms.voidfix.com/services/send.php \
  -d key=$VOIDFIX_API_KEY -d number=+15551234567 -d message="Hi" -d devices=12 -d simSlot=1

# New replies since message 1234 (poll every few seconds, remember the highest ID)
curl "https://sms.voidfix.com/services/v2/list-messages.php?key=$VOIDFIX_API_KEY&direction=inbound&afterId=1234"

# Inbox with unread conversations
curl "https://sms.voidfix.com/services/v2/get-conversations.php?key=$VOIDFIX_API_KEY&unread=1"

# Someone replied STOP
curl -X POST https://sms.voidfix.com/services/v2/add-to-blacklist.php -d key=$VOIDFIX_API_KEY -d number=+15551234567
```

## Webhooks (events)

Set a URL with set-webhook.php or in API & Settings > Webhooks. VoidFix then POSTs form data to it:
- field `messages`: JSON array of messages, sent when a message is received or a sent message changes status.
- field `ussdRequest`: JSON USSD request, sent when a USSD reply arrives.
Header `X-SG-Signature` = base64(HMAC-SHA256(raw field value, API key)). Verify it before trusting the payload, and reply with any 2xx status.