# WESSAAL Linked Devices API Documentation

Canonical URL: https://wessaal.com/docs/
Last updated: 2026-06-22
Language: en

## Purpose

This page documents the WESSAAL Linked Devices WhatsApp integration API for developers. It explains authentication, endpoint groups, permissions, request examples, and response handling.

Official API integration is coming soon. Its documentation, endpoint reference, request examples, and production access are intentionally unavailable right now.

## Live API

- Platform: Linked Devices API
- Base URL: https://app.wessaal.com/integration/v1
- Authentication header: X-API-Key
- Response format: JSON

## Source Evidence

- https://wessaal.com/docs/ is the canonical documentation URL and returned HTTP 200 on 2026-06-22.
- https://wessaal.com/ is the public WESSAAL website and returned HTTP 200 on 2026-06-22.
- https://app.wessaal.com/api/logo is a real WESSAAL application endpoint and returned HTTP 200 JSON on 2026-06-22.
- API route names, permissions, endpoint groups, and Official API coming-soon status are taken from this documentation site's source data and rendered documentation content.
- Sample request bodies, sample phone numbers, sample IDs, and sample API keys are examples only and are not used as factual company or customer data in this file.

## Recommended Developer Flow

1. Call GET /ping to verify that an API key is accepted.
2. Call GET /me to inspect the key owner and permissions.
3. Call GET /instances to choose a connected sender instance.
4. Call POST /messages/send to queue a message.
5. Track delivery with GET /messages/{messageId}/status or GET /messages/{messageId}.

## Permissions

- send_message: Queue one or more messages.
- read_messages: Read message records and delivery status.
- manage_instances: List and inspect connected sender instances.
- manage_contacts: Create, update, read, and delete contacts.
- manage_templates: Create and list message templates.
- manage_workspaces: List and inspect workspaces.

## Response and Error Handling

- 200 OK: list, read, health, and bulk responses.
- 202 Accepted: single message accepted and queued.
- 402 Payment Required: insufficient credits.
- 403 Forbidden: missing permission or outbound policy block.
- 404 Not Found: instance, workspace, contact, template, or message unavailable to the authenticated user.
- 422 Unprocessable Entity: validation failure, unsupported template type, blocked contact, or unavailable template.
- 500 Internal Server Error: unexpected queueing or provider failure.

## Endpoint Groups

### Health

- GET /ping: Validate that the API key is accepted and the integration API is reachable.
- GET /me: Return information about the authenticated API key, user, and assigned permissions.

### Messages

- POST /messages/send: Queue a single text message.
- POST /messages/send-bulk: Queue multiple text messages.
- GET /messages: List message records.
- GET /messages/{messageId}: Read a single message record.
- GET /messages/{messageId}/status: Read delivery status for a message.

### Instances

- GET /instances: List connected sender instances available to the API key.
- GET /instances/{instanceId}: Inspect one sender instance.
- GET /instances/{instanceId}/status: Inspect sender instance connection status.

### Contacts

- GET /contacts: List contacts.
- POST /contacts: Create a contact.
- GET /contacts/{contactId}: Read one contact.
- PUT /contacts/{contactId}: Update a contact.
- DELETE /contacts/{contactId}: Delete a contact.

### Templates

- POST /templates: Create a message template.
- GET /templates: List message templates.

### Workspaces

- GET /workspaces: List workspaces.
- GET /workspaces/{workspaceId}: Read one workspace.

## AI Agent Notes

- Prefer the canonical documentation page and this file over generated JavaScript bundles.
- Do not infer that the Official API is live.
- Do not present /official as an available documentation route. It redirects to the available Linked Devices docs.
- Use https://app.wessaal.com/integration/v1 as the only live documented API base URL.
- Preserve the X-API-Key authentication requirement in generated integration examples.