Growing businesses rarely live in one tool. Your order system, ERP, website forms or custom app need to create contacts, send WhatsApp updates or know when a customer writes in. Without an API, that means someone copying data between screens.
SaleMag's developer API connects your systems to the same inbox, CRM, campaigns and AI that your team uses.
What can I do with the SaleMag API?
All endpoints live under /api/v1 and return JSON.
| Area | Endpoints |
|---|---|
| Account | GET /me, list, create and delete tokens |
| Contacts | List, create, read, update and delete contacts |
| Segments | List and create segments, list a segment's contacts |
| Campaigns | List, create and read campaigns, launch, pause, list recipients |
| Messages | POST /messages/send for WhatsApp (template or text) and SMS |
| Conversations | List conversations, read a conversation's messages |
| Webhooks | List, create and delete webhook endpoints |
| AI | List chatbots, chat with a bot, list and create knowledge bases, add or remove documents |
| Automations | List automations, trigger one for a contact |
| Social | List social accounts, publish or schedule a post |
The full list, with parameters and example payloads, is in the OpenAPI 3.1 document at /api/v1/openapi.json and in the API reference page inside the app.
How does authentication work?
Create a personal access token on the API Tokens page and send it in the header:
Authorization: Bearer {token}
- Tokens are stored as hashes and shown only once.
- Each token can expire on a date you choose.
- Scopes limit what a token can do. There are 12:
contacts:read,contacts:write,campaigns:read,campaigns:write,messages:write,conversations:read,webhooks:write,ai:read,ai:write,automations:write,social:writeandanalytics:read, plus*for full access. - The member's workspace role still applies, so a token cannot do more than its owner.
How do I send a WhatsApp message from my system?
Call POST /api/v1/messages/send with the messages:write scope. Choose WhatsApp with a template or text, or SMS. The usual WhatsApp Cloud API rules apply: outside the 24-hour window you need an approved template. Customer replies come into the shared inbox as usual. Email sending through the API is not available yet.
How do webhooks work?
Add an HTTPS endpoint on the Webhooks page and pick events:
| Event | When it fires |
|---|---|
contact.created |
A new contact is created |
message.received |
A customer sends a message |
campaign.completed |
A campaign finishes |
test.ping |
You press Send test |
Every delivery is a JSON POST with an X-Webhook-Event header and an X-Webhook-Signature header in the form t={timestamp},v1={HMAC-SHA256} of {timestamp}.{body}, signed with your whsec_ secret. Deliveries time out after 10 seconds and are retried up to five times (after 1 minute, 5 minutes, 1 hour, 1 day and 1 day). You can rotate the secret, view a delivery log per attempt, and enable or disable an endpoint. Private network addresses are blocked.
Order, cart and other events go through the automation flow builder instead, which can call your URL with its HTTP request step.
What are the limits?
- 60 requests per minute per user across
/api/v1. - An extra 60 per minute on
/messages/send. - A 429 response includes
Retry-After,X-RateLimit-LimitandX-RateLimit-Remaining.
What can I build with it?
| 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 template |
| AI answers in your own app | POST /ai/chatbots/{id}/chat |
| Keep docs fresh for the bot | POST /ai/knowledge-bases/{id}/documents |
| Start a flow from your system | POST /automations/{id}/trigger |
| Log every incoming chat | message.received webhook |
Who is it for?
Developers and agencies who connect SaleMag to an online store, ERP, CRM or custom app. Need help planning an integration? Contact us, or see integrations and pricing.
Step by step
- 1
Create a token
Open API Tokens, name the token, choose its scopes and expiry, and copy it once.
- 2
Make a first call
Call GET /api/v1/me with the bearer token to check it works.
- 3
Add a webhook
Add your endpoint in Webhooks, pick events, and use Send test to check signature verification.
Frequently asked questions
How do I authenticate with the SaleMag API?
Create a personal access token in API Tokens and send it as Authorization: Bearer {token}. Tokens are stored hashed, shown once, can expire, and are limited to the scopes you choose. Your workspace role still applies.
Is there an OpenAPI or Swagger spec?
Yes. The OpenAPI 3.1 document is public at /api/v1/openapi.json, and the API reference inside the app has curl examples for each endpoint.
Can I send WhatsApp messages through the API?
Yes. POST /api/v1/messages/send sends a WhatsApp template or text message, or an SMS, with the messages:write scope. Normal WhatsApp rules apply, so a template is needed outside the 24-hour window.
Which webhook events are available?
contact.created, message.received and campaign.completed, plus a test.ping you can send from the dashboard. Each delivery is signed in the X-Webhook-Signature header.
What are the rate limits?
60 requests per minute per user across the API, with an extra 60 per minute limit on sending messages. A 429 response includes Retry-After and X-RateLimit headers.
Is there an SDK?
There is no official SDK. The API is plain JSON over HTTPS, and you can generate a client from the OpenAPI document.
About the author
WhatsApp & F-commerce automation, Dhaka
The Dhaka team that builds SaleMag, the AI sales inbox for WhatsApp, Messenger and Instagram used by online sellers in Bangladesh.