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.
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
whatsappAccountId | path | integer (int64) | required |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 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-Id | header | integer (int64) | optional | 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. |
List WhatsApp accounts in the current workspace
/v1/whatsapp-accountswhatsapp-accounts.list- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
whatsapp feature on your workspace. Until it is on, calls answer 404.Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
limit | query | integer (int32) | optional | Items per page, from 1 to 200. Default 50. |
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
/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
whatsapp feature on your workspace. Until it is on, calls answer 404.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
/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.update- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
whatsapp feature on your workspace. Until it is on, calls answer 404.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.
| Field | Type | Required | Description |
|---|---|---|---|
dailyNewChatCap | integer (int32) | optional | |
dailyMessageCap | integer (int32) | optional | |
resetCaps | boolean | optional | |
timezone | string | optional | |
workingHoursSchedule | LinkedInWeeklySchedule | optional | 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 | optional | |
paused | boolean | optional |
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
/v1/whatsapp-accounts/{whatsappAccountId}whatsapp-accounts.delete- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
whatsapp feature on your workspace. Until it is on, calls answer 404.Returns 204. Requires Delivery edit. Removes the Unipile session too and stops the monthly charge.
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
HTTP/1.1 204 No ContentStart a hosted WhatsApp connect or reconnect session
/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
whatsapp feature on your workspace. Until it is on, calls answer 404.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.
| Field | Type | Required | Description |
|---|---|---|---|
whatsappAccountId | integer (int64) | optional |
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.
More in Inbox:ThreadsReply templatesScheduled messagesAttachmentsInboxesInbox importsLinkedIn accountsWhatsApp settingsAll resources