# WaSMS API

WaSMS (https://wasms.net) lets a business send and receive WhatsApp, SMS and email
messages from one place. This API lets your own software send messages through
the WhatsApp number the business has connected to WaSMS.

## Address and sign-in

Base address: https://wasms.net/api/public/v1
Every request carries the API key in a header:

    Authorization: Bearer YOUR_WASMS_API_KEY

A key starts with "wasms_". It is created, and can be copied again, in the
WaSMS dashboard under Developers, API keys (https://wasms.net/dashboard/api-keys). Keep
it on the server; never put it in a web page or a mobile app. Sending needs a key with the "messages:send" permission.

## Send a WhatsApp message

POST https://wasms.net/api/public/v1/whatsapp/send
Content-Type: application/json

Body fields:
  to           required  recipient phone with country code, digits only (a leading + is accepted), e.g. "923001234567"
  message      required unless media_url is given  the text; with media_url it is the caption
  media_url    optional  public https address of a file to send (image, video, audio or document)
  media_type   optional  "image", "video", "audio" or "document"; worked out from the address when left out
  filename     optional  name shown for a document
  whatsapp_id  optional  which connected number to send from (its id from GET https://wasms.net/api/public/v1/whatsapp/accounts); the organization's connected number is used when left out

Example:

curl -X POST https://wasms.net/api/public/v1/whatsapp/send \
  -H "Authorization: Bearer YOUR_WASMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "923001234567", "message": "Hello from my software"}'

Success (HTTP 200):

    { "success": true,
      "data": { "sent": true, "id": "<id of this message, for asking about it later>",
                "to": "923001234567", "type": "text",
                "whatsapp_id": "<id of the sending number>",
                "account_phone": "<the sending number>",
                "message_id": "<WhatsApp's own id for the message>" } }

Keep "id". It is how you find out later whether the message was delivered and
read (see "Delivered and read" below). It is absent only when WhatsApp gave no
id for the message.

## Errors

Every failure has the same shape, with an HTTP status that is not 200:

    { "success": false, "error": "<CODE>", "code": "<CODE>", "message": "<what went wrong, in words>" }

  400 INVALID_BODY          "to" is missing, or neither "message" nor "media_url" was given
  400 INVALID_ACCOUNT_ID    "whatsapp_id" is not a valid id
  401 UNAUTHORIZED          the key is missing, mistyped or revoked
  403 INSUFFICIENT_SCOPE    the key does not have the "messages:send" permission
  403 PLAN_LIMIT            the plan's sending limit is used up
  409 WHATSAPP_DISCONNECTED the number was signed out of WhatsApp and must be connected again
  429 RATE_LIMITED          the key made more requests this minute than it is allowed; wait the number of seconds in the "Retry-After" header
  502 GATEWAY_CLOSED        the WaSMS app that sends for this number is not running
  502 GATEWAY_ERROR         the WaSMS app reported a problem; "message" says what
  503 NO_CONNECTED_ACCOUNT  no WhatsApp number is connected to the organization

Show "message" to a person; branch on "code". A 429, 502 or 503 can be tried
again later; a 400, 401, 403 or 409 will fail the same way until the request,
the key, the plan or the connection changes.

## How many requests

Each key may make a set number of requests a minute (60 unless changed; it can
be set from 1 to 1000 on the API keys page). Every reply carries
"X-RateLimit-Limit" and "X-RateLimit-Remaining". One request too many gets
429 RATE_LIMITED with "Retry-After: <seconds>".

## Other routes

All under https://wasms.net/api/public/v1, same header, same error shape. Fields for each are in
the full reference.

  POST /sms/send            send an SMS                      (messages:send)
  POST /email/send          send an email                    (messages:send)
  POST /whatsapp/bulk       send up to 1000 WhatsApp messages in one call  (messages:send)
  GET  /whatsapp/accounts   the connected WhatsApp numbers   (accounts:read)
  GET  /messages            messages sent and received, on every channel; pass since=<time> for only the new ones  (messages:read)
  GET  /conversations       web chat conversations only, not WhatsApp  (conversations:read)

To learn about a new WhatsApp message from a customer, do not ask again and
again: use a webhook (next section). If you must ask, use GET /messages with
"since".

## Delivered and read

A WhatsApp message goes sent, then delivered, then read.

  GET /messages/{id}   the status of one message  (messages:read)

    { "success": true,
      "data": { "id": "<id>", "channel": "whatsapp", "status": "delivered",
                "to": "923001234567", "provider_message_id": "<WhatsApp's id>",
                "conversation_id": null, "sent_at": "<time>",
                "delivered_at": "<time>", "read_at": null } }

"status" is pending, sent, delivered, read or failed. Do not ask this for every
message again and again: subscribe to the "message.status" webhook instead and
WaSMS tells you once per change.

What the two words mean, so they are not over-read:
- delivered: WhatsApp reported the message reached the recipient's phone.
- read: the recipient opened the chat AND has read receipts switched on. A
  recipient with read receipts off never produces "read", and a sending number
  with read receipts off gets no "read" for anyone. A message that stays at
  "delivered" is NOT proof that it was not read.
- A played voice message counts as read. Messages to groups are not tracked
  and stay at "sent". A status is accepted for 30 days after sending.

## Being told when something happens (webhooks)

Instead of asking again and again, your server can be called by WaSMS when a
customer sends a message, a lead form is filled in or a campaign finishes. The
address and the events are set in the dashboard under Developers, Webhooks
(https://wasms.net/dashboard/webhooks). WaSMS sends a POST with a JSON body:

    { "id": "<event id>", "type": "message.received", "created_at": "<time>",
      "organization_id": "<id>", "data": { ... } }

Events: message.received, message.sent, message.status (delivered and read
for WhatsApp, with "delivered_at" and "read_at" in data.message), form.submitted,
campaign.completed. Each request is signed in the header
"X-WaSMS-Signature: t=<unix seconds>,v1=<hex>", where v1 is HMAC-SHA256 of
"<t>.<raw body>" with the endpoint's signing secret. Answer with a 2xx status
within 10 seconds. The same event can arrive more than once; use "id" to
ignore a repeat. Guide: https://wasms.net/docs/api/webhook-setup

## Full reference

For people: https://wasms.net/docs/developers/reference
For tools (OpenAPI 3, every route and field): https://wasms.net/api/public/v1/openapi.json