API REFERENCE

Integrate WhatsApp into your product.

Create a session, pair your number using a QR code and integrate messages over HTTP. You need active access and a key with the scopes required by each operation. The plan includes one connection.

Base URL

https://cloud.wppconnect.io/api

Authentication

Send your key in the Authorization header with every request. Keep the secret on your application server.

Authorization: Bearer YOUR_KEY
Content-Type: application/json

Manage keys

First connection

Run the example in your environment. Save the returned sessionId and use it to retrieve the QR code and status. Creation uses provider=go and runtime=wppconnect-server-go.

curl -X POST "https://cloud.wppconnect.io/api/v1/sessions" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "go",
  "runtime": "wppconnect-server-go",
  "waitQrCode": false
}'

Example request. Replace YOUR_KEY with your API key.

View the complete walkthrough

Endpoints

Append the paths below to the base URL. Replace {sessionId} with your session identifier.

POST/v1/sessions

Create session

Creates a Cloud session and routes it through the manager to a dedicated container.

{
  "runtime": "wppconnect-server-go",
  "provider": "go",
  "webhookUrl": "https://example.com/webhook"
}

POST/v1/sessions/{sessionId}/start

Resume session

Restarts a closed session to generate a fresh QR code without consuming another connection.

GET/v1/sessions/{sessionId}

Session status

Retrieves the session state, provider, runtime, worker and metadata.

GET/v1/sessions/{sessionId}/qrcode

QR Code

Returns a PNG image when the session is waiting for pairing.

POST/v1/sessions/{sessionId}/send-text

Send text

Sends a text message to a WhatsApp number.

{ "phone": "5511999999999", "message": "Hello from WPPConnect Cloud" }

POST/v1/sessions/{sessionId}/send-media

Send media

Sends an image, video, audio or document using a URL/base64, depending on provider support.

{
  "phone": "5511999999999",
  "url": "https://example.com/file.png",
  "caption": "File sent from Cloud"
}

POST/v1/sessions/{sessionId}/send-location

Send location

Sends latitude, longitude and a description when supported by the provider.

POST/v1/sessions/{sessionId}/check-number

Check number

Checks whether a number can receive WhatsApp messages.

POST/v1/sessions/{sessionId}/logout

Log out session

Disconnects WhatsApp. To free your connection and create another session, delete the session using DELETE.

DELETE/v1/sessions/{sessionId}

Delete session

Removes the session and frees the connection for new pairing.

Webhooks

Provide webhookUrl when creating the session. Your endpoint must accept integration events. Each event's availability depends on the feature used.

session.qrcodesession.connectedsession.disconnectedmessage.receivedmessage.sentmessage.ackgroup.createderror.provider_not_supported

{
  "event": "message.received",
  "sessionId": "session_123",
  "provider": "go",
  "runtime": "wppconnect-server-go",
  "data": {}
}

Errors

Check the HTTP status and error field before continuing. Unavailable operations return an error response rather than simulating success.

{
  "success": false,
  "error": {
    "code": "PROVIDER_CAPABILITY_NOT_SUPPORTED",
    "message": "Feature unavailable for this operation.",
    "status": 501
  }
}