> Source: https://wexa.ai/docs/connectors/get-whatsapp-connection

# get-whatsapp-connection

Read the connection state of a WhatsApp connector that [`connect-whatsapp`](/docs/connectors/connect-whatsapp) created, without changing it. Needs the `fabric:orchestrate.read` grant.

**Get a WhatsApp connection**

**Wexa MCP server**

```bash
curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get-whatsapp-connection","arguments":{"connector_id":"6b0f2c9e4a1d8e7f3c2b1a90"}}}'
```

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000005\",\"result\":{\"connector_id\":\"6b0f2c9e4a1d8e7f3c2b1a90\",\"name\":\"Support WhatsApp\",\"status\":\"pending\",\"connected\":false}}"
    }
  ],
  "isError": false
}
```

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/get-whatsapp-connection \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"connector_id":"6b0f2c9e4a1d8e7f3c2b1a90"}'
```

```json
{
  "lifecycle_id": "qlc_000005",
  "result": {
    "connector_id": "6b0f2c9e4a1d8e7f3c2b1a90",
    "name": "Support WhatsApp",
    "status": "pending",
    "connected": false
  }
}
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.getWhatsAppConnection({
  connector_id: '6b0f2c9e4a1d8e7f3c2b1a90'
})
```

```ts
// result is the payload itself, with no `.result` to read
{
  connector_id: '6b0f2c9e4a1d8e7f3c2b1a90',
  name: 'Support WhatsApp',
  status: 'pending',
  connected: false
}
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.get_whatsapp_connection(
    connector_id="6b0f2c9e4a1d8e7f3c2b1a90",
)
```

```python
# out is the result, already unwrapped
{
    "connector_id": "6b0f2c9e4a1d8e7f3c2b1a90",
    "name": "Support WhatsApp",
    "status": "pending",
    "connected": False
}
```

## Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `connector_id` | string | Required | The `connector_id` that `connect-whatsapp` returned. A string. One that is not a WhatsApp connector this project may use is refused (403). |

**Show full response**

An example response, for a connector whose QR code has not been scanned yet.

**Result of get-whatsapp-connection**

**REST API**

```json
{
  "lifecycle_id": "qlc_000005",
  "result": {
    "connector_id": "6b0f2c9e4a1d8e7f3c2b1a90",
    "name": "Support WhatsApp",
    "status": "pending",
    "connected": false,
    "next_step": "The account is not linked yet. Call complete-whatsapp-connection with connector_id 6b0f2c9e4a1d8e7f3c2b1a90 to check again and get a new QR link."
  }
}
```

**Wexa MCP server**

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000005\",\"result\":{\"connector_id\":\"6b0f2c9e4a1d8e7f3c2b1a90\",\"name\":\"Support WhatsApp\",\"status\":\"pending\",\"connected\":false,\"next_step\":\"The account is not linked yet. Call complete-whatsapp-connection with connector_id 6b0f2c9e4a1d8e7f3c2b1a90 to check again and get a new QR link.\"}}"
    }
  ],
  "isError": false
}
```

**TypeScript SDK**

```ts
// the object you get back IS the result — there is no `.result` to read
{
  "connector_id": "6b0f2c9e4a1d8e7f3c2b1a90",
  "name": "Support WhatsApp",
  "status": "pending",
  "connected": false,
  "next_step": "The account is not linked yet. Call complete-whatsapp-connection with connector_id 6b0f2c9e4a1d8e7f3c2b1a90 to check again and get a new QR link."
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000005'
```

**Python SDK**

```python
# a dict subclass; `result` is already unwrapped
{
 "connector_id": "6b0f2c9e4a1d8e7f3c2b1a90",
 "name": "Support WhatsApp",
 "status": "pending",
 "connected": False,
 "next_step": "The account is not linked yet. Call complete-whatsapp-connection with connector_id 6b0f2c9e4a1d8e7f3c2b1a90 to check again and get a new QR link."
}

out.lifecycle_id  # 'qlc_000005' — an attribute, not a key
```

Keeping the `lifecycle_id` is what lets you ask later why a call was allowed, refused or held.

**More details**

**Response fields**

- `connector_id`: The connector you asked about.
- `name`: The connector's name.
- `status`: `pending` while the account is not linked, `ready` once it is.
- `connected`: `true` when the WhatsApp account is linked, whatever `status` says.
- `next_step`: What to do next, in words.

This call reads the connector only, so it never returns `connect_url`, `link_type` or `link_expires_at`. To get a
link for a pending connector, call `complete-whatsapp-connection`. The connector's configuration, and the PIN in
it, is never returned.

`connected` says whether the WhatsApp account is linked. `status` is the connector's own status: `pending` until the account is linked, then `ready`, or `failed` when a later data sync of the linked connector failed. A `failed` connector is still connected, and its actions still run; `next_step` says so, and [`sync-connector`](/docs/connectors/sync-connector) runs the sync again.

A pending connector stays pending until [`complete-whatsapp-connection`](/docs/connectors/complete-whatsapp-connection) is called after the scan. WhatsApp's provider may also report the scan to the platform on its own, which turns the connector `ready` without that call, but do not count on it: call `complete-whatsapp-connection` once the code is scanned.

A connector that is not linked yet is not an error. It comes back with `status: "pending"`. This call never issues a link, so it is safe to poll, and both SDKs poll it when they wait for a scan. It never returns `connect_url`, `link_type` or `link_expires_at`: to get a link for a pending connector, call `complete-whatsapp-connection`. The connector's configuration, and the PIN in it, is never returned.

The connector id in the example is illustrative. Swap it for the one `connect-whatsapp` returned to you.

Reading the state needs only `fabric:orchestrate.read`, so a key that watches a connection does not need the power to start one. Not marked consequential.

Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).