> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/whatsapp-accounts/openapi.json](/docs/api/whatsapp-accounts/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# WhatsApp accounts

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Canonical WhatsApp accounts. Served only when `Ken-Version: 1.1` and the workspace's `whatsapp` flag is on (404 otherwise). Delivery view to read and edit to change, except the connect session, which any member may call: a client seat reconnects only the account it connected. No seat limit; each account costs 1,500 credits a month, charged when it binds.

Inbox. 5 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/whatsapp-accounts/openapi.json](/docs/api/whatsapp-accounts/openapi.json).

- `GET /v1/whatsapp-accounts` - List WhatsApp accounts in the current workspace (`whatsapp-accounts.list`): [/docs/api/whatsapp-accounts/list.md](/docs/api/whatsapp-accounts/list.md)
- `GET /v1/whatsapp-accounts/{whatsappAccountId}` - Return one WhatsApp account in the current workspace (`whatsapp-accounts.get`): [/docs/api/whatsapp-accounts/get.md](/docs/api/whatsapp-accounts/get.md)
- `PATCH /v1/whatsapp-accounts/{whatsappAccountId}` - Update a WhatsApp account (`whatsapp-accounts.update`): [/docs/api/whatsapp-accounts/update.md](/docs/api/whatsapp-accounts/update.md)
- `DELETE /v1/whatsapp-accounts/{whatsappAccountId}` - Delete a WhatsApp account (`whatsapp-accounts.delete`): [/docs/api/whatsapp-accounts/delete.md](/docs/api/whatsapp-accounts/delete.md)
- `POST /v1/whatsapp-accounts/connect-sessions` - Start a hosted WhatsApp connect or reconnect session (`whatsapp-accounts.create-connect-session`): [/docs/api/whatsapp-accounts/create-connect-session.md](/docs/api/whatsapp-accounts/create-connect-session.md)

## List WhatsApp accounts in the current workspace

`GET /v1/whatsapp-accounts` - operationId `whatsapp-accounts.list`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

Needs the `whatsapp` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/whatsapp-accounts/GET/v1/whatsapp-accounts)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Omit it for the first page. |
| `limit` | query | integer (int32) | no | Items per page, from 1 to 200. Default 50. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `WhatsAppAccount`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) |  |
| `phoneE164` | string |  |
| `displayName` | string |  |
| `profileImageUrl` | string |  |
| `status` | string |  |
| `statusChangedAt` | string (date-time) |  |
| `connectedAt` | string (date-time) |  |
| `connectedByMemberId` | integer (int64) |  |
| `quietUntil` | string (date-time) |  |
| `rampupStartedAt` | string (date-time) |  |
| `rampStage` | integer (int32) |  |
| `lowHistory` | boolean |  |
| `paused` | boolean |  |
| `pausedAt` | string (date-time) |  |
| `pauseReason` | string |  |
| `pausedUntil` | string (date-time) |  |
| `timezone` | string |  |
| `workingHoursSchedule` | LinkedInWeeklySchedule | A LinkedIn account's working hours, one entry per day from `mon` to `sun`, in the account's time zone. Kenso runs the account's LinkedIn actions only inside these hours. A day with no entry uses the default: 08:00 to 18:00 on weekdays, closed on weekends. An update must include all seven days. |
| `dailyNewChatCap` | integer (int32) |  |
| `dailyMessageCap` | integer (int32) |  |
| `newChatCap` | integer (int32) |  |
| `coldNewChatCap` | integer (int32) |  |
| `messageCap` | integer (int32) |  |
| `checkCap` | integer (int32) |  |
| `newChatCapCeiling` | integer (int32) |  |
| `messageCapCeiling` | integer (int32) |  |
| `newChatsToday` | integer (int32) |  |
| `messagesToday` | integer (int32) |  |
| `checksToday` | integer (int32) |  |
| `unpaid` | boolean |  |
| `lastSyncedAt` | string (date-time) |  |
| `createdAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |

### Request

```bash
curl -X GET "https://api.ken.so/v1/whatsapp-accounts?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "phoneE164": "string",
      "displayName": "string",
      "profileImageUrl": "https://example.com",
      "status": "string",
      "statusChangedAt": "2026-09-23T15:02:11Z",
      "connectedAt": "2026-09-23T15:02:11Z",
      "connectedByMemberId": 812,
      "quietUntil": "2026-09-23T15:02:11Z",
      "rampupStartedAt": "2026-09-23T15:02:11Z",
      "rampStage": 1,
      "lowHistory": true,
      "paused": true,
      "pausedAt": "2026-09-23T15:02:11Z",
      "pauseReason": "string",
      "pausedUntil": "2026-09-23T15:02:11Z",
      "timezone": "string",
      "workingHoursSchedule": {
        "mon": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "tue": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "wed": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "thu": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "fri": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "sat": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        },
        "sun": {
          "open": true,
          "start": "09:00",
          "end": "17:30"
        }
      },
      "dailyNewChatCap": 1,
      "dailyMessageCap": 1,
      "newChatCap": 1,
      "coldNewChatCap": 1,
      "messageCap": 1,
      "checkCap": 1,
      "newChatCapCeiling": 1,
      "messageCapCeiling": 1,
      "newChatsToday": 1,
      "messagesToday": 1,
      "checksToday": 1,
      "unpaid": true,
      "lastSyncedAt": "2026-09-23T15:02:11Z",
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Return one WhatsApp account in the current workspace

`GET /v1/whatsapp-accounts/{whatsappAccountId}` - operationId `whatsapp-accounts.get`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

Needs the `whatsapp` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/whatsapp-accounts/GET/v1/whatsapp-accounts/%7BwhatsappAccountId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `whatsappAccountId` | path | integer (int64) | yes |  |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `WhatsAppAccount`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) |  |
| `phoneE164` | string |  |
| `displayName` | string |  |
| `profileImageUrl` | string |  |
| `status` | string |  |
| `statusChangedAt` | string (date-time) |  |
| `connectedAt` | string (date-time) |  |
| `connectedByMemberId` | integer (int64) |  |
| `quietUntil` | string (date-time) |  |
| `rampupStartedAt` | string (date-time) |  |
| `rampStage` | integer (int32) |  |
| `lowHistory` | boolean |  |
| `paused` | boolean |  |
| `pausedAt` | string (date-time) |  |
| `pauseReason` | string |  |
| `pausedUntil` | string (date-time) |  |
| `timezone` | string |  |
| `workingHoursSchedule` | LinkedInWeeklySchedule | A LinkedIn account's working hours, one entry per day from `mon` to `sun`, in the account's time zone. Kenso runs the account's LinkedIn actions only inside these hours. A day with no entry uses the default: 08:00 to 18:00 on weekdays, closed on weekends. An update must include all seven days. |
| `dailyNewChatCap` | integer (int32) |  |
| `dailyMessageCap` | integer (int32) |  |
| `newChatCap` | integer (int32) |  |
| `coldNewChatCap` | integer (int32) |  |
| `messageCap` | integer (int32) |  |
| `checkCap` | integer (int32) |  |
| `newChatCapCeiling` | integer (int32) |  |
| `messageCapCeiling` | integer (int32) |  |
| `newChatsToday` | integer (int32) |  |
| `messagesToday` | integer (int32) |  |
| `checksToday` | integer (int32) |  |
| `unpaid` | boolean |  |
| `lastSyncedAt` | string (date-time) |  |
| `createdAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |

### Request

```bash
curl -X GET "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "phoneE164": "string",
    "displayName": "string",
    "profileImageUrl": "https://example.com",
    "status": "string",
    "statusChangedAt": "2026-09-23T15:02:11Z",
    "connectedAt": "2026-09-23T15:02:11Z",
    "connectedByMemberId": 812,
    "quietUntil": "2026-09-23T15:02:11Z",
    "rampupStartedAt": "2026-09-23T15:02:11Z",
    "rampStage": 1,
    "lowHistory": true,
    "paused": true,
    "pausedAt": "2026-09-23T15:02:11Z",
    "pauseReason": "string",
    "pausedUntil": "2026-09-23T15:02:11Z",
    "timezone": "string",
    "workingHoursSchedule": {
      "mon": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "tue": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "wed": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "thu": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "fri": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "sat": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "sun": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      }
    },
    "dailyNewChatCap": 1,
    "dailyMessageCap": 1,
    "newChatCap": 1,
    "coldNewChatCap": 1,
    "messageCap": 1,
    "checkCap": 1,
    "newChatCapCeiling": 1,
    "messageCapCeiling": 1,
    "newChatsToday": 1,
    "messagesToday": 1,
    "checksToday": 1,
    "unpaid": true,
    "lastSyncedAt": "2026-09-23T15:02:11Z",
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Update a WhatsApp account

`PATCH /v1/whatsapp-accounts/{whatsappAccountId}` - operationId `whatsapp-accounts.update`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 4,800 requests a minute per API key |

Absent fields stay unchanged.

Requires Delivery edit. `dailyNewChatCap` runs from 0 to `newChatCapCeiling` and `dailyMessageCap` from 0
to `messageCapCeiling` (above is `400 validation_failed` naming the field); `resetCaps` goes back to the
ramp defaults. `timezone` takes an IANA id (empty clears it); `workingHoursSchedule` takes all seven days and
`resetWorkingHours` clears them. `paused: true` pauses the account; `paused: false` resumes a manual or
low-reply-rate pause, and is `409 conflict` with `restricted_pause` while WhatsApp restricts it.

Needs the `whatsapp` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/whatsapp-accounts/PATCH/v1/whatsapp-accounts/%7BwhatsappAccountId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `whatsappAccountId` | path | integer (int64) | yes |  |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dailyNewChatCap` | integer (int32) | no |  |
| `dailyMessageCap` | integer (int32) | no |  |
| `resetCaps` | boolean | no |  |
| `timezone` | string | no |  |
| `workingHoursSchedule` | LinkedInWeeklySchedule | no | A LinkedIn account's working hours, one entry per day from `mon` to `sun`, in the account's time zone. Kenso runs the account's LinkedIn actions only inside these hours. A day with no entry uses the default: 08:00 to 18:00 on weekdays, closed on weekends. An update must include all seven days. |
| `resetWorkingHours` | boolean | no |  |
| `paused` | boolean | no |  |

### Response 200

`data` is a `WhatsAppAccount`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) |  |
| `phoneE164` | string |  |
| `displayName` | string |  |
| `profileImageUrl` | string |  |
| `status` | string |  |
| `statusChangedAt` | string (date-time) |  |
| `connectedAt` | string (date-time) |  |
| `connectedByMemberId` | integer (int64) |  |
| `quietUntil` | string (date-time) |  |
| `rampupStartedAt` | string (date-time) |  |
| `rampStage` | integer (int32) |  |
| `lowHistory` | boolean |  |
| `paused` | boolean |  |
| `pausedAt` | string (date-time) |  |
| `pauseReason` | string |  |
| `pausedUntil` | string (date-time) |  |
| `timezone` | string |  |
| `workingHoursSchedule` | LinkedInWeeklySchedule | A LinkedIn account's working hours, one entry per day from `mon` to `sun`, in the account's time zone. Kenso runs the account's LinkedIn actions only inside these hours. A day with no entry uses the default: 08:00 to 18:00 on weekdays, closed on weekends. An update must include all seven days. |
| `dailyNewChatCap` | integer (int32) |  |
| `dailyMessageCap` | integer (int32) |  |
| `newChatCap` | integer (int32) |  |
| `coldNewChatCap` | integer (int32) |  |
| `messageCap` | integer (int32) |  |
| `checkCap` | integer (int32) |  |
| `newChatCapCeiling` | integer (int32) |  |
| `messageCapCeiling` | integer (int32) |  |
| `newChatsToday` | integer (int32) |  |
| `messagesToday` | integer (int32) |  |
| `checksToday` | integer (int32) |  |
| `unpaid` | boolean |  |
| `lastSyncedAt` | string (date-time) |  |
| `createdAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "dailyNewChatCap": 1,
  "dailyMessageCap": 1,
  "resetCaps": true,
  "timezone": "string",
  "workingHoursSchedule": {
    "mon": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "tue": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "wed": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "thu": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "fri": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "sat": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    },
    "sun": {
      "open": true,
      "start": "09:00",
      "end": "17:30"
    }
  },
  "resetWorkingHours": true,
  "paused": true
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "phoneE164": "string",
    "displayName": "string",
    "profileImageUrl": "https://example.com",
    "status": "string",
    "statusChangedAt": "2026-09-23T15:02:11Z",
    "connectedAt": "2026-09-23T15:02:11Z",
    "connectedByMemberId": 812,
    "quietUntil": "2026-09-23T15:02:11Z",
    "rampupStartedAt": "2026-09-23T15:02:11Z",
    "rampStage": 1,
    "lowHistory": true,
    "paused": true,
    "pausedAt": "2026-09-23T15:02:11Z",
    "pauseReason": "string",
    "pausedUntil": "2026-09-23T15:02:11Z",
    "timezone": "string",
    "workingHoursSchedule": {
      "mon": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "tue": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "wed": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "thu": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "fri": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "sat": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      },
      "sun": {
        "open": true,
        "start": "09:00",
        "end": "17:30"
      }
    },
    "dailyNewChatCap": 1,
    "dailyMessageCap": 1,
    "newChatCap": 1,
    "coldNewChatCap": 1,
    "messageCap": 1,
    "checkCap": 1,
    "newChatCapCeiling": 1,
    "messageCapCeiling": 1,
    "newChatsToday": 1,
    "messagesToday": 1,
    "checksToday": 1,
    "unpaid": true,
    "lastSyncedAt": "2026-09-23T15:02:11Z",
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Delete a WhatsApp account

`DELETE /v1/whatsapp-accounts/{whatsappAccountId}` - operationId `whatsapp-accounts.delete`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 4,800 requests a minute per API key |

Returns `204`. Requires Delivery edit. Removes the Unipile session too and stops the monthly charge.

Needs the `whatsapp` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/whatsapp-accounts/DELETE/v1/whatsapp-accounts/%7BwhatsappAccountId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `whatsappAccountId` | path | integer (int64) | yes |  |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 204

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Start a hosted WhatsApp connect or reconnect session

`POST /v1/whatsapp-accounts/connect-sessions` - operationId `whatsapp-accounts.create-connect-session`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Any workspace member except a Network member | Spends credits, price not on the rate card yet (`whatsapp_account_monthly`) | 10 requests a minute per API key |

Omit `whatsappAccountId` to connect a new account (it shows as `connecting` until the scan completes);
pass it to reconnect. A new account needs one month of credits up front (`400 validation_failed` with the
credit refusal otherwise). On the Growth trial a new account is refused with `402 trial_cap_reached` once the
workspace holds its one LinkedIn or WhatsApp account. A client seat reconnects only the account it connected (`403 forbidden` with
`not_your_whatsapp`). `503 service_unavailable` while WhatsApp is switched off or Unipile is throttled.
A workspace key gets `403 forbidden`: a WhatsApp seat is a person's own, and a workspace key is not a person.

Needs the `whatsapp` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/whatsapp-accounts/POST/v1/whatsapp-accounts/connect-sessions)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `whatsappAccountId` | integer (int64) | no |  |

### Response 201

`data` is a `WhatsAppConnectSession`.

| Field | Type | Description |
| --- | --- | --- |
| `whatsappAccountId` | integer (int64) |  |
| `url` | string |  |

### Request

```bash
curl -X POST "https://api.ken.so/v1/whatsapp-accounts/connect-sessions" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "whatsappAccountId": 812
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "whatsappAccountId": 812,
    "url": "https://example.com"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### LinkedInWeeklySchedule

A LinkedIn account's working hours, one entry per day from `mon` to `sun`, in the account's time zone. Kenso runs the account's LinkedIn actions only inside these hours. A day with no entry uses the default: 08:00 to 18:00 on weekdays, closed on weekends. An update must include all seven days.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mon` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `tue` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `wed` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `thu` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `fri` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `sat` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |
| `sun` | LinkedInWorkingDay | no | One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone. |

### LinkedInWorkingDay

One day of a LinkedIn account's working hours. Times are `HH:mm` in the account's time zone.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | boolean | no | True when the account works on this day; false when it takes the day off. |
| `start` | string | no | When the working day starts, such as `09:00`. |
| `end` | string | no | When the working day ends, such as `17:30`. |

All resources: [/docs.md](/docs.md).
