Linked Devices live Official coming soon

Production documentation for Wessaal integration developers.

Linked Devices documentation is live for developers. Official API integration is marked coming soon and is not reachable until its public contract is ready.

Base URL

https://app.wessaal.com/integration/v1

Authentication

X-API-Key

Platform Status

Live

Developer portal

Integration Documentation

Wessaal currently exposes the Linked Devices integration track. Official API integration content is marked as coming soon while the public contract is being finalized.

Live platform

Linked Devices

Base path

/integration/v1

Authentication

X-API-Key

Linked Devices endpoints are served under /integration/v1 and require a valid X-API-Key header.
API keys are permission-scoped, so each endpoint group requires the matching permission.
Successful send requests queue WhatsApp messages and return the local Wessaal message_id for tracking.
Official API integration content and endpoints are coming soon and are not reachable yet.

API keys

Authentication

Send the API key with every Linked Devices request. The backend middleware reads the authenticated key and enforces the permission required by the route group.

curl "https://app.wessaal.com/integration/v1/ping" \
  -H "X-API-Key: sk_live_your_key"

Create separate keys per integration or environment.
Grant only the permissions required by that integration.
Rotate exposed keys immediately and update the external service using them.

Recommended flow

Quickstart

Start with a health check, inspect the authenticated key, list available instances, then queue a message using an instance ID or instance_name.

1
Verify the key
Call GET /ping. A valid key returns success=true and message=pong.
2
Inspect scope
Call GET /me to confirm the key owner and permissions.
3
Choose sender
Call GET /instances with manage_instances permission and pick an instance.
4
Queue message
Call POST /messages/send with send_message permission.
5
Track delivery
Use GET /messages/{messageId}/status or GET /messages/{messageId}.

OpenAPI download

API Collection

Download the Integration API v1 OpenAPI collection and import it into Postman, Insomnia, Bruno, or any OpenAPI-compatible client.

OpenAPI JSON

Integration API v1.openapi.json

OpenAPI 3.0.1 collection with authentication, variables, examples, and endpoint schemas.

Download collection

Set base_url to your Wessaal app domain, then append /integration/v1 as shown in the collection.
Set api_key to the X-API-Key value generated for the integration.
Use the collection variables for instance, message_id, contact_id, template_id, and workspace_id while testing flows.

Production handling

Responses and Errors

Responses are JSON. Send endpoints return queued messages, validation failures return field-level errors, and policy or credit failures include an error_code when available.

202 Accepted: single message accepted and queued.
200 OK: list, read, health, and bulk responses.
402 Payment Required: insufficient credits.
403 Forbidden: missing permission or outbound policy block.
404 Not Found: instance, workspace, contact, template, or message is 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.

Coming soon

Official API

Official integration is coming soon. The documentation, endpoint reference, request examples, and production access for this platform are intentionally unavailable right now.

Official endpoint content is hidden from the active endpoint reference until launch.
The /official documentation route redirects to the available Linked Devices docs.
API keys, scopes, examples, and production URLs will be published when the Official API is released.

Endpoint reference

Linked Devices endpoints

These are the live Linked Devices routes. Permission names match the API key middleware scopes.

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.

GETHealthAny valid API key

Ping API

200 OK

Validate that the API key is accepted and the integration API is reachable.

Endpoint

https://app.wessaal.com/integration/v1/ping

curl -X GET "https://app.wessaal.com/integration/v1/ping" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "message": "pong",
  "timestamp": "2026-06-02T09:30:00.000000Z"
}

GETHealthAny valid API key

API Key Info

200 OK

Return information about the authenticated API key, user, and assigned permissions.

Endpoint

https://app.wessaal.com/integration/v1/me

curl -X GET "https://app.wessaal.com/integration/v1/me" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

POSTMessagessend_message

Send Message

202 Accepted

Queue a single text message. You can send direct content or use an approved text template owned by the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/messages/send

Parameter	Type	Required	Description
instance	string	Yes	Instance ID or instance_name.
recipient	string	unless contact_id	E.164 phone number.
contact_id	integer	No	Existing contact ID.
content	string	unless template_id	Direct text content.
template_id	integer	unless content	Approved text template ID.
template_variables	object	No	Template placeholder overrides.
delay	integer	No	Optional delay in milliseconds.
quoted	object	No	Quoted message payload.
link_preview	boolean	No	Enable link preview.
mentions_everyone	boolean	No	Mention everyone in a group.
mentioned	array	No	List of JIDs to mention.

curl -X POST "https://app.wessaal.com/integration/v1/messages/send" \
  -H "X-API-Key: sk_live_your_key"
  -H "Content-Type: application/json" \
  -d '{
  "instance": "main-whatsapp",
  "recipient": "+966501234567",
  "content": "Your appointment is confirmed.",
  "link_preview": false
}'

Example response

{
  "success": true,
  "message": "Message queued for sending",
  "data": {
    "message_id": 1245,
    "status": "pending",
    "type": "text",
    "recipient": "+966501234567",
    "queued_at": "2026-06-02T09:30:00.000000Z",
    "instance": {
      "id": 12,
      "name": "main-whatsapp"
    },
    "template_used": false,
    "content_type": "direct",
    "message_type": "text",
    "credits_charged": 1
  }
}

POSTMessagessend_message

Send Bulk Messages

200 OK

Queue up to 100 text messages in one request. Each item may use recipient or contact_id.

Endpoint

https://app.wessaal.com/integration/v1/messages/send-bulk

Parameter	Type	Required	Description
instance	string	Yes	Instance ID or instance_name.
content	string	unless template_id	Shared direct text content.
template_id	integer	unless content	Shared approved text template.
template_variables	object	No	Shared template variables.
messages	array	Yes	1 to 100 recipient objects.
messages.*.recipient	string	unless contact_id	Recipient phone number.
messages.*.contact_id	integer	No	Existing contact ID.
messages.*.template_variables	object	No	Per-recipient overrides.

curl -X POST "https://app.wessaal.com/integration/v1/messages/send-bulk" \
  -H "X-API-Key: sk_live_your_key"
  -H "Content-Type: application/json" \
  -d '{
  "instance": "main-whatsapp",
  "content": "Your monthly statement is ready.",
  "messages": [
    {
      "recipient": "+966501234567"
    },
    {
      "contact_id": 902,
      "template_variables": {
        "first_name": "Ahmad"
      }
    }
  ]
}'

Example response

{
  "success": true,
  "message": "Bulk: 2 queued, 0 failed",
  "data": {
    "total": 2,
    "success_count": 2,
    "failure_count": 0,
    "content_type": "direct",
    "message_type": "text",
    "results": [
      {
        "index": 0,
        "recipient": "+966501234567",
        "success": true,
        "message_id": 1246,
        "status": "pending"
      },
      {
        "index": 1,
        "recipient": "+966555987654",
        "success": true,
        "message_id": 1247,
        "status": "pending"
      }
    ]
  }
}

GETMessagessend_message

Message Delivery Status

200 OK

Read the delivery status for a message ID returned by a send endpoint.

Endpoint

https://app.wessaal.com/integration/v1/messages/{messageId}/status

Parameter	Type	Required	Description
messageId	integer	Yes	Wessaal message ID.

curl -X GET "https://app.wessaal.com/integration/v1/messages/{messageId}/status" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETMessagesread_messages

List Messages

200 OK

List message records available to the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/messages

curl -X GET "https://app.wessaal.com/integration/v1/messages" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETMessagesread_messages

Get Message

200 OK

Read a single message record by ID.

Endpoint

https://app.wessaal.com/integration/v1/messages/{messageId}

Parameter	Type	Required	Description
messageId	integer	Yes	Wessaal message ID.

curl -X GET "https://app.wessaal.com/integration/v1/messages/{messageId}" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETInstancesmanage_instances

List Instances

200 OK

List connected WhatsApp sender instances available to the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/instances

curl -X GET "https://app.wessaal.com/integration/v1/instances" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETInstancesmanage_instances

Get Instance

200 OK

Inspect a single connected sender instance.

Endpoint

https://app.wessaal.com/integration/v1/instances/{instanceId}

Parameter	Type	Required	Description
instanceId	integer\|string	Yes	Instance ID.

curl -X GET "https://app.wessaal.com/integration/v1/instances/{instanceId}" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETInstancesmanage_instances

Get Instance Status

200 OK

Read connection status for a connected sender instance.

Endpoint

https://app.wessaal.com/integration/v1/instances/{instanceId}/status

Parameter	Type	Required	Description
instanceId	integer\|string	Yes	Instance ID.

curl -X GET "https://app.wessaal.com/integration/v1/instances/{instanceId}/status" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETContactsmanage_contacts

List Contacts

200 OK

List saved contacts for the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/contacts

curl -X GET "https://app.wessaal.com/integration/v1/contacts" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

POSTContactsmanage_contacts

Create Contact

201 Created

Create a contact that can later be used with contact_id in send requests.

Endpoint

https://app.wessaal.com/integration/v1/contacts

curl -X POST "https://app.wessaal.com/integration/v1/contacts" \
  -H "X-API-Key: sk_live_your_key"
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+966501234567",
  "label": "Operations Manager",
  "name": "Ahmad Saleh"
}'

Example response

{
  "success": true,
  "data": {}
}

GETContactsmanage_contacts

Get Contact

200 OK

Read one saved contact.

Endpoint

https://app.wessaal.com/integration/v1/contacts/{contactId}

Parameter	Type	Required	Description
contactId	integer	Yes	Contact ID.

curl -X GET "https://app.wessaal.com/integration/v1/contacts/{contactId}" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

PUTContactsmanage_contacts

Update Contact

200 OK

Update a saved contact.

Endpoint

https://app.wessaal.com/integration/v1/contacts/{contactId}

Parameter	Type	Required	Description
contactId	integer	Yes	Contact ID.

curl -X PUT "https://app.wessaal.com/integration/v1/contacts/{contactId}" \
  -H "X-API-Key: sk_live_your_key"
  -H "Content-Type: application/json" \
  -d '{
  "label": "Billing Manager",
  "name": "Ahmad Saleh"
}'

Example response

{
  "success": true,
  "data": {}
}

DELETEContactsmanage_contacts

Delete Contact

200 OK

Delete a saved contact.

Endpoint

https://app.wessaal.com/integration/v1/contacts/{contactId}

Parameter	Type	Required	Description
contactId	integer	Yes	Contact ID.

curl -X DELETE "https://app.wessaal.com/integration/v1/contacts/{contactId}" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

POSTTemplatesmanage_templates

Create Template

201 Created

Create a message template for later sending.

Endpoint

https://app.wessaal.com/integration/v1/templates

curl -X POST "https://app.wessaal.com/integration/v1/templates" \
  -H "X-API-Key: sk_live_your_key"
  -H "Content-Type: application/json" \
  -d '{
  "name": "appointment_confirmed",
  "message_type": "text",
  "content": "Hello {{first_name}}, your appointment is confirmed."
}'

Example response

{
  "success": true,
  "data": {}
}

GETTemplatesmanage_templates

List Templates

200 OK

List templates available to the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/templates

curl -X GET "https://app.wessaal.com/integration/v1/templates" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETWorkspacesmanage_workspaces

List Workspaces

200 OK

List workspaces owned by or available to the authenticated user.

Endpoint

https://app.wessaal.com/integration/v1/workspaces

curl -X GET "https://app.wessaal.com/integration/v1/workspaces" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

GETWorkspacesmanage_workspaces

Get Workspace

200 OK

Read a single workspace.

Endpoint

https://app.wessaal.com/integration/v1/workspaces/{workspaceId}

Parameter	Type	Required	Description
workspaceId	integer	Yes	Workspace ID.

curl -X GET "https://app.wessaal.com/integration/v1/workspaces/{workspaceId}" \
  -H "X-API-Key: sk_live_your_key"

Example response

{
  "success": true,
  "data": {}
}

Production documentation for Wessaal integration developers.

Integration Documentation

Authentication

Quickstart

Verify the key

Inspect scope

Choose sender

Queue message

Track delivery

API Collection

Integration API v1.openapi.json

Responses and Errors

Official API

Linked Devices endpoints

Ping API

API Key Info

Send Message

Send Bulk Messages

Message Delivery Status

List Messages

Get Message

List Instances

Get Instance

Get Instance Status

List Contacts

Create Contact

Get Contact

Update Contact

Delete Contact

Create Template

List Templates

List Workspaces

Get Workspace