---
title: "WhatsApp API for Developers: SaleMag REST API | SaleMag"
description: SaleMag's REST API lets your code create contacts, send WhatsApp
  and SMS, launch campaigns and ask AI agents. Bearer tokens, 12 scopes, an
  OpenAPI 3.1 spec.
url: https://salemag.net/solutions/api
language: en
published: 2026-10-21
updated: 2026-10-24
author: SaleMag Team
tags:
  - whatsapp api
  - rest api
  - developer api
  - send whatsapp message api
  - openapi
---

# WhatsApp API for Developers: SaleMag REST API | SaleMag

> SaleMag's REST API is a JSON-over-HTTPS interface at /api/v1 that lets your own software create contacts, send WhatsApp and SMS messages, launch campaigns, read conversations, ask AI agents and trigger automations. Requests use bearer tokens with 12 scopes, are limited to 60 per minute per user, and every endpoint is described in a public OpenAPI 3.1 document.

- One REST API at /api/v1 for contacts, campaigns, messages, conversations, AI agents, automations, social posts and analytics.
- Personal access tokens carry scopes such as contacts:write or messages:write, can expire, and are shown only once.
- POST /api/v1/messages/send sends a WhatsApp template or text, or an SMS, to a contact.
- 60 requests per minute per user, plus 60 per minute on message sends; a 429 includes Retry-After.
- The OpenAPI 3.1 document at /api/v1/openapi.json is public, so Postman or a code generator can read it.

You built the order system, the ERP sync or the shop app. Now the business wants a WhatsApp message when an order ships. Going straight to Meta's Cloud API means template management, phone number IDs, token handling and an inbox for the replies. That is weeks of work before the first message.

SaleMag's REST API gives you that layer ready-made. Your code calls one endpoint, and the reply lands in the same inbox the support team already uses.

A REST API is a set of HTTPS endpoints that lets another program read and change data with JSON requests. SaleMag's REST API connects your systems to the contacts, campaigns, WhatsApp numbers and AI agents in your SaleMag workspace.

## What can I do with the SaleMag REST API?

The SaleMag REST API lets your code manage contacts, campaigns, messages, conversations, AI agents, automations, social posts and analytics. Every endpoint lives under `/api/v1` and returns JSON:

| Resource | Endpoints | Scope |
|---|---|---|
| Account | `GET /me`, workspaces, plan usage, subscription, notifications, audit log, tokens | none |
| Contacts | List, create, read, update and delete contacts | `contacts:read`, `contacts:write` |
| Segments | List and create segments, list a segment's contacts | `contacts:read`, `contacts:write` |
| Campaigns | List, create, read and update campaigns, launch, pause, list recipients | `campaigns:read`, `campaigns:write` |
| Messages | `POST /messages/send` for WhatsApp (template or text) and SMS | `messages:write` |
| Conversations | List conversations, read a conversation's messages | `conversations:read` |
| AI agents | List AI agents, chat with one, manage knowledge bases and documents | `ai:read`, `ai:write` |
| Automations | List automations, trigger one for a contact | `automations:write` |
| Social | List social accounts, publish or schedule a post | `social:write` |
| Analytics | Message and conversation stats, AI usage, campaign funnel | `analytics:read` |
| Webhooks | List, create and delete webhook endpoints | `webhooks:write` |

Contact lists use cursor pagination, 25 per request: follow `meta.next_cursor` for the next batch.

## How does SaleMag API authentication work?

The SaleMag API uses personal access tokens sent as a bearer header, each limited to the scopes you choose. Create one on the API Tokens page:

```
Authorization: Bearer {token}
```

- Copy the whole token, including the number and `|` before it. It is shown only once and stored as a hash.
- Set an expiry date, or leave it open.
- Pick scopes from the 12 available: `contacts:read`, `contacts:write`, `campaigns:read`, `campaigns:write`, `messages:write`, `conversations:read`, `webhooks:write`, `ai:read`, `ai:write`, `automations:write`, `social:write` and `analytics:read`. Choosing none gives the token full access (`*`).
- The owner's workspace role still applies, so a token can never do more than the person who made it.

A call without the needed scope returns 403 with a `required_scope` field that names it.

## How do I send a WhatsApp message with the API?

Send a WhatsApp message by calling `POST /api/v1/messages/send` with a contact id and the `messages:write` scope. The contact must exist in SaleMag with an E.164 phone number, so create it first:

```bash
curl -X POST \
  -H "Authorization: Bearer $SALEMAG_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"phone_e164":"+8801700000001","first_name":"Rahim","opt_in_whatsapp":true}' \
  https://your-salemag-domain/api/v1/contacts
```

The new contact comes back under `data`, with its `id`. Then send an approved template:

```bash
curl -X POST \
  -H "Authorization: Bearer $SALEMAG_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":42,"channel":"whatsapp","template_name":"order_confirmation","template_vars":{"1":"ORD-99"}}' \
  https://your-salemag-domain/api/v1/messages/send
```

A success returns `{"provider_message_id": "wamid...", "status": "sent"}`.

What to know before you build on it:

| Rule | Detail |
|---|---|
| Sender | The first active [WhatsApp Business API](https://salemag.net/platforms/whatsapp-business-api) number in your workspace |
| Template or text | Give `template_name` for a template, or `body` for plain text |
| [24-hour window](https://salemag.net/glossary/24-hour-window) | Outside it, only an approved [message template](https://salemag.net/glossary/message-template) is delivered |
| Template variables | `template_vars` fill the template body, keyed by position |
| Template language | Sent as the `en` version of the template |
| SMS | Set `channel` to `sms`; it goes through your default SMS gateway |
| Email | Not available on this endpoint yet; returns 422 |

Customer replies arrive in the [unified inbox](https://salemag.net/solutions/unified-inbox). To message many contacts at once, create and launch a campaign through the API instead; see [Broadcasting](https://salemag.net/solutions/broadcasting).

## What are the SaleMag API rate limits?

The SaleMag API allows 60 requests per minute per user across `/api/v1`, with a second limit on sending messages:

| Limit | Value |
|---|---|
| All `/api/v1` requests | 60 per minute per user |
| `POST /messages/send` | another 60 per minute per user |
| Over the limit | HTTP 429 with `Retry-After`, `X-RateLimit-Limit` and `X-RateLimit-Remaining` |

For large sends, use a campaign. SaleMag paces campaign messages itself.

## Is there an OpenAPI spec or SDK for the SaleMag API?

Yes, there is an OpenAPI spec; there is no SDK. The OpenAPI 3.1 document at `/api/v1/openapi.json` is public, so Postman, Insomnia or a code generator can read it without a token. Inside the app, the API reference page lists every endpoint with parameters, example payloads and curl commands filled with your own base URL.

Errors are JSON: business errors use an `error` key, and validation errors return 422 with a `message` and an `errors` object.

## Does the SaleMag API send webhooks?

Yes. SaleMag can POST a signed JSON event to your server when a contact is created, a message arrives or a campaign finishes. You register endpoints in the app or through the `/webhooks` endpoints of this API. Events, signature checks and retries are covered on the [webhooks page](https://salemag.net/solutions/webhooks).

## What can I build with the SaleMag API?

The SaleMag API can sync customers, send order updates and put AI answers into your own app:

| Use case | How |
|---|---|
| Sync customers from your ERP | `POST /contacts` and `PATCH /contacts/{id}` with custom fields |
| Send order updates | `POST /messages/send` with a WhatsApp [utility](https://salemag.net/glossary/utility-message) template |
| AI answers in your own app | `POST /ai/agents/{id}/chat` |
| Keep the AI agent's knowledge fresh | `POST /ai/knowledge-bases/{id}/documents` |
| Start a flow from your system | `POST /automations/{id}/trigger` |
| Pull numbers into a BI tool | `GET /analytics/messages` and `GET /analytics/conversations` |

## Who is the SaleMag API for?

The SaleMag API is for developers and [agencies](https://salemag.net/industries/agencies) who connect SaleMag to an online store, ERP, CRM or custom app. If you want the automation without code, the [automation flow builder](https://salemag.net/solutions/automation-flow-builder) can call your URL with its HTTP request step.

Ready to make your first call? [Create an account](https://salemag.net/register) and open API Tokens, or [compare plans](https://salemag.net/pricing).

## Steps

1. **Create a token**: Open API Tokens in SaleMag, name the token, choose its scopes and expiry, and copy it. It is shown once.
2. **Check the token**: Call GET /api/v1/me with the token as a bearer header. It returns the user the token belongs to.
3. **Create a contact**: POST /api/v1/contacts with a phone number in E.164 format and WhatsApp opt-in.
4. **Send a message**: POST /api/v1/messages/send with the contact id, the channel and a template name or text body.

## FAQ

### How do I authenticate with the SaleMag API?

Create a personal access token on the SaleMag API Tokens page and send it as Authorization: Bearer {token}. Tokens are stored hashed, shown once, can expire, and are limited to the scopes you pick.

### Can I send WhatsApp messages through the SaleMag API?

Yes. POST /api/v1/messages/send with the messages:write scope sends a WhatsApp template or text message to a contact. Outside the 24-hour window you need an approved template.

### Does SaleMag have an OpenAPI or Swagger spec?

Yes. The SaleMag OpenAPI 3.1 document is public at /api/v1/openapi.json, and the API reference inside the app shows each endpoint with curl examples.

### What are the SaleMag API rate limits?

The SaleMag API allows 60 requests per minute per user, with a second limit of 60 per minute on sending messages. A 429 response carries Retry-After and X-RateLimit headers.

### Can I send email through the SaleMag API?

No. The messages endpoint accepts the email channel but returns 422 for now. Email goes out through campaigns, which you can create and launch through the API.

### Is there a SaleMag SDK?

No. SaleMag has no official SDK. The API is plain JSON over HTTPS, and you can generate a client from the OpenAPI document.

### Does the SaleMag API have webhooks?

Yes. SaleMag sends signed webhooks when a contact is created, a message arrives or a campaign finishes. See [SaleMag webhooks](https://salemag.net/solutions/webhooks) for events and signatures.

### Can I send OTP codes through the SaleMag API?

No. SaleMag has no OTP endpoint that generates and checks one-time codes. You can create WhatsApp authentication templates, but your system must make and verify the code.