Kenso MCP tools

Account Touches account_touches

Planned 1:1 actions on target accounts: emails, LinkedIn notes, calls and tasks, and each account's 90-day touch plan (plan-* operations). A person approves sends in the Kenso app or by clicking the card approvals_review shows; approved touches then send from the account's Sends from inbox or LinkedIn. client_approvals touches-approve and touches-retry approve as you, only when the person asked for that touch. contact-limits-get returns the guardrails your touch writes must pass. Contact limit collisions list the touches and campaign steps that break a contact limit, and fix one.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through account_touches_read and changes through account_touches_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: create, delete, draft, plan-end, feedback, contact-limit-collisions-fix, plan-get, contact-limits-get, get, contact-limit-collisions-list, list, plan-pause, plan-resume, rewrite, skip, snooze, plan-start, undo, contact-limits-update, update

create

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches

Body (json): accountId integer, assetLinkId integer, attachmentIds array, body string, channel string, dueAt date-time, findNumber boolean, judgeScore integer, mediaIds array, rationale string, reason string, stakeholderId integer, subject string, title string, voiceId string, voiceProvider string, whatsappAccountId integer

Plan a touch on an account. With a body it waits for a person's approval. Without a body it is planned. Nothing sends from here. Returns 201.

POST /api/v1/touches. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
channel: email, linkedin_connect, linkedin_message, linkedin_follow, linkedin_like,
linkedin_comment, instagram_dm, instagram_follow, instagram_like, instagram_comment,
whatsapp_message, call, event, intro, asset, task. linkedin_follow,
linkedin_like and linkedin_comment need the linkedin_engagement and accounts_writer
flags on the workspace (400 not_enabled otherwise). With linkedin_engagement turned
off later, such a touch waits: planned, or approved with holdReason
linkedin_engagement_off, and it goes on once the flag is back on. A like or comment
skips with read_failed, no_recent_post or author_mismatch when the person's recent
posts cannot be read or none fits. A follow or like has no body. A comment takes no
body on create (400 validation_failed on body with not_allowed): Ken picks the
person's most recent LinkedIn post and writes the comment (up to 1250 characters)
when the workspace has accounts_writer, and a person may edit that text before
approving. Once the post is picked, the touch's person and channel are fixed. A
comment that reaches its send with no picked post skips with no_post_picked and
spends nothing; one whose person's LinkedIn URL changed after approval skips with
recipient_changed. instagram_dm, instagram_follow, instagram_like and
instagram_comment need the instagram flag (400 not_enabled, "Instagram outreach is not
enabled for this workspace."). They go to the person's accepted Instagram handle and
send from the account's Sends from Instagram account. An instagram_follow or
instagram_like has no body; an instagram_comment takes no body (400 validation_failed
on body with not_allowed). whatsapp_message needs the whatsapp and accounts_send flags on
the workspace (400 not_enabled otherwise). It sends from whatsapp_account_id when
given (a WhatsApp account of this workspace; 400 validation_failed on
whatsappAccountId with not_found otherwise), else the account's Sends from WhatsApp,
else the WhatsApp account the account owner connected; that account's connector
approves it, and with none usable an approved touch waits with holdReason
connect_whatsapp. find_number (default true) looks for a mobile number when the
person has none on WhatsApp. whatsapp_account_id and find_number on another channel
are 400 validation_failed with not_allowed. media_ids (up to 6 message-media ids,
images uploaded with message_media) and voice_provider with voice_id (deepgram or
elevenlabs, together) are for whatsapp_message only (400 validation_failed with
not_allowed on another channel); an image that is not a live image of this workspace
is not_found on mediaIds, images and a voice together are not_allowed, and a voice
with a body over 900 characters is too_long_for_voice. With a voice, Ken speaks the
body as a voice note, and approval waits for that note: approve is 409 invalid_state
with voice_note_not_ready on voiceId until it is generated for the current text and
voice. due_at: ISO-8601
instant (UTC when no offset). stakeholder_id must be on the same account. reason:
cadence, signal, manual (default), reply. A linkedin_follow or linkedin_like can't be
cadence, which marks the ones Ken's plan places (400 validation_failed on reason
with not_allowed). title up to 200 characters says what the
step is ("Share the ramp benchmark with Maya"). subject up to 500 characters, body up
to 20000, rationale up to 2000: say why this touch, now. judge_score 0 to 100 from
your own review of the draft. On a send channel, a subject or body that names an
event (funding, a hire, a launch, news, an award) that no signal, dossier fact or
research source on the account mentions fails with 400 unsourced_claim: name only
events the account's signals or research state. asset_link_id: a link of a
published Studio page of the same account (assets operation list-links). Its URL is
added to the end of the body unless the body already has it; a later draft writes it
in. linkedin_follow, linkedin_like, linkedin_comment and the Instagram channels take no
page link. 400 validation_failed on assetLinkId with not_allowed on those channels, or
not_found, wrong_account, not_published, or too_long when the URL would make a
linkedin_connect note longer than 300 characters. attachment_ids: up to 3 att_ ids
sent with an instagram_dm; any other channel fails with 400 validation_failed on
attachmentIds not_allowed, more than 3 with out_of_range, an id that is not att_ with
invalid.

delete

Write. Early access: needs accounts on for the workspace. DELETE https://api.ken.so/v1/touches/{touchId}

Path: touchId

Delete a touch that has not gone out. Only on the user's explicit request.

DELETE /api/v1/touches/{touchId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Returns 204. Works from planned, drafted, awaiting_approval and failed; another status
fails with invalid_transition. The touch is also skipped (skipReason deleted) and every
later read is not_found. Use skip to keep it visible in the plan instead.

draft

Write. Early access: needs accounts, accounts_writer on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/draft

Path: touchId

Have Ken write a planned touch from the account, the person and the dossier. Grades it and puts it up for a person's approval. Charged. Nothing sends.

POST /api/v1/touches/{touchId}/draft. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. No body. Works on a planned or drafted touch with no body, on
channel email, linkedin_connect, linkedin_message, call, instagram_dm or
instagram_comment. A touch that
already has a body fails with already_written; edit it with touches_update. A touch
in any other status fails with invalid_transition. Other channels fail with
not_draftable, linkedin_comment too: Ken writes a comment once the LinkedIn worker
has picked the person's most recent post. An Instagram touch needs the workspace's
Instagram outreach on (409 not_draftable otherwise). An instagram_comment waits until Kenso picked
the post it answers: before that, or once the post left their recent posts, it fails with 503
instagram_post_unavailable. 503 no_instagram_context means Ken has no Instagram profile, post
or allowed chat for the person, and 503 instagram_rules means the draft broke the Instagram
rules twice: write a DM by hand with touches_update, or skip the touch (a comment body cannot
be written by hand). On success the touch is awaiting_approval
with body, originalBody, rationale, sources, judgeScore and draftModel. Out of credits returns 402
INSUFFICIENT_CREDITS. A model failure returns 503 (model_failed, invalid_output,
model_refused, too_long, no_sender) or 504 and leaves the touch retryable. 503
context_unavailable means Ken could not read the account yet: retry in a minute. A
reply touch (one with inReplyToMessageId) is drafted as a reply to that email, with no
subject. 503 reply_not_found means Ken cannot read that email from someone at the
account: write the reply by hand with touches_update.
409 concurrent_change means the touch's person, channel or page link changed while Ken wrote:
nothing was written or charged; draft it again. A person still approves in the Kenso app.

plan-end

Write. Early access: needs accounts, accounts_plan on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/plan/end

Path: accountId

End an account's touch plan. Only on the user's explicit request.

POST /api/v1/accounts/{accountId}/plan/end. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. From active or paused. The plan's open steps are skipped
(skipReason plan_ended); reply touches stay. An ended plan comes back unchanged; a
plan that never started is invalid_state. Start it again with start.

feedback

Write. Early access: needs accounts, accounts_writer on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/feedback

Path: touchId

Body (json): body string, subject string

Grade a touch's text: a score, a band and five bars. Not charged.

POST /api/v1/touches/{touchId}/feedback. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Grades subject and body when sent, else the stored text. Returns
score 0 to 10, band (keep, rewrite, start_over or write_first), bars (quick_read, cta,
easy, weird_words, personal, each with score and note), grounded, wordCount,
questionCount, characterCount, characterLimit and judgeScoreSaved. An empty body
returns write_first with no model call. judgeScoreSaved is true when the graded text
equals the stored text and the touch's judge score was updated.

contact-limit-collisions-fix

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/contact-limit-collisions/{collisionId}/fix

Path: collisionId

Move the collision's fix item to its fix time so the collision clears.

POST /api/v1/contact-limit-collisions/{collisionId}/fix. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. collision_id is a clc_ id from contact-limit-collisions-list. The API
recomputes first. A touch moves its dueAt (its edit rules apply). A campaign step moves by
holding the contact's next step in that campaign until moveToAt, which needs the
workspace's contact_limits_campaign_moves flag. 409 conflict with error.details[0].code:
collision_resolved (already gone: list again), not_movable (nothing in it may move, or no
day in the next 90 days clears every limit), campaign_moves_disabled (only a campaign step
could move).

plan-get

Read. Early access: needs accounts, accounts_plan on for the workspace. GET https://api.ken.so/v1/accounts/{accountId}/plan

Path: accountId

Return an account's touch plan: status, dates, step counts and whether it is thin.

GET /api/v1/accounts/{accountId}/plan. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
status: none (never planned), active, paused or ended. stepCount counts steps not
skipped or deleted, openStepCount those not sent or done yet, nextStepAt the earliest
open step. thin: an active or paused plan with fewer steps than its shape's minimum
(the account tier's minTouches where tiers are on, else 8); map more people.
pauseReason: reply or owner (pausedByMessageId is the reply's msg_ id). endReason:
completed, owner, meeting_booked or stage_changed.

contact-limits-get

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/contact-limits

Return the workspace's Contact limits: limits, rule switches, send window and Ken agent guardrails. Read it before planning touches: the guardrails bind your touch writes.

GET /api/v1/contact-limits. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Limits: emailsPerAccountPerDay (1-5), peoplePerAccountPerWeek (1-10),
minDaysBetweenTouches (1-7). Switches: holdCampaignStepsOnOneToOneDays,
pauseAccountOnReply, skipAccountsWithOpenOpportunity.
sendWindow {days, startTime, endTime} is the one rule for when Ken sends, in each
person's time zone, shaped like a campaign's schedule: days 0 (Sunday) to 6 (Saturday),
sorted, and one time range for all of them, startTime "HH:mm" (00:00-23:45) to endTime
(00:15-24:00, exclusive), on 15-minute steps. Default [1, 2, 3, 4, 5], "08:00" to
"17:00" (Monday to Friday). Accounts email
touches wait for it and calls go out only inside it (LinkedIn keeps the seat's working
hours, campaigns their own schedule), and your touch dueAt must fall on one of its days
(America/New_York). An API deployed before DEV-3930 has no sendWindow yet.
businessHoursOnly (true unless the window is 00:00-24:00) and agentSendWindow (any_time when
every day is open, else weekdays_8_to_6) are deprecated, derived from sendWindow.
Guardrails (bind agents, never a person): agentWeeksBetweenTouches (1-12, presets 2, 3
and 4) between touches to one person on any channel but task; agentNewPeoplePerDay
(1-200, presets 5, 10 and 20) first touches a day across the workspace; and the send
window's days, rule agent_send_window. skipAccountsWithOpenOpportunity
(default on) also binds your touch writes: no new touch, on any channel but task, on
an account with an open opportunity (moving or snoozing an existing touch is not held).
Calls: callsPerPersonPerDay (1-3) and the deprecated findPhonesOnInterestedReply (no
effect: Kenso's "Find phones for interested replies" workflow finds phones now, so turn
that workflow on or off instead).
engageWithPosts ("Like and comment on prospects' posts", default on): off, Ken's account
plans place no LinkedIn like before a connection note (follows stay), a like or comment
touch on any network is refused with 400 post_engagement_off and a queued one skips at
send, and a campaign Like post or Comment on post step cannot be saved and skips when it
runs.
unavailableRules lists rules stored but not enforced yet. updatedAt is null while the
workspace runs on the defaults.
A touches create, update or snooze that breaks a guardrail fails with 422
guardrail_violation; error.details[0] has rule and nextAllowedAt (the first dueAt that
passes, omitted when none in 180 days). Rule skip_accounts_with_open_opportunity has no
nextAllowedAt: no dueAt clears it, so leave the account to a person or ask the user
to turn the switch off.

get

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/touches/{touchId}

Path: touchId

Return one touch with its full body, the original draft and its account.

GET /api/v1/touches/{touchId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
originalBody is the first draft; editDistance shows how much a person changed it.
Sending: sendAt is when an approved touch may go out, and holdReason why it waits
(connect_inbox, connect_linkedin, connect_instagram, connect_whatsapp,
account_has_no_owner when an email or LinkedIn touch's account has no owner and no
Sends from sender (set the owner or the Sends from, not a connection), a contact_limit_*
reason, plan_paused while the account's plan is paused, ...). failureReason says
why a send failed. senderInboxId, linkedInAccountId or instagramAccountId is the
sender; attachmentIds lists an instagram_dm's att_ attachments; threadId and
messageId point at what was sent (thr_ and msg_ conversation ids on email and LinkedIn
messages; a LinkedIn invite has none). approverMemberId is the member who must approve
it (null when anyone may); stakeholder carries title and email for the To line.
voiceNote (a LinkedIn message with an AI voice note): voiceNoteId, status, durationMs,
language, provider, voiceId, scriptText (the words spoken), failureReason,
audioAvailable and audioUrl, the route that returns the audio. A WhatsApp touch carries
whatsappAccountId, recipientPhone (the number Ken checked), warmth (warm or cold),
findNumber, approvalMode (person or auto), mediaIds (its images, [] when none) and
voiceProvider with voiceId (the voice Ken speaks the body in; approval waits for that
note: voice_note_not_ready). mirror (DEV-5528) is Ken's draft translated into the
approving rep's language, {language, subject, body}: a meeting follow-up written in the
recipient's language carries one. It is for reading only and is never sent; it is null
once the subject or body was edited, and when the draft is already in the rep's language.

contact-limit-collisions-list

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/contact-limit-collisions

Query: accountId integer, cursor string, limit integer

List touches and campaign steps that break a contact limit in the next 90 days. Each collision names its rule, the items in it and the fix (what moves, and to when).

GET /api/v1/contact-limit-collisions. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Computed on read from unsent 1:1 touches (planned, drafted, awaiting_approval, approved)
and projected campaign email steps for contacts at the workspace's accounts. Days are
calendar days in America/New_York. rule: emails_per_account_per_day (limit is emails a
day), min_days_between_touches (limit is the minimum days, daysApart how far apart they are),
people_per_account_per_week (limit is people a week, people how many the week reaches).
items[].kind: touch (touchId, status) or campaign_step (campaignId, contactId,
sequenceStepId, stepNumber). items[].sendAt: when an approved touch will send (a hold,
business hours or a retry can move it off scheduledAt); it counts on that day.
When the same two items break several rules, one collision names
the rule that clears last. fix: { item, moveToDate, moveToAt }, the first weekday from that
rule's own target where the item breaks no rule; absent when nothing may move or no day in
the 90 days clears. A campaign step already sending never moves. holdCampaignSteps: the workspace holds campaign steps on 1:1 days until one moves.
account_id limits the list to one account. Pass pagination.nextCursor back unchanged.

list

Read. Early access: needs accounts on for the workspace. GET https://api.ken.so/v1/touches

Query: accountId integer, approverMemberId integer, channel string, createdByMemberId integer, cursor string, dueAfter date-time, dueBefore date-time, limit integer, ownerMemberId integer, sort string, stakeholderId integer, status string

List touches: one account's plan (account_id) or the work queue (status, due dates). Items carry bodyPreview; get one touch for the full body.

GET /api/v1/touches. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
status (comma = OR): planned, drafted, awaiting_approval, approved, sending, sent,
failed, skipped, done. channel (comma = OR): email, linkedin_connect,
linkedin_message, linkedin_follow, linkedin_like, linkedin_comment, instagram_dm,
instagram_follow, instagram_like, instagram_comment, whatsapp_message, call, event, intro, asset, task. due_after (inclusive) and
due_before (exclusive) are ISO-8601 instants (UTC when no offset); due_after must be
earlier than due_before. owner_member_id: touches on accounts that member owns.
approver_member_id: touches that member must approve (their approverMemberId).
created_by_member_id: touches that member made (createdBy.memberId), whoever owns the
account, such as the next-step tasks from their call on a teammate's account. Filters
combine with AND.
sort: dueAt (default) or -createdAt. Pass pagination.nextCursor back unchanged.
Each item's approverMemberId is who approves it: the member whose Sends from inbox
(email), LinkedIn account (LinkedIn), Instagram account (Instagram) or WhatsApp account
(WhatsApp: the touch's own, else the account's) sends it, else the account owner; null when
anyone may. stakeholder carries fullName, role, title and email. A LinkedIn message
with an AI voice note carries voiceNote (voiceNoteId, status, durationMs, language,
provider, voiceId, failureReason, audioAvailable, audioUrl); get the touch for its
scriptText.

plan-pause

Write. Early access: needs accounts, accounts_plan on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/plan/pause

Path: accountId

Pause an account's touch plan. Unsent steps stay; nothing drafts or sends them.

POST /api/v1/accounts/{accountId}/plan/pause. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. From active. A paused plan comes back unchanged; a plan that
never started or ended is invalid_state.

plan-resume

Write. Early access: needs accounts, accounts_plan on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/plan/resume

Path: accountId

Resume a paused touch plan. Open steps move forward by the days it was paused.

POST /api/v1/accounts/{accountId}/plan/resume. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. From paused. Planned, drafted and awaiting_approval steps and
endsAt move forward by the whole days paused, then to a weekday. An active plan
comes back unchanged; a plan that never started or ended is invalid_state, and so
is a won deal (a customer, or its latest opportunity is won), with deal_won on
field deal.

rewrite

Write. Early access: needs accounts, accounts_writer on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/rewrite

Path: touchId

Body (json): body string, instruction string, prompt string

Rewrite a touch's text with one instruction, or your own words. Stores nothing. Charged.

POST /api/v1/touches/{touchId}/rewrite. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. instruction: shorter, warmer, more_specific, in_my_voice or
custom. With custom, prompt says what to change in your own words ("say we already
emailed their cofounder the sample", "drop the second sentence"): required, 1 to 1000
characters after trimming. The other instructions take no prompt. A prompt can
change what the message says, its tone and its length, not the channel's rules:
a connection note stays under 300 characters and a LinkedIn touch gets no subject.
body is the current unsaved text; without it the stored body is rewritten, and a
touch with neither fails with a body validation error. Returns {touchId,
instruction, body, model}. The touch is unchanged: save the result with
touches_update. 402, 503 and 504 as touches_draft.

skip

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/skip

Path: touchId

Body (json): reason string

Skip a touch, with an optional reason.

POST /api/v1/touches/{touchId}/skip. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. reason up to 500 characters. Works from planned, drafted,
awaiting_approval, approved and failed.

snooze

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/snooze

Path: touchId

Body (json): days integer

Push a touch out by days (1 to 90, default 7).

POST /api/v1/touches/{touchId}/snooze. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. The new due time is the later of now and the current due time,
plus days. Works from planned, drafted, awaiting_approval and failed. A new due time
that breaks a Contact limits guardrail fails with 422 guardrail_violation, with rule
and nextAllowedAt (contact-limits-get).

plan-start

Write. Early access: needs accounts, accounts_plan on for the workspace. POST https://api.ken.so/v1/accounts/{accountId}/plan/start

Path: accountId

Start an account's touch plan, sized by its tier where account tiers are on.

POST /api/v1/accounts/{accountId}/plan/start. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. From none or ended. Ken places the steps as planned touches,
on weekdays across the reachable people. Where account tiers are on
(accounts_tiers), the plan follows the policy of the account's tier (hand-set,
else placed, else its score's) on the workspace's ladder, which
account_signals(operation="account-tiers-get") returns: up to maxTouches steps
over days, gapDays or more apart, in its channelMix. On the default ladder Tier 1
is 10 to 11 steps over 100 days and Tier 5 is 2 to 3 over 21, so read the tier
before expecting a step count. A tier with no touches is invalid_state with
tier_plans_no_touches on field tier. Elsewhere every plan has the fixed shape: up
to 9 steps over 90 days, 10 or more days apart (8 or more once two people are
mapped). The account must be researching, warming or engaged with one person who
has an email or LinkedIn, else invalid_state says which. A won deal (a customer,
or its latest opportunity is won) is invalid_state with deal_won on field deal. An
active plan comes back unchanged; a paused plan is invalid_state (resume or end it).

undo

Write. Early access: needs accounts on for the workspace. POST https://api.ken.so/v1/touches/{touchId}/undo

Path: touchId

Body (json): action string, updatedAt date-time

Undo your own snooze or skip of a touch, right after doing it.

POST /api/v1/touches/{touchId}/undo. Staff. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. updated_at is the touch's updatedAt from the snooze or skip
response. Snooze goes back to the old due time; skip goes back to the old status (a
skipped approved send is queued again under its approval). Only the caller that did the
action may undo it, and only while
nothing else has changed the touch: 409 concurrent_change or nothing_to_undo
otherwise, and stakeholder_removed once its person left the account. Undoing an
approval is the person's own button in the Kenso app, so it is not offered here.

contact-limits-update

Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/contact-limits

Update the workspace's Contact limits. Absent fields stay unchanged. Change them only when the user asks, tighter or looser. Requires the workspace_settings permission.

PATCH /api/v1/contact-limits. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
changes keys (snake_case or wire camelCase): emails_per_account_per_day 1-5,
people_per_account_per_week 1-10, min_days_between_touches 1-7,
agent_weeks_between_touches 1-12, agent_new_people_per_day 1-200, and the booleans
hold_campaign_steps_on_one_to_one_days, pause_account_on_reply,
skip_accounts_with_open_opportunity. send_window is the whole window, shaped like a
campaign's schedule: {"days": [1, 2, 3, 4, 5], "start_time": "08:00", "end_time": "17:00"},
days 0 (Sunday) to 6 (Saturday) each once, start_time "HH:mm" 00:00-23:45 and end_time
00:15-24:00 after it, both on 15-minute steps ("24:00" runs through midnight). Deprecated,
never together with send_window: business_hours_only (true sets the window to
08:00-17:00, false to 00:00-24:00, keeping the days) and agent_send_window
(weekdays_8_to_6 sets Monday to Friday, any_time every day, keeping the times);
sending back the value the get returned changes nothing. An API
deployed before DEV-3930 refuses send_window and
custom guardrail values outside its old presets (2, 3, 4 weeks; 5, 10, 20 people).
Calls: calls_per_person_per_day 1-3 and the deprecated boolean
find_phones_on_interested_reply (no effect: the "Find phones for interested replies"
workflow finds phones). Null is not allowed.
engage_with_posts (boolean): "Like and comment on prospects' posts". When the user asks
Ken to stop liking, commenting on or engaging with prospects' posts, set it to false here:
a team rule does not stop the planner. Setting it to false also skips the workspace's
open like and comment touches (again, if it was already off), and the response's
skippedEngagementTouches says how many.
Follows, connection notes and messages are not affected.
A save by someone else between this call's read and its write fails with 409
conflict and nothing is saved: read the limits again and retry.

update

Write. Early access: needs accounts on for the workspace. PATCH https://api.ken.so/v1/touches/{touchId}

Path: touchId

Body (json): assetLinkId integer, attachmentIds array, body string, channel string, dueAt date-time, findNumber boolean, imageIds array, mediaIds array, rationale string, senderInboxId integer, stakeholderId integer, subject string, title string, voiceId string, voiceProvider string, whatsappAccountId integer

Edit a touch's title, channel, subject, body, rationale, due time, stakeholder, page link, attachments or inbox. Works from planned, drafted, awaiting_approval and failed. A body moves it to approval.

PATCH /api/v1/touches/{touchId}. Staff. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
changes keys: title, channel, subject, body, rationale, due_at, stakeholder_id,
asset_link_id, attachment_ids, image_ids, sender_inbox_id, whatsapp_account_id, find_number, media_ids,
voice_provider, voice_id.
sender_inbox_id (email only) moves the touch to another inbox of the workspace (an id from
inboxes(operation="list")): 400 validation_failed with inbox_not_found for an inbox that is not the
workspace's or is deleted, 403 forbidden with inbox_not_owned for a member's own mailbox unless that
member is the person you act for. As for an account's Sends from, the send must be able to use it:
400 not_owned for a shared inbox off the cold sending domains, email_domain_mismatch for a mailbox
off the workspace's domains, not_member for a former member's. Null clears it, so the account's Sends
from inbox, else the owner's primary inbox, sends it. The new inbox's owner approves the touch, and a
change on an approved touch sends it back for approval. On another channel, or on a reply
(inReplyToRef set), a new value fails with 400 validation_failed on senderInboxId not_allowed; the
touch's own inbox is no change (409 concurrent_change if another edit moved the touch meanwhile).
A channel change off email clears sender_inbox_id (not on a reply), so a move back to email sends
from the account's sender unless the same edit names an inbox.
Null clears title, subject, body, rationale, stakeholder_id, asset_link_id, attachment_ids or image_ids;
channel and due_at cannot be null. A channel change keeps the body. A change to linkedin_follow,
linkedin_like or linkedin_comment needs the linkedin_engagement and accounts_writer flags, and one to
instagram_dm, instagram_follow, instagram_like or instagram_comment the instagram flag
(400 not_enabled); a channel equal to the
stored one is no change. attachment_ids (up to 3 att_ ids) is for an instagram_dm only
(400 validation_failed on attachmentIds not_allowed otherwise); moving a touch off
instagram_dm drops its attachments, and a change to them sends it back for approval. image_ids (up to 4 touch
image att_ ids, uploaded in the app) is for a facebook_message only (400 validation_failed on imageIds not_allowed
otherwise, not_found for an image of another workspace); moving a touch off facebook_message drops them, and a
change to them sends it back for approval. asset_link_id is a link of a published
Studio page of the same account: setting it adds its URL to the end of the body
unless the body has it (switching links replaces the old URL), and clearing it
leaves the body as it is. linkedin_follow, linkedin_like, linkedin_comment and the
Instagram channels take no page link: setting one on such a touch, or moving a touch that has
one to such a channel without clearing it, fails with 400 validation_failed on
assetLinkId not_allowed. 400 validation_failed on assetLinkId with not_found,
wrong_account, not_published, or too_long when the URL would make a
linkedin_connect note longer than 300 characters. A linkedin_comment touch answers
the post Ken picked: once it is picked, changing stakeholder_id or moving the touch
off linkedin_comment fails with 400 validation_failed not_allowed (skip it and add a
new touch instead), while body stays editable so a person can change Ken's text
before approving. Before Ken picks the post a comment takes no body: writing one,
or moving a touch with a body to linkedin_comment without clearing body, fails with
400 validation_failed on body not_allowed; an instagram_comment takes no body either.
Only a planned touch moves to linkedin_comment or instagram_comment, and a cadence touch can't move to linkedin_follow or
linkedin_like: both fail with 400 validation_failed on channel not_allowed (add a
new touch instead). Another status fails with
invalid_transition and the allowed statuses. A new stakeholder_id on a reply that
had a stakeholder (inReplyToRef set) makes it a fresh email to the new person:
inReplyToRef, senderInboxId and the subject are cleared (a subject in the same
changes stays), so set a subject before approving. A new subject or body on a send
channel that names an event no signal or research source on the account mentions
fails with 400 unsourced_claim, as touches_create does. whatsapp_account_id (null
goes back to the account's sender) and find_number apply only to whatsapp_message
(400 validation_failed with not_allowed on another channel); find_number cannot be
null. Moving a touch onto whatsapp_message needs the whatsapp and accounts_send flags
(400 not_enabled). A new whatsapp_account_id, channel or stakeholder clears an
approval and the number Ken checked. media_ids (up to 6 ids; [] or null removes every image)
and voice_provider with voice_id (set together; both null removes the voice) are for
whatsapp_message only (400 validation_failed with not_allowed on another channel, and
moving a touch off whatsapp_message drops them). New images, a new voice or a new body
with a voice clear an approval, and approval waits for the voice note again
(voice_note_not_ready).