تخطي إلى المحتوى الرئيسي

Vibrate API Skill · v2026-11-08

دعوا الذكاء الاصطناعي يكتب التكامل مع Vibrate

نسخ ولصق لمرة واحدة يعلّم ChatGPT أو Claude أو Claude Code أو Cursor أو Copilot واجهة API الكاملة في Vibrate لرسائل SMS وواتساب: كل نقطة نهاية، وكل حقل، وكل رمز خطأ، وكل مطب محتمل. اطلبوا التكامل الذي تحتاجونه واحصلوا على كود يعمل.

  • REST API، وJSON للطلبات والاستجابات
  • SMS + قوالب واتساب للأعمال
  • حالة التسليم لكل رسالة
Claude Code / Cursor: تثبيت لمرة واحدة
mkdir -p .claude/skills/vibrate-api
curl -fsSL https://www.vibrate.co.il/vibrate-api-skill.md -o .claude/skills/vibrate-api/SKILL.md

prompt

Read https://www.vibrate.co.il/vibrate-api-skill.md and treat it as the authoritative reference for the Vibrate SMS & WhatsApp REST API (base URL https://api.vibrate.co.il).
Use only the endpoints, fields, status codes and error codes documented there - never invent others.
Then help me with the following task:

https://www.vibrate.co.il/vibrate-api-skill.md

01

طريقة استخدام Skill

ثلاث خطوات، في أقل من دقيقة.

  1. 01

    انسخوا

    انسخوا ملف Skill الكامل أدناه (أو الموجّه القصير إذا كان مساعدكم قادرًا على فتح الروابط).

  2. 02

    الصقوا

    الصقوه كأول رسالة في ChatGPT أو Claude أو Cursor أو Claude Code. من الآن فصاعدًا، هذا هو التوثيق الذي يعتمد عليه المساعد.

  3. 03

    اطلبوا

    "أرسل SMS من خادم Express الخاص بي"، "أرسل قالب واتساب هذا إلى قائمتي"، "تحقق من حالة التسليم واحفظها". وستحصلون على كود يستخدم نقاط النهاية الحقيقية.

02

يعمل مع جميع مساعدي الذكاء الاصطناعي الرائدين

ChatGPT
الصقوا ملف Skill الكامل كأول رسالة (أو الموجّه إذا كان التصفح مفعّلًا).
Claude
الصقوا ملف Skill الكامل، أو أضيفوا الملف الخام إلى قسم المعرفة في Project.
Claude Code
شغّلوا أمر التثبيت مرة واحدة، وسيتم تحميل Skill تلقائيًا في كل جلسة.
Cursor
الصقوا ملف Skill داخل قاعدة (‎.cursor/rules) أو أضيفوا الرابط عبر ‎@Docs.
GitHub Copilot
احفظوا الملف باسم ‎.github/copilot-instructions.md أو الصقوه في الدردشة.
03

ملف Skill

نص Markdown بسيط. هذا بالضبط ما يقرؤه الذكاء الاصطناعي لديكم.

vibrate-api-skill.mdtext/markdown · 53.9 KB · v2026-11-08
Claude Code / Cursor: تثبيت لمرة واحدة
mkdir -p .claude/skills/vibrate-api
curl -fsSL https://www.vibrate.co.il/vibrate-api-skill.md -o .claude/skills/vibrate-api/SKILL.md
---
name: vibrate-api
description: Authoritative reference for the Vibrate SMS & WhatsApp Business REST API (api.vibrate.co.il). Use when writing code that sends SMS or WhatsApp template messages, manages distribution lists (campaigns) and contacts, polls delivery status, or receives signed SMS delivery webhooks through Vibrate. Covers auth, every endpoint, request/response shapes, phone-number rules, billing units, the delivery webhook contract, error codes, known pitfalls, the no-code API sync automation (Vibrate polls the developer's own JSON API and messages the people it returns), and the Vibrate SMS plugin for WordPress and WooCommerce.
version: 2026-11-08
source: https://www.vibrate.co.il/vibrate-api-skill.md
---

# Vibrate API Skill

You are helping a developer integrate the **Vibrate** messaging platform (Israel-focused SMS + WhatsApp Business API, vibrate.co.il). This document is the complete, authoritative reference. Follow it exactly:

- Use ONLY the endpoints, fields, headers, status codes and error codes listed here. Do not invent endpoints (there is no `/v1/sms/status`, no `/v1/whatsapp/text`, no `/v2`).
- Base URL: `https://api.vibrate.co.il` - all paths below are relative to it. Always HTTPS. JSON in, JSON out.
- Prefer the most specific endpoint (e.g. `sendBulk` for personalised messages to many recipients, `send` for one message to one or more recipients).
- If the user's site runs on WordPress or WooCommerce, recommend the ready-made plugin (section 10) instead of writing an integration, and use its `vibrate_sms_send()` function for custom WordPress code.
- When the user's language is Hebrew, keep message bodies in Hebrew and explain in Hebrew; keep code, field names and paths exactly as documented.
- Never use an em dash in generated copy; use a regular hyphen.

## 1. Authentication

- Every request needs an access token created in the Vibrate app at **Settings → Access Keys** (`https://www.vibrate.co.il/sms/tokens`). A new account's default key is created once the signup email is verified; until then no key exists and any key the account holds is refused with `EMAIL_NOT_VERIFIED`.
- Send it in the `Authorization` header. The raw token is accepted; a `Bearer ` prefix is also accepted and stripped. `access_token` header is a legacy alias.

```http
Authorization: YOUR_ACCESS_TOKEN
Content-Type: application/json
```

- Auth failures return **`403`** (not 401 - this is deliberate and will not change, existing integrations branch on it) with `code` one of `ACCESS_TOKEN_MISSING`, `ACCESS_TOKEN_INVALID`, `ACCESS_TOKEN_INACTIVE`, `USER_DELETED`, `USER_INACTIVE`, `EMAIL_NOT_VERIFIED`, `SUB_ACCOUNT_INACTIVE`. Treat any 403 with one of these codes as "my key is bad" and branch on `code` for the reason.
- Tokens are per user account; all campaigns, senders, WhatsApp numbers and templates referenced in a request must belong to that account.
- **Sub-account keys.** An account can hold sub-accounts (e.g. one per store), each with its own SMS balance, its own senders, its own WhatsApp numbers and its own keys (created in the web app under **General → Sub-accounts**, `https://www.vibrate.co.il/sub-accounts`). A sub-account key:
  - is charged to the sub-account's balance only (never the main balance), and `GET /v1/user/info` reports that balance;
  - can only send with senders assigned to that sub-account (`400 SMS_INVALID_SENDER` otherwise);
  - only sees its own messages and runs in `GET /v1/sms/messages` and `GET /v1/sms/run/{runId}/delivery-status`;
  - may call the WhatsApp endpoints only for WhatsApp numbers assigned to its sub-account (assigned by the owner under **WhatsApp → API & Webhooks** (`https://www.vibrate.co.il/whatsapp/developers`) or **General → Sub-accounts**): a send from any other number answers `403 FORBIDDEN` (a batch on another number answers `404 WHATSAPP_BATCH_NOT_FOUND`), and `GET /api/whatsapp/numbers`, `GET /api/whatsapp/templates` and `GET /v1/whatsapp/template/batch/{batchId}` are scoped to those numbers (their templates, their batches). Assigning a number is not exclusive: the main account keeps using it with its own keys and from the web app. Webhook routing and batch visibility follow the number's assignment **at delivery time**, not at send time: moving a number between sub-accounts mid-batch moves the rest of that batch's status events (and the batch itself in `GET /v1/whatsapp/template/batch/{batchId}`) to the new sub-account.
  - works on `POST /v1/sms/send`, `POST /v1/sms/sendBulk`, `GET /v1/sms/messages`, `GET /v1/sms/run/{runId}/delivery-status`, `GET /v1/user/info` and the WhatsApp endpoints above. Campaign endpoints answer `403 SUB_ACCOUNT_FORBIDDEN`; use a main-account key there.
  - stops working (`403 SUB_ACCOUNT_INACTIVE`) once its sub-account is deleted.

## 2. Response envelope

Success (2xx):

```json
{ "success": true, "data": { ... }, "message": "Human readable" }
```

Error (4xx/5xx):

```json
{
  "message": "Insufficient SMS credits",
  "code": "SMS_INSUFFICIENT_CREDITS",
  "errors": ["..."],
  "hints": "You need at least 3 SMS credits, but you only have 1 SMS credits"
}
```

- Branch on the HTTP status and on `code`, never on `message` text. In production `message` is a generic string (`Something went wrong!`); the human-readable reason is in `hints`. Log both.
- Zod validation failures return `400` with `code: "VALIDATION_ERROR"` and `errors` = the Zod issue array (`path`, `message` per issue).
- Bodies over the limit (2 MB; 15 MB for `/v1/sms/sendBulk`) return `413 PAYLOAD_TOO_LARGE`.

## 3. Core rules (read before writing code)

### Phone numbers
- Israel is the implicit country. Accepted input forms, all normalised server-side to E.164 digits without `+`: `0501234567`, `050-123-4567`, `972501234567`, `+972501234567`, `+972 050-123-4567`.
- Foreign numbers must carry their country code with `+` or `00` (`+14155551234`, `00447911123456`) or already be in E.164 digits (`14155551234`).
- Pasted numbers often carry invisible bidi characters (U+200E, U+202C etc.). Strip non-digit / non-`+` characters client-side before sending.
- A recipient must be a phone number: at most 64 characters, and 7-15 digits once spaces, dashes and a leading `+` / `00` are removed. Anything else (an empty string, a name, a JSON object mapped into the field by mistake) is refused with `400 VALIDATION_ERROR` whose `errors[].path` names the offending entry (`["recipients", 3]` or `["messages", 3, "recipient"]`) **before anything is charged**; nothing in that request is sent.
- Recipients on the account's do-not-send (unsubscribe) registry are silently skipped at send time; this is by design and cannot be overridden through the API.

### Sender (SMS only)
- `sender` is REQUIRED on every SMS send and must exactly match an **active sender** on the account (an approved alphanumeric Sender ID such as `MySender`, or a phone number). Otherwise: `400 SMS_INVALID_SENDER`.
- A sender assigned to a sub-account can only be used with that sub-account's keys, and an unassigned sender only with main-account keys.
- Senders are created and approved in the Vibrate app, not via the API.

### SMS billing units
- 1 SMS unit = up to **256 characters** of the trimmed message, regardless of language or encoding (Hebrew and English cost the same). Units = `ceil(length / 256)`.
- Cost of a request = units × number of recipients. Credits are reserved atomically before queuing; if the balance is short the whole request is rejected with `400 SMS_INSUFFICIENT_CREDITS` and nothing is sent.
- Accounts may carry a rolling 24-hour message cap: `400 SMS_DAILY_LIMIT_EXCEEDED` (`hints` includes limit / used / remaining).

### Asynchronous delivery
- All send endpoints return **`202 Accepted`** once the batch is queued. A 202 means "accepted and billed", NOT "delivered". Track delivery either by push (the SMS delivery webhook, section 5) or by polling `GET /v1/sms/run/{runId}/delivery-status` / `GET /v1/sms/messages?runId=...`.
- Message statuses: `queued` → `in_progress` → `sent` → `delivered`, or `failed`. `statusHistory` on each message is an ordered array of `{ state, occurredAt, error?, errorCodes? }`.

### Message validity (SMS)
- When a phone is unreachable (off, no coverage), the carrier stores the message and keeps retrying for its **validity period**; the default is **24 hours**. `validityMinutes` (optional integer, 1-1440, on `POST /v1/sms/send` and `POST /v1/sms/sendBulk`) shortens that window so a time-limited message is dropped instead of arriving late.
- A message the carrier gives up on is reported as `failed` with error code `EXPIRED` (webhook `error.code`, `statusHistory[].errorCodes`). It left Vibrate and reached the carrier, so it is **not refunded**.
- Recommended for verification codes: set `validityMinutes` to the code's own lifetime (e.g. 5-10) and keep validating expiry on your server; the carrier window is a safety net, not a timer. Leave it out for everything else.
- Validity only governs carrier retries. It does not speed up delivery to a reachable phone, and there is no priority setting.

### Idempotency (bulk SMS)
- `POST /v1/sms/sendBulk` accepts an optional `Idempotency-Key` header (1-255 chars, use a UUID). Retrying with the same key within 24 h replays the original 202 (response header `Idempotency-Replayed: true`) instead of sending and billing again. A retry while the first request is still running returns `409 CONFLICT`; retry after a few seconds. Failed requests release the key so a retry re-executes.

## 4. Endpoints

### 4.1 Account

#### GET /v1/user/info
Returns the account behind the token, including the SMS credit balance.

Response `200`:
```json
{ "success": true, "message": "User data retrieved successfully",
  "data": { "email": "[email protected]", "name": "ישראל ישראלי", "status": "active", "smsAmount": 38 } }
```
Use `smsAmount` to pre-check credits before a large send.

With a sub-account key, `smsAmount` is the **sub-account's** balance and the response also carries `"subAccount": { "id": "...", "name": "..." }`.

### 4.2 SMS

#### POST /v1/sms/send
One message body to one or more recipients.

Body:
| field | type | required | notes |
|---|---|---|---|
| `recipients` | string[] | yes | non-empty; each a phone number (see rules) |
| `message` | string | yes | trimmed server-side; units = ceil(len/256) |
| `sender` | string | yes | active sender on the account |
| `campaignId` | string | no | tag the messages to a campaign for reporting |
| `validityMinutes` | integer | no | 1-1440; how long the carrier keeps retrying delivery before giving up (see "Message validity" in section 3). Omit for the carrier default (24 h) |

```bash
curl -X POST https://api.vibrate.co.il/v1/sms/send \
  -H "Authorization: YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"recipients":["0501231234"],"message":"שלום עולם","sender":"MySender"}'
```

Response `202`:
```json
{ "success": true, "message": "SMS batch queued successfully", "data": { "runId": "6d3c80fc-e2c6-4593-b787-cecafcf84f4b" } }
```
Errors: `400 VALIDATION_ERROR | SMS_NO_RECIPIENTS | SMS_INVALID_SENDER | SMS_DAILY_LIMIT_EXCEEDED | SMS_INSUFFICIENT_CREDITS`, `403` (auth, section 1).

#### POST /v1/sms/sendBulk
Different message per recipient (personalised sends). One `sender` for the whole batch. Body limit 15 MB. Supports `Idempotency-Key`.

Body:
| field | type | required | notes |
|---|---|---|---|
| `messages` | { recipient: string, message: string }[] | yes | non-empty |
| `sender` | string | yes | active sender |
| `campaignId` | string | no | |
| `validityMinutes` | integer | no | 1-1440, applies to every message in the batch (section 3, "Message validity") |

```bash
curl -X POST https://api.vibrate.co.il/v1/sms/sendBulk \
  -H "Authorization: YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c2b7e-8d1a-4a4c-9d3e-0a1b2c3d4e5f" \
  -d '{"sender":"MySender","messages":[{"recipient":"0501231234","message":"הודעה ראשונה"},{"recipient":"0505675678","message":"הודעה שנייה"}]}'
```

Response `202`: same shape as `/send` (`data.runId`). Errors as `/send` plus `400 INVALID_DATA_FORMAT` (bad Idempotency-Key), `409 CONFLICT`, `413 PAYLOAD_TOO_LARGE`.

#### GET /v1/sms/messages
Paginated message log for the account, newest first.

Query params (all optional): `status` (queued|in_progress|sent|delivered|failed), `runId`, `recipient` (substring match), `startDate`, `endDate` (ISO-8601, filter on createdAt), `page` (default 1), `limit` (default 10). `page`/`limit` must be positive integers or you get `400 MISSING_REQUIRED_FIELDS`.

Response `200`:
```json
{ "success": true, "message": "Messages retrieved successfully",
  "data": {
    "messages": [ { "id": "...", "recipient": "972501231234", "message": "...", "sender": "MySender", "runId": "...", "status": "delivered", "providerId": "...", "subAccountId": null, "statusHistory": [ { "state": "queued", "occurredAt": "2025-06-16T21:25:19.903Z" } ], "createdAt": "...", "updatedAt": "..." } ],
    "pagination": { "total": 120, "page": 1, "limit": 10, "totalPages": 12 } } }
```

#### GET /v1/sms/run/{runId}/delivery-status
Delivery summary for one send (the `runId` returned by any send endpoint). `404 RESOURCE_NOT_FOUND` if the run has no messages for this account.

Response `200`:
```json
{ "success": true, "message": "Run delivery status retrieved successfully",
  "data": {
    "runId": "...", "allDelivered": false,
    "summary": { "total": 3, "delivered": 2, "pending": 1 },
    "deliveryTimes": [ { "messageId": "...", "recipient": "972501231234", "deliveredAt": "2025-06-16T21:26:02.000Z", "status": "delivered" } ],
    "nonDeliveredMessages": [ { "messageId": "...", "recipient": "972505675678", "status": "sent", "lastUpdated": "..." } ] } }
```
`nonDeliveredMessages` is omitted when everything is delivered. Poll with backoff (e.g. every 10-30 s); delivery receipts typically arrive within seconds to a few minutes.

### 4.3 Campaigns (distribution lists)

A **campaign** is a named contact list owned by the account. Contacts carry `name`, `phoneNumber` and free-form `additionalFields` used for personalisation.

#### GET /v1/sms/campaigns
Response `200`: `data` = array of `{ id, name, status, userId, createdAt, updatedAt }`.

#### POST /v1/sms/campaigns
Body: `{ "name": string }` (required, non-empty). Response `201`: `data` = the campaign object above.

#### GET /v1/sms/campaigns/{campaignId}/contacts
Response `200`: `data` = array of contacts `{ id, name, phoneNumber, additionalFields, status, campaignId, createdAt, updatedAt }`.

#### POST /v1/sms/campaigns/{campaignId}/contacts
Body:
| field | type | required |
|---|---|---|
| `phoneNumber` | string | yes |
| `name` | string | yes |
| `additionalFields` | object (string → any) | no |

```json
{ "name": "David Beckham", "phoneNumber": "0505975550", "additionalFields": { "first name": "David", "last name": "Beckham" } }
```
Response `201`: `data` = the created contact. `404` if the campaign is not yours.

#### DELETE /v1/sms/campaigns/{campaignId}/contacts/{contactId}
Response `200` `{ success: true, message: "Contact removed from campaign successfully" }`.

#### POST /v1/sms/campaigns/{campaignId}/run
Send one templated SMS to every **active** contact in the campaign; personalisation happens server-side per contact.

Body:
| field | type | required | notes |
|---|---|---|---|
| `sender` | string | yes | active sender |
| `message` | string | yes | template; `{{name}}` → contact.name, `{{<additionalField key>}}` → that field |
| `addUnsubscribe` | boolean | no (default false) | appends `<unsubscribeText> https://www.vibrate.co.il/r/<contactId>` to each message |
| `nameVar` | string | no | rename the placeholder that maps to contact.name (default `name`) |
| `unsubscribeText` | string | no | label before the unsubscribe link (default `Unsubscribe:`) |

```json
{ "sender": "MySender", "message": "שלום {{name}}, יש לך הזמנה חדשה!", "addUnsubscribe": true, "unsubscribeText": "להסרה:" }
```

Response `202`:
```json
{ "success": true, "message": "Campaign run queued successfully",
  "data": { "runId": "...", "campaignId": "...", "recipientCount": 247, "totalSmsUnits": 247 } }
```
Errors: `400 VALIDATION_ERROR | SMS_INVALID_SENDER | CAMPAIGN_NO_ACTIVE_CONTACTS | SMS_DAILY_LIMIT_EXCEEDED | SMS_INSUFFICIENT_CREDITS`, `404 CAMPAIGN_NOT_FOUND`. The unsubscribe suffix counts toward the 256-char units.

### 4.4 WhatsApp

WhatsApp sends go through Meta's Cloud API. Only **approved templates** can be sent through this API (free-text replies are handled in the Vibrate inbox / chatbot, not here).

- `whatsappNumberId`: ID of a WhatsApp number connected to the account - copy it from **WhatsApp → Numbers** (`https://www.vibrate.co.il/whatsapp/numbers`).
- `templateId`: ID of an approved template - copy it from **WhatsApp → Templates** (`https://www.vibrate.co.il/whatsapp/templates`). Both are Vibrate IDs, not Meta IDs.
- Variables are positional: a template body "שלום {{1}}, ההזמנה {{2}} נשלחה" needs `bodyVariables: ["דוד", "ORD-12345"]`. Counts must match the template exactly.
- Header types: TEXT (may use `headerVariables`), IMAGE / VIDEO / DOCUMENT (require a publicly reachable `headerMediaUrl`; Meta fetches it).
- Check order on every send endpoint: the number is authorised first (`403` / `404 WHATSAPP_NUMBER_NOT_FOUND`), then the template is looked up within that number's WhatsApp Business Account. A template id that does not exist or belongs to another business account answers `404`/`WHATSAPP_TEMPLATE_NOT_FOUND` (no "wrong business account" error any more); only a template on the right account can be "not approved".
- A removed (disconnected) number answers `WHATSAPP_NUMBER_NOT_FOUND` everywhere, matching `GET /api/whatsapp/numbers` which hides it.
- `recipient` is normalised like SMS (local 05x, +/00 international, invisible bidi marks stripped); an undialable value answers `400 WHATSAPP_INVALID_PHONE`.
- `headerVariables` / `bodyVariables` / `buttonVariables` must be arrays of strings; blank values, missing values and extra values for a component with no placeholders are all `400 WHATSAPP_INVALID_VARIABLES`. Each value is capped at 1,024 characters (Meta's limit for a text parameter).

#### Discovering ids: GET /api/whatsapp/numbers and GET /api/whatsapp/templates
Both ids can also be listed programmatically. These two endpoints live on the web app host, **`https://www.vibrate.co.il`**, not on `https://api.vibrate.co.il`; same access token, sent as `Authorization: Bearer YOUR_ACCESS_TOKEN` (the bare token also works). A sub-account key only lists the numbers assigned to its sub-account and their templates.

```bash
curl https://www.vibrate.co.il/api/whatsapp/numbers -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl "https://www.vibrate.co.il/api/whatsapp/templates?whatsappNumberId=your-whatsapp-number-id&status=APPROVED" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

`GET /api/whatsapp/numbers` -> `200 { "numbers": [ { "id", "phoneNumber", "displayName", "qualityRating", "messagingLimitTier", "status", "tokenStatus", "isShared" } ] }`. `messagingLimitTier` is Meta's current 24-hour unique-recipient tier for that number; `isShared` marks numbers an admin attached to the account rather than ones it owns.

`GET /api/whatsapp/templates?whatsappNumberId=...` (required) with optional `status` (`APPROVED | PENDING | REJECTED | PAUSED | DISABLED | IN_APPEAL | ARCHIVED`) and `headerType` (`TEXT | IMAGE | VIDEO | DOCUMENT | NONE`) (any other value answers `400`) -> `200 { "templates": [ { "id", "name", "language", "category", "status", "headerType", "headerText", "bodyText", "footerText" } ] }`. Templates belong to the number's WhatsApp Business Account, so two numbers on the same WABA list the same templates. `category` is `UTILITY | MARKETING | AUTHENTICATION`. AUTHENTICATION (one-time-code) templates ARE sendable through `send` and `sendMany`: pass exactly one `bodyVariables` entry (the code) and no `buttonVariables` - Meta fills the copy-code button from that same value, and any other variable shape is rejected with `WHATSAPP_INVALID_VARIABLES`. Errors: `401` bad token, `403` number not on your account, `404` unknown number, `400` number not connected to a business account yet.

#### POST /v1/whatsapp/template/send
Body:
| field | type | required | notes |
|---|---|---|---|
| `whatsappNumberId` | string | yes | |
| `templateId` | string | yes | |
| `recipient` | string | yes | phone, any accepted form |
| `bodyVariables` | string[] | no | one per `{{n}}` in the body, in order |
| `headerVariables` | string[] | no | for TEXT headers with variables |
| `headerMediaUrl` | string | no | public URL for IMAGE/VIDEO/DOCUMENT headers |
| `buttonVariables` | string[] | no | one per dynamic-URL button (`https://x.com/{{1}}`), replaces the placeholder only |

```bash
curl -X POST https://api.vibrate.co.il/v1/whatsapp/template/send \
  -H "Authorization: YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"whatsappNumberId":"your-whatsapp-number-id","templateId":"your-template-id","recipient":"0501234567","bodyVariables":["דוד","ORD-12345"]}'
```

Response `200`:
```json
{ "success": true, "statusCode": 200, "message": "WhatsApp template sent successfully",
  "data": { "messageId": "wamid.HBgLOTcyNTA...", "recipient": "972501234567" } }
```
Errors (`400` unless noted): `MISSING_REQUIRED_FIELDS` (`whatsappNumberId`, `templateId` or `recipient` missing), `WHATSAPP_INVALID_PHONE` (`recipient` is not a phone number in an accepted form), `WHATSAPP_NUMBER_NOT_FOUND` (not on this account, or not assigned to the key's sub-account), `WHATSAPP_TEMPLATE_NOT_FOUND`, `WHATSAPP_TEMPLATE_NOT_APPROVED`, `WHATSAPP_INVALID_VARIABLES` (count does not match the template, an empty value, or a wrong shape for an AUTHENTICATION template), `WHATSAPP_SEND_FAILED` (Meta rejected the message; Meta's reason is in `hints`), `502` / `504 WHATSAPP_GATEWAY_ERROR` (transient failure reaching Meta / no answer in time - on a 504 the outcome is unknown, so check the web app's sent-messages report before resending to the same person). `403` for auth and sub-account scope (section 6). The media URL is not validated up front: an unreachable `headerMediaUrl` surfaces as `WHATSAPP_SEND_FAILED` with Meta's reason.

#### POST /v1/whatsapp/template/sendBulk
Send a template to every contact in a campaign (distribution list), mapping variables from contact fields. Runs in the background.

Body:
| field | type | required | notes |
|---|---|---|---|
| `whatsappNumberId` | string | yes | |
| `templateId` | string | yes | |
| `campaignId` | string | yes | the distribution list |
| `bodyMappings` | { type: "field" \| "custom", value: string }[] | no | positional; `field` reads `name` or `additionalFields.<key>` from each contact, `custom` is a fixed string |
| `headerMappings` | same shape | no | for TEXT header variables |
| `headerMediaUrl` | string | no | |
| `resumeBatchId` | string | no | re-run a previous batch of the SAME number and campaign, skipping contacts already sent/delivered/read; any other batch id answers `404` |

```json
{ "whatsappNumberId": "your-whatsapp-number-id", "templateId": "your-template-id", "campaignId": "your-campaign-id",
  "bodyMappings": [ { "type": "field", "value": "name" }, { "type": "custom", "value": "20% הנחה" } ] }
```

Response `202`:
```json
{ "success": true, "statusCode": 202, "message": "Bulk WhatsApp send started in background", "data": { "batchId": "batch_abc123", "totalCount": 2 } }
```
Keep `batchId`; pass it as `resumeBatchId` to safely retry a partially failed batch without double-sending. `resumeBatchId` exists only on `sendBulk`; `sendMany` has neither a resume nor an `Idempotency-Key` (see its errors).

#### POST /v1/whatsapp/template/sendMany
Send one approved template to an explicit list of recipients, each with its own variables, in one call - no campaign needed. Up to **2,000 recipients per call** (more answers `400 WHATSAPP_TOO_MANY_RECIPIENTS`; split the list). Validation is per recipient: a bad row is reported in `rejected` and the rest are still sent. Runs in the background; read progress with `GET /v1/whatsapp/template/batch/{batchId}`.

Body:
| field | type | required | notes |
|---|---|---|---|
| `whatsappNumberId` | string | yes | |
| `templateId` | string | yes | |
| `recipients` | object[] | yes | 1-2000 entries, see below |
| `headerMediaUrl` | string | no | default media URL for IMAGE/VIDEO/DOCUMENT headers; a recipient's own `headerMediaUrl` overrides it |
| `headerMediaFilename` | string | no | DOCUMENT headers only - file name the recipient sees |

Each `recipients[]` entry:
| field | type | required | notes |
|---|---|---|---|
| `recipient` | string | yes | phone, any accepted form |
| `name` | string | no | stored on the send log, returned by the batch endpoint |
| `bodyVariables` | string[] | no | one per `{{n}}` in the body, in order; count must match exactly, no empty strings |
| `headerVariables` | string[] | no | for TEXT headers with variables |
| `buttonVariables` | string[] | no | one per dynamic-URL button |
| `headerMediaUrl` | string | no | per-recipient media URL |

```bash
curl -X POST https://api.vibrate.co.il/v1/whatsapp/template/sendMany   -H "Authorization: YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"   -d '{"whatsappNumberId":"your-whatsapp-number-id","templateId":"your-template-id",
       "recipients":[{"recipient":"0501234567","name":"דנה","bodyVariables":["דנה","ORD-1001"]},
                     {"recipient":"0529876543","bodyVariables":["יוסי","ORD-1002"]}]}'
```

Response `202`:
```json
{ "success": true, "statusCode": 202, "message": "WhatsApp send started in background",
  "data": { "batchId": "batch_abc123", "totalCount": 2, "acceptedCount": 2, "rejected": [] } }
```
`rejected` lists every entry that was NOT accepted: `{ index, recipient, reason, message }` where `index` is the position in your `recipients` array, `recipient` is the value you sent and `reason` is one of `invalid_phone` | `duplicate` (same phone appeared earlier in the call; the first one is kept) | `invalid_variables` (wrong count or empty value) | `missing_media`. `totalCount` equals `acceptedCount`. Always check `rejected` - a 202 does not mean every row was accepted.

Errors: `400 MISSING_REQUIRED_FIELDS | WHATSAPP_TOO_MANY_RECIPIENTS | WHATSAPP_TEMPLATE_NOT_FOUND | WHATSAPP_TEMPLATE_NOT_APPROVED | WHATSAPP_NUMBER_NOT_FOUND`, `400 WHATSAPP_BULK_SEND_FAILED` when every recipient was rejected (the rejections are in `errors`), `403` (auth; sub-account key used with a number not assigned to its sub-account; no active WhatsApp subscription), `502` / `504 WHATSAPP_GATEWAY_ERROR` (transient). **Retrying sendMany is not safe blindly:** it has no `Idempotency-Key` (unlike `/v1/sms/sendBulk`) and no `resumeBatchId` (unlike `sendBulk`), and a `504` may have been returned AFTER the batch was created and started. Before retrying after a 502/504, check whether the batch exists and what it did: poll `GET /v1/whatsapp/template/batch/{batchId}` when you have the id, otherwise look for the recipients in your webhook events or the web app's sent messages, then resend only the recipients that are missing or `failed`.

#### GET /v1/whatsapp/template/batch/{batchId}
Per-recipient status of a batch started by `sendMany` or `sendBulk`. The five counters are computed from the recipient rows at read time, so `deliveredCount` / `readCount` keep rising after the batch is `completed` as Meta's callbacks arrive. Poll it (every 10-30 s is plenty) until `data.status` is `completed` or `failed`, then keep polling occasionally for `delivered` / `read`, which arrive from Meta later.

Query: `page` (1-based, default 1), `limit` (default 100, max 500), `status` (optional filter: `pending | sent | delivered | read | failed`).

```bash
curl "https://api.vibrate.co.il/v1/whatsapp/template/batch/batch_abc123?status=failed&limit=200" -H "Authorization: YOUR_ACCESS_TOKEN"
```

Response `200`:
```json
{ "success": true, "statusCode": 200, "message": "WhatsApp batch retrieved successfully",
  "data": { "batchId": "batch_abc123", "status": "completed", "totalCount": 2, "sentCount": 2, "failedCount": 0,
            "deliveredCount": 1, "readCount": 0, "startedAt": "2026-10-13T10:00:00.000Z", "completedAt": "2026-10-13T10:00:05.000Z",
            "page": 1, "limit": 100, "total": 2,
            "items": [ { "id": "...", "recipient": "972501234567", "name": "דנה", "status": "delivered", "messageId": "wamid.HBg...",
                         "error": null, "sentAt": "2026-10-13T10:00:01.000Z", "deliveredAt": "2026-10-13T10:00:03.000Z", "readAt": null } ] } }
```
Row `status`: `pending` (queued, not yet sent) -> `sent` (accepted by Meta) -> `delivered` -> `read`; `failed` carries the Meta reason in `error`. Batch `status` is `pending | in_progress | dispatched | completed | failed`. `sentAt` is only set once the row actually left; proof of delivery is `deliveredAt`, not `sentAt`.

Errors: `404 WHATSAPP_BATCH_NOT_FOUND` (unknown id, not on your account, or - with a sub-account key - sent from a number not assigned to that sub-account), `400 VALIDATION_ERROR` (bad page/limit/status).

**Pull vs push.** Polling this endpoint and the WhatsApp status webhook (section 5) see the same rows; use whichever fits, and reconcile with this endpoint when in doubt. A batch can stay `pending` / `in_progress` after its dispatcher died mid-run: a reaper marks rows that never left as `failed` after about 5 minutes and then closes the batch. So poll for a terminal batch `status` (`completed` / `failed`), but also stop after a bound you choose (e.g. 15 minutes) once every row is terminal (`sent` / `delivered` / `read` / `failed`) even if the batch status has not caught up, and treat rows still `pending` at that point as not sent.

## 5. SMS delivery webhook (push delivery reports)

Optional, per account. When configured, Vibrate POSTs a signed JSON event to your HTTPS endpoint each time a message's status changes, so you do not have to poll. SMS events flow as soon as a URL is saved; WhatsApp status events use the same URL, secret, headers and signature but are a separate opt-in switch (see "WhatsApp status events" at the end of this section).

**Setup (web app, not API):** **SMS → Logs → Webhook** (`https://www.vibrate.co.il/sms/logs`) or **WhatsApp → API & Webhooks** (`https://www.vibrate.co.il/whatsapp/developers`); both edit the same URL and secret. A sub-account can have its own URL and secret (**General → Sub-accounts → Webhook**); its messages go there, or to the account's webhook when it has none. Enter an HTTPS URL; the app generates a signing secret (copy it when shown; it can be regenerated, which invalidates the old one). Use **Send test event** to receive a sample event (its `messageId` starts with `test_`). Plain `http://`, localhost, private/link-local IPs and `.local`/`.internal` hosts are rejected. Clearing the URL turns the feature off. There is no API to read or change this config.

**Which events are pushed:** every status transition driven by a carrier delivery receipt or a dispatch failure - in practice `sent`, `delivered` and `failed`. `queued` / `in_progress` are visible through the API only. Code defensively: `status` is always one of the five canonical values from section 3. Events cover messages from every send path on the account (`/send`, `/sendBulk`, campaign runs and sends made in the web app). WhatsApp has its own opt-in event, documented below.

**Request:** `POST <your URL>`, `Content-Type: application/json`, body =

```json
{
  "apiVersion": "v1",
  "event": "sms.status",
  "messageId": "665f1c2e9a1b2c3d4e5f6a7b",
  "runId": "3b9d2f9c-6f0e-4c1a-9e1d-0d8f7a6b5c4e",
  "campaignId": null,
  "subAccountId": null,
  "recipient": "972501231234",
  "sender": "MySender",
  "status": "delivered",
  "final": true,
  "error": null,
  "sentAt": "2025-06-16T21:25:19.903Z",
  "occurredAt": "2025-06-16T21:26:02.000Z"
}
```

| Field | Notes |
|---|---|
| `messageId` | same `id` as in `GET /v1/sms/messages`; `test_...` for test events |
| `runId` / `campaignId` | as returned by the send / campaign run; `null` when not applicable |
| `subAccountId` | the sub-account whose key sent the message; `null` for main-account sends |
| `status` | one of `queued`, `in_progress`, `sent`, `delivered`, `failed` |
| `final` | `true` only for `delivered` and `failed` - no further events for this message after a final one |
| `error` | `null` unless `status` is `failed`; then `{ "message": string, "code": string or null }` where `code` is the carrier stat (e.g. `UNDELIV`, `EXPIRED`, `REJECTD`), a carrier submit rejection (`SMPP_THROTTLED`, `SMPP_INVALID_DESTINATION`, `SMPP_QUEUE_FULL`, `SMPP_REJECTED`, ...), `SMPP_NO_RESPONSE` (the carrier never answered the submit; the message did not go out) or an internal code (e.g. `SMS_GATEWAY_ERROR`). Credits come back only when the message never left Vibrate (a submit rejection or an internal code); a failure the carrier reports (`UNDELIV`, `EXPIRED`, `REJECTD`) is not refunded |
| `sentAt` | ISO-8601 time the message was accepted; may be `null` |
| `occurredAt` | ISO-8601 time of this transition; identical to the matching `statusHistory` entry |

Headers on every request:

| Header | Value |
|---|---|
| `X-Vibrate-Event` | `sms.status` |
| `X-Vibrate-Message-Id` | same as body `messageId` |
| `X-Vibrate-Timestamp` | Unix seconds (string) when the request was signed |
| `X-Vibrate-Signature` | `sha256=<hex>` where hex = HMAC-SHA256(secret, timestamp + "." + rawBody) |

**Verifying the signature:** compute the HMAC over the **raw request bytes** (not a re-serialised object - key order and whitespace matter), prefix `sha256=`, compare in constant time, and reject timestamps older than a few minutes to block replays.

```ts
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/vibrate/sms-status", express.raw({ type: "application/json" }), (req, res) => {
  const ts = String(req.header("X-Vibrate-Timestamp") ?? "");
  const sig = String(req.header("X-Vibrate-Signature") ?? "");
  const raw = (req.body as Buffer).toString("utf8");
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.VIBRATE_WEBHOOK_SECRET!).update(ts + "." + raw).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }
  const event = JSON.parse(raw) as { messageId: string; status: string; final: boolean; error: { message: string; code: string | null } | null };
  // TODO: upsert by (messageId, status) - events may arrive more than once or out of order
  res.status(200).end();
});
```

**Delivery semantics (design for these):**
- Respond with any **2xx within 10 seconds**. Do your processing after acknowledging. Non-2xx, timeouts and redirects (redirects are **not** followed) all count as failures.
- A failed delivery is retried **twice**, about 5 s and then 30 s after the previous attempt, then dropped.
- **At-least-once, unordered:** the same event can arrive more than once (e.g. duplicate carrier receipts) and a later status can arrive before an earlier one. De-duplicate on `messageId` + `status` and never let a non-final event overwrite a final one.
- **Best effort, not a ledger:** after 20 consecutive failures to reach your endpoint, forwarding for the account pauses for 60 s and events in that window are dropped; a platform-wide in-flight cap can also shed events during very large bursts. The API (`GET /v1/sms/run/{runId}/delivery-status`, `GET /v1/sms/messages`) is always the source of truth - reconcile any message still non-final after a few minutes against it.
- One URL per account, plus an optional one per sub-account. Use the test event to verify the endpoint before relying on it.

### WhatsApp status events (opt-in, same endpoint)

Turn on **Also send WhatsApp status events** on **WhatsApp → API & Webhooks** (`https://www.vibrate.co.il/whatsapp/developers`), where the URL, secret, test event and sub-account number assignments live together (the SMS webhook dialog edits the same settings). Until the switch is on, nothing WhatsApp-related is sent, so existing SMS integrations are unaffected. **Send WhatsApp test** posts a sample (`messageId` starts with `test_`). Headers, signing and the verification code are identical to SMS; dispatch on `X-Vibrate-Event` / `event`. Sub-account routing: events for a number assigned to a sub-account go to that sub-account's own webhook URL (signed with its secret) when it has one, otherwise to the account's webhook, and carry the sub-account's `subAccountId` either way; the account-level switch is the only opt-in - there is no per-sub-account switch - and a sub-account's dialog has its own **Send WhatsApp test**.

Pushed for every WhatsApp message sent from the account (`POST /v1/whatsapp/template/send`, `sendMany`, `sendBulk`, campaigns, API sync, inbox and RSVP sends), one event per status transition that Vibrate actually applied: `sent`, `delivered`, `read`, `failed`. Out-of-order Meta receipts that change nothing (a `delivered` after `read`) are not pushed. **Do not wait for a `sent` event:** it is pushed only when Meta's accepted-receipt reaches Vibrate before the send itself is recorded, which in practice happens for inbox / free-text messages. For API template sends the `200` / `202` response (and the batch row's `sent` status) IS the "sent" signal, and the first pushed event is usually `delivered`. Messages sent through a number an admin shared with the account (`isShared: true` in `GET /api/whatsapp/numbers`) report to the **number owner's** webhook, not to the account that sent them.

```json
{
  "apiVersion": "v1",
  "event": "whatsapp.status",
  "messageId": "wamid.HBgLOTcyNTAxMjM0NTY3FQIAERgSMUE2QjNDNEQ1RTZGN0E4QjkA",
  "whatsappNumberId": "c1f7c0e4-2b6e-4f3a-9d2a-5e8b1a2c3d4e",
  "templateId": "8a4f2d1e-6c3b-4a5d-9e8f-1b2c3d4e5f6a",
  "batchId": null,
  "campaignId": null,
  "subAccountId": null,
  "recipient": "972501234567",
  "status": "failed",
  "final": true,
  "error": { "message": "Message undeliverable", "code": "131026" },
  "sentAt": "2026-07-31T10:12:00.000Z",
  "occurredAt": "2026-07-31T10:12:07.000Z"
}
```

| Field | Notes |
|---|---|
| `messageId` | the Meta wamid, the same `messageId` returned by `POST /v1/whatsapp/template/send`; `test_...` for test events |
| `whatsappNumberId` | the sending number, the same id you pass to the send endpoints |
| `templateId` / `batchId` / `campaignId` | the template, send batch (the `batchId` from `/sendBulk`) and campaign behind the message; `null` when not applicable (free-text inbox messages have all three `null`) |
| `subAccountId` | the sub-account the sending number is assigned to (same field as on the SMS event); `null` for unassigned numbers. Present whether the event reached the sub-account's own webhook or the account's |
| `recipient` | digits only, international form |
| `status` | `sent`, `delivered`, `read`, `failed` |
| `final` | `true` for `read` and `failed`. `read` is terminal. `failed` is NOT always the last word: Meta revises some "undeliverable" messages to `delivered` / `read` later, and Vibrate pushes that revision. Let a later `delivered` / `read` overwrite `failed`; never let anything overwrite `read` |
| `error` | `null` unless `status` is `failed`; then `{ "message": string, "code": string or null }` where `code` is Meta's numeric error code as a string (e.g. `"131026"` undeliverable, `"131049"` marketing limit, `"131047"` re-engagement window) |
| `sentAt` | ISO-8601 time the send was recorded; may be `null` |
| `occurredAt` | ISO-8601 time of this transition as reported by Meta |

Headers: `X-Vibrate-Event: whatsapp.status`, `X-Vibrate-Message-Id` (= body `messageId`), `X-Vibrate-Timestamp`, `X-Vibrate-Signature` (same HMAC scheme as SMS). Delivery semantics, same as SMS unless stated: 2xx within 10 s, redirects not followed, two retries (~5 s, ~30 s) for 5xx / 3xx / 408 / 425 / 429 / timeouts / network errors - **any other 4xx (401, 403, 404, 400 ...) is final for that event and is not retried**, so a rotated secret or a wrong path drops events until fixed; at-least-once and unordered; best effort. The circuit breaker differs from SMS: WhatsApp events normally go out through a long-lived gateway with a breaker **per webhook URL** (a dead endpoint pauses only its own events, and events shed while it is open are dropped); when that gateway is unavailable or saturated, Vibrate delivers directly with no breaker at all (every event gets the full retry schedule). Reconcile: for `sendMany` / `sendBulk` rows the source of truth is `GET /v1/whatsapp/template/batch/{batchId}` (section 4.4); a single `send` has no status endpoint, so treat it as unknown when still non-final after a few minutes and check the web app's sent-messages report (`https://www.vibrate.co.il/whatsapp/templates`) when it matters.

## 6. Error code reference

| HTTP | code | meaning / fix |
|---|---|---|
| 400 | VALIDATION_ERROR | body failed schema; read `errors[]` |
| 400 | MISSING_REQUIRED_FIELDS | a required field or query param is missing/invalid |
| 400 | INVALID_DATA_FORMAT | e.g. malformed Idempotency-Key |
| 400 | SMS_NO_RECIPIENTS | `recipients` empty |
| 400 | SMS_INVALID_SENDER | `sender` missing, not an active sender on this account, or assigned to a different (sub-)account than the key |
| 400 | SMS_INSUFFICIENT_CREDITS | top up credits; nothing was sent or charged |
| 400 | SMS_DAILY_LIMIT_EXCEEDED | 24 h cap reached; `hints` tells when it resets |
| 400 | CAMPAIGN_NO_ACTIVE_CONTACTS | list is empty or all contacts inactive/unsubscribed |
| 400 | WHATSAPP_INVALID_PHONE / WHATSAPP_NUMBER_NOT_FOUND / WHATSAPP_TEMPLATE_NOT_FOUND / WHATSAPP_TEMPLATE_NOT_APPROVED / WHATSAPP_INVALID_VARIABLES | fix the WhatsApp send input (section 4.4) |
| 400 | WHATSAPP_SEND_FAILED / WHATSAPP_BULK_SEND_FAILED / WHATSAPP_TOO_MANY_RECIPIENTS | Meta rejected the message (reason in `hints`) / every sendMany row was rejected / more than 2,000 recipients |
| 403 | ACCESS_TOKEN_MISSING / ACCESS_TOKEN_INVALID / ACCESS_TOKEN_INACTIVE | fix the Authorization header / create a new key (403, never 401) |
| 403 | USER_INACTIVE / USER_DELETED | account problem; contact Vibrate support |
| 403 | EMAIL_NOT_VERIFIED | the account's signup email was never verified; enter the code mailed at signup in the Vibrate app |
| 403 | SUB_ACCOUNT_FORBIDDEN | a sub-account key called an endpoint it may not use (campaigns); use a main-account key |
| 403 | FORBIDDEN | a sub-account key used a WhatsApp number not assigned to its sub-account (assign it under General → Sub-accounts), or the account has no active WhatsApp subscription |
| 403 | SUB_ACCOUNT_INACTIVE | the key's sub-account was deleted; create a new key |
| 404 | CAMPAIGN_NOT_FOUND / RESOURCE_NOT_FOUND | wrong ID or belongs to another account |
| 409 | CONFLICT | same Idempotency-Key still in flight; retry shortly |
| 413 | PAYLOAD_TOO_LARGE | split the batch |
| 502 / 504 | WHATSAPP_GATEWAY_ERROR | transient failure reaching Meta (502) or no answer in time (504); retry with backoff, but for `sendMany` first check `GET /v1/whatsapp/template/batch/{batchId}` / your webhook events - a 504 may have started the batch and sendMany has no Idempotency-Key |
| 5xx | SERVER_ERROR / SMS_GATEWAY_ERROR / SMS_GATEWAY_TIMEOUT | transient; retry with backoff and (for bulk SMS) the same Idempotency-Key |

## 7. Recommended integration pattern

1. On startup / before big sends: `GET /v1/user/info` → check `smsAmount` ≥ recipients × units.
2. Normalise phones and de-duplicate recipients client-side.
3. Send with `/v1/sms/sendBulk` + `Idempotency-Key` (or `/send` for a single body). Store the returned `runId`.
4. Track delivery: configure the SMS delivery webhook (section 5) and persist each event by `messageId`; then reconcile anything still non-final after a few minutes with `GET /v1/sms/run/{runId}/delivery-status`. Without a webhook, poll that endpoint with backoff until `allDelivered` or a timeout you choose (e.g. 30 min).
5. Handle `400` and `403` codes as permanent (fix input / the key), `409` and `5xx` as retryable - except that a `502`/`504` from `sendMany` must be checked against the batch endpoint before any retry (no idempotency there).
6. For WhatsApp, verify the template is APPROVED and the variable counts match before sending; re-runs of `sendBulk` use `resumeBatchId`, re-runs of `sendMany` resend only the rows the batch endpoint reports as `failed`.

## 8. Things this API does NOT do

- No **inbound-message** webhooks (replies to your SMS or WhatsApp are not pushed to you). Outbound **SMS delivery status IS pushed** through the delivery webhook in section 5, and **WhatsApp status** (sent / delivered / read / failed) is pushed to the same endpoint once its opt-in switch is on; both are configured in the web app rather than through the API.
- No free-text WhatsApp sends, no sender/number/template creation, no credit purchase via API - all of that is done in the Vibrate web app (https://www.vibrate.co.il).
- No rate-limit header is returned; keep concurrency modest (a few parallel requests) and batch through `sendBulk` instead of looping `/send`.
- No "poll my system" endpoint: if the user wants Vibrate to read THEIR API and message the people it returns, that is the no-code **API sync automation** in section 9, not something to build with this API.

## 9. API sync automations (Vibrate calls YOUR API - no code)

The reverse integration. Configured in the web app at `https://www.vibrate.co.il/whatsapp/api-sync` (docs: `https://www.vibrate.co.il/docs/whatsapp#whatsapp-api-sync`); there is no REST endpoint for it. Recommend it instead of custom code whenever the user's goal is "every X, take the people my system returns and send each of them a WhatsApp template once" (appointment reminders, order updates, lead follow-ups). The user's job is only to expose a JSON endpoint; Vibrate does the scheduling, dedupe, approval and sending.

What the user configures (one automation = one template):
- **Source**: URL (GET or POST), query params, headers (API keys go here; values are encrypted and never shown again), optional body. Date placeholders are filled at request time in Israel time and work in the URL, params, headers and body: `{{now}}` (ISO UTC), `{{unix}}`, `{{today}}` (YYYY-MM-DD), `{{startOfDay}}` / `{{endOfDay}}` (Israel midnight / 23:59:59.999 as UTC ISO), `{{startOfDayLocal}}` / `{{endOfDayLocal}}` (wall clock, no zone). Every one takes a day offset: `{{today+1}}`, `{{startOfDay-7}}`. Unknown `{{...}}` tokens are left untouched.
- **Extraction**: dotted path to the items array (empty = the response is the array), dotted path to the phone inside an item (Israeli 05x and international forms accepted), optional name template, optional "same person" dedupe key template (default: the normalised phone; use `{{item.id}}-{{item.startTime}}` for one message per appointment), up to 10 filters (equals, not_equals, contains, not_contains, exists, not_exists, is_true, is_false, on_or_after, before; all must pass, case-insensitive), up to 12 named fields (`{key,label,path}`).
- **Message**: WhatsApp number + approved non-OTP template on the same business account, one text template per `{{N}}` in header / body / URL buttons, optional header media URL. Tokens inside those texts: `{{fieldKey}}` (resolved first), `{{item.any.path[0]}}`, `{{index}}` (1-based). Formatters after a pipe, dates rendered in Israel time: `|date` 09/09/2026, `|time` 10:00, `|datetime`, `|weekday` (Hebrew day name), `|dayMonth` 9/9, `|first` (first word), `|upper`, `|lower`. ISO strings and epoch seconds/millis parse; "12/09/2026" style does not.
- **Schedule**: interval 5 minutes to 90 days (cron ticks every 5 minutes, so a run can start up to 5 minutes late), optional send window HH:mm-HH:mm Israel time (overnight windows wrap), repeat policy `once` (a key is messaged once ever) or `cooldown` (again after N days, max 365).
- **Approval**: `manual` (default) parks every batch for a human to review and press Send; unapproved batches expire after 7 days and no new batch is prepared while one is open. `auto` sends as soon as the list is planned.
- **Test mode**: a phone that receives every message instead of the customers, 5 per run, without writing the ledger.

Planner decision order per item, first match wins (the preview shows the same decisions the run makes): `filtered` → `invalid_phone` → `suppressed` (account do-not-send list) → `duplicate_in_batch` → `already_sent` → send.

Guarantees and caps the user's endpoint should be designed around:
- Response: max 8MB, 20s timeout, max 5,000 items read per response, public hosts only (private / internal addresses are blocked). Return a stable id per item so the dedupe key can be built from it.
- Sends: max 300 per run; leftovers go out in a follow-up run 5 minutes later. Each recipient is written to the ledger BEFORE Meta is called, so a crash mid-run never double-sends.
- Sends use the same path as `POST /v1/whatsapp/template/send`, so they appear in sent messages and the inbox like API sends.
- Export / import of an automation is JSON (header values are blanked on export; imported automations start paused).

Minimal endpoint the user can expose (any shape works, this is just the simplest):
```json
GET /appointments?from={{today+1}}&to={{today+1}}
{ "data": [ { "id": "apt_1", "status": "confirmed", "startTime": "2026-09-09T07:00:00.000Z",
              "customer": { "firstName": "דנה", "mobile": "050-1234567" } } ] }
```
Settings: items path `data`, phone `customer.mobile`, name `{{item.customer.firstName}}`, dedupe key `{{item.id}}`, filter `status equals confirmed`, body variables `{{item.customer.firstName}}`, `{{item.startTime|date}}`, `{{item.startTime|time}}`.

## 10. WordPress & WooCommerce plugin (no code)

**Vibrate SMS**, by Lightup Software Engineering: a WordPress plugin for businesses in Israel that sends through this API (screenshots and FAQ at https://www.vibrate.co.il/he/woocommerce-sms-plugin). Two ways to install, same plugin:
- From the WordPress.org plugin directory (https://wordpress.org/plugins/vibrate-sms/): in WordPress **Plugins → Add New Plugin**, search "Vibrate SMS", **Install Now**, **Activate**. Updates come through WordPress.org. The interface is English until WordPress.org publishes the plugin's Hebrew and Arabic language packs.
- Download `https://www.vibrate.co.il/downloads/vibrate-sms.zip` (always the latest version), then **Plugins → Add New → Upload Plugin**. Includes the Hebrew and Arabic interface and updates itself from vibrate.co.il.

Requires WordPress 6.2+ and PHP 7.4+; WooCommerce 7.0+ for the order features (works with HPOS and the block checkout). Interface in English, Hebrew and Arabic, following the site's language.

Setup in **Vibrate SMS → Settings**: the access key (from **Developers → API Keys**, `https://www.vibrate.co.il/sms/tokens`; stored encrypted) and the sender, exactly as an approved Sender ID. Both can live in `wp-config.php` instead: `define( 'VIBRATE_SMS_ACCESS_TOKEN', '...' );` and `define( 'VIBRATE_SMS_SENDER', 'MyShop' );`. **Test connection** shows the balance; **Send test SMS** costs one credit.

What it does without code:
- WooCommerce: an SMS to the customer per order status the owner picks (processing and completed by default, custom statuses included), each status with its own text and at most once per order; alerts to the shop team's phones; an SMS for every "Note to customer"; send from the order screen; a private order note for every SMS. Placeholders: `{first_name}`, `{last_name}`, `{full_name}`, `{order_number}`, `{order_status}`, `{order_total}`, `{order_date}`, `{items}`, `{item_count}`, `{order_url}`, `{payment_url}`, `{payment_method}`, `{shipping_method}`, `{shipping_city}`, `{tracking_number}`, `{tracking_url}`, `{billing_phone}`, `{billing_email}`, `{site_name}`, `{site_url}`.
- A **Send SMS** page and an **SMS log** with delivery status (it polls `GET /v1/sms/run/{runId}/delivery-status` every 10 minutes for two days).
- Protection against SMS pumping: automatic SMS are capped at 10 per number and 200 per site per hour; sends typed by a person in wp-admin are not rate limited.

How it calls the API: every send is `POST /v1/sms/sendBulk` with `Idempotency-Key: wp-<uuid>` (one key per batch). A send that times out or gets `409`, `429` or `5xx` is retried in the background after 1, 5 and 15 minutes with the same key, so it is never delivered or billed twice. Order SMS always go out in the background (Action Scheduler, or WP-Cron without WooCommerce), so a checkout never waits for the API.

For custom WordPress code, call the plugin rather than the API directly (same key, sender, protection and log):
```php
$result = vibrate_sms_send( '050-1234567', 'Your table is ready.', array( 'source' => 'my_plugin' ) );
if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_code() . ': ' . $result->get_error_message() );
}
// $result: status ("queued" | "pending" with 'async' => true | "retrying"), batch_key, run_id, recipients, blocked, units.
// Without checking that the plugin is active:
do_action( 'vibrate_sms_send', '050-1234567', 'Your table is ready.' );
```
Filters: `vibrate_sms_pre_send` (change the text or drop recipients, return `WP_Error` to cancel), `vibrate_sms_send_order_sms`, `vibrate_sms_order_message`, `vibrate_sms_order_placeholders` (add your own `{placeholders}`), `vibrate_sms_order_phone`, `vibrate_sms_send_async`, `vibrate_sms_rate_limit_exempt_sources`, `vibrate_sms_send_capability`, `vibrate_sms_settings_capability`. Actions: `vibrate_sms_sent` (run id, log rows, replayed), `vibrate_sms_failed` (`WP_Error`, log rows).

## 11. Minimal client (TypeScript)

```ts
const BASE = "https://api.vibrate.co.il";
const headers = { Authorization: process.env.VIBRATE_TOKEN!, "Content-Type": "application/json" };

export async function sendSms(recipients: string[], message: string, sender: string) {
  const res = await fetch(`${BASE}/v1/sms/send`, { method: "POST", headers, body: JSON.stringify({ recipients, message, sender }) });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.code}: ${json.message} (${json.hints ?? ""})`);
  return json.data.runId as string;
}

export async function deliveryStatus(runId: string) {
  const res = await fetch(`${BASE}/v1/sms/run/${runId}/delivery-status`, { headers });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.code}: ${json.message}`);
  return json.data as { allDelivered: boolean; summary: { total: number; delivered: number; pending: number } };
}
```

---
Docs (public, no login): https://www.vibrate.co.il/docs/sms and https://www.vibrate.co.il/docs/whatsapp. Public copy of this skill: https://www.vibrate.co.il/vibrate-api-skill.md. Site index for AI: https://www.vibrate.co.il/llms.txt.
فتح الملف الخام
04

نقاط النهاية المشمولة

base urlhttps://api.vibrate.co.il
account
  • GET/v1/user/info
sms
  • POST/v1/sms/send
  • POST/v1/sms/sendBulk
  • GET/v1/sms/messages
  • GET/v1/sms/run/{runId}/delivery-status
campaigns
  • GET/v1/sms/campaigns
  • POST/v1/sms/campaigns
  • GET/v1/sms/campaigns/{campaignId}/contacts
  • POST/v1/sms/campaigns/{campaignId}/contacts
  • DELETE/v1/sms/campaigns/{campaignId}/contacts/{contactId}
  • POST/v1/sms/campaigns/{campaignId}/run
whatsapp
  • POST/v1/whatsapp/template/send
  • POST/v1/whatsapp/template/sendBulk
05

الأسئلة الشائعة

مستند Markdown واحد يصف واجهة REST API الكاملة في Vibrate: المصادقة، وكل نقطة نهاية لرسائل SMS وواتساب، وبنية الطلبات والاستجابات، وقواعد أرقام الهواتف، ووحدات الاحتساب، ورموز الأخطاء. تلصقونه في مساعد الذكاء الاصطناعي ليكتب تكاملًا صحيحًا دون تخمين.

مع أي مساعد يقبل النصوص: ChatGPT وClaude وClaude Code وCursor وGitHub Copilot وGemini وغيرها. ويمكن أيضًا تثبيته في Claude Code وCursor كـSkill أو قاعدة (rule) محلية ليتم تحميله تلقائيًا.

نعم. أنشئوا حسابًا مجانيًا، واشحنوا رصيد SMS أو اربطوا رقم واتساب للأعمال، ثم أنشئوا مفتاح وصول من الإعدادات ← مفاتيح الوصول. يُرسل المفتاح في ترويسة Authorization مع كل طلب.

إرسال رسائل SMS فردية أو جماعية، وتشغيل حملات مخصصة لقوائم التوزيع، وإدارة جهات الاتصال، ومتابعة حالة التسليم لكل رسالة، وإرسال قوالب واتساب للأعمال المعتمدة مع متغيرات ووسائط إلى مستلم واحد أو إلى قائمة كاملة.

نعم. يتم إنشاؤه من المصدر نفسه الذي يُنشأ منه توثيق API، ويُتاح عبر رابط ثابت، لذا يعيد كل تنزيل جديد أحدث إصدار.

إنشاء حساب مجاني

انسخوا موجّهًا واحدًا، وسيتعرّف ChatGPT أو Claude أو Claude Code أو Cursor على واجهة API الكاملة في Vibrate: إرسال رسائل SMS وقوالب واتساب، وإدارة القوائم، ومتابعة حالة التسليم. API لرسائل SMS وواتساب للأعمال في إسرائيل.

يستخدم الموقع ملفات تعريف الارتباط الضرورية لتشغيله، وملفات تعريف ارتباط تحليلية لفهم كيفية تفاعل مستخدمينا معه. يخضع استخدام ملفات تعريف الارتباط التحليلية لموافقتك، وفقًا لقانون حماية الخصوصية. مزيد من التفاصيل في سياسة الخصوصية