Skip to Content
Inbox

WhatsApp accounts

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.

Inbox5 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
whatsappAccountIdpathinteger (int64)required

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

List WhatsApp accounts in the current workspace

GET/v1/whatsapp-accountswhatsapp-accounts.list
Permission
Delivery view
Rate limit
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

Parameters

NameInTypeRequiredDescription
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
limitqueryinteger (int32)optionalItems per page, from 1 to 200. Default 50.
Request
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"

Response 200

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

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Return one WhatsApp account in the current workspace

GET/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.get
Permission
Delivery view
Rate limit
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

Request
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"

Response 200

data is a WhatsAppAccount.

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update a WhatsApp account

PATCH/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.update
Permission
Delivery edit
Rate limit
4,800 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

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
dailyNewChatCapinteger (int32)optional
dailyMessageCapinteger (int32)optional
resetCapsbooleanoptional
timezonestringoptional
workingHoursScheduleLinkedInWeeklyScheduleoptionalA 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.
resetWorkingHoursbooleanoptional
pausedbooleanoptional
Request
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
}'

Response 200

data is a WhatsAppAccount.

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Delete a WhatsApp account

DELETE/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.delete
Permission
Delivery edit
Rate limit
4,800 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

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

Request
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"

Response 204

Response 204
HTTP/1.1 204 No Content

Start a hosted WhatsApp connect or reconnect session

POST/v1/whatsapp-accounts/connect-sessionswhatsapp-accounts.create-connect-session
Permission
Any workspace member except a Network member
Credits
Spends credits, price not on the rate card yet (whatsapp_account_monthly)
Rate limit
10 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

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
whatsappAccountIdinteger (int64)optional
Request
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
}'

Response 201

data is a WhatsAppConnectSession.

Show the 2 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page