Introduction

The SanadWA API lets your own server work with your SanadWA account: send WhatsApp messages, keep your contacts and tags up to date, send campaigns, and check your credit balance. It is a REST API: you send HTTPS requests with JSON bodies and get JSON responses.

Who this is for

This documentation is for backend developers at SanadWA customers. You write code that runs on your own server, for example an order system that sends a WhatsApp message when an order ships.

You need:

• A SanadWA account with at least one connected WhatsApp number.
• An API key. An admin of your account creates it in the console (the SanadWA web app). See Authentication.
• At least one message template that Meta has approved. A template is a message text that you register with WhatsApp in advance. WhatsApp only lets a business start a conversation with a template.

What you can do today

Task	Endpoint	Scope
Send an approved template message	POST /messages/template	send
Reply with free-form text while the customer-service window is open	POST /messages/text	send
Look up a sent message and its delivery status	GET /messages/{id}	read
List your approved templates	GET /templates	read
List the WhatsApp numbers you can send from	GET /phone-numbers	read
List, create and delete tags	GET /tags, POST /tags, DELETE /tags/{id}	read / full
List contacts, filtered by tag	GET /contacts	read
Create or update up to 100 contacts at once	POST /contacts	full
Import contacts from a CSV file	POST /contacts/import	full
Delete a contact	DELETE /contacts/{id}	full
Send a campaign to everyone with a tag, now or scheduled	POST /campaigns	send
Follow campaigns, pause and resume them	GET /campaigns, GET /campaigns/{id}, POST /campaigns/{id}/pause, POST /campaigns/{id}/resume	read / send
Check your credit balance and this month’s usage	GET /balance	read
Check that your API key works	GET /health	read

The scope is what your API key must allow; see Scopes. The OpenAPI description of the API is at GET /openapi.json and needs no key.

You can also receive webhooks: SanadWA sends an HTTPS request to your server when a customer writes to you, or when a message is delivered, read or fails. See Webhooks.

The API reference lists every endpoint, field and response.

Base URL

All endpoints in this documentation are relative to this base URL:

https://api.sanadwa.com/v1

For example, the full URL of GET /health is https://api.sanadwa.com/v1/health.

Older integrations

Integrations built before this site used the path https://api.sanadwa.com/api/public/v1. That path keeps working, but new code should use https://api.sanadwa.com/v1.

Phone numbers in this documentation

The API expects phone numbers in E.164 format: a plus sign, the country code, then the number, with no spaces or dashes. For example, Saudi mobile numbers begin with +9665.

The examples in this documentation use made-up numbers from the range +12025550100 to +12025550199. Replace them with real numbers in your code.

Where to start

1. Quick start: create an API key and send your first message in a few minutes.
2. Authentication: key scopes, IP allowlists, rotating keys.
3. The guides, step by step: Send a template message, Import contacts and tag them, Send a campaign to a tag and Check your balance.

Get help

If something does not work as this documentation describes, open a support ticket in the console (Support tickets). Include:

• the X-Request-Id header of the response (see Requests and responses),
• the endpoint and the time of the request (with time zone),
• the code and message from the error response,
• the meta_error.fbtrace_id value, if the response has one.

Never send your API key or a webhook signing secret to support, or to anyone else.