--- title: WhatsApp REST API and Webhooks for Developers | SaleMag description: Use SaleMag's REST API to manage contacts, send WhatsApp and SMS, launch campaigns, chat with AI bots and trigger automations. Signed webhooks and OpenAPI spec. url: https://salemag.net/features/developer-api language: en published: 2026-10-21 updated: 2026-10-21 author: SaleMag Team tags: - developer api - whatsapp api - rest api - webhooks - openapi --- # WhatsApp REST API and Webhooks for Developers | SaleMag > SaleMag has a REST API at /api/v1 with bearer tokens and 12 permission scopes. Create and update contacts, read segments and conversations, send WhatsApp and SMS messages, launch campaigns, chat with your AI chatbots, add knowledge-base documents, trigger automations and schedule social posts. Signed webhooks push new contacts, incoming messages and finished campaigns to your server. - Bearer-token API at /api/v1, with an OpenAPI 3.1 document at /api/v1/openapi.json. - Tokens carry scopes such as contacts:write or messages:write, can expire, and are shown only once. - Send WhatsApp (template or text) and SMS from your own system through one endpoint. - Webhooks are signed with HMAC-SHA256 and retried up to five times. - 60 requests per minute per user, with standard rate-limit headers on every 429. 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:write` and `analytics: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](https://salemag.net/glossary/whatsapp-cloud-api) rules apply: outside the [24-hour window](https://salemag.net/glossary/24-hour-window) you need an approved template. Customer replies come into the [shared inbox](https://salemag.net/features/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](https://salemag.net/features/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-Limit` and `X-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](https://salemag.net/contact), or see [integrations](https://salemag.net/integrations) and [pricing](https://salemag.net/pricing). ## Steps 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. ## FAQ ### 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.