Connections

What the API can and cannot do with your connection: status, QR code for re-pairing, and the number's profile.

A connection is one WhatsApp number linked to your Wappfy account. Every API key belongs to one connection, and every call acts on that connection only.

What the API does and doesn't do

In the dashboard	Through the API
Create a connection and scan the first QR code	Read the connection's status (`GET /instance`)
Generate and revoke API keys	Get the QR code to re-pair a connection that dropped (`GET /instance/qr`)
Register the webhook	Read and change the number's profile (`/profile`)
Delete or disconnect a connection

The API cannot create, delete or log out a connection. A key only exists for a connection that already exists, so the first pairing always happens in the dashboard: in Connections, create the connection, then scan its QR code with WhatsApp on your phone (Linked devices).

These routes are under the Connection and Profile tags in the API Reference tab.

Connection status

curl https://app.wappfy.io/api/v1/instance \
  -H "X-Api-Key: wpf_YOUR_KEY"

{
  "data": {
    "id": 12,
    "name": "Support",
    "status": "connected",
    "connected": true,
    "phone": "5581988888888",
    "push_name": "Downtown Store",
    "profile_picture_url": null,
    "status_updated_at": "2026-10-14T12:00:00.000Z"
  }
}

Field	Meaning
`id`	The connection id in Wappfy. It also appears as `instance.id` in every webhook.
`name`	The name you gave the connection in the dashboard.
`status`	One of the values below.
`connected`	`true` only when `status` is `connected`. That is when sends work.
`phone`	The connected number, digits only, or `null` before it connects.
`push_name`	The WhatsApp profile name.
`profile_picture_url`	The profile picture, when known.
`status_updated_at`	When the status last changed (ISO 8601, UTC).

`status`	Meaning
`connected`	Connected. Messages can be sent.
`disconnected`	The number dropped.
`starting`	The session is starting.
`scan_qr`	Waiting for the QR code to be scanned.
`failed`	The session failed.
`suspended`	Suspended for billing reasons.
`created`	Created but never connected.

GET /instance returns what Wappfy has stored and does not ask WhatsApp, so it is cheap. It can come from the 10-second cache (Age header).

To know when the connection drops or comes back, listen to the instance.status webhook instead of polling. It uses the same words: connected, disconnected, scan_qr and failed. See Webhooks.

When the number is not connected, sends answer 409 conexao_desconectada. A suspended connection answers 409 instancia_suspensa.

Re-pairing with the QR code

If a connection dropped, you can scan the QR code again from the dashboard, or fetch it through the API and show it in your own system:

curl https://app.wappfy.io/api/v1/instance/qr \
  -H "X-Api-Key: wpf_YOUR_KEY"

{
  "data": {
    "mimetype": "image/png",
    "base64": "iVBORw0KGgo...",
    "data_url": "data:image/png;base64,iVBORw0KGgo..."
  }
}

data_url is ready for an <img src>.
WhatsApp changes the QR code every twenty-odd seconds while pairing. If the scan fails, ask for a new one.
A connected number answers 409 ja_conectada. A session that is not waiting for a scan right now answers 409 qr_indisponivel: try again in a moment.
The QR code is never cached, but it counts toward the polling limit. See Rate limits.

The number's profile

# read the profile
curl https://app.wappfy.io/api/v1/profile \
  -H "X-Api-Key: wpf_YOUR_KEY"

# change the name (up to 25 characters)
curl -X PUT https://app.wappfy.io/api/v1/profile/name \
  -H "X-Api-Key: wpf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Downtown Store" }'

# change the picture (JPEG, by url or base64)
curl -X PUT https://app.wappfy.io/api/v1/profile/picture \
  -H "X-Api-Key: wpf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/logo.jpg" }'

# remove the picture
curl -X DELETE https://app.wappfy.io/api/v1/profile/picture \
  -H "X-Api-Key: wpf_YOUR_KEY"

Route	Body	Response `data`
`GET /profile`		`phone`, `name`, `picture_url`
`PUT /profile/name`	`name` (1 to 25 characters)	`name`
`PUT /profile/picture`	`url` or `base64`	`picture_updated: true`
`DELETE /profile/picture`		`picture_removed: true`

These routes change the profile of the whole number, everywhere it appears, not just in your integration. Every change is recorded in Wappfy's audit log with the connection and the key used.

The picture must be JPEG (ideally square, up to 640×640). Another format answers 422 formato_de_foto_invalido and nothing changes.
The profile "about" text is not part of the API: the WhatsApp server Wappfy uses doesn't report it and refuses changes to it.

What the API does and doesn't doCopy Anchor Link

Connection statusCopy Anchor Link

Re-pairing with the QR codeCopy Anchor Link

The number's profileCopy Anchor Link

On this page

What the API does and doesn't do

Connection status

Re-pairing with the QR code

The number's profile