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

# Voice note previews: Preview a voice note step

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

One endpoint of [Voice note previews](/docs/api/voice-note-previews.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Preview a voice note step

`POST /v1/voice-note-previews` - operationId `voice-note-previews.create`

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

Makes the voice note an unsaved step would send to 1 to 3 of the campaign's contacts, so you can hear it before
you save the step. Send the step's `body`, `subject` and `voice` as you would save them. Ken writes
each note (or reads the step's script), Kenso speaks it right away, and nothing is sent to the contacts.

Returns `201` with one item per contact. Each item's `voiceNote` is `ready` with an
`audioUrl` to play, or `failed` with a `failureReason`. One contact failing never fails the call.
The `audioUrl` is `GET /v1/voice-notes/{voiceNoteId}/audio`, or
`GET /v1/voice-notes/{voiceNoteId}/imessage-audio` in a workspace whose `linkedin_voice_notes` feature is
off. Playing the audio needs Inbox view.

Previews cost no credits. Each contact counts toward the workspace's limit of 15 previews a day, and a contact
that fails before Kenso writes or speaks anything does not count.

Errors:

- `400 validation_failed`: `contactIds` does not list 1 to 3 contacts, the step is not a valid voice
note step, or the voice is not available.
- `404 not_found`: the campaign is not in this workspace, or a contact is not in the campaign.
- `409 provider_key_missing`: the voice is imported and the workspace has no ElevenLabs API key in Settings,
Integrations.
- `429 quota_exceeded`: the workspace reached its daily preview limit. Wait for `Retry-After`
seconds; `quotaResetAt` and `error.details[0]` give the limit and when it resets.
- `502 provider_rejected`: ElevenLabs refused the workspace's key. Check it in Settings, Integrations.
- `503 voice_notes_unavailable`: voice notes are not available right now, Kenso could not read the
workspace's ElevenLabs key, or ElevenLabs did not answer. Try again later.

Requires Campaigns edit.

Needs the `imessage` or `linkedin_voice_notes` feature on your workspace. Until one of them is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/voice-note-previews/POST/v1/voice-note-previews)

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

The campaign, the contacts and the step to preview.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignId` | integer (int64) | no | The campaign the contacts are in. |
| `contactIds` | array of integer (int64) | no | The contacts to make the note for: 1 to 3 distinct contacts of the campaign. |
| `step` | VoiceNotePreviewStep | no | The unsaved step: its fallback text, its InMail subject and its voice settings. |

### Response 201

`data` is a `VoiceNotePreviews`.

| Field | Type | Description |
| --- | --- | --- |
| `items` | array of VoiceNotePreview | One preview for each contact in the request. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/voice-note-previews" \
  -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 '{
  "campaignId": 812,
  "contactIds": [
    812
  ],
  "step": {
    "body": "string",
    "subject": "string",
    "voice": {
      "provider": "deepgram",
      "voiceId": "string",
      "speed": 0.5,
      "wordsMode": "string",
      "instructions": "string",
      "script": "string",
      "model": "haiku",
      "matchLeadLanguage": true
    }
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "contactId": 812,
        "voiceNote": {
          "voiceNoteId": 812,
          "status": "pending",
          "durationMs": 1,
          "language": "string",
          "provider": "string",
          "voiceId": "string",
          "scriptText": "string",
          "failureReason": "string",
          "audioAvailable": true,
          "audioUrl": "https://example.com"
        }
      }
    ]
  }
}
```

## Types

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

### VoiceNotePreviewStep

An unsaved LinkedIn voice note step.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | The text Kenso sends instead when the note cannot go, at most 1,900 characters. Required. |
| `subject` | string | no | The subject Kenso uses when it sends the text as an InMail, at most 200 characters. Optional. |
| `voice` | LinkedInVoiceNoteSettings | no | The voice settings, the same object a voice note step saves. |

### LinkedInVoiceNoteSettings

The voice settings of a LinkedIn voice note step: which voice speaks, and where the words come from. Every value that names an option is a lowercase string.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | no | Who provides the voice: `deepgram` or `elevenlabs`. Variant A's value applies to every variant. |
| `voiceId` | string | yes | The voice's id at its provider, at most 200 characters. Required. Variant A's value applies to every variant. |
| `speed` | number (double) | no | How fast the voice speaks, from 0.50 to 1.50. Kenso applies it to Deepgram voices only. Null keeps the provider's default. Variant A's value applies to every variant. |
| `wordsMode` | string | no | Where the words come from: `ken_writes` (Ken writes each contact's note from `instructions`) or `script` (Kenso speaks `script`). |
| `instructions` | string | no | What Ken should say, at most 1,000 characters. Required when `wordsMode` is `ken_writes`, and must be empty when it is `script`. |
| `script` | string | no | The words to speak, at most 900 characters, with contact `{tokens}` filled in for each contact. Required when `wordsMode` is `script`, and must be empty when it is `ken_writes`. |
| `model` | string | no | The model Ken writes with: `haiku` or `sonnet`. Null or blank means `haiku`. |
| `matchLeadLanguage` | boolean | no | When true, the note is spoken in the contact's outreach language when Kenso knows it. |

### VoiceNotePreview

One contact's preview.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactId` | integer (int64) | no | The contact the note was made for. |
| `voiceNote` | VoiceNoteRef | no | The note: `ready` with an `audioUrl` to play, or `failed` with a `failureReason`. |

### VoiceNoteRef

A LinkedIn voice note on a message, touch or account activity. `audioUrl` is an API route that redirects to a short-lived link to the audio, and is set only while Kenso keeps the audio.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceNoteId` | integer (int64) | no | The voice note's id. 0 for a voice note a contact sent. |
| `status` | string | no | `pending`, `generating`, `ready`, `sent`, `failed` or `expired`. On a thread message, a contact's note reads `received`. |
| `durationMs` | integer (int32) | no | The audio's length in milliseconds. Null until known. |
| `language` | string | no | The language of the script. Null when unknown. |
| `provider` | string | no | The voice service that made the audio. Null when unknown. |
| `voiceId` | string | no | The voice used for the audio. Null when unknown. |
| `scriptText` | string | no | The words spoken. Null until generated, and left out of list reads. |
| `failureReason` | string | no | Why the voice note failed. Null unless status is `failed`. |
| `audioAvailable` | boolean | no | True while Kenso keeps the audio. |
| `audioUrl` | string | no | The API route that serves the audio. Null when the audio is gone. |
