Kenso
Get early access

Whatsapp accounts

The Whatsapp accounts endpoints of the Kenso API.

5 endpointsKen-Version: 1.1AuthenticationWorkspacesErrors

List WhatsApp accounts in the current workspace

GET/v1/whatsapp-accountswhatsapp-accounts.list

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

Try it on developer.ken.so

Parameters

Name
In
Type
Required
Description
cursor
In: query
string
optional
limit
In: query
integer (int32)
optional
Ken-Version
In: 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. 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
In: 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.

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
curl -X GET "https://api.ken.so/v1/whatsapp-accounts?limit=1" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "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": "string",
          "end": "string"
        },
        "tue": {
          "open": true,
          "start": "string",
          "end": "string"
        },
        "wed": {
          "open": true,
          "start": "string",
          "end": "string"
        },
        "thu": {
          "open": true,
          "start": "string",
          "end": "string"
        },
        "fri": {
          "open": true,
          "start": "string",
          "end": "string"
        },
        "sat": {
          "open": true,
          "start": "string",
          "end": "string"
        },
        "sun": {
          "open": true,
          "start": "string",
          "end": "string"
        }
      },
      "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,
    "isTotalCapped": true
  }
}

Start a hosted WhatsApp connect or reconnect session

POST/v1/whatsapp-accounts/connect-sessionswhatsapp-accounts.create-connect-session

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). 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.

Parameters

Name
In
Type
Required
Description
Ken-Version
In: 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. 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
In: 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.

Request body

application/json, optional.

Field
Type
Required
Description
whatsappAccountId
integer (int64)
optional

Response 201

data is a WhatsAppConnectSession.

Field
Type
Description
whatsappAccountId
integer (int64)
url
string
Request
curl -X POST "https://api.ken.so/v1/whatsapp-accounts/connect-sessions" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "whatsappAccountId": 812
}'
Response 201
{
  "success": true,
  "data": {
    "whatsappAccountId": 812,
    "url": "https://example.com"
  }
}

Return one WhatsApp account in the current workspace

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

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

Try it on developer.ken.so

Parameters

Name
In
Type
Required
Description
whatsappAccountId
In: path
integer (int64)
required
Ken-Version
In: 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. 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
In: 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.

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
curl -X GET "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "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": "string",
        "end": "string"
      },
      "tue": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "wed": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "thu": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "fri": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "sat": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "sun": {
        "open": true,
        "start": "string",
        "end": "string"
      }
    },
    "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}whatsapp-accounts.update

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.

Parameters

Name
In
Type
Required
Description
whatsappAccountId
In: path
integer (int64)
required
Ken-Version
In: 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. 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
In: 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.

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

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
curl -X PATCH "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "dailyNewChatCap": 1,
  "dailyMessageCap": 1,
  "resetCaps": true,
  "timezone": "string",
  "workingHoursSchedule": {
    "mon": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "tue": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "wed": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "thu": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "fri": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "sat": {
      "open": true,
      "start": "string",
      "end": "string"
    },
    "sun": {
      "open": true,
      "start": "string",
      "end": "string"
    }
  },
  "resetWorkingHours": true,
  "paused": true
}'
Response 200
{
  "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": "string",
        "end": "string"
      },
      "tue": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "wed": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "thu": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "fri": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "sat": {
        "open": true,
        "start": "string",
        "end": "string"
      },
      "sun": {
        "open": true,
        "start": "string",
        "end": "string"
      }
    },
    "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}whatsapp-accounts.delete

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.

Parameters

Name
In
Type
Required
Description
whatsappAccountId
In: path
integer (int64)
required
Ken-Version
In: 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. 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
In: 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.

Response 204

Request
curl -X DELETE "https://api.ken.so/v1/whatsapp-accounts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 204
HTTP/1.1 204 No Content
More in the API:AI feedbackContact behaviorDelivery settingsSaved list membersVoice note previewsVoice notesVoicesWhatsapp settingsAll resources