Wapiworld API 1.0.0

GET/api/instances

List WhatsApp instances

Lists the WhatsApp instances of your organization. An API key is scoped to a single project and only sees that project's instances. Requires the instances:read scope.

Parameters

Responses

POST/api/instances

Create a WhatsApp instance

Creates a new WhatsApp instance in your project. A caller-supplied _id, whether in the body or instanceId query, requires a stable Idempotency-Key; retrying the same create (including the same write-only webhook signing secret) returns the same resource, while reusing either identity for a different intent returns 409. The first accepted command pins its runtime backend, so an exact retry resumes the same command even if a deployment gate changed meanwhile. Keyed creates reserve the resource in stopped state and must be started with the reconnect action after the caller durably stores the returned id. Unkeyed legacy creates retain their historical auto-start behavior. Requires the instances:write scope and emits instance.created.

Parameters

Responses

GET/api/instances/{instanceId}

Get a WhatsApp instance

Returns a single instance by id. Requires the instances:read scope. Answers 404 when the instance belongs to another organization or project.

Parameters

Responses

PUT/api/instances/{instanceId}

Update a WhatsApp instance

Updates an existing instance. A body containing webhookSigningSecret is always an atomic durable configuration command and requires a stable Idempotency-Key. Its exact public patch and write-only secret may be replayed until the returned configurationOperation reaches completed; changing that intent for the same key returns 409. Requires the instances:write scope. May emit instance.connected / instance.disconnected on a status transition.

Parameters

Responses

DELETE/api/instances/{instanceId}

Delete a WhatsApp instance

Durably requests logout, provider-state purge, and deletion. Repeat the same DELETE to poll the intrinsic delete:{instanceId} operation; 202 is pending and 200 includes the immutable completion event. Requires the instances:write scope and emits instance.deleted exactly once. Answers 404 for an instance in another organization or project.

Parameters

Responses

POST/api/instances/{instanceId}/action/send-message-idempotent

Send a WhatsApp message with a durable idempotency key

Requires one stable Idempotency-Key and the instances:write scope. Reuse the key only for the exact same instance, normalized chat, and content. An exact retry reuses one deterministic WhatsApp message id; changed intent returns 409. The unversioned send-message action is legacy and rejects every Idempotency-Key.

Parameters

Responses

POST/api/instances/{instanceId}/action/{action}

Perform a legacy or non-send action on a WhatsApp instance

Drives actions such as logout, reconnect, and the legacy unkeyed send-message. Every Idempotency-Key is rejected on this route. Use the exact send-message-idempotent path for durable keyed sends.

Parameters

Responses

GET/api/messages

List recorded WhatsApp messages

Reads the recorded messages of one instance, optionally filtered by chat. Message recording is opt-in per instance and TTL-expired. Requires the messages:read scope.

Parameters

Responses

GET/api/projects

List projects

Lists your organization's projects. An API key is scoped to a single project and returns only that one. Requires the projects:read scope.

Parameters

Responses

GET/api/projects/{projectId}

Get a project

Returns a single project by id. Requires the projects:read scope. Answers 404 for a project in another organization, or for a project-scoped key asking for a different project.

Parameters

Responses

GET/api/webhooksubscriptions

List webhook subscriptions

Webhook subscriptions deliver instance.created, instance.connected, instance.disconnected and instance.deleted events to your server as signed POST requests (X-Wapiworld-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token. Responses contain only the reviewed public subscription fields; the secret is returned once, on create.

Responses

POST/api/webhooksubscriptions

Create a webhook subscription

The response includes the signing secret exactly once — store it; it cannot be retrieved again.

Request body application/json

Responses

PUT/api/webhooksubscriptions/{webhookSubscriptionId}

Update a webhook subscription

url, events, deliveryVersion and active are editable; the secret and project are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.

Parameters

Responses

DELETE/api/webhooksubscriptions/{webhookSubscriptionId}

Delete a webhook subscription

Parameters

Responses