# Wapisimo API

> Wapisimo is a multi-tenant WhatsApp API. Create phone connections, pair them by scanning a QR code, then send and receive WhatsApp messages over HTTP. Inbound activity is pushed to your webhooks and retained in a queryable event history.

This file follows the llms.txt convention. For the complete documentation in a
single fetch, use [llms-full.txt](https://app.wapisimo.dev/llms-full.txt).

## Documentation

- [Full API documentation (markdown)](https://app.wapisimo.dev/llms-full.txt): every endpoint, event, parameter and limit in one file.
- [OpenAPI 3.1 specification](https://app.wapisimo.dev/openapi.json): machine-readable spec for client generation.
- [Human-readable API reference](https://app.wapisimo.dev/docs/): the same content as a browsable page.

## Endpoints

- [Create Phone](https://app.wapisimo.dev/docs/#create-phone): `POST /v1/phones` — Create a new phone in your account. It starts disconnected and must be paired by fetching a QR code and scanning it from WhatsApp on the handset.
- [List Phones](https://app.wapisimo.dev/docs/#list-phones): `GET /v1/phones` — List every phone in the account that has not been deleted.
- [Delete Phone](https://app.wapisimo.dev/docs/#delete-phone): `DELETE /v1/phones/{phone_id}` — Close the WhatsApp session and soft-delete the phone. It stops appearing in List Phones, stops counting toward active usage, and frees a subscription slot.
- [Send Text Message](https://app.wapisimo.dev/docs/#send-message): `POST /v1/{phone_id}/send` — Queue a text message. The response means accepted for delivery, not delivered — watch the event history or your webhook for the outcome.
- [Send Media Message](https://app.wapisimo.dev/docs/#send-media): `POST /v1/{phone_id}/send` — Queue an image, video, audio file, or document. The file is fetched from your URL and forwarded to WhatsApp.
- [Send Location Message](https://app.wapisimo.dev/docs/#send-location): `POST /v1/{phone_id}/send` — Queue a location pin.
- [Send Template Message](https://app.wapisimo.dev/docs/#send-template): `POST /v1/{phone_id}/send` — Queue an approved WhatsApp message template. Official Cloud API phones only. Templates deliver both inside and outside the 24-hour customer-service window — they are the only way to reach a contact who has not messaged you in the last 24 hours.
- [List Templates](https://app.wapisimo.dev/docs/#list-templates): `GET /v1/cloud/templates/{phone_id}` — List the message templates on a cloud phone's WhatsApp Business Account, with their approval status. Official Cloud API phones only.
- [Check Cloud Connection](https://app.wapisimo.dev/docs/#check-cloud-connection): `POST /v1/cloud/check/{phone_id}` — Ask Meta whether the stored token and phone number id still work, and reconcile the phone's status with the answer. Official Cloud API phones only.
- [Verify Number](https://app.wapisimo.dev/docs/#verify-number): `GET /v1/verify` — Check whether a number is registered on WhatsApp.
- [Get QR Code](https://app.wapisimo.dev/docs/#get-qr): `GET /v1/{phone_id}/qr` — Fetch the pairing QR code for a phone. Scan it from WhatsApp on the handset (Settings → Linked devices) to move the phone to `connected`.
- [List WhatsApp Groups](https://app.wapisimo.dev/docs/#list-groups): `GET /v1/{phone_id}/groups` — List the WhatsApp group chats this phone belongs to, with metadata and participants.
- [List Webhooks](https://app.wapisimo.dev/docs/#list-webhooks): `GET /v1/{phone_id}/webhook` — List the webhooks registered for a phone.
- [Add Webhook](https://app.wapisimo.dev/docs/#add-webhook): `POST /v1/{phone_id}/webhook` — Register a URL to receive this phone's events.
- [Delete Webhook](https://app.wapisimo.dev/docs/#delete-webhook): `DELETE /v1/{phone_id}/webhook/{webhook_id}` — Remove a registered webhook.
- [Resync Phone](https://app.wapisimo.dev/docs/#resync-phone): `POST /v1/{phone_id}/resync` — Tear down the WhatsApp session, clear stored pairing credentials, and start a fresh one so a new QR code can be issued.
- [List Events for a Phone](https://app.wapisimo.dev/docs/#list-events): `GET /v1/{phone_id}/events` — Read one phone's event history, newest first by default.
- [List Events for a Phone Group](https://app.wapisimo.dev/docs/#list-group-events): `GET /v1/{group_id}/events` — Read the merged event history of every phone in a group, interleaved into one timeline. Use `phone_id` on each row to tell members apart.
- [List Events Across the Account](https://app.wapisimo.dev/docs/#list-account-events): `GET /v1/events` — Read the merged event history of every phone in the account. The widest read available, and the right one for building an inbox or syncing to your own store.

## Concepts

- [Authentication](https://app.wapisimo.dev/docs/#authentication)
- [Event Samples](https://app.wapisimo.dev/docs/#event-samples)
- [Phone Groups](https://app.wapisimo.dev/docs/#phone-groups)
- [Selection Strategies](https://app.wapisimo.dev/docs/#group-strategies)
- [Contact Affinity](https://app.wapisimo.dev/docs/#contact-affinity)
- [Send via Group](https://app.wapisimo.dev/docs/#send-via-group)
- [Media Types](https://app.wapisimo.dev/docs/#media-types)
- [Webhook Events](https://app.wapisimo.dev/docs/#webhook-events)
- [Natural Mode](https://app.wapisimo.dev/docs/#natural-mode)
- [Rate Limits](https://app.wapisimo.dev/docs/#rate-limits)
- [Status Codes](https://app.wapisimo.dev/docs/#error-codes)

## Notes

- Authentication is `Authorization: Bearer <key>`. `X-API-Key` is internal to the platform and will not authenticate you.
- A `202` from a send endpoint means queued, not delivered. Confirm delivery through the event history or a webhook.
- Webhook payloads use camelCase (`subType`, `fromMe`); event history rows use snake_case (`subtype`, `from_me`).