# Activities
Source: https://docs.clarky.ai/api-reference/activities

Log notes, calls, meetings, tasks, and reminders against contacts and companies

Activities are the timeline of CRM events on a contact or company — notes you took, calls you had, meetings you scheduled, tasks you owe, and reminders you set. The API exposes a read endpoint for a contact's activity timeline and a write endpoint to log new activities.

## The Activity object

<ResponseField name="id" type="string" />

<ResponseField name="contact_id" type="string | null">
  The contact this activity is logged against. Either `contact_id` or `company_id` is set.
</ResponseField>

<ResponseField name="company_id" type="string | null">
  The company this activity is logged against. Either `contact_id` or `company_id` is set.
</ResponseField>

<ResponseField name="activity_type" type="string">
  One of `note`, `call`, `meeting`, `video_call`, `task`, `todo`, `reminder`.
</ResponseField>

<ResponseField name="title" type="string | null" />

<ResponseField name="description" type="string | null" />

<ResponseField name="due_date" type="string | null">
  ISO 8601 timestamp. Used for `task`, `todo`, and `reminder` activities.
</ResponseField>

<ResponseField name="duration_minutes" type="number | null">
  Duration in minutes. Useful for `call`, `meeting`, and `video_call`.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  ISO 8601 timestamp marking the activity as done.
</ResponseField>

<ResponseField name="metadata" type="object">
  Free-form JSON for extra context (call recording URL, meeting attendees, etc.).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

## Activity types

| Type         | Use for                                               |
| ------------ | ----------------------------------------------------- |
| `note`       | Free-form notes recorded against a contact or company |
| `call`       | Phone calls made or received                          |
| `meeting`    | In-person or scheduled meetings                       |
| `video_call` | Zoom, Google Meet, etc.                               |
| `task`       | Work to be done, typically with a `due_date`          |
| `todo`       | Lightweight checklist items                           |
| `reminder`   | Time-based prompts to follow up                       |

<Tip>
  For more on how Clarky's CRM uses activities, see the [CRM Activity feature docs](/features/crm/activity).
</Tip>

***

## List a contact's activities

<ParamField type="GET">
  `GET /api/v1/contacts/{contact_id}/activities`
</ParamField>

Returns a paginated, reverse-chronological timeline of activities on a single contact.

### Query parameters

| Param           | Type    | Description                                            |
| --------------- | ------- | ------------------------------------------------------ |
| `activity_type` | string  | Filter to a single activity type (e.g. `note`, `call`) |
| `page`          | integer | See [Pagination](/api-reference/pagination)            |
| `page_size`     | integer | See [Pagination](/api-reference/pagination)            |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts/c_01HXYZ/activities?activity_type=call" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "a_01HACT...",
      "contact_id": "c_01HXYZ...",
      "company_id": null,
      "activity_type": "call",
      "title": "Discovery call",
      "description": "Walked through the platform, customer is interested in the Pro plan.",
      "due_date": null,
      "duration_minutes": 32,
      "completed_at": "2026-04-29T15:30:00.000Z",
      "metadata": { "outcome": "qualified" },
      "created_at": "2026-04-29T15:31:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Log an activity

<ParamField type="POST">
  `POST /api/v1/activities`
</ParamField>

Requires a key with the `write` scope. Each activity must be linked to **either** a `contact_id` **or** a `company_id` (you can pass both, but at least one is required).

### Body fields

| Field              | Type              | Required    | Description                                                                |
| ------------------ | ----------------- | ----------- | -------------------------------------------------------------------------- |
| `activity_type`    | string            | Yes         | One of `note`, `call`, `meeting`, `video_call`, `task`, `todo`, `reminder` |
| `contact_id`       | string            | Conditional | Required unless `company_id` is provided                                   |
| `company_id`       | string            | Conditional | Required unless `contact_id` is provided                                   |
| `title`            | string            | No          |                                                                            |
| `description`      | string            | No          |                                                                            |
| `due_date`         | string (ISO 8601) | No          | Useful for `task`, `todo`, `reminder`                                      |
| `duration_minutes` | number            | No          | Useful for `call`, `meeting`, `video_call`                                 |
| `completed_at`     | string (ISO 8601) | No          | Mark the activity as already done                                          |
| `metadata`         | object            | No          | Free-form JSON                                                             |

### Example: log a note

```bash theme={null}
curl https://clarky.ai/api/v1/activities \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "note",
    "contact_id": "c_01HXYZ",
    "title": "Follow-up needed",
    "description": "Customer asked about migration help next quarter."
  }'
```

```json theme={null}
{
  "data": {
    "id": "a_01HACT...",
    "contact_id": "c_01HXYZ...",
    "company_id": null,
    "activity_type": "note",
    "title": "Follow-up needed",
    "description": "Customer asked about migration help next quarter.",
    "due_date": null,
    "duration_minutes": null,
    "completed_at": null,
    "metadata": {},
    "created_at": "2026-04-29T19:25:00.000Z"
  }
}
```

### Example: schedule a task

```bash theme={null}
curl https://clarky.ai/api/v1/activities \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "task",
    "contact_id": "c_01HXYZ",
    "title": "Send follow-up proposal",
    "due_date": "2026-05-06T17:00:00.000Z"
  }'
```

```json theme={null}
{
  "data": {
    "id": "a_01HACT...",
    "contact_id": "c_01HXYZ...",
    "activity_type": "task",
    "title": "Send follow-up proposal",
    "due_date": "2026-05-06T17:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-04-29T19:26:00.000Z"
  }
}
```


# Agents
Source: https://docs.clarky.ai/api-reference/agents

Discover the agents in your workspace and their channel configuration

Agents are the AI assistants in your workspace — every contact, conversation, form, and pipeline lives under one. The Agents API is a **read-only** discovery endpoint: use it to list the agents in a workspace and look up the IDs you'll pass as `bot_id` to the rest of the API.

<Tip>
  Most resources in the API (contacts, companies, forms, pipelines, conversations) are scoped by `bot_id`. If you don't already have one, list agents first and pick the right `id`.
</Tip>

## The Agent object

<ResponseField name="id" type="string">
  Unique agent identifier — pass this as `bot_id` to other endpoints.
</ResponseField>

<ResponseField name="workspace_id" type="string">
  The workspace this agent belongs to.
</ResponseField>

<ResponseField name="name" type="string | null">
  Human-readable agent name.
</ResponseField>

<ResponseField name="slug" type="string | null">
  URL-safe handle used in dashboard links (`/admin/{workspace}/{slug}`).
</ResponseField>

<ResponseField name="summary" type="string | null">
  One-line description of what this agent does.
</ResponseField>

<ResponseField name="is_agent" type="boolean">
  `true` for next-gen agents (`/admin/{workspace}/agents`). Some legacy bots may have `is_agent=false` — they're still valid `bot_id` targets for the rest of the API.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  `false` if the agent has been disabled by an admin.
</ResponseField>

<ResponseField name="public" type="boolean">
  `true` if the agent's chat embed is allowed on public sites.
</ResponseField>

<ResponseField name="agent_role" type="string | null">
  Role string (e.g. `"sales"`, `"support"`).
</ResponseField>

<ResponseField name="agent_type" type="string | null">
  One of `internal`, `external`, or `both`.
</ResponseField>

<ResponseField name="agent_status" type="string | null" />

<ResponseField name="agent_color" type="string | null">
  Brand color used in the dashboard / inbox.
</ResponseField>

<ResponseField name="agent_email" type="string | null">
  Auto-provisioned inbound email address (e.g. `b_01HDEF@inbound.clarky.ai`).
</ResponseField>

<ResponseField name="agent_phone" type="string | null">
  Provisioned voice / SMS phone number, when one is attached.
</ResponseField>

<ResponseField name="chat_greeting" type="string | null">
  Opening message shown in the chat widget.
</ResponseField>

<ResponseField name="chat_avatar_intro" type="string | null">
  Speech bubble shown next to the avatar before the user opens the widget.
</ResponseField>

<ResponseField name="chat_avatar_image_url" type="string | null" />

<ResponseField name="phone_greeting" type="string | null">
  Spoken greeting on inbound calls.
</ResponseField>

<ResponseField name="phone_voice_id" type="string | null">
  ID of the TTS voice used for outbound speech.
</ResponseField>

<ResponseField name="text_greeting" type="string | null">
  Auto-reply for first SMS contact.
</ResponseField>

<ResponseField name="email_inbound" type="boolean | null">
  `true` if inbound emails to `agent_email` are processed.
</ResponseField>

<ResponseField name="email_outbound_autoreply" type="boolean | null" />

<ResponseField name="email_outbound_email" type="string | null">
  "From" address used for outbound emails.
</ResponseField>

<ResponseField name="email_outbound_name" type="string | null">
  "From" name used for outbound emails.
</ResponseField>

<ResponseField name="booking_provider" type="string | null">
  Booking integration in use — `clarky`, `calcom`, `google`, etc. `null` if booking isn't enabled.
</ResponseField>

<ResponseField name="enabled_event_type_ids" type="string[] | null">
  IDs of [Event Types](/features/booking/event-types) this agent can offer when scheduling.
</ResponseField>

<ResponseField name="allow_human_takeover" type="boolean">
  `true` if teammates can take over conversations from this agent.
</ResponseField>

<ResponseField name="escalation_detection_enabled" type="boolean">
  `true` if Clarky should auto-flag conversations that need a human.
</ResponseField>

<ResponseField name="sentiment_analysis_enabled" type="boolean">
  `true` if conversations are analyzed for sentiment.
</ResponseField>

<ResponseField name="knowledge_count" type="number">
  Approximate number of [context documents](/features/context/overview) attached to this agent.
</ResponseField>

<ResponseField name="number_of_conversations" type="number">
  Lifetime conversation count.
</ResponseField>

<ResponseField name="popular_topics" type="string[] | null">
  Recent top topics extracted from this agent's conversations.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<Note>
  We deliberately omit secrets (Slack tokens, Resend API keys), system prompts (`internal_personality`, `external_personality`, `custom_escalation_prompt`), and internal RAG tuning knobs (`match_threshold`, `match_count`) from this response. Manage those in the dashboard.
</Note>

***

## List agents

<ParamField type="GET">
  `GET /api/v1/agents`
</ParamField>

Returns a paginated list of every agent in the workspace.

### Query parameters

| Param        | Type    | Description                                 |
| ------------ | ------- | ------------------------------------------- |
| `search`     | string  | Match against name, slug, or summary        |
| `slug`       | string  | Exact-match agent slug                      |
| `is_agent`   | boolean | Filter to next-gen agents only              |
| `enabled`    | boolean | Filter by enabled state                     |
| `agent_type` | string  | One of `internal`, `external`, `both`       |
| `page`       | integer | See [Pagination](/api-reference/pagination) |
| `page_size`  | integer | See [Pagination](/api-reference/pagination) |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/agents?enabled=true" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "b_01HDEF...",
      "workspace_id": "w_01HXXX...",
      "name": "Clarky Sales",
      "slug": "sales",
      "summary": "Outbound + inbound sales agent for the marketing site.",
      "is_agent": true,
      "enabled": true,
      "public": true,
      "agent_role": "sales",
      "agent_type": "external",
      "agent_status": "live",
      "agent_color": "#0586ff",
      "agent_email": "b_01HDEF@inbound.clarky.ai",
      "agent_phone": "+15125550100",
      "chat_greeting": "Hey! What can I help you with today?",
      "chat_avatar_intro": "Got questions? Ask me anything.",
      "chat_avatar_image_url": null,
      "phone_greeting": "Hi, this is Clarky's sales agent — how can I help?",
      "phone_voice_id": "elv_voice_andy",
      "text_greeting": "Thanks for texting! What's up?",
      "email_inbound": true,
      "email_outbound_autoreply": true,
      "email_outbound_email": "sales@example.com",
      "email_outbound_name": "Clarky Sales",
      "booking_provider": "clarky",
      "enabled_event_type_ids": ["et_01HABC..."],
      "allow_human_takeover": true,
      "escalation_detection_enabled": true,
      "sentiment_analysis_enabled": true,
      "knowledge_count": 184,
      "number_of_conversations": 5421,
      "popular_topics": ["pricing", "demo", "integrations"],
      "created_at": "2026-01-12T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get an agent

<ParamField type="GET">
  `GET /api/v1/agents/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/agents/b_01HDEF \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "b_01HDEF...",
    "name": "Clarky Sales",
    "slug": "sales",
    "is_agent": true,
    "enabled": true,
    "agent_email": "b_01HDEF@inbound.clarky.ai",
    "agent_phone": "+15125550100",
    "booking_provider": "clarky",
    "knowledge_count": 184,
    "number_of_conversations": 5421,
    "created_at": "2026-01-12T10:00:00.000Z"
  }
}
```

***

## Common patterns

### Resolve an agent by slug

The dashboard URL `https://clarky.ai/admin/{workspace}/{slug}` exposes each agent's slug. Use it to look up the canonical `id`:

```bash theme={null}
curl "https://clarky.ai/api/v1/agents?slug=sales" \
  -H "Authorization: Bearer ck_live_example"
```

### Bootstrap an integration

A first-run flow for a new integration:

```bash theme={null}
# 1. List agents to let the user pick one.
curl https://clarky.ai/api/v1/agents \
  -H "Authorization: Bearer ck_live_example"

# 2. Use the chosen id as bot_id everywhere else.
curl -X POST https://clarky.ai/api/v1/contacts \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "b_01HDEF", "first_name": "Ada", "emails": [{ "email": "ada@example.com" }] }'
```


# Authentication
Source: https://docs.clarky.ai/api-reference/authentication

Authenticate API requests with workspace-scoped Bearer tokens

The Clarky API uses **Bearer token** authentication. Every request must include an `Authorization` header containing a valid API key.

```bash theme={null}
Authorization: Bearer ck_live_example
```

Requests without a valid key — or with a key that has been revoked — return `401 Unauthorized`.

<Info>
  **Plan availability:** Creating API keys requires a **Standard**, **Pro**, or **Enterprise** plan. See [Plans & Billing](/features/settings/plans).
</Info>

## Creating an API key

<Steps>
  <Step title="Open Workspace Settings">
    Go to **Settings > API Keys** (under the Workspace Settings section).
  </Step>

  <Step title="Click 'Create API Key'">
    Give the key a descriptive name — for example, "Production data warehouse" or "Zapier sync" — so it's easy to identify later.
  </Step>

  <Step title="Choose the scopes">
    Select **read**, **write**, or both. A key without `write` cannot create, update, or delete records.
  </Step>

  <Step title="Copy the key immediately">
    The full key is shown **only once**, right after you create it. Store it in a secure secret manager. If you lose it, revoke the key and create a new one.
  </Step>
</Steps>

## Key format

Every Clarky API key follows the same shape:

```
ck_live_<random>
```

Keys are 38–39 characters total and prefixed with `ck_live_` so they're easy to recognize in logs and source control scans.

## Workspace scope

Every key is bound to **exactly one workspace**. The workspace is determined by which workspace you were viewing when the key was created. A key cannot be transferred across workspaces — to access a different workspace, create a new key from inside that workspace.

## Scopes

Scopes are selected when the key is created. Two scopes are currently available:

<ResponseField name="read" type="scope">
  Allows `GET` and `HEAD` requests on every endpoint.
</ResponseField>

<ResponseField name="write" type="scope">
  Allows `POST`, `PATCH`, and `DELETE` requests in addition to reads. A request that requires `write` made with a read-only key returns `403 Forbidden` with code `forbidden`.
</ResponseField>

<Tip>
  For backend services that only need to push data into Clarky (for example, a lead-capture form on a marketing site), grant **write** only. For analytics workloads that pull data into a warehouse, grant **read** only. Use the principle of least privilege.
</Tip>

## Sending the header

<CodeGroup>
  ```bash curl theme={null}
  curl https://clarky.ai/api/v1/contacts \
    -H "Authorization: Bearer ck_live_example"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://clarky.ai/api/v1/contacts", {
    headers: {
      Authorization: `Bearer ${process.env.CLARKY_API_KEY}`,
    },
  });
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      "https://clarky.ai/api/v1/contacts",
      headers={"Authorization": f"Bearer {os.environ['CLARKY_API_KEY']}"}
  )
  ```
</CodeGroup>

## Rotating keys

To rotate a key without downtime:

<Steps>
  <Step title="Create a new key">
    Create a fresh key with the same scopes from **Settings > API Keys**.
  </Step>

  <Step title="Roll it out">
    Update your application's secret store and deploy. Verify the new key is working in production.
  </Step>

  <Step title="Revoke the old key">
    Once nothing depends on the old key, revoke it from the API Keys list. Revocation takes effect immediately.
  </Step>
</Steps>

## Revoking a key

You can revoke any key at any time from **Settings > API Keys**. Revocation is **immediate and permanent** — every subsequent request using that key will return `401 Unauthorized`. The key cannot be re-enabled.

<Warning>
  If a key is leaked — committed to a public repo, posted in a Slack message, or pasted into a screenshot — revoke it immediately and create a new one. There's no way to "expire" a leaked key while keeping it usable.
</Warning>

## Security best practices

* **Never commit keys to source control.** Use a secret manager (AWS Secrets Manager, GCP Secret Manager, Doppler, 1Password, etc.) and load them at runtime.
* **Use environment variables** for local development — never hardcode keys.
* **Restrict by scope.** A read-only key cannot accidentally delete data even if it's compromised.
* **Use one key per integration** so you can rotate or revoke them independently.
* **Audit regularly.** Review your API key list quarterly and delete any that are no longer in use.
* **Don't expose keys client-side.** API keys must only ever be used from a trusted backend. They should never be embedded in browser JavaScript, mobile apps, or anywhere an end user could read them.

<Check>
  You're authenticated and ready to make requests. Continue to [Errors](/api-reference/errors) to learn the error envelope, or jump straight to [Contacts](/api-reference/contacts).
</Check>


# Companies
Source: https://docs.clarky.ai/api-reference/companies

Manage companies and the contacts that belong to them

Companies represent organizations in your CRM — typically the employers, customers, or accounts that your contacts belong to. Each company is owned by a specific agent (`bot_id`) and inherits the workspace from your API key.

## The Company object

<ResponseField name="id" type="string">
  Unique company identifier.
</ResponseField>

<ResponseField name="workspace_id" type="string" />

<ResponseField name="bot_id" type="string">
  The agent that owns this company.
</ResponseField>

<ResponseField name="name" type="string">
  Company name.
</ResponseField>

<ResponseField name="domain" type="string | null">
  Primary domain (e.g. `acme.com`).
</ResponseField>

<ResponseField name="website" type="string | null" />

<ResponseField name="industry" type="string | null" />

<ResponseField name="company_size" type="string | null">
  Free-form size band (e.g. `"50-200"`).
</ResponseField>

<ResponseField name="company_type" type="string | null" />

<ResponseField name="employee_count" type="number | null" />

<ResponseField name="annual_revenue" type="number | null" />

<ResponseField name="description" type="string | null" />

<ResponseField name="emails" type="array">
  Array of `{ email, is_primary }` objects.
</ResponseField>

<ResponseField name="phone_numbers" type="array">
  Array of `{ phone_number, is_primary }` objects.
</ResponseField>

<ResponseField name="tags" type="string[]" />

<ResponseField name="total_deal_value" type="number | null">
  Sum of `deal_value` across all contacts linked to this company.
</ResponseField>

<ResponseField name="pipeline_stage_id" type="string | null" />

<ResponseField name="address_line1" type="string | null" />

<ResponseField name="address_line2" type="string | null" />

<ResponseField name="city" type="string | null" />

<ResponseField name="state" type="string | null" />

<ResponseField name="postal_code" type="string | null" />

<ResponseField name="country" type="string | null" />

<ResponseField name="linkedin_url" type="string | null" />

<ResponseField name="notes" type="string | null" />

<ResponseField name="custom_fields" type="object" />

<ResponseField name="last_activity_at" type="string | null">
  ISO 8601 timestamp of the most recent activity on a related contact.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## List companies

<ParamField type="GET">
  `GET /api/v1/companies`
</ParamField>

Paginated list of companies in the workspace.

### Query parameters

| Param       | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `search`    | string  | Match against name, domain, or industry         |
| `tags`      | string  | Comma-separated list of tags                    |
| `industry`  | string  | Exact-match industry filter                     |
| `domain`    | string  | Exact-match domain filter                       |
| `bot_id`    | string  | Restrict to companies owned by a specific agent |
| `page`      | integer | See [Pagination](/api-reference/pagination)     |
| `page_size` | integer | See [Pagination](/api-reference/pagination)     |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/companies?search=acme" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "co_01HABC...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Acme Corp",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Manufacturing",
      "company_size": "200-500",
      "employee_count": 320,
      "annual_revenue": 18000000,
      "emails": [{ "email": "hello@acme.com", "is_primary": true }],
      "phone_numbers": [],
      "tags": ["enterprise"],
      "total_deal_value": 125000,
      "pipeline_stage_id": null,
      "city": "Austin",
      "country": "US",
      "custom_fields": {},
      "last_activity_at": "2026-04-28T13:14:00.000Z",
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-04-28T13:14:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get a company

<ParamField type="GET">
  `GET /api/v1/companies/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"],
    "total_deal_value": 125000,
    "created_at": "2026-03-01T10:00:00.000Z",
    "updated_at": "2026-04-28T13:14:00.000Z"
  }
}
```

***

## Create a company

<ParamField type="POST">
  `POST /api/v1/companies`
</ParamField>

Requires a key with the `write` scope.

### Body fields

| Field               | Type      | Required | Description                             |
| ------------------- | --------- | -------- | --------------------------------------- |
| `bot_id`            | string    | Yes      | Owning agent                            |
| `name`              | string    | Yes      | Company name                            |
| `domain`            | string    | No       |                                         |
| `website`           | string    | No       |                                         |
| `industry`          | string    | No       |                                         |
| `company_size`      | string    | No       |                                         |
| `company_type`      | string    | No       |                                         |
| `employee_count`    | number    | No       |                                         |
| `annual_revenue`    | number    | No       |                                         |
| `description`       | string    | No       |                                         |
| `emails`            | array     | No       | Array of `{ email, is_primary }`        |
| `phone_numbers`     | array     | No       | Array of `{ phone_number, is_primary }` |
| `tags`              | string\[] | No       |                                         |
| `pipeline_stage_id` | string    | No       |                                         |
| `address_line1`     | string    | No       |                                         |
| `address_line2`     | string    | No       |                                         |
| `city`              | string    | No       |                                         |
| `state`             | string    | No       |                                         |
| `postal_code`       | string    | No       |                                         |
| `country`           | string    | No       |                                         |
| `linkedin_url`      | string    | No       |                                         |
| `notes`             | string    | No       |                                         |
| `custom_fields`     | object    | No       |                                         |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/companies \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "b_01HDEF",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "tags": ["enterprise"],
    "created_at": "2026-04-29T18:55:00.000Z",
    "updated_at": "2026-04-29T18:55:00.000Z"
  }
}
```

***

## Update a company

<ParamField type="PATCH">
  `PATCH /api/v1/companies/{id}`
</ParamField>

Same fields as [Create a company](#create-a-company). `bot_id` cannot be changed.

### Example

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "annual_revenue": 24000000, "tags": ["enterprise", "expansion"] }'
```

```json theme={null}
{
  "data": {
    "id": "co_01HABC...",
    "annual_revenue": 24000000,
    "tags": ["enterprise", "expansion"],
    "updated_at": "2026-04-29T19:01:00.000Z"
  }
}
```

***

## Delete a company

<ParamField type="DELETE">
  `DELETE /api/v1/companies/{id}`
</ParamField>

Returns `204 No Content` with an empty body on success.

### Example

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/companies/co_01HABC \
  -H "Authorization: Bearer ck_live_example"
```

<Warning>
  Deletion is permanent. Contacts that referenced this company will have their `company_id` cleared but will not themselves be deleted.
</Warning>


# Contacts
Source: https://docs.clarky.ai/api-reference/contacts

Create, read, update, delete, and bulk upsert contacts

Contacts represent the people in your CRM — leads, customers, prospects, and anyone else captured by your agents or imported from another system. Every contact belongs to a specific agent (`bot_id`) and inherits the workspace from your API key.

## The Contact object

<ResponseField name="id" type="string">
  Unique contact identifier.
</ResponseField>

<ResponseField name="workspace_id" type="string">
  The workspace this contact belongs to.
</ResponseField>

<ResponseField name="bot_id" type="string">
  The agent that owns this contact.
</ResponseField>

<ResponseField name="first_name" type="string | null" />

<ResponseField name="last_name" type="string | null" />

<ResponseField name="emails" type="array">
  Array of `{ email, is_primary }` objects. The first item is treated as primary if no `is_primary` flag is set.
</ResponseField>

<ResponseField name="phone_numbers" type="array">
  Array of `{ phone_number, is_primary }` objects.
</ResponseField>

<ResponseField name="company" type="string | null">
  Free-text company name. Use `company_id` to link to a structured Company record.
</ResponseField>

<ResponseField name="company_id" type="string | null">
  Foreign key to a [Company](/api-reference/companies).
</ResponseField>

<ResponseField name="job_title" type="string | null" />

<ResponseField name="lead_source" type="string | null" />

<ResponseField name="tags" type="string[]" />

<ResponseField name="deal_value" type="number | null">
  Estimated deal value as a number (currency assumed to match workspace settings).
</ResponseField>

<ResponseField name="pipeline_stage_id" type="string | null">
  Current stage in a sales pipeline.
</ResponseField>

<ResponseField name="contact_type" type="string | null">
  Free-form classification (e.g. `"lead"`, `"customer"`).
</ResponseField>

<ResponseField name="address_line1" type="string | null" />

<ResponseField name="address_line2" type="string | null" />

<ResponseField name="city" type="string | null" />

<ResponseField name="state" type="string | null" />

<ResponseField name="postal_code" type="string | null" />

<ResponseField name="country" type="string | null" />

<ResponseField name="linkedin_url" type="string | null" />

<ResponseField name="notes" type="string | null" />

<ResponseField name="custom_fields" type="object">
  Workspace-defined custom fields, stored as a free-form JSON object.
</ResponseField>

<ResponseField name="last_contacted_at" type="string | null">
  ISO 8601 timestamp of the most recent activity.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## List contacts

<ParamField type="GET">
  `GET /api/v1/contacts`
</ParamField>

Returns a paginated list of contacts in the workspace.

### Query parameters

| Param               | Type              | Description                                     |
| ------------------- | ----------------- | ----------------------------------------------- |
| `search`            | string            | Match against name, email, phone, or company    |
| `tags`              | string            | Comma-separated list of tags to filter by       |
| `lead_source`       | string            | Filter by lead source                           |
| `pipeline_stage_id` | string            | Filter to contacts in a specific pipeline stage |
| `bot_id`            | string            | Filter to contacts owned by a specific agent    |
| `created_after`     | string (ISO 8601) | Created at or after this timestamp              |
| `created_before`    | string (ISO 8601) | Created at or before this timestamp             |
| `updated_after`     | string (ISO 8601) | Updated at or after this timestamp              |
| `page`              | integer           | See [Pagination](/api-reference/pagination)     |
| `page_size`         | integer           | See [Pagination](/api-reference/pagination)     |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts?search=ada&page_size=10" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "c_01HXYZ...",
      "workspace_id": "w_01HABC...",
      "bot_id": "b_01HDEF...",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "emails": [{ "email": "ada@example.com", "is_primary": true }],
      "phone_numbers": [],
      "company": "Analytical Engines Inc.",
      "company_id": null,
      "job_title": "Founder",
      "lead_source": "website",
      "tags": ["vip"],
      "deal_value": 25000,
      "pipeline_stage_id": "ps_01HGHI...",
      "contact_type": "lead",
      "address_line1": null,
      "address_line2": null,
      "city": "London",
      "state": null,
      "postal_code": null,
      "country": "UK",
      "linkedin_url": null,
      "notes": null,
      "custom_fields": {},
      "last_contacted_at": "2026-04-29T14:00:00.000Z",
      "created_at": "2026-04-12T09:30:00.000Z",
      "updated_at": "2026-04-29T14:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 10, "total": 1, "total_pages": 1 }
}
```

***

## Get contact by email

<ParamField type="GET">
  `GET /api/v1/contacts/by-email`
</ParamField>

Looks up a single contact by primary email address. Returns `404 not_found` if no contact matches.

### Query parameters

| Param   | Type   | Required | Description                       |
| ------- | ------ | -------- | --------------------------------- |
| `email` | string | Yes      | Email to match (case-insensitive) |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts/by-email?email=ada@example.com" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "emails": [{ "email": "ada@example.com", "is_primary": true }],
    "phone_numbers": [],
    "company": "Analytical Engines Inc.",
    "tags": ["vip"],
    "created_at": "2026-04-12T09:30:00.000Z",
    "updated_at": "2026-04-29T14:00:00.000Z"
  }
}
```

***

## Get a contact

<ParamField type="GET">
  `GET /api/v1/contacts/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/contacts/c_01HXYZ \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "emails": [{ "email": "ada@example.com", "is_primary": true }],
    "phone_numbers": [],
    "tags": ["vip"],
    "created_at": "2026-04-12T09:30:00.000Z",
    "updated_at": "2026-04-29T14:00:00.000Z"
  }
}
```

***

## Create a contact

<ParamField type="POST">
  `POST /api/v1/contacts`
</ParamField>

Requires a key with the `write` scope.

### Body fields

| Field               | Type      | Required | Description                             |
| ------------------- | --------- | -------- | --------------------------------------- |
| `bot_id`            | string    | Yes      | Agent that should own this contact      |
| `first_name`        | string    | No       |                                         |
| `last_name`         | string    | No       |                                         |
| `emails`            | array     | No       | Array of `{ email, is_primary }`        |
| `phone_numbers`     | array     | No       | Array of `{ phone_number, is_primary }` |
| `company`           | string    | No       | Free-text company name                  |
| `company_id`        | string    | No       | Link to an existing Company             |
| `job_title`         | string    | No       |                                         |
| `lead_source`       | string    | No       |                                         |
| `tags`              | string\[] | No       |                                         |
| `deal_value`        | number    | No       |                                         |
| `pipeline_stage_id` | string    | No       |                                         |
| `contact_type`      | string    | No       |                                         |
| `address_line1`     | string    | No       |                                         |
| `address_line2`     | string    | No       |                                         |
| `city`              | string    | No       |                                         |
| `state`             | string    | No       |                                         |
| `postal_code`       | string    | No       |                                         |
| `country`           | string    | No       |                                         |
| `linkedin_url`      | string    | No       |                                         |
| `notes`             | string    | No       |                                         |
| `custom_fields`     | object    | No       |                                         |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/contacts \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "b_01HDEF",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "emails": [{ "email": "ada@example.com", "is_primary": true }],
    "company": "Analytical Engines Inc.",
    "tags": ["vip"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "emails": [{ "email": "ada@example.com", "is_primary": true }],
    "company": "Analytical Engines Inc.",
    "tags": ["vip"],
    "created_at": "2026-04-29T18:42:00.000Z",
    "updated_at": "2026-04-29T18:42:00.000Z"
  }
}
```

***

## Update a contact

<ParamField type="PATCH">
  `PATCH /api/v1/contacts/{id}`
</ParamField>

Updates the listed fields and leaves everything else untouched. Same fields as [Create a contact](#create-a-contact), **except** `bot_id` cannot be changed.

### Example

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/contacts/c_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "newsletter"],
    "deal_value": 30000
  }'
```

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "tags": ["vip", "newsletter"],
    "deal_value": 30000,
    "updated_at": "2026-04-29T18:50:00.000Z"
  }
}
```

***

## Delete a contact

<ParamField type="DELETE">
  `DELETE /api/v1/contacts/{id}`
</ParamField>

Returns `204 No Content` with an empty body on success.

### Example

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/contacts/c_01HXYZ \
  -H "Authorization: Bearer ck_live_example"
```

<Warning>
  Deletion is permanent — there's no undo.
</Warning>

***

## Bulk upsert contacts

<ParamField type="POST">
  `POST /api/v1/contacts/upsert`
</ParamField>

Insert or update up to **200 contacts** in a single request. Each input contact is matched against existing contacts in this order:

1. Primary email (if provided)
2. Primary phone number (if no email match)

If a match is found, the existing contact is updated. If not, a new contact is created.

### Body fields

| Field      | Type   | Required | Description                                                                     |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `bot_id`   | string | Yes      | Agent to own newly created contacts                                             |
| `contacts` | array  | Yes      | Array of contact objects (same fields as [Create](#create-a-contact)). Max 200. |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/contacts/upsert \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "b_01HDEF",
    "contacts": [
      {
        "first_name": "Ada",
        "emails": [{ "email": "ada@example.com", "is_primary": true }]
      },
      {
        "first_name": "Grace",
        "emails": [{ "email": "grace@example.com", "is_primary": true }]
      }
    ]
  }'
```

### Response

```json theme={null}
{
  "data": {
    "created": [
      {
        "id": "c_01HNEW1...",
        "first_name": "Grace",
        "emails": [{ "email": "grace@example.com", "is_primary": true }]
      }
    ],
    "updated": [
      {
        "id": "c_01HXYZ...",
        "first_name": "Ada",
        "emails": [{ "email": "ada@example.com", "is_primary": true }]
      }
    ],
    "errors": []
  }
}
```

<ResponseField name="created" type="Contact[]">
  Contacts that were newly inserted.
</ResponseField>

<ResponseField name="updated" type="Contact[]">
  Contacts that matched an existing record and were updated.
</ResponseField>

<ResponseField name="errors" type="array">
  Per-row failures as `{ index, message }`. The numeric `index` is the position of the failing item in the input `contacts` array. The rest of the batch still succeeds.
</ResponseField>

<Tip>
  Upsert counts as a single write against your [rate limit](/api-reference/rate-limits) regardless of how many contacts are in the batch — much more efficient than a loop of `POST /contacts` calls.
</Tip>


# Conversations
Source: https://docs.clarky.ai/api-reference/conversations

Read, manage, and clean up conversations and messages across every channel — chat, voice, text, email, and forms

Conversations capture every back-and-forth your agents have with people — chat sessions on your site, phone calls, SMS threads, inbound emails, and form submissions. Each conversation belongs to an agent (`bot_id`) and may be linked to a [Contact](/api-reference/contacts) and/or an anonymous [Visitor](/features/traffic/visitors).

You can read transcripts, update inbox state (assignment, archive, takeover, internal notes), and soft-delete conversations from the API. Creating conversations is **not** supported — they originate from real channel events (the chat widget, voice/SMS webhooks, inbound email, form submissions) so that routing, billing, and analytics stay accurate.

<Tip>
  Looking for the full transcript of a single conversation? Fetch the conversation, then call [List messages](#list-messages-in-a-conversation) with `order=asc`.
</Tip>

## The Conversation object

<ResponseField name="id" type="string">
  Unique conversation identifier.
</ResponseField>

<ResponseField name="bot_id" type="string">
  The agent this conversation belongs to.
</ResponseField>

<ResponseField name="contact_id" type="string | null">
  The CRM contact linked to this conversation, if one has been resolved.
</ResponseField>

<ResponseField name="type" type="integer">
  Channel the conversation happened on. See [Conversation types](#conversation-types) below.
</ResponseField>

<ResponseField name="email" type="string | null">
  Best-known email for the participant (may be `null` for anonymous chats).
</ResponseField>

<ResponseField name="phone_number" type="string | null">
  E.164 phone number for the participant on voice / text conversations.
</ResponseField>

<ResponseField name="human" type="string | null">
  Display name of the human, when known.
</ResponseField>

<ResponseField name="human_takeover" type="boolean">
  `true` when a human teammate has taken over the conversation from the agent.
</ResponseField>

<ResponseField name="assigned_to" type="string | null">
  User ID of the teammate the conversation is assigned to.
</ResponseField>

<ResponseField name="assigned_at" type="string | null">
  ISO 8601 timestamp of the most recent assignment.
</ResponseField>

<ResponseField name="active" type="boolean">
  `true` while the conversation is in progress; flips to `false` after a period of inactivity.
</ResponseField>

<ResponseField name="archived" type="boolean | null" />

<ResponseField name="archived_at" type="string | null" />

<ResponseField name="deleted" type="boolean | null">
  Soft-delete flag. Deleted conversations are excluded from list responses unless you pass `include_deleted=true`.
</ResponseField>

<ResponseField name="deleted_at" type="string | null" />

<ResponseField name="internal" type="boolean">
  `true` for conversations between teammates (e.g. asking your internal agent), `false` for customer-facing conversations.
</ResponseField>

<ResponseField name="internal_notes" type="string | null">
  Free-text notes added by your team. Never shared with the participant.
</ResponseField>

<ResponseField name="last_message" type="string | null">
  Snippet of the most recent message — useful for inbox-style list views.
</ResponseField>

<ResponseField name="last_message_at" type="string | null">
  ISO 8601 timestamp of the most recent message.
</ResponseField>

<ResponseField name="last_active_at" type="string | null">
  ISO 8601 timestamp of the participant's most recent activity (typing, page change, etc.).
</ResponseField>

<ResponseField name="sentiment_positive" type="boolean | null">
  `true` if Clarky's sentiment analysis judged the conversation as net-positive, `false` if negative, `null` if not yet analyzed.
</ResponseField>

<ResponseField name="sentiment_score" type="number | null">
  Sentiment score in the range `[-1, 1]`.
</ResponseField>

<ResponseField name="sentiment_summary" type="string | null">
  One-sentence summary of the participant's mood and intent.
</ResponseField>

<ResponseField name="audio_url" type="string | null">
  Storage path for the call recording on voice conversations. Use the dashboard or a workspace-authenticated session to download.
</ResponseField>

<ResponseField name="minutes" type="number | null">
  Duration of voice / phone calls, in minutes.
</ResponseField>

<ResponseField name="visitor_id" type="string | null">
  Linked anonymous [Visitor](/features/traffic/visitors), when the conversation came from an unauthenticated chat.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

### Conversation types

The `type` field is a numeric ID. The list endpoint also accepts the names below as a convenience.

| `type` | Name                         | Channel                         |
| ------ | ---------------------------- | ------------------------------- |
| `1`    | `chat`                       | Web chat widget                 |
| `2`    | `phone` (or `voice`, `call`) | Inbound or outbound voice calls |
| `3`    | `text` (or `sms`)            | SMS / text-message threads      |
| `4`    | `email`                      | Inbound email threads           |
| `5`    | `form`                       | Form submissions                |

## The Message object

<ResponseField name="id" type="string" />

<ResponseField name="conversation_id" type="string" />

<ResponseField name="role" type="string">
  Who sent the message. Common roles: `user` (participant), `assistant` (the agent), `system`, `tool`, `human` (a human teammate during takeover).
</ResponseField>

<ResponseField name="content" type="string">
  The text payload of the message. May be empty for tool-only messages.
</ResponseField>

<ResponseField name="content_type" type="string | null">
  MIME hint for the content (e.g. `text/plain`, `text/markdown`).
</ResponseField>

<ResponseField name="status" type="string | null">
  Delivery status, when available — e.g. `sent`, `delivered`, `failed`.
</ResponseField>

<ResponseField name="tool_used" type="string | null">
  Name of the tool the assistant called, when this message represents a tool invocation.
</ResponseField>

<ResponseField name="tool_arguments" type="object | null">
  JSON arguments passed to the tool.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## List conversations

<ParamField type="GET">
  `GET /api/v1/conversations`
</ParamField>

Returns a paginated list of conversations across all agents in your workspace. Sorted by `created_at` descending by default.

### Query parameters

| Param                 | Type              | Description                                                                      |
| --------------------- | ----------------- | -------------------------------------------------------------------------------- |
| `bot_id`              | string            | Filter to a single agent                                                         |
| `contact_id`          | string            | Filter to conversations linked to a specific contact                             |
| `visitor_id`          | string            | Filter to conversations linked to a specific anonymous visitor                   |
| `assigned_to`         | string            | Filter by the user ID of the assigned teammate                                   |
| `type`                | string \| integer | Filter by channel — `chat`, `phone`, `text`, `email`, `form`, or numeric `1`–`5` |
| `active`              | boolean           | `true` for in-progress conversations, `false` for inactive                       |
| `archived`            | boolean           | Filter on the archived flag (omit to include both)                               |
| `human_takeover`      | boolean           | `true` for conversations currently being handled by a human                      |
| `include_deleted`     | boolean           | Pass `true` to include soft-deleted conversations                                |
| `created_after`       | string (ISO 8601) | Created at or after this timestamp                                               |
| `created_before`      | string (ISO 8601) | Created at or before this timestamp                                              |
| `last_message_after`  | string (ISO 8601) | Most-recent message at or after this timestamp                                   |
| `last_message_before` | string (ISO 8601) | Most-recent message at or before this timestamp                                  |
| `search`              | string            | Substring match against the latest message snippet, email, phone, or human name  |
| `sort`                | string            | `created_at` (default) or `last_message_at`                                      |
| `order`               | string            | `desc` (default) or `asc`                                                        |
| `page`                | integer           | See [Pagination](/api-reference/pagination)                                      |
| `page_size`           | integer           | See [Pagination](/api-reference/pagination)                                      |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/conversations?type=chat&active=true&page_size=10" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "conv_01HXYZ...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 1,
      "email": "ada@example.com",
      "phone_number": null,
      "human": "Ada Lovelace",
      "human_takeover": false,
      "assigned_to": null,
      "assigned_at": null,
      "active": true,
      "archived": false,
      "archived_at": null,
      "deleted": false,
      "deleted_at": null,
      "internal": false,
      "internal_notes": null,
      "last_message": "Sounds good, talk soon!",
      "last_message_at": "2026-04-30T14:21:00.000Z",
      "last_active_at": "2026-04-30T14:21:30.000Z",
      "sentiment_positive": true,
      "sentiment_score": 0.74,
      "sentiment_summary": "Customer is excited about the upcoming demo.",
      "audio_url": null,
      "minutes": null,
      "visitor_id": "v_01HVIS...",
      "created_at": "2026-04-30T14:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 10, "total": 1, "total_pages": 1 }
}
```

***

## Get a conversation

<ParamField type="GET">
  `GET /api/v1/conversations/{id}`
</ParamField>

Fetches a single conversation by ID. Returns `404 not_found` if the conversation does not exist or belongs to another workspace.

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "conv_01HXYZ...",
    "bot_id": "b_01HDEF...",
    "contact_id": "c_01HABC...",
    "type": 1,
    "human": "Ada Lovelace",
    "human_takeover": false,
    "active": true,
    "last_message": "Sounds good, talk soon!",
    "last_message_at": "2026-04-30T14:21:00.000Z",
    "sentiment_positive": true,
    "sentiment_score": 0.74,
    "created_at": "2026-04-30T14:00:00.000Z"
  }
}
```

***

## Update a conversation

<ParamField type="PATCH">
  `PATCH /api/v1/conversations/{id}`
</ParamField>

Requires a key with the `write` scope. Updates the listed fields and leaves everything else untouched. Use this to manage inbox state — assigning conversations to teammates, archiving, taking over from the agent, or adding private notes.

### Body fields

| Field            | Type           | Description                                                                        |
| ---------------- | -------------- | ---------------------------------------------------------------------------------- |
| `internal_notes` | string \| null | Private notes for your team. Never shared with the participant.                    |
| `assigned_to`    | string \| null | User ID of the teammate who should own this conversation. Pass `null` to unassign. |
| `archived`       | boolean        | `true` to archive, `false` to unarchive.                                           |
| `human_takeover` | boolean        | `true` to mute the agent and let a human reply.                                    |
| `active`         | boolean        | Mark the conversation in-progress (`true`) or closed (`false`).                    |

<Note>
  Setting `assigned_to` automatically updates `assigned_at`. Setting `archived` automatically updates `archived_at`. You don't need to send those fields yourself.
</Note>

### Example: assign a conversation

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to": "u_01HUSER",
    "internal_notes": "Hot lead — follow up by EOD."
  }'
```

```json theme={null}
{
  "data": {
    "id": "conv_01HXYZ...",
    "bot_id": "b_01HDEF...",
    "contact_id": "c_01HABC...",
    "assigned_to": "u_01HUSER...",
    "assigned_at": "2026-04-30T19:10:00.000Z",
    "internal_notes": "Hot lead — follow up by EOD.",
    "archived": false,
    "active": true,
    "created_at": "2026-04-30T14:00:00.000Z"
  }
}
```

### Example: archive

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
```

### Example: take over from the agent

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "human_takeover": true }'
```

<Tip>
  Updating `human_takeover` only flips the flag — sending the actual reply still happens through the agent's channel (chat widget, SMS, etc.). Use takeover to silence the agent while a human responds in the dashboard.
</Tip>

***

## Delete a conversation

<ParamField type="DELETE">
  `DELETE /api/v1/conversations/{id}`
</ParamField>

Requires a key with the `write` scope. Returns `204 No Content` with an empty body on success.

This is a **soft delete** — the conversation is hidden from list responses (and from the dashboard inbox) but transcripts, recordings, and analytics are preserved. Pass `include_deleted=true` on [List conversations](#list-conversations) to surface deleted records, and `PATCH` with `deleted: false` is **not** supported via the API; restoration is dashboard-only.

### Example

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"
```

<Warning>
  Deleting a conversation removes it from your inbox and all dashboard views. The underlying transcript is retained for compliance and analytics, but cannot be re-surfaced through the public API.
</Warning>

***

## List messages in a conversation

<ParamField type="GET">
  `GET /api/v1/conversations/{id}/messages`
</ParamField>

Returns the messages in a single conversation, paginated. Defaults to **chronological order** (`order=asc`) — the natural read order for a transcript.

### Query parameters

| Param            | Type              | Description                                                                       |
| ---------------- | ----------------- | --------------------------------------------------------------------------------- |
| `role`           | string            | Filter to messages from a single role — e.g. `user`, `assistant`, `human`, `tool` |
| `created_after`  | string (ISO 8601) | Created at or after this timestamp                                                |
| `created_before` | string (ISO 8601) | Created at or before this timestamp                                               |
| `order`          | string            | `asc` (default) or `desc`                                                         |
| `page`           | integer           | See [Pagination](/api-reference/pagination)                                       |
| `page_size`      | integer           | See [Pagination](/api-reference/pagination)                                       |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/conversations/conv_01HXYZ/messages?page_size=50" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "msg_01HMSG1...",
      "conversation_id": "conv_01HXYZ...",
      "role": "user",
      "content": "Hi! Do you support importing from HubSpot?",
      "content_type": "text/plain",
      "status": null,
      "tool_used": null,
      "tool_arguments": null,
      "created_at": "2026-04-30T14:00:05.000Z"
    },
    {
      "id": "msg_01HMSG2...",
      "conversation_id": "conv_01HXYZ...",
      "role": "assistant",
      "content": "Yes — we have a one-click HubSpot importer. Want me to walk you through it?",
      "content_type": "text/markdown",
      "status": "delivered",
      "tool_used": null,
      "tool_arguments": null,
      "created_at": "2026-04-30T14:00:08.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 2, "total_pages": 1 }
}
```

<Tip>
  For long transcripts, page through with `page_size=100` (the maximum) to minimize round-trips. The total message count is in `pagination.total`.
</Tip>

***

## List a contact's conversations

<ParamField type="GET">
  `GET /api/v1/contacts/{contact_id}/conversations`
</ParamField>

Convenience endpoint that returns every conversation linked to a single contact, across all agents and channels.

### Query parameters

| Param             | Type    | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| `include_deleted` | boolean | Pass `true` to include soft-deleted conversations |
| `page`            | integer | See [Pagination](/api-reference/pagination)       |
| `page_size`       | integer | See [Pagination](/api-reference/pagination)       |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/contacts/c_01HABC/conversations \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "conv_01HXYZ...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 1,
      "last_message": "Sounds good, talk soon!",
      "last_message_at": "2026-04-30T14:21:00.000Z",
      "created_at": "2026-04-30T14:00:00.000Z"
    },
    {
      "id": "conv_01HOLD...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 2,
      "minutes": 12,
      "last_message_at": "2026-04-15T10:05:00.000Z",
      "created_at": "2026-04-15T09:53:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 2, "total_pages": 1 }
}
```

***

## Common patterns

### Sync new conversations to a data warehouse

Poll for conversations that have started since your last sync.

```bash theme={null}
curl "https://clarky.ai/api/v1/conversations?created_after=2026-04-30T00:00:00Z&sort=created_at&order=asc" \
  -H "Authorization: Bearer ck_live_example"
```

### Pull a full transcript

```bash theme={null}
# 1. Fetch the conversation (for metadata).
curl https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"

# 2. Page through its messages in order.
curl "https://clarky.ai/api/v1/conversations/conv_01HXYZ/messages?page_size=100&order=asc" \
  -H "Authorization: Bearer ck_live_example"
```

### Find every chat a customer has had with you

```bash theme={null}
curl https://clarky.ai/api/v1/contacts/c_01HABC/conversations \
  -H "Authorization: Bearer ck_live_example"
```

### Auto-assign new conversations from your CRM

Combine [List conversations](#list-conversations) with [Update a conversation](#update-a-conversation) to route inbound chats to the right rep. Filter for unassigned, in-progress conversations and PATCH each one with the right `assigned_to`.

```bash theme={null}
curl "https://clarky.ai/api/v1/conversations?active=true&type=chat" \
  -H "Authorization: Bearer ck_live_example"

curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": "u_01HUSER" }'
```


# Errors
Source: https://docs.clarky.ai/api-reference/errors

Consistent error envelope and codes returned by the Clarky API

Every Clarky API error — whether it's an authentication failure, a validation problem, or an internal error — comes back in the same envelope. This makes it easy to write a single error handler that works across every endpoint.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "first_name must be a string",
    "details": {
      "field": "first_name"
    }
  }
}
```

<ResponseField name="error.code" type="string">
  A short machine-readable identifier for the failure. Use this for branching logic — never the message.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description of what went wrong. Safe to surface to developers, but not generally suitable for end users.
</ResponseField>

<ResponseField name="error.details" type="object">
  Optional structured context. The shape depends on the error code — for `validation_error` this often includes the offending field name, expected type, etc.
</ResponseField>

## Error codes

| Code               | HTTP | Meaning                                                            |
| ------------------ | ---- | ------------------------------------------------------------------ |
| `unauthorized`     | 401  | Missing, malformed, or revoked API key                             |
| `forbidden`        | 403  | Authenticated, but the key doesn't have permission for this action |
| `not_found`        | 404  | The resource doesn't exist or isn't visible to your workspace      |
| `bad_request`      | 400  | The request was malformed (bad JSON, unsupported parameter, etc.)  |
| `validation_error` | 422  | The request was well-formed but a field failed validation          |
| `conflict`         | 409  | The request conflicts with the current state of a resource         |
| `rate_limited`     | 429  | Too many requests — see [Rate Limits](/api-reference/rate-limits)  |
| `internal_error`   | 500  | Something went wrong on our end. Retry with backoff                |

## Examples

### `unauthorized` (401)

Returned when the `Authorization` header is missing, the key has been revoked, or the key format is invalid.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key"
  }
}
```

### `forbidden` (403)

Returned when the key is valid but doesn't have permission for the action — for example, a `read`-only key trying to `POST`.

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have the 'write' scope"
  }
}
```

### `not_found` (404)

Returned when the resource doesn't exist, or exists in a different workspace than the one your key belongs to.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Contact not found"
  }
}
```

### `bad_request` (400)

Returned for malformed requests — invalid JSON, unsupported query parameters, missing `Content-Type`, etc.

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Request body must be valid JSON"
  }
}
```

### `validation_error` (422)

Returned when the request is structurally valid but at least one field failed validation. The `details` object identifies the offending field.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "deal_value must be a non-negative number",
    "details": {
      "field": "deal_value"
    }
  }
}
```

### `conflict` (409)

Returned when the request would violate a uniqueness constraint or otherwise conflict with the current state.

```json theme={null}
{
  "error": {
    "code": "conflict",
    "message": "A contact with this primary email already exists",
    "details": {
      "field": "emails",
      "existing_contact_id": "c_01HXYZ..."
    }
  }
}
```

### `rate_limited` (429)

Returned when you exceed the per-key request budget. The response includes `Retry-After` and `X-RateLimit-*` headers — see [Rate Limits](/api-reference/rate-limits).

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 30 seconds."
  }
}
```

### `internal_error` (500)

Returned when something unexpected happened server-side. These should be rare. Retry with exponential backoff.

```json theme={null}
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}
```

<Tip>
  Always branch on `error.code`, never on `error.message`. We may improve message wording over time, but codes are stable contract.
</Tip>


# Forms
Source: https://docs.clarky.ai/api-reference/forms

Read forms and the submissions captured by them

Forms collect structured data from your users — typically lead capture, surveys, or onboarding flows. The Forms API is **read-only**: forms themselves are configured in the dashboard (see the [Forms feature docs](/features/forms/overview)), and submissions are created when users fill them out. The API lets you list forms, fetch a single form's configuration, and read submissions.

## The Form object

<ResponseField name="id" type="string" />

<ResponseField name="workspace_id" type="string" />

<ResponseField name="bot_id" type="string">The agent that owns this form.</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string | null" />

<ResponseField name="standard_fields" type="object">
  Configuration for built-in fields (name, email, phone, etc.) — JSON shape varies by form.
</ResponseField>

<ResponseField name="custom_fields" type="object">
  Configuration for custom fields the workspace has defined.
</ResponseField>

<ResponseField name="survey_questions" type="object">
  Configuration for survey questions, if the form is a survey form.
</ResponseField>

<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>

## The Submission object

<ResponseField name="id" type="string" />

<ResponseField name="form_id" type="string" />

<ResponseField name="contact_id" type="string | null">
  Linked contact, if the submission was associated with one.
</ResponseField>

<ResponseField name="custom_field_responses" type="object">
  The submitter's answers, keyed by field name.
</ResponseField>

<ResponseField name="is_internal" type="boolean">
  `true` if the submission was created by an internal user (e.g. via dashboard testing). Filtered out of submission lists by default.
</ResponseField>

<ResponseField name="submitted_at" type="string">ISO 8601 timestamp.</ResponseField>

***

## List forms

<ParamField type="GET">
  `GET /api/v1/forms`
</ParamField>

### Query parameters

| Param       | Type    | Description                                 |
| ----------- | ------- | ------------------------------------------- |
| `bot_id`    | string  | Restrict to forms owned by a specific agent |
| `page`      | integer | See [Pagination](/api-reference/pagination) |
| `page_size` | integer | See [Pagination](/api-reference/pagination) |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/forms \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "f_01HFRM...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Demo Request",
      "description": "Lead capture form for the marketing site",
      "standard_fields": {
        "first_name": { "enabled": true, "required": true },
        "email": { "enabled": true, "required": true }
      },
      "custom_fields": {},
      "survey_questions": {},
      "created_at": "2026-02-10T10:00:00.000Z",
      "updated_at": "2026-04-15T08:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get a form

<ParamField type="GET">
  `GET /api/v1/forms/{id}`
</ParamField>

Returns the full form configuration, including every standard, custom, and survey field.

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/forms/f_01HFRM \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "f_01HFRM...",
    "workspace_id": "w_01HXXX...",
    "bot_id": "b_01HDEF...",
    "name": "Demo Request",
    "description": "Lead capture form for the marketing site",
    "standard_fields": {
      "first_name": { "enabled": true, "required": true },
      "last_name": { "enabled": true, "required": false },
      "email": { "enabled": true, "required": true },
      "company": { "enabled": true, "required": false }
    },
    "custom_fields": {
      "team_size": {
        "label": "How big is your team?",
        "type": "select",
        "options": ["1-10", "11-50", "51-200", "200+"]
      }
    },
    "survey_questions": {},
    "created_at": "2026-02-10T10:00:00.000Z",
    "updated_at": "2026-04-15T08:00:00.000Z"
  }
}
```

***

## List form submissions

<ParamField type="GET">
  `GET /api/v1/forms/{id}/submissions`
</ParamField>

Returns a paginated list of submissions for a single form, in reverse-chronological order.

### Query parameters

| Param              | Type    | Description                                                    |
| ------------------ | ------- | -------------------------------------------------------------- |
| `include_internal` | boolean | Include submissions where `is_internal=true` (default `false`) |
| `page`             | integer | See [Pagination](/api-reference/pagination)                    |
| `page_size`        | integer | See [Pagination](/api-reference/pagination)                    |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/forms/f_01HFRM/submissions?page_size=50" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "s_01HSUB...",
      "form_id": "f_01HFRM...",
      "contact_id": "c_01HXYZ...",
      "custom_field_responses": {
        "first_name": "Ada",
        "email": "ada@example.com",
        "company": "Analytical Engines Inc.",
        "team_size": "11-50"
      },
      "is_internal": false,
      "submitted_at": "2026-04-29T13:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 }
}
```

<Note>
  By default, submissions where `is_internal=true` (typically internal test fills from the dashboard) are excluded. Pass `include_internal=true` to see them — useful when reconciling totals against the dashboard's "include internal" toggle.
</Note>

***

## Get a submission

<ParamField type="GET">
  `GET /api/v1/submissions/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/submissions/s_01HSUB \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "s_01HSUB...",
    "form_id": "f_01HFRM...",
    "contact_id": "c_01HXYZ...",
    "custom_field_responses": {
      "first_name": "Ada",
      "email": "ada@example.com",
      "company": "Analytical Engines Inc.",
      "team_size": "11-50"
    },
    "is_internal": false,
    "submitted_at": "2026-04-29T13:00:00.000Z"
  }
}
```

<Tip>
  To get notified the moment a new submission lands — instead of polling — set up a [Webhook](/features/settings/webhooks) on the contact-created or form-submission events.
</Tip>


# API Reference
Source: https://docs.clarky.ai/api-reference/introduction

Programmatic access to your Clarky workspace data via a public REST API

The Clarky REST API gives you programmatic access to the same CRM and conversation data you see in the dashboard — contacts, companies, pipelines, activities, conversations, messages, forms, and submissions. Use it to sync data into your data warehouse, build custom dashboards, automate lead capture, or power two-way integrations with your stack.

<Info>
  **Plan availability:** API access is available on the **Standard**, **Pro**, and **Enterprise** plans. See [Plans & Billing](/features/settings/plans).
</Info>

## Base URL

All endpoints are served from a single base URL:

```bash theme={null}
https://clarky.ai/api/v1
```

The API is versioned in the URL path. The current version is `v1`. We'll announce breaking changes well in advance and maintain older versions for a documented deprecation window.

## Conventions

* **Format** — All requests and responses are JSON. Send `Content-Type: application/json` with `POST` and `PATCH` requests.
* **Workspace scope** — Every API key belongs to a single workspace. Calls automatically operate on that workspace's data.
* **Single resources** — Returned as `{ "data": { ... } }`.
* **List resources** — Returned as `{ "data": [...], "pagination": { ... } }`.
* **Deletes** — Return `204 No Content` with an empty body.
* **Errors** — Wrapped in a consistent `error` envelope. See [Errors](/api-reference/errors).

## Quick example

```bash theme={null}
curl https://clarky.ai/api/v1/contacts \
  -H "Authorization: Bearer ck_live_example"
```

## Get started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/api-reference/quickstart">
    Make your first curl request in under 2 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Create an API key, understand scopes, and authenticate requests
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Error envelope shape and every error code with examples
  </Card>

  <Card title="Pagination" icon="list" href="/api-reference/pagination">
    Page through list endpoints with `page` and `page_size`
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Per-key request limits and recommended retry behavior
  </Card>
</CardGroup>

## Resources

<CardGroup>
  <Card title="Agents" icon="robot" href="/api-reference/agents">
    Discover the agents in your workspace and their channel configuration
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts">
    Create, read, update, delete, and bulk upsert contacts
  </Card>

  <Card title="Companies" icon="building" href="/api-reference/companies">
    Manage companies and the contacts that belong to them
  </Card>

  <Card title="Pipelines" icon="diagram-project" href="/api-reference/pipelines">
    Read pipelines and stages, manage pipeline cards
  </Card>

  <Card title="Activities" icon="clock-rotate-left" href="/api-reference/activities">
    Log notes, calls, meetings, tasks, and reminders
  </Card>

  <Card title="Conversations" icon="messages" href="/api-reference/conversations">
    Read conversations and messages across every channel
  </Card>

  <Card title="Forms" icon="clipboard-list" href="/api-reference/forms">
    Read forms and their submissions
  </Card>
</CardGroup>

## API and Webhooks

The REST API and [Webhooks](/features/settings/webhooks) are complementary. The API is the right tool for two-way data flow — pulling data on demand, creating and updating records, or backfilling historical data. Webhooks are best for one-way, real-time push notifications when something happens inside Clarky. Most integrations use both.

<Note>
  Need a feature that isn't covered yet? Email [support@clarky.ai](mailto:support@clarky.ai) — we're actively expanding the API surface.
</Note>


# Pagination
Source: https://docs.clarky.ai/api-reference/pagination

Page through list endpoints with `page` and `page_size`

All list endpoints in the Clarky API return paginated results. Pagination is page-based — you ask for a specific page and a page size, and the response tells you how many pages there are in total.

## Query parameters

<ParamField type="integer">
  The 1-indexed page number to fetch.
</ParamField>

<ParamField type="integer">
  Number of items per page. **Maximum is 100.** Requests above the maximum return `validation_error`.
</ParamField>

## Response shape

Every list endpoint wraps results in `data` (the items for the current page) and `pagination` (metadata about the pagination state).

```json theme={null}
{
  "data": [
    { "id": "c_01HXYZ...", "first_name": "Ada" },
    { "id": "c_01HXYZ...", "first_name": "Grace" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total": 142,
    "total_pages": 6
  }
}
```

<ResponseField name="pagination.page" type="integer">
  The current page number (1-indexed).
</ResponseField>

<ResponseField name="pagination.page_size" type="integer">
  Number of items returned per page.
</ResponseField>

<ResponseField name="pagination.total" type="integer">
  Total number of items across every page.
</ResponseField>

<ResponseField name="pagination.total_pages" type="integer">
  Total number of pages. `total_pages` is `Math.ceil(total / page_size)`.
</ResponseField>

## Examples

### Fetch the first page

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts?page=1&page_size=25" \
  -H "Authorization: Bearer ck_live_example"
```

### Fetch a larger page

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts?page_size=100" \
  -H "Authorization: Bearer ck_live_example"
```

### Iterate every page

```javascript theme={null}
async function fetchAllContacts(apiKey) {
  const all = [];
  let page = 1;

  while (true) {
    const res = await fetch(
      `https://clarky.ai/api/v1/contacts?page=${page}&page_size=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const { data, pagination } = await res.json();
    all.push(...data);

    if (page >= pagination.total_pages) break;
    page += 1;
  }

  return all;
}
```

<Tip>
  For large backfills, prefer `page_size=100` to minimize round-trips, and respect the [rate limits](/api-reference/rate-limits) by backing off when you see `429` responses.
</Tip>

## Endpoints that don't paginate

A small number of endpoints return collections without pagination because the result set is bounded — for example, [stages within a pipeline](/api-reference/pipelines#list-pipeline-stages). These return `{ "data": [...] }` with no `pagination` object. The shape is documented per-endpoint.

## Single-resource responses

For endpoints that return a single resource (e.g. `GET /contacts/{id}`), the response is just `{ "data": { ... } }` — no `pagination` object.

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada"
  }
}
```


# Pipelines
Source: https://docs.clarky.ai/api-reference/pipelines

Read pipelines and stages, manage pipeline cards

Pipelines model your sales (or other) workflow. Each pipeline has an ordered list of **stages**, and each stage holds **cards** — usually one per deal or opportunity. Pipelines and stages are read-only via the API; cards support full CRUD.

## Resources

<CardGroup>
  <Card title="Pipelines" icon="diagram-project" href="#list-pipelines">
    The top-level container, owned by an agent
  </Card>

  <Card title="Stages" icon="bars-staggered" href="#list-pipeline-stages">
    Ordered columns within a pipeline
  </Card>

  <Card title="Cards" icon="rectangle-list" href="#list-pipeline-cards">
    Individual deals living in a stage
  </Card>
</CardGroup>

***

## The Pipeline object

<ResponseField name="id" type="string" />

<ResponseField name="workspace_id" type="string" />

<ResponseField name="bot_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="is_default" type="boolean" />

<ResponseField name="is_private" type="boolean" />

<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>

## List pipelines

<ParamField type="GET">
  `GET /api/v1/pipelines`
</ParamField>

### Query parameters

| Param       | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `bot_id`    | string  | Restrict to pipelines owned by a specific agent |
| `page`      | integer | See [Pagination](/api-reference/pagination)     |
| `page_size` | integer | See [Pagination](/api-reference/pagination)     |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/pipelines?bot_id=b_01HDEF" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "p_01HPLA...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Sales Pipeline",
      "is_default": true,
      "is_private": false,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-04-01T08:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## The Stage object

<ResponseField name="id" type="string" />

<ResponseField name="bot_id" type="string" />

<ResponseField name="pipeline_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="color" type="string">Hex color (e.g. `"#0586ff"`).</ResponseField>
<ResponseField name="order_index" type="integer">0-indexed position within the pipeline.</ResponseField>

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

## List pipeline stages

<ParamField type="GET">
  `GET /api/v1/pipelines/{id}/stages`
</ParamField>

Returns every stage in the pipeline, sorted by `order_index`. **Not paginated** — the response shape is `{ "data": [...] }` with no `pagination` object.

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/pipelines/p_01HPLA/stages \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "ps_01HSTA...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Lead",
      "color": "#94a3b8",
      "order_index": 0,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "ps_01HSTB...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Qualified",
      "color": "#3b82f6",
      "order_index": 1,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "ps_01HSTC...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Closed Won",
      "color": "#22c55e",
      "order_index": 2,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}
```

***

## The Pipeline Card object

<ResponseField name="id" type="string" />

<ResponseField name="pipeline_stage_id" type="string">The stage the card is currently in.</ResponseField>
<ResponseField name="contact_id" type="string | null">The contact associated with this card, if any.</ResponseField>

<ResponseField name="title" type="string" />

<ResponseField name="description" type="string | null" />

<ResponseField name="tags" type="string[]" />

<ResponseField name="order_index" type="integer">Position within the stage. Lower values sort first.</ResponseField>
<ResponseField name="archived_at" type="string | null">ISO 8601 timestamp the card was archived. `null` if active.</ResponseField>

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

## List pipeline cards

<ParamField type="GET">
  `GET /api/v1/pipeline-cards`
</ParamField>

### Query parameters

| Param               | Type    | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| `pipeline_id`       | string  | Restrict to cards in a specific pipeline       |
| `pipeline_stage_id` | string  | Restrict to cards in a specific stage          |
| `bot_id`            | string  | Restrict to cards owned by a specific agent    |
| `contact_id`        | string  | Restrict to cards linked to a specific contact |
| `include_archived`  | boolean | Include archived cards (default `false`)       |
| `page`              | integer | See [Pagination](/api-reference/pagination)    |
| `page_size`         | integer | See [Pagination](/api-reference/pagination)    |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/pipeline-cards?pipeline_stage_id=ps_01HSTA" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": [
    {
      "id": "pc_01HCRD...",
      "pipeline_stage_id": "ps_01HSTA...",
      "contact_id": "c_01HXYZ...",
      "title": "Acme Corp – renewal",
      "description": "Renewal due in Q2",
      "tags": ["renewal"],
      "order_index": 0,
      "archived_at": null,
      "created_at": "2026-04-10T09:00:00.000Z",
      "updated_at": "2026-04-29T15:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}
```

***

## Get a pipeline card

<ParamField type="GET">
  `GET /api/v1/pipeline-cards/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTA...",
    "contact_id": "c_01HXYZ...",
    "title": "Acme Corp – renewal",
    "description": "Renewal due in Q2",
    "tags": ["renewal"],
    "order_index": 0,
    "archived_at": null,
    "created_at": "2026-04-10T09:00:00.000Z",
    "updated_at": "2026-04-29T15:00:00.000Z"
  }
}
```

***

## Create a pipeline card

<ParamField type="POST">
  `POST /api/v1/pipeline-cards`
</ParamField>

Requires a key with the `write` scope.

### Body fields

| Field               | Type      | Required | Description                      |
| ------------------- | --------- | -------- | -------------------------------- |
| `pipeline_stage_id` | string    | Yes      | The stage to drop the card into  |
| `title`             | string    | Yes      |                                  |
| `contact_id`        | string    | No       | Link to a contact                |
| `description`       | string    | No       |                                  |
| `tags`              | string\[] | No       |                                  |
| `order_index`       | integer   | No       | Defaults to the end of the stage |

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/pipeline-cards \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_stage_id": "ps_01HSTA",
    "title": "Acme Corp – renewal",
    "contact_id": "c_01HXYZ",
    "tags": ["renewal"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTA...",
    "contact_id": "c_01HXYZ...",
    "title": "Acme Corp – renewal",
    "tags": ["renewal"],
    "order_index": 3,
    "archived_at": null,
    "created_at": "2026-04-29T19:10:00.000Z",
    "updated_at": "2026-04-29T19:10:00.000Z"
  }
}
```

***

## Update a pipeline card

<ParamField type="PATCH">
  `PATCH /api/v1/pipeline-cards/{id}`
</ParamField>

Update any combination of fields. Setting `pipeline_stage_id` to a new stage moves the card. Setting `archived_at` to an ISO 8601 timestamp archives the card; setting it to `null` un-archives it.

### Body fields

| Field               | Type           | Description                                 |
| ------------------- | -------------- | ------------------------------------------- |
| `pipeline_stage_id` | string         | Move the card to a different stage          |
| `contact_id`        | string \| null | Link or unlink a contact                    |
| `title`             | string         |                                             |
| `description`       | string         |                                             |
| `tags`              | string\[]      |                                             |
| `order_index`       | integer        | Reorder within the stage                    |
| `archived_at`       | string \| null | ISO 8601 timestamp, or `null` to un-archive |

### Example: move a card to a new stage

```bash theme={null}
curl -X PATCH https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_stage_id": "ps_01HSTC", "order_index": 0 }'
```

```json theme={null}
{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTC...",
    "order_index": 0,
    "updated_at": "2026-04-29T19:15:00.000Z"
  }
}
```

***

## Delete a pipeline card

<ParamField type="DELETE">
  `DELETE /api/v1/pipeline-cards/{id}`
</ParamField>

Returns `204 No Content`. To preserve a card while removing it from active views, set `archived_at` via [Update](#update-a-pipeline-card) instead of deleting.

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"
```


# Quickstart
Source: https://docs.clarky.ai/api-reference/quickstart

Make your first request to the Clarky API in under 2 minutes

This walks you from zero to a working `curl` call against your live workspace data. By the end you'll have listed contacts, fetched a single contact, and created one — using nothing but the terminal.

<Info>
  **Plan availability:** Standard, Pro, or Enterprise. See [Plans & Billing](/features/settings/plans).
</Info>

## 1. Create an API key

<Steps>
  <Step title="Open Settings → API Keys">
    From the admin dashboard, click **Settings**, then choose **API Keys** under the Workspace section.
  </Step>

  <Step title="Click 'New API Key'">
    Give it a memorable name (e.g. "Local testing"). The full key is shown **only once** — copy it immediately.
  </Step>

  <Step title="Save the key">
    Store it somewhere safe. If you lose it, revoke it and create a new one.
  </Step>
</Steps>

## 2. Set the key as a shell variable

This keeps the key out of your shell history and makes the examples below copy-pasteable.

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export CLARKY_KEY='ck_live_paste_your_key_here'
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:CLARKY_KEY='ck_live_paste_your_key_here'
  ```
</CodeGroup>

## 3. List your contacts

Your first read. The list is automatically scoped to the workspace the key belongs to.

```bash theme={null}
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts?page=1&page_size=5"
```

Expected response shape:

```json theme={null}
{
  "data": [
    {
      "id": "9f1c6a9e-8c3b-4ea2-bf8c-5b08f7a4d6c2",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "emails": ["ada@example.com"],
      "company": "Analytical Engines",
      "tags": ["beta-tester"],
      "created_at": "2026-01-12T14:30:00Z",
      "updated_at": "2026-01-12T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 5, "total": 47, "total_pages": 10 }
}
```

<Tip>
  Pipe the response through `jq` for readable output: `curl ... | jq`. Install with `brew install jq` on macOS.
</Tip>

## 4. Get a single contact

Grab any `id` from the previous response and use it in the path:

```bash theme={null}
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts/9f1c6a9e-8c3b-4ea2-bf8c-5b08f7a4d6c2"
```

## 5. Search by email

Useful for "do I already have this contact?" lookups. Returns `404` if no match.

```bash theme={null}
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts/by-email?email=ada@example.com"
```

## 6. Create a contact (your first write)

You'll need a `bot_id` — find it in the URL when you're inside an agent's admin pages (`/admin/<workspace>/<bot>/...`), or call `GET /api/v1/pipelines` and use the `bot_id` from any returned pipeline.

```bash theme={null}
curl -X POST "https://clarky.ai/api/v1/contacts" \
  -H "Authorization: Bearer $CLARKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your-bot-uuid",
    "first_name": "Test",
    "last_name": "User",
    "emails": ["test@example.com"],
    "tags": ["api-test"],
    "lead_source": "API Quickstart"
  }'
```

A `201 Created` response means it worked. Open **CRM → People** in your dashboard sidebar and you'll see the new contact.

<Tip>
  For idempotent imports use [`POST /api/v1/contacts/upsert`](/api-reference/contacts) — it dedupes on primary email or phone so you can re-run the same payload safely.
</Tip>

## 7. Verify auth is enforced

Sanity-check that the API rejects requests without a valid key:

```bash theme={null}
curl -i "https://clarky.ai/api/v1/contacts"
```

You should get back `HTTP/1.1 401 Unauthorized` with:

```json theme={null}
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key" } }
```

## Common pitfalls

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The `Authorization` header is missing, malformed, or the key has been revoked. The header must be exactly `Authorization: Bearer <key>` — note the literal word `Bearer` and a single space.
  </Accordion>

  <Accordion title="403 Forbidden on a POST/PATCH/DELETE">
    Your key was created without the `write` scope. Revoke it and create a new one with both `read` and `write` (the default).
  </Accordion>

  <Accordion title="422 Validation error referencing bot_id">
    The `bot_id` you sent doesn't belong to your workspace. Use a bot ID from your own workspace — pulling one from `GET /api/v1/pipelines` is the easiest check.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You've exceeded the per-key rate limit (120 reads/min, 60 writes/min). Look at the `Retry-After` header and back off. See [Rate Limits](/api-reference/rate-limits) for details.
  </Accordion>

  <Accordion title="Curl seems to hang">
    On Windows or older curl versions the JSON body may need different quoting. Use single quotes around the `-d` payload on macOS/Linux and escape inner double quotes on Windows, or use a `--data @body.json` file instead.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Scopes, key rotation, security best practices
  </Card>

  <Card title="Pagination" icon="list" href="/api-reference/pagination">
    Walking large result sets
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Per-key limits and retry behavior
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts">
    Full Contacts endpoint reference
  </Card>
</CardGroup>


# Rate Limits
Source: https://docs.clarky.ai/api-reference/rate-limits

Per-key request budgets and recommended client behavior

Every API key has its own request budget, applied independently per key. Limits are split between read and write operations to keep heavy reads from starving writes (and vice versa).

## Limits

| Operation  | Methods                   | Limit                           |
| ---------- | ------------------------- | ------------------------------- |
| **Reads**  | `GET`, `HEAD`             | **120 requests/minute** per key |
| **Writes** | `POST`, `PATCH`, `DELETE` | **60 requests/minute** per key  |

Limits are enforced on a rolling 60-second window. When you hit the limit, subsequent requests return `429 Too Many Requests` until the window resets.

## Rate limit headers

Every response — successful or rate-limited — includes headers that describe your current budget:

<ResponseField name="X-RateLimit-Limit" type="integer">
  Maximum requests allowed in the current window for this method class (read or write).
</ResponseField>

<ResponseField name="X-RateLimit-Remaining" type="integer">
  Requests remaining in the current window.
</ResponseField>

<ResponseField name="X-RateLimit-Reset" type="integer">
  Unix timestamp (seconds since epoch) when the current window resets.
</ResponseField>

Example response headers:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1735689600
```

## What a 429 looks like

When you exceed the limit, you'll get a `429` with a standard error envelope and a `Retry-After` header (in seconds):

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 30 seconds."
  }
}
```

## Recommended client behavior

<Steps>
  <Step title="Respect Retry-After">
    On a `429`, wait at least the number of seconds in the `Retry-After` header before retrying. This is the simplest correct strategy.
  </Step>

  <Step title="Use exponential backoff with jitter">
    For longer-running jobs, layer exponential backoff on top of `Retry-After`. Add random jitter so a fleet of workers doesn't synchronize and thunder back together.
  </Step>

  <Step title="Throttle proactively">
    Watch `X-RateLimit-Remaining`. If it's getting close to zero, slow down before you hit the limit — it's much cheaper than recovering from a `429`.
  </Step>

  <Step title="Parallelize across keys for very large jobs">
    If you genuinely need throughput beyond the per-key limit, create multiple keys (one per worker) and shard your work across them. Limits are per-key, so independent keys give you linear scaling. Reach out to support if you need a higher per-key limit.
  </Step>
</Steps>

## Example: handling 429 in Node.js

```javascript theme={null}
async function fetchWithBackoff(url, options, attempt = 0) {
  const res = await fetch(url, options);

  if (res.status === 429) {
    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "5", 10);
    const jitter = Math.random() * 500;
    const delayMs = retryAfter * 1000 + jitter;

    if (attempt >= 5) throw new Error("Too many retries");

    await new Promise((r) => setTimeout(r, delayMs));
    return fetchWithBackoff(url, options, attempt + 1);
  }

  return res;
}
```

<Warning>
  Don't retry every error blindly — only retry `429` and `5xx` responses. Retrying `4xx` errors (other than `429`) wastes budget and won't change the outcome.
</Warning>

<Tip>
  For bulk loads, the [`POST /contacts/upsert`](/api-reference/contacts#bulk-upsert-contacts) endpoint accepts up to 200 contacts in a single request. Prefer it over a loop of individual `POST /contacts` calls — one upsert costs one write against your budget.
</Tip>


# Sequences
Source: https://docs.clarky.ai/api-reference/sequences

Upsert a contact and start a personalized outbound sequence in one call

<Info>
  **Plan availability:** Standard or higher (requires both **Sequences** and **API Access**). See [Plans & Billing](/features/settings/plans).
</Info>

The Sequences API lets you trigger a fully personalized outbound campaign for a single contact from your own backend. In one call, Clarky will:

1. **Upsert the contact** in your workspace (matched by primary email, falling back to phone).
2. **Append the notes** you send (`Speaks Spanish. Located in Madrid.`) to the contact's record so they survive across calls.
3. **Generate a bespoke sequence** from a saved template using a two-stage LLM pipeline — emails are written for the specific recipient, in their language, referencing real context. SMS / voice scripts are generated the same way.
4. **Optionally launch immediately** — with `auto_approve: true`, the first step (call or email) fires within seconds of generation completing, no human review required.

Templates encode which channels are allowed (`email`, `voice`, `sms`), so the API itself does not expose a channel selector — pick a template that uses the channels you want.

<Note>
  **Generation takes time.** The endpoint responds with `202 Accepted` after a few hundred milliseconds, but the LLM pipeline runs in the background and takes \~30–90s before the first outbound action goes out. Poll the status endpoint to know when it has shipped.
</Note>

## Start a sequence

<ParamField type="POST">
  `POST /api/v1/sequences/start`
</ParamField>

### Request body

<ParamField type="string">
  ID of a [sequence template](#) in your workspace. The template defines the goal prompt, allowed channels, pacing, and (optionally) the bot identity.
</ParamField>

<ParamField type="string">
  Required only if the template has no `bot_id`. The bot whose email/phone identity will be used as the sender.
</ParamField>

<ParamField type="object">
  The contact to upsert.

  <Expandable title="Properties">
    <ResponseField name="emails" type="string[]">
      Array of email addresses. The first is treated as primary and used for matching.
    </ResponseField>

    <ResponseField name="phone_numbers" type="string[]">
      Array of phone numbers in E.164 format. The first is primary. Used for matching when no email is provided.
    </ResponseField>

    <ResponseField name="first_name" type="string" />

    <ResponseField name="last_name" type="string" />

    <ResponseField name="company" type="string" />

    <ResponseField name="job_title" type="string" />

    <ResponseField name="notes" type="string">
      Free-text context the LLM will use to personalize the outreach — e.g. `"Speaks Spanish. Located in Madrid. Returning lead."`. On an existing contact, new notes are **appended** (not overwritten) with a timestamp tag like `[via API 2026-05-06]`.
    </ResponseField>

    <ResponseField name="custom_fields" type="object">
      Workspace-defined custom fields, stored as JSON.
    </ResponseField>

    <ResponseField name="tags" type="string[]" />

    <ResponseField name="lead_source" type="string" />
  </Expandable>

  At least one of `emails` or `phone_numbers` is required.
</ParamField>

<ParamField type="boolean">
  When `true`, skips the human review gate. After generation, step 1's `scheduled_for` is forced to `now` and the dispatcher fires immediately — the contact's phone rings (or inbox dings) within seconds. Use this for trusted automation.

  When `false` (the default), the sequence is generated and parked in `pending_approval`. Workspace admins receive an email with a review link.
</ParamField>

<ParamField type="string">
  A stable identifier (e.g. your internal lead ID). Calling the endpoint a second time with the same key returns the original `sequence_id` and `enrollment_id` — no duplicate sequence is created.
</ParamField>

<ParamField type="string">
  Display name for the sequence. Defaults to the template's name.
</ParamField>

### Response — 202 Accepted

```json theme={null}
{
  "data": {
    "sequence_id":    "seq_01HXYZ...",
    "enrollment_id":  "enr_01HXYZ...",
    "contact_id":     "c_01HXYZ...",
    "contact_action": "created",
    "auto_approve":   true,
    "status":         "generating",
    "status_url":     "/api/v1/sequences/enrollments/enr_01HXYZ..."
  }
}
```

### Example — call back a Spanish-speaking lead immediately

```bash theme={null}
curl -X POST "https://clarky.ai/api/v1/sequences/start" \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id":     "tpl_01HABC...",
    "contact": {
      "first_name":    "Maria",
      "last_name":     "García",
      "emails":        ["maria@example.com"],
      "phone_numbers": ["+34911234567"],
      "company":       "Acme Spain",
      "notes":         "Speaks Spanish. Located in Madrid. Submitted contact form 30 seconds ago asking about pricing."
    },
    "auto_approve":    true,
    "idempotency_key": "lead_20260506_84211"
  }'
```

### Errors

| Code  | Meaning                                                                                           |
| ----- | ------------------------------------------------------------------------------------------------- |
| `400` | Missing required field, or template has no `bot_id` and none was provided.                        |
| `401` | Invalid or revoked API key.                                                                       |
| `403` | API key does not have `write` scope.                                                              |
| `404` | Template not found in this workspace.                                                             |
| `422` | Validation error — e.g. contact has no email or phone, or `bot_id` is from a different workspace. |
| `429` | Rate limit exceeded.                                                                              |

***

## Get enrollment status

<ParamField type="GET">
  `GET /api/v1/sequences/enrollments/{enrollment_id}`
</ParamField>

Use this to poll for generation progress, see the generated steps, and check delivery state.

### Status values

| Status                 | Meaning                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `generating`           | LLM is still producing the sequence. Typical 30–90s.                                                           |
| `pending_approval`     | Sequence is generated but awaiting human approval (only when `auto_approve: false`). Admins have been emailed. |
| `approved`             | Steps are scheduled. The first step is in flight or already sent.                                              |
| `running`              | Sequence is active across multiple steps.                                                                      |
| `stopped_reply`        | Contact replied; the sequence halted (if `stop_on_reply` is on for the template).                              |
| `stopped_unsubscribed` | Contact's email/phone is suppressed.                                                                           |
| `stopped_user`         | Manually halted by a workspace user.                                                                           |
| `completed`            | All steps sent.                                                                                                |
| `failed`               | Generation or dispatch failed. See `generation_error`.                                                         |

### Example response

```json theme={null}
{
  "data": {
    "id":           "enr_01HXYZ...",
    "sequence_id":  "seq_01HXYZ...",
    "contact_id":   "c_01HXYZ...",
    "status":       "approved",
    "generation_error": null,
    "approved_at":  "2026-05-06T14:22:11Z",
    "stop_reason":  null,
    "created_at":   "2026-05-06T14:21:14Z",
    "updated_at":   "2026-05-06T14:22:11Z",
    "sequence": {
      "id":          "seq_01HXYZ...",
      "name":        "Inbound lead — Spanish",
      "status":      "active",
      "bot_id":      "b_01HDEF...",
      "template_id": "tpl_01HABC..."
    },
    "steps": [
      {
        "id":            "stp_01...",
        "sort_order":    1,
        "channel":       "voice",
        "status":        "sent",
        "scheduled_for": "2026-05-06T14:22:11Z",
        "sent_at":       "2026-05-06T14:22:18Z",
        "to_identifier": "+34911234567",
        "voice_objective": "Confirm pricing tier and book a 15-minute demo this week",
        "voice_script":    "Hola Maria, te llamo desde Acme..."
      },
      {
        "id":            "stp_02...",
        "sort_order":    2,
        "channel":       "email",
        "status":        "scheduled",
        "scheduled_for": "2026-05-07T15:00:00Z",
        "email_subject": "Resumen de la llamada y próximos pasos"
      }
    ]
  }
}
```

***

## Notes & limits

* **Latency floor:** \~30–90s from API call to first outbound action. Two LLM calls run in the background; this can't be made faster while still producing language-matched, personalized content.
* **Channels are template-driven.** If the template's `allowed_channels` is `["email", "voice"]`, no SMS will be sent regardless of what the contact has on file.
* **Concurrent enrollments are allowed** — calling the endpoint while the contact is in another active sequence will not be rejected.
* **Suppressed contacts** (unsubscribed email, opted-out phone) cause the enrollment to fail with `no_usable_channels`. Polling the status endpoint will reflect this.


# Availability and Schedules
Source: https://docs.clarky.ai/features/booking/availability

Define when you're bookable and connect your Google Calendar to block real conflicts

## How Availability Works

Clarky calculates available time slots from three sources, in order of priority:

1. **Event type schedule** — working hours set on a specific event type
2. **Default schedule** — your default working hours
3. **Built-in fallback** — Monday through Friday, 9am to 5pm, if nothing else is configured

On top of that, Clarky removes any time that conflicts with existing Clarky bookings or events on connected Google Calendars.

## Working Hours

A schedule defines which days and times you're available. Configure it from the **Availability** tab inside an event type.

<Steps>
  <Step title="Open the Schedule Editor">
    From an event type, open the **Availability** tab.
  </Step>

  <Step title="Pick Your Timezone">
    All hours are stored in your timezone. Invitees see times converted to their own timezone automatically.
  </Step>

  <Step title="Set Working Hours">
    For each day of the week, set a start and end time (for example, Monday–Friday 9:00–17:00). Days you leave blank are unavailable.
  </Step>

  <Step title="Add Time Off">
    Block specific dates — vacations, holidays, conferences — so they never appear as bookable.
  </Step>

  <Step title="Save">
    Changes take effect immediately for new bookings.
  </Step>
</Steps>

## Date Overrides

Override your normal hours for a specific date without changing your weekly schedule.

Use date overrides to:

* Block a single day (for example, "out for a doctor's appointment on Tuesday")
* Open a normally-closed day (for example, "available this Saturday only, 10am–2pm")
* Shorten a day (for example, "Friday 9am–noon only")

## Connecting Google Calendar

Connecting Google Calendar lets Clarky:

* Block time slots that conflict with events on your calendar
* Add new bookings to your calendar automatically
* Generate Google Meet links for Google Meet event types

<Steps>
  <Step title="Open Availability Tab">
    Inside any event type, go to the **Availability** tab.
  </Step>

  <Step title="Click Connect Google Calendar">
    Sign in with the Google account you want to use.
  </Step>

  <Step title="Approve Calendar Access">
    Grant permission so Clarky can read events and create new ones.
  </Step>

  <Step title="Choose Calendars to Check">
    Pick which calendars to scan for conflicts (work, personal, etc.) and which calendar to add new bookings to.
  </Step>
</Steps>

<Note>
  Each workspace member connects their own Google account. The connection is private — your teammates can't see your calendar events, only that your time is busy.
</Note>

## Conflict Detection

Once Google Calendar is connected, Clarky checks your calendar before offering a time slot. If you have an event on your calendar at 2pm — even one created outside Clarky — that time disappears from your booking page.

You control which calendars are checked for conflicts. For example, you might check both your work and personal calendars for conflicts but only add new bookings to your work calendar.

<Tip>
  Calendar sync runs automatically every 15 minutes, so events you add to Google Calendar are reflected on your booking page shortly after.
</Tip>

## Multi-Host Conflict Logic

When an event type has more than one host, Clarky decides which time slots to offer based on the scheduling type:

<Tabs>
  <Tab title="One-on-One / Collective">
    **All hosts must be free.** A single host with a conflict blocks the time slot for everyone. Use this when every host needs to attend the same meeting.
  </Tab>

  <Tab title="Round Robin">
    **At least one host must be free.** A time slot is only blocked if every host is busy. Use this when any teammate can take the booking.
  </Tab>
</Tabs>

## Disconnecting and Changing Calendar Settings

From the **Availability** tab on any event type:

* **Disconnect** the Google account entirely
* **Change which calendars** are checked for conflicts
* **Change which calendar** new bookings are added to
* **Pause sync** by toggling "add bookings to calendar"

## Troubleshooting

<AccordionGroup>
  <Accordion title="No time slots are showing up">
    Check that:

    * The event type is **active**
    * You've configured working hours for the days you expect
    * The day isn't blocked by time off or a date override
    * You haven't hit the maximum bookings per day limit
    * The date is within the **maximum days ahead** window
  </Accordion>

  <Accordion title="Wrong day showing as available">
    Working hours are stored in your timezone. If you set Monday 9–5 in New York, an invitee in Tokyo sees that as a different time of day, but it's still Monday on your calendar.

    Double-check the timezone shown at the top of your schedule editor.
  </Accordion>

  <Accordion title="A Google Calendar event isn't blocking my availability">
    * Make sure that calendar is enabled for **conflict detection** in your connection settings
    * Calendar sync runs every 15 minutes — wait a few minutes and refresh
    * Check that the event isn't marked "free" in Google Calendar (free events don't block)
  </Accordion>

  <Accordion title="Bookings aren't appearing in my Google Calendar">
    * Check that **add bookings to calendar** is enabled in your connection settings
    * Confirm you've selected a destination calendar
    * Make sure your Google connection is still authorized (re-connect if it expired)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Booking Flow" icon="check" href="/features/booking/booking-flow">
    See what invitees experience
  </Card>

  <Card title="Event Types" icon="calendar" href="/features/booking/event-types">
    Configure meeting templates
  </Card>
</CardGroup>


# The Booking Flow
Source: https://docs.clarky.ai/features/booking/booking-flow

What invitees experience when they book a time on your calendar

## The Public Booking Page

Every event type has a public booking page at `/b/[event-slug]`. Share this link in emails, on your website, on social — anywhere. Invitees don't need an account to book.

The booking page walks invitees through a clean three-step flow.

## The Three Steps

<Steps>
  <Step title="Pick a Date">
    A monthly calendar shows available dates highlighted. Unavailable dates — based on your working hours, time off, and existing bookings — are grayed out.
  </Step>

  <Step title="Pick a Time">
    Once a date is picked, available time slots appear. Times display in the invitee's detected timezone, but they can switch to a different one if needed.
  </Step>

  <Step title="Enter Details">
    The invitee enters their name and email (required), and optionally their phone number, notes, and answers to any custom questions you've configured.
  </Step>
</Steps>

After submitting, the invitee sees a confirmation screen with the meeting details and any custom confirmation message you've written.

## What Happens After Booking

Behind the scenes, Clarky:

<CardGroup>
  <Card title="Creates the Booking" icon="database">
    A booking record is created and linked to the invitee
  </Card>

  <Card title="Adds to Google Calendar" icon="calendar-plus">
    If the host has Google Calendar connected, the event is added automatically
  </Card>

  <Card title="Generates a Meet Link" icon="video">
    For Google Meet event types, a unique Meet link is created via Google
  </Card>

  <Card title="Sends Confirmation Email" icon="envelope">
    With meeting details, an ICS attachment, and reschedule/cancel links
  </Card>
</CardGroup>

## The Confirmation Email

Every invitee gets a confirmation email immediately after booking. It includes:

* **Meeting details** — date, time, duration, location
* **The Google Meet link** (for Google Meet event types)
* **An ICS calendar file** they can add to any calendar app
* **A reschedule link** (if rescheduling is enabled)
* **A cancel link**

The host also gets the meeting on their connected Google Calendar with the invitee added as an attendee.

<Note>
  For event types that **require confirmation**, the booking starts as pending. The invitee gets a confirmation email only after a workspace admin confirms it from the booking detail view.
</Note>

## Rescheduling

If you've enabled rescheduling on the event type, invitees can change their meeting time without contacting you.

<Steps>
  <Step title="Click Reschedule">
    The invitee opens the link in their confirmation email.
  </Step>

  <Step title="Pick a New Time">
    They see your current availability and pick a new date and time.
  </Step>

  <Step title="Confirmation Sent">
    The original booking is updated, your Google Calendar event is moved, and a new confirmation email is sent.
  </Step>
</Steps>

You can cap how many times a single booking can be rescheduled. Once the limit is hit, the link stops working and the invitee has to cancel and rebook instead.

## Cancellation

Either side can cancel a booking:

* **The invitee** clicks the cancel link in their confirmation email and optionally provides a reason
* **A workspace admin** opens the booking from the admin calendar and clicks cancel

When a booking is cancelled:

* The status changes to cancelled and the time slot opens back up
* The Google Calendar event is deleted (Google notifies all attendees)
* A cancellation email is sent to the invitee
* The reason is recorded in the booking history

## The Admin Calendar

Workspace admins can see, manage, and create bookings from **Booking > Calendar**.

<Tabs>
  <Tab title="List View">
    Upcoming bookings in chronological order. Best for quickly scanning what's coming up.
  </Tab>

  <Tab title="Week View">
    A 7-day grid. Best for seeing your week at a glance.
  </Tab>

  <Tab title="Month View">
    A monthly overview. Best for spotting busy days and gaps.
  </Tab>
</Tabs>

Filter the calendar by status (pending, confirmed, cancelled, completed, no-show), event type, or date range.

## Managing a Booking

Click any booking to open the detail view, where admins can:

* **Confirm** a pending booking (sends the confirmation email and creates the calendar event)
* **Reschedule** to a different time
* **Cancel** with an optional reason
* **Mark as completed** after the meeting happens
* **Mark as no-show** if the invitee didn't show up
* Add **internal notes** that are only visible to your team

<Tip>
  Marking past bookings as **completed** or **no-show** keeps your calendar tidy and improves reporting on your sales pipeline.
</Tip>

## Reminder Emails and Texts

If you've configured reminders on the event type, invitees automatically receive emails or SMS messages a set number of hours before their meeting.

For example, a 24-hour and 1-hour reminder schedule sends:

* An email or SMS one day before the meeting
* A second one an hour before

<Warning>
  Reminders only go out for **confirmed** bookings. Pending bookings won't trigger reminders until they're confirmed.
</Warning>

## Next Steps

<CardGroup>
  <Card title="In-Chat Booking" icon="messages" href="/features/booking/in-chat-booking">
    Book meetings inside conversations
  </Card>

  <Card title="Event Types" icon="calendar" href="/features/booking/event-types">
    Customize what invitees can book
  </Card>
</CardGroup>


# Event Types
Source: https://docs.clarky.ai/features/booking/event-types

Create the meeting templates people can book on your calendar

## What is an Event Type?

An event type is a template for a bookable meeting — for example, a 15-minute discovery call or a 60-minute strategy session. Each event type has its own duration, location, hosts, availability, and booking link.

Event types live at the workspace level, so you can share the same event type across multiple AI assistants in your workspace.

## Creating an Event Type

<Steps>
  <Step title="Go to Event Types">
    Open **Booking > Event Types** and click **New Event Type**.
  </Step>

  <Step title="Fill in the Basics">
    Name, description, duration, and the URL slug for the public booking link.
  </Step>

  <Step title="Pick a Location">
    Choose how the meeting will happen (Google Meet, Zoom, Teams, phone, or in-person).
  </Step>

  <Step title="Add Hosts">
    Select one or more workspace members who will host this meeting.
  </Step>

  <Step title="Save and Share">
    Your event type gets a public link at `/b/[your-slug]` that you can share anywhere.
  </Step>
</Steps>

## Event Type Fields

<AccordionGroup>
  <Accordion title="Name and Description">
    The name appears at the top of the booking page. The description explains what the meeting is about and shows up under the name. Both are visible to invitees.
  </Accordion>

  <Accordion title="Duration">
    How long the meeting lasts, in minutes. Common choices: 15, 30, 45, 60. The booking page shows time slots in increments of this length.
  </Accordion>

  <Accordion title="Slug">
    The URL-friendly identifier used in the booking link. For example, a slug of `discovery-call` produces a link at `/b/discovery-call`. Pick something short and memorable.
  </Accordion>

  <Accordion title="Location Type">
    Where the meeting happens:

    * **Google Meet** — Clarky generates a Meet link automatically when the host has Google Calendar connected
    * **Zoom** — paste your meeting link or personal Zoom room
    * **Microsoft Teams** — paste your Teams meeting link
    * **Phone** — Clarky shares the invitee's phone number with the host
    * **In-Person** — provide the address or location details
  </Accordion>

  <Accordion title="Color">
    A visual identifier shown on the admin calendar so different event types are easy to scan at a glance.
  </Accordion>

  <Accordion title="Active / Inactive">
    Inactive event types stop accepting new bookings and disappear from public booking pages. Existing bookings are unaffected.
  </Accordion>
</AccordionGroup>

## Scheduling Type

If your event type has more than one host, the **scheduling type** controls how invitees are matched to hosts:

<Tabs>
  <Tab title="One-on-One">
    A single host runs the meeting. The invitee books with that one person.
  </Tab>

  <Tab title="Round Robin">
    Bookings rotate across the host pool. A time slot is offered as long as **at least one** host is free at that time. Great for sales teams or support shifts where any teammate can take the call.
  </Tab>

  <Tab title="Collective">
    Everyone joins the same meeting. A time slot is only offered when **every** host is free. Use this for panel interviews or team intros.
  </Tab>

  <Tab title="Group">
    A single host meets with multiple invitees in the same session. Use this for office hours, group demos, or webinars.
  </Tab>
</Tabs>

<Tip>
  For round-robin, set host **priority** to control the order Clarky tries to assign bookings.
</Tip>

## Booking Rules

Each event type lets you control when and how often it can be booked:

<AccordionGroup>
  <Accordion title="Minimum Notice">
    The shortest amount of time between now and a bookable slot. For example, a 4-hour minimum prevents same-day last-minute bookings.
  </Accordion>

  <Accordion title="Maximum Days Ahead">
    How far into the future invitees can book. A 60-day window is a common default.
  </Accordion>

  <Accordion title="Buffer Times">
    Block extra time before and/or after each meeting to prevent back-to-back calls. For example, a 10-minute buffer after a 30-minute call gives you time to write notes.
  </Accordion>

  <Accordion title="Maximum Bookings Per Day">
    Cap how many of this event type can happen in a single day. Once the limit is reached, the day disappears from the booking page.
  </Accordion>

  <Accordion title="Requires Confirmation">
    When enabled, new bookings start as **pending** and need a workspace admin to approve them before they're confirmed. The invitee gets a confirmation email only after you confirm.
  </Accordion>

  <Accordion title="Allow Reschedule">
    Lets invitees reschedule from the link in their confirmation email. You can also cap the number of times a single booking can be rescheduled.
  </Accordion>
</AccordionGroup>

## Custom Booking Questions

Beyond the standard name, email, and notes fields, you can add custom questions invitees must answer when booking. Use these to qualify leads, gather context, or collect information your team needs before the meeting.

Examples:

* "What's your company size?"
* "What problem are you trying to solve?"
* "Have you used a tool like ours before?"

Responses appear in the booking detail view alongside the meeting.

## Reminders

Set automatic reminder emails and SMS messages before each meeting. Configure how many hours before the meeting to send each reminder — for example, 24 hours and 1 hour before.

<Note>
  Reminders are only sent for **confirmed** bookings, not pending ones.
</Note>

## Confirmation Message and Cancellation Policy

* **Confirmation message** — what the invitee sees on the success screen after booking
* **Cancellation policy** — what the invitee sees if they try to cancel

Use plain language. These are great places to set expectations like "We'll send a Google Meet link by email" or "Please cancel at least 24 hours in advance."

## Choosing Which Event Types Each Bot Offers

Event types are workspace-wide, but you can pick which ones each AI assistant offers. Open the event types list to see a chip for every assistant in your workspace next to each event type. Click a chip to toggle whether that assistant can offer that event type in chat or voice.

<Info>
  By default, every assistant offers every active event type. Per-assistant selection is only needed if you want to scope event types — for example, a sales assistant that only offers discovery calls and a support assistant that only offers triage sessions.
</Info>

## Next Steps

<CardGroup>
  <Card title="Set Availability" icon="clock" href="/features/booking/availability">
    Configure working hours and Google Calendar
  </Card>

  <Card title="Booking Flow" icon="check" href="/features/booking/booking-flow">
    Preview what invitees see
  </Card>
</CardGroup>


# In-Chat Booking
Source: https://docs.clarky.ai/features/booking/in-chat-booking

Let your AI assistant book meetings directly in chat, voice, SMS, and email conversations

## Booking Without Leaving the Conversation

Your AI assistant doesn't just answer questions — it can book meetings on your calendar in the same conversation. When a customer says "Can we hop on a call this week?", the assistant offers available times, takes their details, and confirms the booking, all without sending them to a separate booking page.

## What It Looks Like in Each Channel

<Tabs>
  <Tab title="Chat">
    The assistant detects intent to book and renders a booking widget inline in the chat. The customer picks a date, picks a time, and enters their details — right there in the chat window. Once confirmed, the assistant follows up with a friendly summary.

    If you have multiple event types, the assistant first asks which one to book (or shows a picker). If only one event type is enabled, it goes straight to dates and times.
  </Tab>

  <Tab title="Voice">
    On a phone call, the assistant walks through booking conversationally:

    1. Lists the available event types ("Would you like a 30-minute intro call or a 60-minute deep dive?")
    2. Confirms which one to book
    3. Reads off available times for the customer's preferred day
    4. Confirms the time the customer picks
    5. Captures their name, email, and phone
    6. Books and reads back the confirmation

    The customer never has to type anything — the whole booking happens by voice.
  </Tab>

  <Tab title="SMS">
    The assistant replies with a booking link plus a quick summary of the next available times. The customer taps the link to complete the booking on the public page.

    For simple cases, the assistant can also book directly without redirecting the customer.
  </Tab>

  <Tab title="Email">
    The assistant includes a booking link in its email reply, formatted with the next few available time slots. The customer clicks the link to pick a time.
  </Tab>
</Tabs>

## How the Assistant Decides When to Book

Your AI assistant uses your event types and availability automatically. You don't need to write special instructions for booking — when a customer expresses interest in scheduling, the assistant offers it.

You can shape the experience by:

* **Limiting which event types** an assistant offers (configure per-bot from the event types list)
* **Updating event type names and descriptions** so the assistant has clear context to share
* **Configuring custom questions** so the assistant gathers qualifying info before booking

<Tip>
  A short, descriptive event type name like "30-min Discovery Call" works much better than something generic like "Meeting" — it gives the AI clear language to use in conversation.
</Tip>

## After the Booking

Once a customer books in conversation:

<CardGroup>
  <Card title="Confirmation Email" icon="envelope">
    Sent to the customer with the meeting details
  </Card>

  <Card title="Calendar Event" icon="calendar-check">
    Added to the host's connected Google Calendar
  </Card>

  <Card title="Inbox Update" icon="inbox">
    The conversation continues with the assistant's confirmation
  </Card>

  <Card title="CRM Link" icon="users">
    The booking is associated with the customer's contact record
  </Card>
</CardGroup>

## Switching Booking Providers

If you use Calendly or Cal.com instead of Clarky's built-in scheduler, your AI assistant uses those instead. Switch providers from **Booking > Settings** — see the [providers guide](/features/booking/providers) for setup.

<Note>
  Each AI assistant uses one booking provider at a time. The assistant's chat, voice, SMS, and email flows all use the same provider you've selected.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The assistant isn't offering to book">
    * Make sure your workspace has at least one **active** event type
    * Confirm the event type is enabled for that specific assistant (check the chips on the event types list)
    * Verify your booking provider is set in **Booking > Settings**
  </Accordion>

  <Accordion title="The assistant offers booking but no times are available">
    Check the [Availability guide](/features/booking/availability) — usually no slots means working hours aren't set, the date is outside your max-days-ahead window, or all hosts are busy on connected calendars.
  </Accordion>

  <Accordion title="In voice, the assistant isn't completing the booking">
    Voice booking uses a step-by-step flow. If the assistant gets stuck, the customer can usually re-state their preferred time clearly, or you can fall back to sending them the public link.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Booking Providers" icon="plug" href="/features/booking/providers">
    Use Calendly or Cal.com instead
  </Card>

  <Card title="Event Types" icon="calendar" href="/features/booking/event-types">
    Configure what assistants can book
  </Card>
</CardGroup>


# AI Meeting Briefs
Source: https://docs.clarky.ai/features/booking/meeting-briefs

Clarky researches every guest before your meetings and delivers a prep brief with the goal, who matters, what changed, and the questions worth asking

## What are Meeting Briefs?

Turn on Meeting Briefs for an event type and Clarky prepares you for every booking automatically. Before the meeting starts, Clarky studies the guest's entire history with your workspace (contact and company records, emails, chats, notes, past meeting recordings, and their booking answers), reads their company's website, and sends the meeting host a short, skimmable brief by push notification and email.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What a brief contains

Every brief follows the same structure, written to be read on your phone a minute before the call:

* **Goal**: what you should walk out of the meeting with
* **Stakes**: why this meeting matters and what kind of conversation it is
* **Who matters**: the guest and anyone else relevant, with the context that matters right now
* **What changed**: developments since you last talked
* **Watch for**: risks, open questions, and things to handle early
* **Use this**: specific questions to ask and lines to say
* **Sources**: links that informed the brief, like the guest's LinkedIn or company site

Briefs are built only from real evidence in your CRM and the guest's public web presence. If Clarky does not know something, the section stays empty rather than guessing.

## Key Features

<CardGroup>
  <Card title="Automatic Research" icon="magnifying-glass">
    Contact history, conversations, notes, past meeting recordings, booking answers, and the guest's company website, gathered without lifting a finger
  </Card>

  <Card title="Delivered Before the Call" icon="bell">
    Arrives as a push notification and a formatted email at the lead time you choose, from 15 minutes to a day ahead
  </Card>

  <Card title="Attached to the Meeting" icon="calendar-check">
    Read the brief on the booking in your calendar; after the call it appears as a Brief tab next to the meeting's notes and transcript
  </Card>

  <Card title="Plan vs. Reality" icon="messages">
    The meeting chat knows the brief, so afterwards you can ask whether everything you planned to cover was actually covered
  </Card>
</CardGroup>

## Turning briefs on

<Steps>
  <Step title="Open the event type">
    Go to **Booking, Event Types** and open the event type you want briefs for.
  </Step>

  <Step title="Set the lead time">
    In the **Reminders** tab, find **AI Meeting Brief** and choose when the brief should arrive: 15 minutes, 30 minutes, 1 hour, 2 hours, or 1 day before the meeting. Choose **Off** to disable it.
  </Step>

  <Step title="Choose who gets notified">
    Briefs go to the meeting's assigned host (or the event type's hosts). Each person can turn the push and email delivery on or off under **Notifications** with the **Meeting Brief** toggles.
  </Step>
</Steps>

## Generating a brief on demand

You do not have to wait for the automatic schedule, and briefs are not limited to event types that have them turned on. Open any booking on the calendar and click **Generate brief** in the booking details. Clarky researches the guest on the spot, usually in under a minute, and the brief appears right there. On-demand briefs are shown in place rather than sent by push or email.

## Where briefs live

* **Calendar**: open any booking on the calendar and the brief appears in the booking details once it has been generated.
* **Meeting recordings**: when a recording from your notetaker matches the booking, the recording page gains a **Brief** tab alongside Notes, Transcript, and Chat, so the plan and the outcome live together. See [Meeting Recordings](/features/booking/meeting-recordings).
* **Email**: the full brief is in the notification email, with the guest's name linked to their CRM record.

<Note>
  Briefs are internal prep notes for your team. They are never shown to the guest, and meeting recordings shared by public link never include the brief.
</Note>


# Meeting Recordings
Source: https://docs.clarky.ai/features/booking/meeting-recordings

Clarky's built-in AI notetaker joins your meetings, records them, and writes the notes, with everything filed on your calendar and CRM

## The Clarky Notetaker

Clarky has a built-in AI notetaker. It joins your Google Meet, Zoom, and Microsoft Teams calls, records them, and writes AI meeting notes from the transcript. Every meeting lands in Clarky with the recording, the notes, and the full transcript, matched to the calendar booking it belongs to and linked to your CRM contacts by attendee email. You can ask Clarky questions about any meeting and get answers straight from what was said.

It works two ways, and you can use both at once:

* **Clarky bookings**: any confirmed booking with a video link gets recorded automatically.
* **Your Google Calendar**: connect your calendar and the notetaker joins every meeting with a video link, even ones that were never booked through Clarky. No event types or booking links required.

<Info>
  **Plan availability:** The Clarky Notetaker is available on Standard plans and above. Syncing a third-party notetaker (like Fellow) works on all plans. See [Plans & Billing](/features/settings/plans).
</Info>

## Key Features

<CardGroup>
  <Card title="Joins and Records for You" icon="video">
    Works on Google Meet, Zoom, and Microsoft Teams; joins about a minute before the meeting starts
  </Card>

  <Card title="Your Name and Photo" icon="user">
    Give the notetaker a custom name and profile picture so it joins meetings as part of your team
  </Card>

  <Card title="AI Notes and Transcript" icon="file-lines">
    A TL;DR, key points, decisions, and action items, plus the full speaker-by-speaker transcript
  </Card>

  <Card title="Recording Playback" icon="play">
    Watch or listen to the meeting right inside Clarky
  </Card>

  <Card title="Automatic Booking Match" icon="calendar-check">
    Recordings attach to the right calendar booking using the attendee list and meeting time
  </Card>

  <Card title="CRM Contact Linking" icon="address-book">
    Attendees that match CRM contacts get a meeting activity on their timeline
  </Card>

  <Card title="Ask About This Meeting" icon="sparkles">
    A built-in AI chat that answers questions from the notes and transcript
  </Card>

  <Card title="Team Notifications" icon="bell">
    Your team is notified when a new recording arrives
  </Card>
</CardGroup>

## Turn It On

<Steps>
  <Step title="Open Meeting Recordings settings">
    Go to **Settings > Meeting Recordings** in your workspace and flip on the **Clarky Notetaker**.
  </Step>

  <Step title="Choose what gets recorded">
    Two toggles control coverage: **Record Clarky bookings** and **Record Google Calendar meetings**. Calendar recording needs a connected Google Calendar (set up under **Calendar > Settings**).
  </Step>

  <Step title="Make it yours">
    Set the **notetaker name** and upload a **photo** (your company logo or a headshot). That is the identity everyone sees when it joins a meeting. Left alone, it joins as "Clarky Notetaker" with a "Clarky is recording" badge, so everyone on the call knows the meeting is being recorded.
  </Step>
</Steps>

## Control It Per Meeting

* **From the Calendar screen**: meetings from your connected Google Calendar appear alongside your bookings. Click one and use the **Record with Clarky Notetaker** switch to record or skip just that meeting, without changing your workspace default.
* **Record a meeting right now**: on **Calendar > Recordings**, click **Record a meeting**, paste any Google Meet, Zoom, or Teams link, and the notetaker joins immediately. Great for meetings on someone else's calendar.

## What Happens After a Meeting

When the meeting ends, Clarky automatically:

1. **Transcribes the recording** and writes AI notes: a TL;DR, key points, decisions, and action items.
2. **Stores the recording** so you can watch or listen to it later inside Clarky.
3. **Matches it to the booking** it belongs to, using the attendee emails and the meeting time.
4. **Links matched attendees to your CRM**, adding a meeting activity to each matching contact and company timeline.
5. **Notifies your team** (notification preferences are configurable per user under Notifications).

Notes and the transcript usually land within a few minutes of the meeting ending.

## Recordings on Your Calendar

* In the **week and month views**, bookings that have a recording show a small video icon on the event, and calendar meetings that will be recorded show one too.
* In the **list view**, recorded meetings show a Recording label.
* Opening a booking shows a **Recording** section that jumps to the notes and transcript.

## The Recordings Screen

Find every recording under **Calendar > Recordings**. The list shows when each meeting happened, how long it ran, who attended, and which booking and CRM contacts it matched.

Click any recording to open it:

* **Notes tab**: the AI-generated summary, decisions, and action items.
* **Transcript tab**: the full conversation, grouped by speaker.
* **Recording tab**: play the video or audio of the meeting. Playback keeps going when you switch to the Notes or Transcript tabs, and the video pops out into a floating picture-in-picture window so you can read along.
* **Ask about this meeting**: a chat panel that answers questions using only the notes and transcript. Try "What were the action items?", "Summarize the key decisions", or "What objections came up?"

While a meeting is still being transcribed, the Notes and Transcript tabs show a progress state and update on their own; notes usually land a couple of minutes after the meeting ends. Want the storage space back? **Delete video** (or audio) under the player permanently removes the file after a confirmation, while the notes and transcript stay.

<Tip>
  Meeting activities are also searchable from [Ask Clarky](/features/crm/ask-clarky), so you can ask things like "when did we last meet with Acme?" from anywhere.
</Tip>

## Using a Third-Party Notetaker Instead

Already paying for a notetaker like [Fellow](https://fellow.app)? Clarky can sync its finished recordings instead of (or alongside) the built-in notetaker:

<Steps>
  <Step title="Copy your webhook URL">
    Under **Settings > Meeting Recordings**, the Fellow card shows a unique webhook URL for your workspace.
  </Step>

  <Step title="Add the webhook in Fellow">
    In Fellow, open **User settings > API, MCP & Webhooks > Webhooks**, add a webhook pointing at the URL, and subscribe it to the **AI Note Generated** event.
  </Step>

  <Step title="Save the signing secret">
    Copy the signing secret Fellow gives you (it starts with `whsec_`) into the Signing secret field in Clarky and save.
  </Step>
</Steps>

<Note>
  If both the Clarky Notetaker and a third-party notetaker cover the same meeting, you will get two copies of it. Pick one recorder per meeting source.
</Note>

## Learn More

<CardGroup>
  <Card title="Booking Overview" icon="calendar-days" href="/features/booking/overview">
    How scheduling works in Clarky
  </Card>

  <Card title="Meeting Briefs" icon="lightbulb" href="/features/booking/meeting-briefs">
    AI research on every guest before the meeting starts
  </Card>

  <Card title="Ask Clarky" icon="sparkles" href="/features/crm/ask-clarky">
    Your AI assistant for CRM questions
  </Card>

  <Card title="Plans & Billing" icon="credit-card" href="/features/settings/plans">
    What each plan includes
  </Card>
</CardGroup>


# Booking Overview
Source: https://docs.clarky.ai/features/booking/overview

Let people schedule meetings with you directly from chat, voice, email, or a public page

## What is Booking?

Booking is Clarky's built-in scheduling system. Customers can pick a time on a public booking page, get a confirmation email with a Google Meet link, and add the meeting to their calendar — all without you lifting a finger. Your AI assistant can also offer time slots and complete bookings inside chat, voice calls, SMS, and email conversations.

<Info>
  **Plan availability:** Available on all plans. See [Plans & Billing](/features/settings/plans).
</Info>

## Key Features

<CardGroup>
  <Card title="Public Booking Page" icon="calendar-days">
    A clean three-step flow: pick a date, pick a time, enter details
  </Card>

  <Card title="Google Calendar Sync" icon="calendar-check">
    Connect Google Calendar to block conflicts and add bookings automatically
  </Card>

  <Card title="Google Meet Links" icon="video">
    Auto-generated for every Google Meet event type
  </Card>

  <Card title="Reminders" icon="bell">
    Configurable email and SMS reminders before each meeting
  </Card>

  <Card title="Reschedule and Cancel" icon="rotate">
    Invitees manage their own bookings from links in the confirmation email
  </Card>

  <Card title="Multi-Host Support" icon="users">
    Round-robin or collective scheduling across teammates
  </Card>
</CardGroup>

## Choose Your Provider

Clarky supports three booking providers. Pick the one that matches how your team already schedules:

<Tabs>
  <Tab title="Clarky (default)">
    The built-in scheduler. Includes Google Calendar sync, native event types, multi-host support, and full AI agent integration. Recommended for most workspaces.
  </Tab>

  <Tab title="Calendly">
    Connect your existing Calendly account with a Personal Access Token. Your AI assistant will surface your Calendly event types in chat and email.
  </Tab>

  <Tab title="Cal.com">
    Connect your Cal.com account using your Cal link (for example, `yourname/30min`). Your AI assistant will offer Cal.com event types to invitees.
  </Tab>
</Tabs>

<Note>
  You can switch providers at any time from **Booking > Settings**. Switching changes which event types your AI assistant offers.
</Note>

## Where Booking Happens

Customers can book a meeting from any of these entry points:

* **Public booking page** at `/b/[event-slug]` — share the link anywhere
* **Embedded widget** on your website
* **Chat** — the AI offers a date and time picker inline
* **Voice calls** — the AI walks the caller through booking conversationally
* **SMS** — the AI sends a booking link with available times
* **Email** — the AI includes a booking link in its reply

## Getting Started

<Steps>
  <Step title="Open Booking">
    Click **Booking** in your workspace navigation.
  </Step>

  <Step title="Create an Event Type">
    Define what meeting people can book — name, duration, location, and who hosts it.
  </Step>

  <Step title="Set Your Availability">
    Configure working hours and connect your Google Calendar to block real conflicts.
  </Step>

  <Step title="Share Your Booking Link">
    Send the public link, embed the widget, or let your AI assistant handle bookings in conversation.
  </Step>
</Steps>

## Learn More

<CardGroup>
  <Card title="Event Types" icon="calendar" href="/features/booking/event-types">
    Create and configure bookable meetings
  </Card>

  <Card title="Availability" icon="clock" href="/features/booking/availability">
    Working hours, schedules, and Google Calendar
  </Card>

  <Card title="Booking Flow" icon="check" href="/features/booking/booking-flow">
    What invitees see when they book a time
  </Card>

  <Card title="In-Chat Booking" icon="messages" href="/features/booking/in-chat-booking">
    Let your AI assistant book meetings inline
  </Card>

  <Card title="Booking Providers" icon="plug" href="/features/booking/providers">
    Use Calendly or Cal.com instead of Clarky
  </Card>

  <Card title="Inbox" icon="inbox" href="/features/inbox/overview">
    Manage the conversations that lead to bookings
  </Card>
</CardGroup>


# Booking Providers
Source: https://docs.clarky.ai/features/booking/providers

Use Clarky's built-in scheduler, or connect Calendly or Cal.com

## Choosing a Provider

Clarky supports three booking providers. Each AI assistant uses one provider at a time, set from **Booking > Settings**.

<CardGroup>
  <Card title="Clarky" icon="calendar">
    Built-in scheduler with full feature support
  </Card>

  <Card title="Calendly" icon="link">
    Connect your existing Calendly account
  </Card>

  <Card title="Cal.com" icon="link">
    Connect your existing Cal.com account
  </Card>
</CardGroup>

## Clarky (Default)

The built-in scheduler. No extra setup — it's enabled out of the box.

**Use Clarky when you want:**

* Native Google Calendar sync and Google Meet generation
* Multi-host scheduling (round-robin, collective)
* Custom booking questions and confirmation messages
* Full integration with the AI assistant in chat, voice, SMS, and email
* Reminders and configurable buffer times

If Clarky covers your needs, stop here — you don't need to set up another provider.

## Calendly

Connect your Calendly account to use your existing event types.

<Steps>
  <Step title="Open Booking Settings">
    Go to **Booking > Settings**.
  </Step>

  <Step title="Select Calendly">
    Choose **Calendly** as your booking provider.
  </Step>

  <Step title="Get a Personal Access Token">
    Sign in to Calendly and go to **Integrations > API & Webhooks**. Create a new Personal Access Token and copy it.

    <Warning>
      Treat your Personal Access Token like a password. Anyone with it can read and modify your Calendly events.
    </Warning>
  </Step>

  <Step title="Paste the Token">
    Paste the token into Clarky and save. Clarky validates the token with Calendly automatically.
  </Step>

  <Step title="Test in Conversation">
    Ask your AI assistant to schedule a meeting. It will offer your Calendly event types.
  </Step>
</Steps>

<Note>
  With Calendly selected, your AI assistant offers Calendly event types in chat and email. Calendar conflicts, working hours, and Meet links are all managed through Calendly.
</Note>

## Cal.com

Connect your Cal.com account using your Cal link.

<Steps>
  <Step title="Open Booking Settings">
    Go to **Booking > Settings**.
  </Step>

  <Step title="Select Cal.com">
    Choose **Cal.com** as your booking provider.
  </Step>

  <Step title="Find Your Cal Link">
    In Cal.com, your booking link looks like `cal.com/yourname/30min`. Copy the part after `cal.com/` — for example, `yourname/30min`.
  </Step>

  <Step title="Paste Your Cal Link">
    Paste the link into Clarky and save.
  </Step>

  <Step title="Test in Conversation">
    Ask your AI assistant to schedule a meeting. It will share your Cal.com link.
  </Step>
</Steps>

## Switching Providers

You can switch booking providers any time from **Booking > Settings**. Switching changes which event types your AI assistant offers in conversation, but doesn't delete data from your other providers.

<Info>
  Existing bookings made through one provider stay where they are when you switch. For example, switching from Clarky to Calendly leaves your past Clarky bookings on the Clarky calendar — they aren't migrated.
</Info>

## Comparing Features

<AccordionGroup>
  <Accordion title="Native AI assistant integration">
    All three providers work with your AI assistant. Clarky has the deepest integration — including inline booking widgets in chat — while Calendly and Cal.com surface event types and links in conversation.
  </Accordion>

  <Accordion title="Multi-host scheduling">
    Clarky supports collective and round-robin scheduling natively. Calendly and Cal.com handle their own multi-host logic on their side.
  </Accordion>

  <Accordion title="Google Meet links">
    Clarky generates Meet links automatically when the host has Google Calendar connected. Calendly and Cal.com generate Meet links according to their own settings.
  </Accordion>

  <Accordion title="Custom branding and questions">
    All three providers support custom event names, descriptions, and booking questions through their own UI.
  </Accordion>

  <Accordion title="Reminders">
    All three providers send reminder emails. Clarky also supports SMS reminders configured per event type.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Event Types" icon="calendar" href="/features/booking/event-types">
    Set up Clarky event types
  </Card>

  <Card title="In-Chat Booking" icon="messages" href="/features/booking/in-chat-booking">
    See how the assistant uses your provider
  </Card>
</CardGroup>


# Documents
Source: https://docs.clarky.ai/features/context/documents

Write, edit and organize what your agent knows

## The Documents list

**Context > Documents** lists every document your agent can draw on: text you wrote, uploaded files, crawled website pages and Q\&A pairs. Use the search box, the type filter (All / Text / Files / Website / Q\&A) and the channel filter to find things. Click any column header to sort.

Each row shows:

* The title (and URL or file name), with a **Pinned** badge when it is always included
* One column per channel. A filled dot means the document is used there. **Click a dot to toggle** that channel without opening the document.
* Size, status (Ready / Processing / Error / Disabled) and when it was last updated
* A menu with Edit, Enable/Disable, Always include / Unpin, Re-index and Delete

## Writing a document

<Steps>
  <Step title="Add > Write text">
    Give it a clear title, for example "What is Acme", "Refund policy", "Sales playbook".
  </Step>

  <Step title="Add the content">
    Plain text or markdown. Write the way you would explain it to a new hire. There is no hard size limit, but a document over a few thousand characters should probably not be pinned.
  </Step>

  <Step title="Choose channels">
    Check the channels this document applies to. Voice shows a reminder that voice documents are sent in full at call start.
  </Step>

  <Step title="Pinned or retrieved">
    Turn on **Always include** for the essentials (who you are, core rules). Leave it off for reference material; the agent pulls that in only when a question calls for it.
  </Step>

  <Step title="Create">
    The document is indexed in a few seconds and shows **Ready**.
  </Step>
</Steps>

## Create from website

If a website is connected, **Add > Create from website** reads all crawled pages and writes a new pinned *About \<company>* document with the essentials (services, contact info, hours). Review and edit it afterwards; it is a starting point, not a final answer.

## Editing and managing

* **Edit** any document, including website pages and file text, by clicking its row.
* **Disable** to stop the agent using it without deleting it.
* **Delete** removes it immediately. Website pages come back on the next crawl if the page still exists.
* **Re-index** rebuilds the search index for a document (or re-scrapes a website page). Use it if a document shows **Error**.

## Status meanings

| Status       | Meaning                                                                                 |
| ------------ | --------------------------------------------------------------------------------------- |
| Ready        | Indexed and in use on its channels                                                      |
| Processing   | Being converted or indexed; usually a few seconds                                       |
| Error        | Something failed (hover for details). Re-index, or edit and save.                       |
| Disabled     | Kept but not used                                                                       |
| Needs answer | A Q\&A captured from a conversation, waiting for you (see [Q\&A](/features/context/qa)) |


# Files
Source: https://docs.clarky.ai/features/context/files

Upload PDFs, Word documents, text and markdown

## Supported files

Upload **PDF**, **Word (.docx)**, **text**, **markdown**, **CSV**, **HTML** or **JSON**, up to **25 MB** each. You can select several at once or drag them onto the upload box.

Clarky converts each file to plain text and creates one document per file. The text is fully editable afterwards, so you can fix anything the conversion got wrong or trim sections you do not want the agent to use.

<Note>
  Scanned PDFs (images of pages with no text layer) cannot be read. Run them through OCR first, or paste the text into a document instead.
</Note>

## Uploading

<Steps>
  <Step title="Add > Upload files">
    From **Context > Documents**.
  </Step>

  <Step title="Drop your files">
    Or click to browse. Remove any file from the list before uploading with the ×.
  </Step>

  <Step title="Choose channels">
    Applied to every file in this batch. You can change channels per document later.
  </Step>

  <Step title="Upload">
    Each file is converted and indexed. Files that could not be read stay in the list with the reason so you can fix and retry.
  </Step>
</Steps>

## Tips

* Long files are usually best **retrieved** (Always include off). Pinning a 40 page manual sends the whole thing with every message.
* Files checked for **Voice** count against the voice budget in full. Leave long files off Voice.
* Uploading a new version of a file creates a new document; delete the old one when you are done.


# Context
Source: https://docs.clarky.ai/features/context/overview

Everything your agent knows, organized as documents you control per channel

## What is Context?

Context is your agent's knowledge base. Everything it knows about your business is a **document**: text you write, a file you upload, a page crawled from your website, or a question-and-answer pair. Each document is assigned to the channels where it should be used (chat, voice, text, email), so you can keep a sales playbook chat-only, give voice a short script, and let email see everything.

Open it from **Context** in your agent's sidebar.

<CardGroup>
  <Card title="Documents" icon="file-lines" href="/features/context/documents">
    Write text, pin the essentials, choose channels
  </Card>

  <Card title="Files" icon="file-arrow-up" href="/features/context/files">
    Upload PDFs, Word docs, text and markdown
  </Card>

  <Card title="Websites" icon="globe" href="/features/context/websites">
    Crawl your site; every page becomes a document
  </Card>

  <Card title="Q&A" icon="circle-question" href="/features/context/qa">
    FAQs, plus questions your agent could not answer
  </Card>
</CardGroup>

## How your agent uses it

There are two ways a document reaches your agent:

<AccordionGroup>
  <Accordion title="Pinned (Always include)">
    Pinned documents are included in every conversation on their channels, word for word. Use them for who you are, what you sell, hours, contact details, tone, and hard rules. Keep them short; they are sent with every message. Your **About** document (created from your website when you sign up) is pinned by default.
  </Accordion>

  <Accordion title="Retrieved when relevant">
    Everything else is split into passages and searched for each incoming message. Only the passages that match the customer's question are added, so a 200 page website or a long PDF only shows up when it is useful. This keeps replies focused and fast.
  </Accordion>
</AccordionGroup>

<Note>
  **Voice is different.** Phone calls have no per-message retrieval: the whole prompt is sent to the voice provider once when the call starts. Every document checked for Voice is included in full at that moment, pinned or not, up to a **voice budget** of about 40,000 characters. The budget exists mostly for latency; a bigger prompt means a longer pause before each spoken reply. Website pages are never used on Voice. See [Settings](/features/context/settings#voice-budget).
</Note>

## Channels

Every document has four checkboxes: **Chat**, **Voice**, **Text**, **Email**. A document is only used on the channels you check. Defaults:

| Source                      | Default channels              |
| --------------------------- | ----------------------------- |
| Text you write, files, Q\&A | All four                      |
| Website pages               | Chat, Text, Email (Voice off) |

Turn a channel off to keep a document without using it there. Turn every channel off (or disable the document) to park it without deleting it.

## What replaced the old Knowledge screen

If you used Clarky before Context, the mapping is:

* **General knowledge** became a pinned document called *About \<your agent>*, on all channels.
* **Chat / Voice / Text / Email knowledge** boxes each became a pinned *\<Channel> instructions* document on that one channel.
* **Website pages** are now regular documents you can search, edit, disable, or assign to channels one at a time.
* **Files** and **Q\&A** are real now.

Nothing was lost; open Context and you will see all of it as documents.

## Best practices

<AccordionGroup>
  <Accordion title="Pin the essentials, retrieve the rest">
    A short pinned About document plus longer retrieved documents beats one giant pinned wall of text. It is cheaper, faster, and answers are more precise.
  </Accordion>

  <Accordion title="One topic per document">
    "Refund policy", "Pricing 2026", "Sales playbook" retrieve better than a single mixed document, and they are easier to keep current.
  </Accordion>

  <Accordion title="Answer the questions it could not">
    Check **Context > Q\&A** now and then. Every question your agent could not answer is waiting there; answering it teaches the agent immediately.
  </Accordion>

  <Accordion title="Test before customers do">
    **Context > Settings > Test retrieval** shows exactly which documents your agent would use for any question you type.
  </Accordion>
</AccordionGroup>


# Q&A
Source: https://docs.clarky.ai/features/context/qa

FAQs, and the questions your agent could not answer

## Two kinds of Q\&A

**Context > Q\&A** holds question-and-answer pairs. Some you write yourself (FAQs); some your agent brings you.

## Questions it could not answer

Whenever a customer asks a business question on chat, voice, text or email and your agent does not have the answer, the question is captured and added to Q\&A as **Needs an answer**. Each card shows the question (cleaned up into FAQ form), when and on which channel it was asked, how many times it has come up, and a link to the conversation.

<Steps>
  <Step title="Open Context > Q&A">
    Pending questions are listed first. The sidebar shows how many are waiting.
  </Step>

  <Step title="Type the answer">
    Short and direct works best. Press **Save answer** (or Cmd/Ctrl + Enter).
  </Step>

  <Step title="Done">
    The pair goes live immediately on all channels. The next time a similar question comes up, your agent answers it.
  </Step>
</Steps>

Not a real question, or not something you want to answer? Click × to dismiss it. If it is asked again it will reappear with a higher count.

<Note>
  Questions are captured only when the agent lacked the information. Greetings, small talk, questions it did answer, requests to talk to a human and off-topic questions are ignored.
</Note>

## Adding your own FAQs

**Add Q\&A** lets you write a question and its answer directly. Q\&A pairs are matched by question, so phrase them the way customers actually ask. Like any document they have channels and can be pinned, disabled or deleted.


# Context Settings
Source: https://docs.clarky.ai/features/context/settings

Tune retrieval, watch the voice budget, and test what your agent would use

## Retrieval

Documents that are not pinned are split into passages. For every incoming message the closest passages are added to the prompt.

* **Relevance threshold** (0 to 100%): how close a passage has to be to count. Lower finds more, higher is stricter. Around 30% works well for most sites.
* **Passages per message** (1 to 20): how many passages can be added. More gives more coverage and costs a little more per reply.

## Voice budget

Phone calls have no per-message retrieval. Everything checked for **Voice** is sent to the voice provider in full when a call starts, so on voice every document behaves like a pinned one. The budget (about 40,000 characters) keeps that prompt small, mostly for latency: a bigger prompt means a longer pause before each spoken reply, and a higher cost per minute.

The meter on this page (and on the Documents screen) shows how much of the budget your voice documents use. If you go over, the oldest documents are cut off on calls. Website pages never count; they are not used on voice.

## Test retrieval

Type a question a customer might ask and pick a channel. Clarky shows:

* **Always included**: the pinned documents that go with every message on that channel
* **Retrieved for this question**: the documents whose passages cleared the threshold, with a match score and the matched passage

If nothing is retrieved, lower the threshold or add a document that covers the topic. On a real conversation the same question would land in [Q\&A](/features/context/qa) as unanswered.


# Websites
Source: https://docs.clarky.ai/features/context/websites

Crawl your site so every page becomes a document your agent can use

## Connecting a website

When you create an agent from a domain, Clarky crawls the site right away. If your agent has no website yet, **Context > Websites** shows a box to connect one: enter the domain and Clarky starts the first crawl.

We follow links on your domain (up to 250 pages), keep the readable text of each page and drop navigation, images, scripts and forms.

## Pages are documents

Every crawled page shows up in **Context > Websites** (and in Documents under the Website filter) as its own document with the page title and URL. You can:

* **Search** pages by title or URL
* **Edit** the captured text (re-crawling replaces it)
* **Toggle channels** per page, or **Apply channels to all pages** from the site card
* **Disable** individual pages, or use the **Use website pages** switch to turn the whole site off and on
* **Re-scrape page** from a row's menu to refresh just that page
* **Remove** a page (it returns on the next crawl if it still exists)

Website pages default to Chat, Text and Email. Voice is off for pages: voice prompts are fixed at call start, so a whole site cannot be included. Put the essentials in a text document instead.

## Re-crawling

Click **Re-crawl** on the site card whenever your website changes. Pages that still exist are refreshed in place and keep the channels and settings you chose; pages that disappeared from your site are removed when the crawl finishes. Your existing knowledge stays live while the crawl runs.

Re-crawls are limited to once every 6 hours and are available on paid plans.

## Create a document from the website

**Documents > Add > Create from website** summarizes all crawled pages into a new pinned *About \<company>* document. Useful right after a crawl or a big site update.

<Card title="Manage documents" icon="file-lines" href="/features/context/documents">
  See how pages fit alongside text, files and Q\&A
</Card>


# Activity Logging
Source: https://docs.clarky.ai/features/crm/activity

Log notes, calls, meetings, and tasks against contacts and companies

## What is Activity Logging?

Activity logging lets you keep a running record of every interaction you have with a contact or company. Use it to capture notes from a phone call, log a meeting you just wrapped up, schedule a follow-up task, or backdate something you forgot to record at the time.

Every activity you log shows up on the relevant timelines and in the workspace-wide activity feed, so your whole team has shared context on what's happening with each customer.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Unified Dialog" icon="square-pen">
    The same activity dialog works across contacts, companies, and the workspace feed
  </Card>

  <Card title="Backdating" icon="calendar-clock">
    Set explicit dates and times so logs reflect when the activity actually happened
  </Card>

  <Card title="Multi-Contact Tagging" icon="users">
    Log a single meeting or call against several contacts at once
  </Card>

  <Card title="Tasks and Reminders" icon="list-check">
    Add due dates to keep upcoming follow-ups visible
  </Card>
</CardGroup>

## Where You Can Log Activity

There are three places to log activity, and they all share the same dialog and the same activity-type menu.

<Tabs>
  <Tab title="Contact Timeline">
    Open any contact and click **Add** at the top of the timeline. The contact you opened is automatically attached to the activity and locked in, so it can't be removed by accident.

    Use this when the activity belongs clearly to one specific person.
  </Tab>

  <Tab title="Workspace Activity Feed">
    Go to **CRM > Activity** to see the full workspace feed. Click **Add**, choose a type, and search for one or more contacts to tag.

    Use this when you're catching up at the end of the day, logging a meeting that involved several people, or you don't want to navigate to a specific contact first.
  </Tab>

  <Tab title="Company Timeline">
    Open any company and click **Add** on the timeline. You can log activity directly against the company, optionally tagging contacts who were involved.

    Use this for things that are about the account as a whole, like a renewal conversation or a pricing review.
  </Tab>
</Tabs>

<Note>
  No matter which entry point you use, the **Add** button works the same way: pick a type from the dropdown, fill out the dialog, and save.
</Note>

## Choosing an Activity Type

Clicking **Add** opens a dropdown of activity types. Picking a type sets the icon, label, and which extra fields show up in the dialog.

The supported types are:

<AccordionGroup>
  <Accordion title="Note">
    A general written note. Use this for quick observations, internal context, or anything that doesn't fit a more specific type.
  </Accordion>

  <Accordion title="Call">
    A phone call. The dialog shows a duration field so you can record how long the call lasted.
  </Accordion>

  <Accordion title="Meeting">
    An in-person or video meeting. Like calls, meetings include a duration field.
  </Accordion>

  <Accordion title="Video Call">
    A scheduled video conference. Includes a duration field.
  </Accordion>

  <Accordion title="Task">
    Something you need to do. Tasks show a due date field so the work stays visible until it's complete.
  </Accordion>

  <Accordion title="To-Do">
    A lightweight reminder for yourself or your team, with an optional due date.
  </Accordion>

  <Accordion title="Reminder">
    A scheduled prompt to follow up at a specific time. Includes a due date field.
  </Accordion>
</AccordionGroup>

<Tip>
  Pick the type that best matches what happened. The right type makes your timeline easier to scan and means the dialog only asks for the fields that matter.
</Tip>

## Filling Out the Dialog

<Steps>
  <Step title="Pick the activity type">
    Choose from the dropdown. The dialog opens preconfigured for that type.
  </Step>

  <Step title="Add a title and description">
    The title is what shows up on the timeline at a glance. The description is where you capture the details.
  </Step>

  <Step title="Set the activity date and time">
    By default, this is set to right now. Change it to log something that already happened, or to schedule something for the future.
  </Step>

  <Step title="Add a due date (task-style activities only)">
    For tasks, to-dos, and reminders, set a due date so the work stays on your radar.
  </Step>

  <Step title="Add a duration (call/meeting-style activities only)">
    For calls, meetings, and video calls, enter how long it lasted in minutes.
  </Step>

  <Step title="Tag contacts (workspace activity feed)">
    Search the workspace by name, email, or company, and select everyone involved. You must select at least one contact.
  </Step>

  <Step title="Save">
    The activity appears on every relevant timeline and in the workspace feed.
  </Step>
</Steps>

## Activity Timestamps and Backdating

Every activity has its own date and time, separate from when you actually clicked **Save**. That means you can:

* Log a call you forgot to record yesterday
* Schedule a future follow-up so it shows up on the timeline at the right time
* Capture a meeting that happened last week with the correct date

<Check>
  Timelines and the workspace feed sort by the activity's own timestamp, not by when it was created. Backdated and future-dated activities slot into the right place automatically.
</Check>

## Tagging Multiple Contacts

When you log activity from the workspace activity feed, you can tag more than one contact in a single entry. This is the right pattern for things like:

* A group sales call with two stakeholders
* A meeting where several people from the same account showed up
* A shared note that's relevant to a few different leads

### How Multi-Contact Activities Appear

Even though the activity is linked to multiple contacts, it shows up as **one event** in the workspace activity feed. The card shows contact badges for everyone tagged.

If you tag more than three contacts, the card shows the first few badges followed by a `+N more` indicator so the feed stays clean.

<Info>
  On individual contact and company timelines, multi-contact activities still appear normally — each tagged contact sees the activity on their own timeline.
</Info>

## Field Rules at a Glance

<AccordionGroup>
  <Accordion title="When does the duration field show up?">
    Only for call, meeting, and video-call style activities. Other types don't display it.
  </Accordion>

  <Accordion title="When does the due date field show up?">
    Only for task, to-do, and reminder style activities.
  </Accordion>

  <Accordion title="Do I have to pick a contact?">
    From the contact timeline, the contact is filled in for you. From the workspace activity feed, you must tag at least one contact. From a company timeline, contacts are optional — you can log against the company alone.
  </Accordion>

  <Accordion title="Can I tag contacts from different companies?">
    Yes. From the workspace activity feed, you can tag any combination of contacts across the whole workspace.
  </Accordion>
</AccordionGroup>

## Editing Activities

<Warning>
  The shared activity dialog is currently focused on creating new activities. Full in-dialog editing of existing activities is not yet available.
</Warning>

What you can do today:

* **Edit a description** on any existing activity through the contact timeline.
* **Re-open** existing activities to view details.

What's not yet supported:

* Changing the activity type, timestamp, due date, duration, or tagged contacts after the activity has been saved.

If you need to change something that isn't editable yet, the simplest workaround is to delete the activity and log a new one with the corrected details.

## Tips for Clean Activity History

<CardGroup>
  <Card title="Be specific in titles" icon="text">
    "Pricing call — agreed on annual plan" beats "Call".
  </Card>

  <Card title="Backdate when you catch up" icon="rotate-left">
    If you log activity later, set the timestamp to when it happened.
  </Card>

  <Card title="Use tasks for follow-ups" icon="list-check">
    Pick the task type with a due date instead of a plain note.
  </Card>

  <Card title="Tag everyone involved" icon="user-plus">
    For multi-stakeholder meetings, tag every contact so it shows up on each timeline.
  </Card>
</CardGroup>

## Next Steps

<Card title="CRM Overview" icon="users" href="/features/crm/overview">
  Back to the CRM overview
</Card>


# Ask Clarky
Source: https://docs.clarky.ai/features/crm/ask-clarky

Chat with your CRM in natural language to find data and take action

## What is Ask Clarky?

Ask Clarky is an AI-powered chat interface built directly into your CRM. Instead of clicking through filters and tables to find what you need, you can simply ask. Ask Clarky understands your contacts, companies, pipeline, conversations, activities, and analytics, and can also take action on your behalf.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Natural Language Search" icon="magnifying-glass">
    Find contacts, companies, and deals by describing what you want
  </Card>

  <Card title="Instant Analytics" icon="chart-bar">
    Get pipeline summaries and KPIs without building a report
  </Card>

  <Card title="Take Action" icon="bolt">
    Send emails, send texts, move pipeline cards, log activities
  </Card>

  <Card title="Persistent History" icon="clock-rotate-left">
    Pick up where you left off in any past conversation
  </Card>
</CardGroup>

<Tip>
  Prefer texting? On Standard plans and up you can reach Ask Clarky over iMessage, RCS, or SMS, and even book meetings from a group chat. See [Text Clarky](/features/crm/text-clarky).
</Tip>

## Where to find it

Clarky lives inside [Team Chat](/features/team-chat/overview) as a pinned conversation at the top of your **Direct messages**. Chat is the default screen after you log in, so Clarky is always one click away.

<Steps>
  <Step title="Open Chat">
    Click **Chat** in the sidebar (or just log in, Chat is the landing screen). **Clarky** is pinned at the top of the Direct messages group.
  </Step>

  <Step title="Start chatting">
    Type a question in the composer, or pick one of the starter prompts.
  </Step>
</Steps>

<Tip>
  Want Clarky in a group conversation? Mention **@Clarky** in any Team Chat channel and it answers right there, visible to the whole room. See [Team Chat](/features/team-chat/overview).
</Tip>

<Note>
  Access to Ask Clarky requires the same CRM permission as the rest of the CRM. If you can view the CRM, you can use Ask Clarky.
</Note>

## Starter prompts

Not sure what to ask? Open the starter prompts from the button in the composer to see a menu of ready-made questions, and pick one to send it.

You can also save your own custom prompts. They appear alongside the built-in ones, so the questions you ask every week are always one click away. Custom prompts are personal to you, not shared with the workspace.

## Things you can ask

Ask Clarky works best when you describe what you want in plain language. Here are examples grouped by what you're trying to do.

<Tabs>
  <Tab title="Search">
    Find contacts, companies, conversations, and pipeline cards.

    * "Show me all contacts that attended the AI workshop"
    * "Which companies are in the SaaS industry?"
    * "Find contacts in the Proposal stage with deal value over \$5,000"
    * "Who did I add to the CRM this month?"
    * "Look up Tyler Clark's contact details"
    * "Show me recent conversations about pricing"
    * "Find all pipeline cards in the Negotiation stage"
  </Tab>

  <Tab title="Analytics">
    Ask for counts, totals, and pipeline summaries.

    * "Give me a pipeline summary"
    * "How many deals have been closed this year?"
    * "What's the total value of deals in the Qualified stage?"
    * "How many new contacts did we get last week?"
    * "How many bookings happened this month?"
    * "How many form submissions came in this quarter?"
    * "Who should I follow up with this week?"
  </Tab>

  <Tab title="Actions">
    Ask Clarky to do something. You'll always confirm before it runs.

    * "Send an email to Tyler Clark thanking him for the meeting"
    * "Send a text to Sarah letting her know I'm running 5 minutes late"
    * "Move the Acme Corp deal to the Closed Won stage"
    * "Log a call activity on Jordan's contact with a note that we discussed pricing"
    * "Email everyone in the Proposal stage with a follow-up"
  </Tab>
</Tabs>

<Tip>
  You don't need to know exact tag names, stage names, or lead source labels. Ask Clarky already has your workspace's metadata in context, so phrases like "the AI workshop tag" or "the Proposal stage" map to the right values automatically.
</Tip>

## How results are displayed

Ask Clarky doesn't just dump text at you. Each kind of result is rendered with a purpose-built UI so you can scan and click through to the underlying records.

<AccordionGroup>
  <Accordion title="Contact and company tables">
    When you search for people or companies, results render as a clean table with name, email, company, and pipeline stage. Each row is a clickable link that takes you straight to the contact or company detail page.
  </Accordion>

  <Accordion title="Pipeline summary cards">
    Pipeline questions return a horizontal funnel showing each stage, how many cards are in it, and the total deal value at that stage.
  </Accordion>

  <Accordion title="Analytics cards">
    Counts and totals (new contacts, deals, bookings, form submissions, activities) display as large stat cards so the number is easy to read at a glance.
  </Accordion>

  <Accordion title="Conversations and activities">
    Conversation results show the contact, channel, and a preview of the latest message. Activity results show the type (note, call, meeting, task), date, and details.
  </Accordion>

  <Accordion title="Action confirmations">
    When Ask Clarky completes a write action, you get a clear success or error confirmation with the details of what happened, so there's no ambiguity about whether the email actually went out or the card actually moved.
  </Accordion>
</AccordionGroup>

While Ask Clarky is working, you'll see a small "Using..." indicator in the chat so you know what it's doing behind the scenes.

## Confirming write actions

Anything that changes data or sends a message requires your explicit go-ahead before it runs. This applies to:

* Sending an email
* Sending a text message (SMS)
* Moving a pipeline card
* Creating an activity (note, call, meeting, task)

<Warning>
  Ask Clarky will describe exactly what it's about to do, including the recipient, message content, or destination stage, and wait for you to confirm. Nothing is sent or changed until you say so.
</Warning>

A typical flow looks like this:

<Steps>
  <Step title="Ask for the action">
    "Send Tyler an email saying thanks for the call yesterday."
  </Step>

  <Step title="Review the draft">
    Ask Clarky responds with the recipient, subject, and body it plans to send.
  </Step>

  <Step title="Confirm or revise">
    Reply with "send it" to proceed, or ask for edits like "make it shorter" or "add a P.S. about next steps."
  </Step>

  <Step title="See the confirmation">
    Once it runs, a success badge appears in the chat with the action details.
  </Step>
</Steps>

## Chat history

Every conversation with Ask Clarky is saved automatically, so you can return to past sessions any time.

<CardGroup>
  <Card title="New Chat" icon="plus">
    Start a fresh conversation from a clean slate. Your previous chat is saved automatically.
  </Card>

  <Card title="History" icon="clock">
    Open the History popover to browse and reopen any past conversation.
  </Card>
</CardGroup>

Both buttons live in the top-right corner of the Clarky conversation. Past sessions are sorted with the most recent first, and each one is titled based on your opening message so you can find the right thread at a glance.

<Info>
  Chat history is private to you. Other workspace members can use Ask Clarky too, but they only see their own past conversations.
</Info>

## Tips for great results

<AccordionGroup>
  <Accordion title="Be specific when it matters">
    "Show me contacts in the Proposal stage with deal value over \$10,000" is more useful than "show me good leads."
  </Accordion>

  <Accordion title="Use relative dates freely">
    Phrases like "this week," "last month," or "this quarter" are interpreted automatically. You don't need to spell out date ranges.
  </Accordion>

  <Accordion title="Chain follow-ups">
    Ask a broad question, then narrow it. "Show me contacts from the AI workshop" then "of those, who hasn't been contacted in 30 days?" works just like a normal conversation.
  </Accordion>

  <Accordion title="Combine search and action">
    "Find everyone in the Qualified stage and send each of them a follow-up email" is a valid request. Ask Clarky will preview the action before sending.
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="CRM Overview" icon="users" href="/features/crm/overview">
  Back to the full CRM feature overview
</Card>


# Companies
Source: https://docs.clarky.ai/features/crm/companies

Track and organize the companies behind your contacts

## What is the Companies section?

The Companies section groups your contacts by the organizations they belong to. Use it to see every contact at a given company, the total deal value tied to that company, and a unified activity timeline across all of their people.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Auto-grouping" icon="sitemap">
    Contacts are linked to companies based on their email domain
  </Card>

  <Card title="Aggregated value" icon="dollar-sign">
    See the total deal value across every contact at a company
  </Card>

  <Card title="Shared timeline" icon="clock-rotate-left">
    A single activity feed for everyone at the company
  </Card>

  <Card title="Pipeline tracking" icon="chart-line">
    Track companies through your sales pipeline
  </Card>
</CardGroup>

## How companies are created

<AccordionGroup>
  <Accordion title="Automatically from contacts">
    When a contact is added with a business email address, Clarky checks for an existing company matching that domain. If one exists, the contact is linked to it. If not, a new company record is created using the email domain.
  </Accordion>

  <Accordion title="Manually">
    Use the **New Company** button on the Companies page to create a company directly. You can fill in the name, website domain, industry, size, tags, and notes.
  </Accordion>
</AccordionGroup>

## The Companies list

Each row shows:

* **Name** — the company name
* **Domain** — the website / email domain used for matching
* **Industry** and **Size** — populated when known
* **Contacts** — how many people from this company are in your CRM
* **Total Deal Value** — sum of deal values across all contacts at the company
* **Pipeline Stage** — the stage assigned to the company itself
* **Last Activity** — most recent interaction with anyone at the company

You can search by name or domain, filter by columns, and sort by any field. Click a row to open the company detail view.

## Company detail page

Opening a company shows everything in one place:

<Steps>
  <Step title="Header & summary">
    Name, domain, industry, size, total deal value, pipeline stage, and tags.
  </Step>

  <Step title="Contacts">
    Every contact linked to this company. Click through to any individual contact for their full profile.
  </Step>

  <Step title="Activity timeline">
    A unified feed of activities across all contacts at the company. Add notes, calls, meetings, and tasks directly to the company record.
  </Step>

  <Step title="Deal tracking">
    Move the company through your pipeline and watch the aggregated deal value update.
  </Step>
</Steps>

<Tip>
  Logging an activity from the company timeline lets you tag one or more contacts at that company in a single entry — useful for meetings or calls with multiple stakeholders.
</Tip>

## Tips

<AccordionGroup>
  <Accordion title="Keep domains accurate">
    Auto-grouping uses the email domain to match contacts. If a company has multiple domains (e.g., acme.com and acme-corp.com), you may end up with two separate company records. Merge them manually if needed.
  </Accordion>

  <Accordion title="Use tags for segments">
    Add tags like `enterprise`, `partner`, or `prospect` to group companies in custom ways beyond industry and size.
  </Accordion>

  <Accordion title="Track named accounts">
    For account-based sales, use the company pipeline stage to track named accounts independently of individual contacts moving through their own stages.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="CRM Overview" icon="address-book" href="/features/crm/overview">
    Back to the CRM overview
  </Card>

  <Card title="Contacts" icon="users" href="/features/crm/contacts">
    Manage individual contacts
  </Card>

  <Card title="Activity" icon="clock-rotate-left" href="/features/crm/activity">
    Log activities and view the unified feed
  </Card>

  <Card title="Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
    Track deals through your pipeline
  </Card>
</CardGroup>


# Contact Management
Source: https://docs.clarky.ai/features/crm/contact-management

Advanced contact management features

## Linking Conversations to Contacts

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

### Automatic Linking

Conversations are automatically linked to contacts when:

* Contact's email or phone matches
* Agent identifies them during conversation
* User is logged into their account

### Manual Linking

Link conversations manually:

<Steps>
  <Step title="Open Conversation">
    View the conversation in your inbox.
  </Step>

  <Step title="Click 'Link to Contact'">
    Find the button in the conversation sidebar.
  </Step>

  <Step title="Search or Create">
    Select existing contact or create new one.
  </Step>

  <Step title="Confirm">
    Conversation is linked and appears in contact's history.
  </Step>
</Steps>

## Contact Enrichment

Clarky can automatically enrich contact data:

* Company information
* Social media profiles
* Professional details
* Public data sources

Enable in **Settings > CRM > Data Enrichment**.

## Duplicate Management

Clarky automatically:

* Detects potential duplicates
* Suggests merges
* Prevents duplicate creation

Review and merge duplicates in **CRM > Duplicates**.

## Exporting Contacts

Export contact data:

* CSV format
* Excel spreadsheets
* vCard format
* Custom field selection

Use for:

* Backup purposes
* Migration to other systems
* Email marketing lists
* Reporting and analysis

## Integration with Conversations

When viewing a contact:

* Click to start new conversation
* See suggested responses based on history
* View sentiment trends
* Access all prior interactions

<Card title="Back to CRM Overview" icon="users" href="/features/crm/overview">
  Return to CRM overview
</Card>


# Contact Management
Source: https://docs.clarky.ai/features/crm/contacts

Organize and manage your customer contacts

## Table View

The Contacts Table provides a comprehensive view of all your contacts with sortable columns and powerful filtering.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

### Search, Filters, and Saved Searches

One search bar covers names, emails, phone numbers, and companies, and results update as you type. Stack filter chips (tags, pipeline stage, source, and more) to narrow the list, and click any column header to sort.

Once you have a search and filter combination you like, save it:

<Steps>
  <Step title="Build your view">
    Enter a search and apply any filters.
  </Step>

  <Step title="Save the search">
    Open the saved searches menu and give it a name.
  </Step>

  <Step title="Share it (optional)">
    Keep the search personal, or share it so everyone in the workspace can use the same view.
  </Step>
</Steps>

### Bulk Actions and CSV Export

Selections survive pagination, so you can check contacts across multiple pages and act on all of them at once:

* **Add to list**: put the whole selection on a list for a campaign or a sequence
* **Export CSV**: download your selection, or the entire filtered result set, as a spreadsheet-ready CSV

<Tip>
  The contact and company detail pages autosave as you type. There is no save button to forget.
</Tip>

### Contact Information

Each contact record includes:

<ResponseField name="name" type="string">
  Contact's full name
</ResponseField>

<ResponseField name="email" type="string">
  Email address
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number
</ResponseField>

<ResponseField name="stage" type="string">
  Current pipeline stage (Lead, Qualified, Proposal, etc.)
</ResponseField>

<ResponseField name="value" type="number">
  Estimated deal value
</ResponseField>

<ResponseField name="last_contact" type="date">
  Date of most recent interaction
</ResponseField>

<ResponseField name="source" type="string">
  How they found you (chat, voice, referral, etc.)
</ResponseField>

## Adding Contacts

### Automatic Creation

Contacts are created automatically when:

* Customer provides name and contact info in chat
* Phone call is completed
* SMS conversation includes identification
* Email is received from new address

### Manual Creation

Add contacts manually:

<Steps>
  <Step title="Click 'Add Contact'">
    Button in the top-right of CRM view.
  </Step>

  <Step title="Fill Information">
    Enter name, email, phone, and any other details.
  </Step>

  <Step title="Set Pipeline Stage">
    Place them in the appropriate stage.
  </Step>

  <Step title="Save">
    Contact is immediately available in your CRM.
  </Step>
</Steps>

### Importing Contacts

Import existing contacts from:

* CSV files
* Other CRM systems
* Email contact lists
* Spreadsheets

<Tip>
  Tick **Validate emails after import** in the import options to check every new address with [Email Validation](/features/crm/email-validation). The list arrives pre-badged, and Sequences will skip anything undeliverable. Each contact record also has a **Validate email** action for one-off checks.
</Tip>

### Business Card Scanner

Turn a paper business card into a contact in seconds:

<Steps>
  <Step title="Open the scanner">
    In **CRM > People**, choose **Scan Card**.
  </Step>

  <Step title="Snap a photo">
    Use your phone camera or upload an image of the card.
  </Step>

  <Step title="Review and save">
    AI reads the card and prefills the name, title, company, email, and phone. Fix anything that needs it and save.
  </Step>
</Steps>

<Tip>
  Great for conferences: scan a stack of cards from your phone and they all land in your CRM, ready for a follow-up sequence.
</Tip>

<Note>
  New contacts automatically inherit tags and address details from their company, so records created by hand, by scan, or by the AI stay consistent.
</Note>

## Contact Details

Click any contact to see their detailed profile:

### Information Tab

* Full contact details
* Custom fields
* Tags and categories
* Creation date and source

### Conversations Tab

See all interactions:

* Complete conversation history
* Across all channels
* Searchable and filterable
* Linked to original conversations

### Activity Timeline

Chronological view of all activities:

* Conversations
* Status changes
* Notes added
* Emails sent
* Calls made

### Notes and Tasks

* Internal notes (not visible to contact)
* Assigned tasks and follow-ups
* Important dates and reminders

## Calling and Texting Contacts

### Click-to-Call

Tap any phone number on a contact record to place the call. Clarky logs a call activity on the contact's timeline automatically, so your history stays complete without manual notes.

### Phone Line Types

Clarky detects whether each number is a **mobile**, **landline**, or **VoIP** line and shows it next to the number. Use it to know who can receive texts before you send an SMS or launch a texting sequence.

## Organizing Contacts

### Tags

Apply custom tags to categorize contacts:

* **VIP**: High-value customers
* **Follow-up**: Needs attention
* **Interested**: Showed interest
* **Custom**: Create your own

Tags autocomplete from the vocabulary already used in your workspace, so the same tag never ends up spelled three different ways.

### Custom Fields

Add custom fields for your business needs:

* Industry
* Company size
* Budget
* Specific preferences
* Any data you track

## Next Steps

<Card title="Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
  Move contacts through your sales process
</Card>


# Email Validation
Source: https://docs.clarky.ai/features/crm/email-validation

Verify email deliverability with ZeroBounce so Sequences skip addresses that would bounce and your sender reputation stays protected

## What is Email Validation?

Email Validation checks whether an address can actually receive mail before you spend a send on it. Clarky verifies addresses with ZeroBounce, an industry-standard email verification service, and shows the result as a small status pill wherever emails appear: the People page, contact records, and Prospecting search results. Most importantly, **Sequences automatically skip addresses that fail validation**, so a stale contact list cannot burn your sender reputation with bounces.

<Info>
  **Plan availability:** Startup or higher. Email Validation is pay as you go: any paid plan can buy validation credits, and there is no subscription add-on. See [Plans & Billing](/features/settings/plans).
</Info>

## How credits work

Email Validation runs on **validation credits**, purchased in **Settings > Email Validation**. One credit validates one address.

<AccordionGroup>
  <Accordion title="Buying credits">
    Pick a one-time pack of 1,000, 5,000, or 25,000 validations. Credits never expire and are shared by everyone in the workspace. Payment goes through Stripe on the card you already use for Clarky.
  </Accordion>

  <Accordion title="What is charged and what is free">
    A credit is used only when an address is checked for the first time. Results are kept for 90 days, so re-validating the same address anywhere in Clarky during that window is free: launching a second sequence at the same list, re-importing a CSV, or viewing badges costs nothing.
  </Accordion>

  <Accordion title="What happens with no credits">
    Nothing breaks. Validation quietly pauses, badges stop appearing for new addresses, and emails send without a deliverability check, exactly as they did before this feature existed. Buy credits any time to switch protection back on.
  </Accordion>
</AccordionGroup>

## What the statuses mean

| Badge                       | Meaning                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| <strong>valid</strong>      | The mailbox exists and accepts mail. Safe to send.                                                              |
| <strong>invalid</strong>    | The address failed validation (dead mailbox, spam trap, or known complainer). Sequences skip it automatically.  |
| <strong>catch-all</strong>  | The mail server accepts everything, so delivery cannot be confirmed. Sends proceed, flagged for your awareness. |
| <strong>unverified</strong> | Deliverability could not be determined. Sends proceed.                                                          |

## Where validation shows up

<CardGroup>
  <Card title="Sequences" icon="paper-plane">
    The launch preview warns how many target emails are undeliverable, and the dispatcher skips them at send time. A contact stopped for a bad address shows an "Invalid email" status on the sequence detail page. Validation is on per sequence by default; the **Email validation** switch on the launch page's Sender section turns it off for that sequence.
  </Card>

  <Card title="People" icon="users">
    The People table shows a status pill next to each contact's primary email, so you can spot unreachable contacts at a glance.
  </Card>

  <Card title="Contact records" icon="address-card">
    Every email on a contact record carries its badge, plus a **Validate email** action for an instant on-demand check.
  </Card>

  <Card title="Prospecting" icon="radar">
    Search results are validated in the background, so you know which prospects have a working email before you save them or launch outreach.
  </Card>
</CardGroup>

## Validating on CSV import

When importing contacts, tick **Validate emails after import** in the import options. Every new address in the file is checked in the background once the import finishes, so the list is fully badged before you launch a sequence at it.

<Steps>
  <Step title="Buy credits">
    Go to **Settings > Email Validation** and pick a pack. Credits never expire.
  </Step>

  <Step title="Import or prospect as usual">
    New addresses from imports (with the checkbox on), prospecting searches, and sequence launches are validated automatically.
  </Step>

  <Step title="Launch with confidence">
    The sequence launch preview shows how many addresses will be skipped, and the rest go out clean.
  </Step>
</Steps>

<Tip>
  Validation protects the thing that is hardest to rebuild: your sending domain's reputation. If you run cold outreach from a warmed-up domain, validating a list before the first send is the cheapest insurance you can buy.
</Tip>


# MCP Server
Source: https://docs.clarky.ai/features/crm/mcp-server

Connect Claude, Codex, and other AI tools directly to your Clarky CRM

Clarky's MCP server lets AI tools you already use, like Claude and Codex, work with your CRM directly. Ask Claude about your pipeline, look up contacts, check analytics, or prepare an email draft without leaving your AI tool. It is the same brain as [Ask Clarky](/features/crm/ask-clarky), available everywhere MCP is supported.

Clarky implements the newest MCP specification (the 2026-07-28 revision) and remains backwards compatible with clients on earlier versions of the protocol.

<Info>
  **Plan availability:** Standard or higher (included with API Access). See [Plans & Billing](/features/settings/plans).
</Info>

## What your AI tools can do

Once connected, your AI tool has live access to this workspace's CRM:

* **Contacts and companies**: search, filter by tags or lead source, and pull full contact details
* **Pipeline**: stage summaries, deal values, and moving cards between stages
* **Analytics**: contact counts, deal totals, conversations, bookings, and form submissions over any date range
* **Bookings and meetings**: upcoming and past meetings
* **Conversations and activities**: chat, email, text, and voice history plus logged notes, calls, and tasks
* **Drafts**: prepare email, text, and sequence drafts to review and send inside Clarky

<Note>
  AI tools can never send emails or texts through the MCP connection. Drafts always come back to Clarky, where you review and click Send yourself.
</Note>

## Connect Claude (claude.ai and Claude Desktop)

<Steps>
  <Step title="Add a custom connector">
    In Claude, open Settings, then Connectors, and choose Add custom connector. Paste your server URL: `https://clarky.ai/api/mcp`
  </Step>

  <Step title="Sign in to Clarky">
    Claude opens a Clarky sign-in page. Log in with your normal Clarky account and pick the workspace you want to connect.
  </Step>

  <Step title="Approve access">
    Review the requested access and click Allow. Claude can now use your CRM in any conversation.
  </Step>
</Steps>

## Connect Claude Code

Run this in your terminal:

```bash theme={null}
claude mcp add --transport http clarky https://clarky.ai/api/mcp
```

Then run `/mcp` inside Claude Code to sign in to Clarky.

## Connect Codex

```bash theme={null}
codex mcp add clarky https://clarky.ai/api/mcp
```

## Connect with an API key instead

For headless or shared setups where a sign-in flow is inconvenient, use a workspace API key as the bearer token. Create one in Settings under MCP Server, then:

```bash theme={null}
claude mcp add --transport http clarky https://clarky.ai/api/mcp --header "Authorization: Bearer ck_live_..."
```

<Tip>
  Read-only keys are a good fit for shared or automated setups: the AI can look things up but cannot change pipeline stages or log activities.
</Tip>

## Managing connections

The MCP Server section in Settings shows every AI tool connected to your workspace, who connected it, and when it was last used. Disconnect any of them at any time; the tool will need to sign in again to regain access. API keys are managed separately in the API Keys section.

Access also ends automatically when a user is removed from the workspace.

## Tips for better answers

* Ask your AI tool to call `get-crm-context` first when a question mentions tags, pipeline stages, or lead sources by an approximate name. It returns the exact values in your workspace.
* If your workspace has more than one agent, mention which agent's CRM you mean, or ask for `list-agents` to see the options.


# CRM Overview
Source: https://docs.clarky.ai/features/crm/overview

Built-in customer relationship management for your AI agent

## What is the Clarky CRM?

Clarky includes a built-in CRM to track contacts, companies, deals, and activity, all automatically populated from your agent conversations. The CRM lives under **CRM** in the sidebar, and each part of your sales workflow (Activity, People, Companies, Lists, Sequences, Pipeline, Forms) appears as its own sidebar sub-section while you are in the CRM.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## CRM Sections

<CardGroup>
  <Card title="Activity" icon="clock-rotate-left" href="/features/crm/activity">
    A unified feed of every interaction across your workspace
  </Card>

  <Card title="People (Contacts)" icon="users" href="/features/crm/contacts">
    Individual contact records with full conversation history
  </Card>

  <Card title="Companies" icon="building" href="/features/crm/companies">
    Group contacts by the organizations they belong to
  </Card>

  <Card title="Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
    Visual kanban pipeline with drag-and-drop stages
  </Card>

  <Card title="Sequences" icon="paper-plane" href="/features/crm/sequences">
    Multi-touch outbound campaigns drafted by AI per contact
  </Card>

  <Card title="Forms" icon="rectangle-list" href="/features/forms/overview">
    Capture leads with traditional forms or surveys
  </Card>

  <Card title="Ask Clarky" icon="sparkles" href="/features/crm/ask-clarky">
    Chat with an AI that has tool access to your CRM
  </Card>
</CardGroup>

## Key Features

### Automatic Contact Creation

When customers provide their information during a conversation, Clarky automatically:

1. Creates a contact record
2. Captures name, email, and phone
3. Links the conversation history
4. Adds them to the appropriate pipeline stage
5. Groups them under a company based on email domain

### Unified Customer View

See everything about a contact in one place:

* Contact information and tags
* All conversation history across chat, voice, text, and email
* Pipeline stage and deal value
* Custom notes and activity timeline
* Form submissions and bookings

### Ask Clarky

Use natural language to query your CRM. Ask things like:

* "Show me all contacts that attended the AI workshop"
* "How many deals have closed this year?"
* "Who should I follow up with this week?"

Clarky returns clickable tables, pipeline summaries, and analytics cards inline. It can also take actions like sending an email, sending an SMS, or moving a pipeline card — always with a confirmation step before executing.

## Getting Started

<Steps>
  <Step title="Open the CRM">
    Click **CRM** in the main navigation.
  </Step>

  <Step title="Review auto-created contacts">
    Contacts created from conversations appear in **People** automatically.
  </Step>

  <Step title="Customize your pipeline">
    Open **Pipeline** and set up stages that match your sales process.
  </Step>

  <Step title="Connect forms">
    Build a form or survey to capture leads from your website.
  </Step>

  <Step title="Try Ask Clarky">
    Open **Ask Clarky** and ask anything about your CRM data.
  </Step>
</Steps>

## CRM Benefits

<AccordionGroup>
  <Accordion title="No data entry">
    Contacts and companies are created automatically from conversations, forms, and bookings — no manual input needed.
  </Accordion>

  <Accordion title="Complete context">
    See the full conversation history, activity timeline, and form submissions when following up with any contact.
  </Accordion>

  <Accordion title="Pipeline visibility">
    Track deals at both the contact level and the company level through visual kanban stages.
  </Accordion>

  <Accordion title="Natural language access">
    Ask Clarky lets anyone on your team query the CRM without learning filters or building reports.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="View Activity" icon="clock-rotate-left" href="/features/crm/activity">
    See the unified activity feed
  </Card>

  <Card title="Manage Contacts" icon="users" href="/features/crm/contacts">
    Open the People section
  </Card>

  <Card title="Companies" icon="building" href="/features/crm/companies">
    Group contacts by company
  </Card>

  <Card title="Use Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
    Set up your sales pipeline
  </Card>

  <Card title="Launch a Sequence" icon="paper-plane" href="/features/crm/sequences">
    Send a multi-touch outbound campaign
  </Card>

  <Card title="Build a Form" icon="rectangle-list" href="/features/forms/overview">
    Capture leads from your website
  </Card>

  <Card title="Ask Clarky" icon="sparkles" href="/features/crm/ask-clarky">
    Chat with your CRM data
  </Card>
</CardGroup>


# Prospecting
Source: https://docs.clarky.ai/features/crm/prospecting

Find new people to sell to by title, seniority, industry, company, and location, then save them straight into People and your lists

## What is Prospecting?

Prospecting is a people search built into the CRM. Describe who you want to reach (a title, a seniority level, an industry, a company size, a location) and Clarky searches People Data Labs, a database of hundreds of millions of professional profiles, for matches. Every result comes with name, current title, company, location, LinkedIn profile, and any work email or mobile phone on file. Save the ones you like into **People** with one click, optionally straight into a **List**, and they are ready for a Sequence.

Prospecting lives under **CRM > Prospecting**.

<Info>
  **Plan availability:** Startup or higher. Prospecting is pay as you go: any paid plan can buy prospect credits, and there is no subscription add-on. See [Plans & Billing](/features/settings/plans).
</Info>

## How credits work

Prospecting runs on **prospect credits**. One credit reveals one person. The price of every search is shown on the button before you click it, so there are no surprises.

<AccordionGroup>
  <Accordion title="Buying credits">
    Click **Buy credits** for a one-time pack of 100, 500, or 2,000 credits. Credits never expire and are shared by everyone in the workspace. Payment goes through Stripe on the card you already use for Clarky.
  </Accordion>

  <Accordion title="Included credits">
    Plans do not currently include monthly prospect credits; if a plan ever does, they are used before purchased credits and the balance pill shows both.
  </Accordion>

  <Accordion title="What is charged and what is free">
    A credit is used for each person a search reveals, whether or not you save them. Everything after that is free: browsing people you already revealed (the **Prospects** tab), saving them to People, adding them to lists, and running Sequences against them. Clarky also skips people your workspace already holds, so re-running a search brings you new people instead of charging you twice for the same ones.
  </Accordion>
</AccordionGroup>

<Tip>
  Start with **10 people per search** while you tune your filters, then move to 25 or 50 once results look right. The **Has work email** filter is on by default so every credit buys someone you can actually contact; switch it off if you are researching rather than reaching out.
</Tip>

## Running a search

<Tip>
  In a hurry? Type a sentence into **Describe who you want** at the top of the filters ("owners of roofing companies in Tampa with an email") and click **Fill filters**. Clarky fills in the chips for you, free of charge; review them, then press Search.
</Tip>

<Steps>
  <Step title="Describe who you want">
    Use the filter pane on the left. Every filter accepts several values (they are OR'd within a filter, AND'd across filters):

    * **Job title**: free text, matched loosely ("head of sales" also finds "Head of Sales, North America"). Suggestions appear as you type.
    * **Seniority**: C-level, Owner, Partner, VP, Director, Manager, Senior, Entry.
    * **Department**: Sales, Marketing, Engineering, Operations, Finance, and so on.
    * **Company**, **Company keyword** (a word that should appear in the company name, like "roofing"), **Company website**, **Industry**, **Company size**.
    * **Country**, **State / region**, **City**, and **Skills**.
    * **Has work email** and **Has mobile phone** toggles.
  </Step>

  <Step title="Pick how many people to reveal">
    Choose 10, 25, or 50 people per search. The Search button shows exactly how many credits it will use.
  </Step>

  <Step title="Search">
    Results appear in the table with name, title, company (with industry and size), location, email, and phone. Click the LinkedIn icon next to a name to open the profile. **Show more** at the bottom reveals the next page for the same price per person. With [Email Validation](/features/crm/email-validation) credits in the workspace, emails are checked in the background and a red **invalid** or amber **catch-all** pill appears next to addresses that may not be reachable.
  </Step>

  <Step title="Save to CRM">
    Tick the people you want and click **Save to CRM**. Choose no list, an existing list, or type a name to create a new list on the spot. Clarky creates the contacts (and their companies), tags them `prospect`, and links anyone who was already in your CRM instead of duplicating them.
  </Step>
</Steps>

## Example: owners of small roofing companies in Texas

1. **Industry**: Construction
2. **Job title**: owner, roofing, president
3. **Seniority**: Owner, C-level
4. **Company size**: 1-10, 11-50
5. **Country**: United States, **State / region**: Texas
6. Leave **Has work email** on

The title list is what narrows a broad industry like Construction down to roofers; the seniority and size filters keep you on owner-operators rather than staff at large firms.

## Ask Clarky and MCP

You can prospect from Ask Clarky too: "Find me 10 roofing companies in Tampa" runs the same search, shows the people in the chat, and offers to save them or add them to a list. Ten people means ten credits, so Ask Clarky defaults to 10 and only goes higher when you name a number. If the workspace has no credits it tells you where to buy them. The same `find-prospects` and `save-prospects` tools are available to Claude, Codex, and other AI tools through the [MCP server](/features/crm/mcp-server) on a write-scoped connection.

## The Prospects tab

Everyone you have ever revealed lives in **Prospects**, free to browse and search. Come back later, tick a few, and save them, or open a saved person's contact record with the **In CRM** link.

## Saved contacts

Prospects saved into People arrive with:

* First and last name, title, company, LinkedIn URL, and location
* Work email and mobile phone when People Data Labs has them
* Lead source **prospecting** and the tag **prospect**, so you can filter or build saved searches on them
* A linked Company record (created if it did not exist, matched by website or name if it did)

If a contact with the same email or LinkedIn URL already exists, Clarky links to that record and fills in any blank fields rather than creating a duplicate.

## FAQ

<AccordionGroup>
  <Accordion title="Why did a search return fewer people than I asked for?">
    Either fewer people match your filters, or you had fewer credits left than the page size. The result bar shows how many people match in total.
  </Accordion>

  <Accordion title="Do saved prospects count against my list limit?">
    Yes, lists are capped at 1,000 contacts like everywhere else in the CRM. If a save would overflow a list, Clarky adds as many as fit and tells you how many did not.
  </Accordion>

  <Accordion title="Where does the data come from?">
    People Data Labs, which aggregates public professional profiles and business contact data. Coverage is strongest for people with an established professional footprint online.
  </Accordion>

  <Accordion title="Can I get a refund for a search that came back empty?">
    Empty searches are free: credits are only used for people actually revealed.
  </Accordion>
</AccordionGroup>


# Sales Pipeline
Source: https://docs.clarky.ai/features/crm/sales-pipeline

Visual pipeline for tracking deals and opportunities

## Pipeline View

The Sales Pipeline provides a Kanban-style board for visually tracking deals through your sales process.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Default Pipeline Stages

Clarky includes these default stages:

<Steps>
  <Step title="Lead">
    Initial contact, early qualification phase
  </Step>

  <Step title="Qualified">
    Confirmed fit, moving to proposal
  </Step>

  <Step title="Proposal">
    Quote or proposal sent
  </Step>

  <Step title="Negotiation">
    Discussing terms and pricing
  </Step>

  <Step title="Closed Won">
    Deal completed successfully
  </Step>

  <Step title="Closed Lost">
    Deal didn't close
  </Step>
</Steps>

## Customizing Stages

Modify stages to match your sales process:

1. Go to **CRM > Pipeline Settings**
2. Add, remove, or rename stages
3. Set stage colors
4. Define stage criteria

## Moving Contacts

### Drag and Drop

Simply drag contact cards between stages to update their status.

### Manual Update

Click a contact and change their stage manually in the details view.

### Automated Movement

Set up rules to automatically move contacts:

* After certain conversation topics
* Based on time in stage
* When specific actions occur

## Deal Tracking

Each contact card shows:

* Contact name
* Deal value
* Time in current stage
* Last interaction date
* Quick action buttons

## Pipeline Metrics

View key metrics at the top:

* **Total Pipeline Value**: Sum of all open deals
* **Conversion Rate**: Percentage moving through stages
* **Average Deal Size**: Typical deal value
* **Average Sales Cycle**: Time from lead to close

## Next Steps

<Card title="Manage Contacts" icon="users" href="/features/crm/contact-management">
  Learn more about contact management
</Card>


# Sequences
Source: https://docs.clarky.ai/features/crm/sequences

Multi-touch outbound campaigns drafted per contact by AI, then approved one-by-one before sending

## What is a Sequence?

A Sequence is a multi-step outbound campaign that reaches a list of contacts across email, SMS, and voice. Sequences come in two flavors: **AI-personalized**, where Clarky drafts every message for every contact from your goal and the contact's profile and you approve each one before it sends, and **fully authored**, where you write each step yourself with merge fields and skip the review queue entirely.

Sequences live under **CRM > Sequences** and pair with **Lists** for selecting recipients.

<Info>
  **Plan availability:** Pro or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## How a Sequence Works

<Steps>
  <Step title="Pick a list of contacts">
    Open **CRM > Lists**, build a list of contacts (or pick an existing one), then click **Generate Sequences**. You can also start a sequence from a single contact's detail page.
  </Step>

  <Step title="Compose the sequence">
    Define the goal ("Book a 15-minute intro call", "Re-engage", etc.), pick a tone, and lay out the steps — each step is a touch on email, SMS, or voice scheduled some number of days after the start.
  </Step>

  <Step title="Generate drafts">
    Click **Generate drafts**. Clarky drafts each message for each contact in your list — so a 5-step sequence with 50 contacts produces 250 personalized drafts.
  </Step>

  <Step title="Review one-by-one">
    Walk the queue of contacts and approve, edit, or skip each draft per step. The sequence won't start sending until you approve the contacts you want included.
  </Step>

  <Step title="Launch">
    Configure the sender (your name and from-email), pick a start time, and launch. From that moment the cron schedules and sends each step on its assigned day in the contact's local timezone.
  </Step>
</Steps>

## Compose

The compose page is where you describe the sequence and lay out the steps.

### Goal

A short paragraph telling Clarky what the sequence is meant to accomplish. The clearer the goal, the more on-target each draft will be. Built-in starter prompts for common goals:

* **Book a meeting** — short hook + clear ask for time
* **Start a reply** — single specific question, no meeting ask
* **Re-engage** — fresh angle for a contact who went quiet
* **Renew** — customer-success toned renewal conversation

### Tone

Pick how the message should sound: **formal**, **warm**, **direct**, or **playful**. Drafts adopt the tone you choose.

### Steps (the timeline)

Each step is one touch on a specific channel, sent N days after the start. The middle column shows the timeline; click a step to open its details on the right:

* **Channel** — Email, Text, or Call
* **Name** — internal label (e.g. "Nice to meet you", "Quick call", "Breakup")
* **Send on day** — 0 means start day; 3 means three days after start
* **Send window** — local-time hours when this step is allowed to send
* **AI instructions** — extra guidance for this specific step (e.g. "Lead with a recent product announcement, ≤90 words")

Add or remove steps with the **Add step** button. Three steps spaced over a week is a good starting cadence; five over two weeks for a longer nurture.

### Save as template

Once you've shaped a sequence, save it as a template so the next launch is one click. Templates capture the goal, tone, and step blueprints — see [My Templates](#my-templates) below.

## Fully Authored Sequences

Prefer to control every word? Build a **fully authored** template instead of an AI-personalized one:

* Write the subject and body of each step yourself, once
* Personalize with merge fields such as `{{first_name|there}}`, where the part after the `|` is the fallback when a contact is missing that field
* No AI drafting, no per-contact review queue: launches are instant and auto-approve is on by default
* Every contact receives the same message with their own fields substituted

Fully authored templates are ideal for compliance-sensitive messaging, short transactional touches, and any campaign where the copy is already settled.

### Pre-launch preview

Before a launch generates or sends anything, Clarky shows a preview count: how many contacts on the list are **eligible**, how many are **already enrolled**, and how many are **suppressed**. AI-personalized launches also show an estimated drafting cost, so there are no surprises.

<Note>
  With [Email Validation](/features/crm/email-validation) credits in the workspace, the preview also reports how many target addresses are **undeliverable**. Those contacts are skipped automatically at send time and marked "Invalid email" on the sequence detail page, protecting your sender reputation from bounces.
</Note>

## Review

When you click **Generate drafts**, Clarky writes each step for each contact and routes you to the review screen.

### Stepper + queue

The review screen has step tabs across the top (Step 1, Step 2, …) and a queue of contacts on the left. You can:

* Click a step tab to switch to that step (your selected contact stays the same)
* Click a contact in the queue to switch to that contact's draft
* Edit the day this step fires inline (next to the contact name) without going back to compose

### Approve / Skip / Edit

For each draft you can:

* **Approve** — locks the draft for this contact + step. Approved steps will send when the sequence launches.
* **Skip step** — skips just this contact for just this step. Other steps for the same contact still send.
* **Edit** — open the draft for in-place editing of subject, body, etc. Save before approving.
* **Customize with AI** *(coming soon)* — ask the model to rewrite the draft based on a short instruction.

The progress bar at the top shows total approved / total drafts.

## Launch

The launch screen confirms what's about to ship.

### Sender

* **From name** — overrides the bot's default outbound name for this sequence
* **From email** — a local part (e.g. `tyler`) plus a dropdown of every verified sending domain on your account
* **Sending domains** — select more than one verified domain and Clarky rotates enrollments across them to spread volume. Each contact is pinned to a single domain for the life of the sequence so threading and replies stay consistent
* **Reply-to and BCC** — set a custom reply-to address and BCC list for this sequence without changing your agent's global email settings

### When should it start?

* **Start now** — first messages queue immediately within each contact's send window
* **Schedule** — pick a specific date and time for the first touch

### Send rules

* **Respect each contact's timezone** — interpret send windows in the contact's local time, not yours
* **Only send during business hours (9a–5p)** — pause overnight sends and resume in the morning
* **Skip weekends** — Saturday/Sunday sends roll to Monday

Click **Launch sequence** and the cron takes over from there.

## Lists

Lists are reusable groups of contacts that you target with a sequence. Create them under **CRM > Lists**:

* **Static lists** — manually pick contacts, or bulk-add from a CSV import or a filtered People view
* **Member count** — visible on the list index so you know the size before you launch
* **Archive** — hide old lists from the picker without deleting them

Launch a sequence from a list with one click — every active member gets enrolled.

## Suppressions

Compliance is handled automatically. The **Suppressions** page (under CRM) shows every email/phone that's opted out, and the cron skips them everywhere.

Three sources fill the suppression list:

* **Unsubscribe link** — every outbound sequence email includes a one-click unsubscribe footer (RFC 8058 List-Unsubscribe header included)
* **STOP / UNSUBSCRIBE replies on SMS** — the Twilio STOP keyword is honored automatically
* **Manual entries** — paste an email or phone in the manual-add row

Suppressions can be scoped to a specific channel (email-only, SMS-only) or applied to all channels.

### SMS Consent

Text steps only send to contacts who have opted in to SMS. When a step is blocked because consent is missing, the step shows the reason and a **Record consent** action: capture how the contact opted in (verbal, form, written) and retry the step on the spot. Consent is stored on the contact so future sequences do not hit the same block.

## Trigger From Your Backend (API)

If your team operates from another system — a custom CRM, a marketing automation tool, your own form handler — you can start a sequence for a single contact via a public API call. This is the fastest way to wire **form-submitted-now-call-them-back** automations.

In one request, Clarky will:

* **Upsert the contact** (matched by primary email, falling back to phone). Notes from the request are appended to the contact's record so they survive across calls.
* **Generate a bespoke sequence** from one of your saved templates — emails are written for that specific recipient, in their language, referencing real context from the notes you sent.
* **Optionally launch immediately** — with `auto_approve: true`, the first step (call or email) fires within seconds of generation completing, no human review required. Use this for trusted automation pipelines.
* **Notify your admins** when `auto_approve: false` — the sequence is generated, parked in the review queue, and an email goes out to your workspace admins with a link to approve.

Templates encode which channels are allowed (email, voice, SMS), so you don't pick channels in the request — choose a template that uses the channels you want.

<Tip>
  Use this for **inbound lead automation**: a prospect submits your contact form, your backend POSTs to `/api/v1/sequences/start` with the lead's details and a few notes ("Spanish speaker, asked about enterprise pricing"), and Clarky calls them within \~60 seconds in their native language.
</Tip>

See the full reference at [API Reference > Sequences](/api-reference/sequences).

## My Templates

Reusable recipes that save you time on the next launch. Templates capture the goal, tone, allowed channels, and step blueprints.

* Save any sequence as a template from the compose page
* Templates show up under **CRM > Sequences > My Templates** and inside the "Start a sequence" picker
* The picker also includes built-in starter templates (Founder-led outbound, Event handoff, Renewal runway, etc.) — those don't appear in My Templates because they're stock recipes

## Send Windows & Timezones

Sequence sends respect a few layers of guard rails:

* **Email** — never gated by quiet hours; sends during the per-step send window
* **SMS** — TCPA-compliant 8 AM – 9 PM local time
* **Voice** — Mon–Fri 9 AM – 6 PM local time (typical professional hours)

"Local time" is the contact's timezone. New contacts inherit the workspace timezone by default; you can override per contact from the contact detail page.

## Stop on Reply

When **Stop on reply** is enabled (default), an inbound reply from the contact halts the sequence for that enrollment so you don't keep emailing someone who's already responding. Replies thread back into the original conversation in the Inbox.

## Frequently Asked

<AccordionGroup>
  <Accordion title="What happens if a draft fails to generate for one contact?">
    The contact's enrollment shows a red badge with the reason. Click **Retry for this contact** to re-run just that contact's drafts, or **Regenerate all** to restart the whole batch.
  </Accordion>

  <Accordion title="Can I edit a step's day after launching?">
    Yes — the day editor is available on every step card from the review page (and the sequence detail page after launch). Pulling a step earlier is allowed even on running sequences. Editing message content requires pausing the enrollment first.
  </Accordion>

  <Accordion title="Can I send a step right now instead of waiting?">
    Yes. Each step card has a **Send now** button that pulls the schedule forward and tells the cron to send on the next tick. The 4-hour per-contact throttle is bypassed for manual sends.
  </Accordion>

  <Accordion title="Will replies break threading in the Inbox?">
    No. Outbound sequence emails set proper `In-Reply-To` and `References` headers so replies thread into the same conversation. The Inbox uses Message-ID, References, and a sender-fallback to match replies to the right thread.
  </Accordion>

  <Accordion title="Can I cancel a launched sequence?">
    Yes — open the sequence detail page and click **Cancel sequence**. Every pending step is skipped immediately. The sequence record stays around for the audit trail.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="CRM Overview" icon="users" href="/features/crm/overview">
    Back to the CRM hub
  </Card>

  <Card title="Activity Feed" icon="clock-rotate-left" href="/features/crm/activity">
    See every sequence send in the unified activity feed
  </Card>

  <Card title="Plans & Billing" icon="credit-card" href="/features/settings/plans">
    Included with Pro or higher
  </Card>

  <Card title="Email Channel" icon="envelope" href="/guides/channels/email">
    How outbound email works behind the scenes
  </Card>
</CardGroup>


# Text Clarky
Source: https://docs.clarky.ai/features/crm/text-clarky

Text your CRM over iMessage, RCS, or SMS: ask questions, draft messages, and book meetings from a group chat

## What is Text Clarky?

Text Clarky puts [Ask Clarky](/features/crm/ask-clarky) in your Messages app. Text the Clarky number like you would a coworker and get answers about your contacts, companies, pipeline, meetings, and analytics, or have Clarky draft emails and texts that you approve with a single reply. You can even add Clarky to a group chat with a guest and let it find a time and book the meeting.

Clarky replies over iMessage when the recipient supports it, falling back to RCS and then SMS automatically, all on the same number. There is no app to install.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Ask Anything" icon="message">
    The same CRM knowledge as Ask Clarky, from your phone
  </Card>

  <Card title="Group Chat Booking" icon="calendar-check">
    Add Clarky to a group text and it schedules the meeting for you
  </Card>

  <Card title="Reply YES to Confirm" icon="check">
    Drafted emails, texts, and bookings only go out after you approve
  </Card>

  <Card title="Private by Design" icon="lock">
    In group chats Clarky sticks to scheduling and never shares CRM data
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Add your phone number">
    Clarky recognizes you by your phone number. Add it in either place:

    * Click your avatar in the sidebar, choose **Edit Profile**, and enter your phone number. This applies to every workspace you belong to.
    * Or have a workspace admin set it under **Settings, then Users**, using **Edit User** on your row.

    A phone number can only belong to one Clarky account. If yours is already claimed by another account, you'll see an error when saving.
  </Step>

  <Step title="Find the Clarky number">
    Open **Ask Clarky** in your CRM. The greeting shows the number you can text. Save it as a contact so it's easy to reach.
  </Step>

  <Step title="Send your first text">
    Text anything you'd ask in the web app: "How many deals closed this month?", "Catch me up on Rafael", "Who should I follow up with this week?"
  </Step>
</Steps>

## What You Can Do

Text Clarky can answer the same questions and take the same actions as Ask Clarky in the web app:

* Search contacts and companies, and pull up anyone's details and history
* Summarize your pipeline, analytics, and running sequences
* List today's or this week's meetings
* Draft an email or text to a contact, then send it after you reply YES
* Log notes, calls, and meetings
* Check availability, share your booking link, and book meetings

Replies are kept short and text-friendly. For big result sets, Clarky gives you the count and highlights instead of a wall of messages.

## Confirming Actions with YES or NO

Anything that sends or books is prepared as a draft first. Clarky texts you a recap and waits:

* Reply **YES** to send the email or text, or confirm the booking
* Reply **NO** to cancel
* Reply with anything else and the draft is discarded, so a stray "yes" later can never fire an old draft

Only you (the workspace admin) can approve emails and texts. Drafts also expire on their own after 30 minutes.

## Booking Meetings in a Group Chat

The fastest way to schedule with someone: start a group text that includes your guest and the Clarky number, then ask Clarky to find a time.

<Steps>
  <Step title="Start the group">
    Create a group text with your guest (or guests) and the Clarky number, and say something like "Clarky, help us find 30 minutes next week."
  </Step>

  <Step title="Clarky proposes times">
    Clarky checks your real availability, proposes two or three open slots, and shares your booking page link so the guest can also browse on their own.
  </Step>

  <Step title="Agree and confirm">
    When a time works, Clarky collects the guest's name and email, recaps the booking, and books it after a YES. The guest gets a confirmation email with the calendar invite, and it lands on your calendar like any other booking.
  </Step>
</Steps>

<Note>
  Group chats are strictly for scheduling. Clarky will not share contact records, pipeline data, or anything else from your CRM in a thread that includes guests.
</Note>

<Tip>
  Clarky can only reply to threads that message it first, so always start the group chat yourself and include the Clarky number from the beginning.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Clarky doesn't reply to my texts">
    Make sure your phone number is saved on your profile (avatar menu, then Edit Profile) and that your workspace is on the Standard plan or higher. If you text from a number Clarky doesn't recognize, it replies with instructions instead of answers.
  </Accordion>

  <Accordion title="I'm in multiple workspaces. Which one does Clarky use?">
    Texts route to your default workspace. Switch your default workspace in the app to change where your texts go.
  </Accordion>

  <Accordion title="Clarky answered in the group but won't share other info">
    That's intentional. Group chats with guests are scheduling-only so your CRM data stays private. Text Clarky directly (1:1) for everything else.
  </Accordion>

  <Accordion title="My draft disappeared before I said YES">
    Drafts expire after 30 minutes, and replying with anything other than YES or NO discards them. Just ask Clarky to draft it again.
  </Accordion>
</AccordionGroup>


# Dashboard Overview
Source: https://docs.clarky.ai/features/dashboard/overview

Monitor your AI agent's performance at a glance

## What is the Dashboard?

The Dashboard is your central hub for monitoring your AI agent's performance. Get real-time insights into conversations, key metrics, and overall agent effectiveness. With the Clarky 2 redesign, the Dashboard (along with Ask Clarky, Inbox, CRM, Calendar, Context, and Settings) is always one click away in the sidebar.

<Frame>
  <img alt="Clarky dashboard" />
</Frame>

## Key Sections

<CardGroup>
  <Card title="Key Metrics" icon="chart-line" href="/features/dashboard/metrics">
    View essential performance indicators
  </Card>

  <Card title="Analytics" icon="chart-bar" href="/features/dashboard/analytics">
    Dive deep into conversation data
  </Card>

  <Card title="Recent Conversations" icon="messages">
    Quick access to latest interactions
  </Card>

  <Card title="Active Users" icon="users">
    See who's currently chatting
  </Card>
</CardGroup>

## Accessing the Dashboard

Navigate to the Dashboard from any page:

<Steps>
  <Step title="Select Your Agent">
    From the workspace, choose the agent you want to monitor.
  </Step>

  <Step title="Click 'Dashboard'">
    The Dashboard is usually the default landing page for each agent.
  </Step>

  <Step title="Explore Metrics">
    Scroll through to see all available insights.
  </Step>
</Steps>

## Dashboard Layout

### Top Overview Cards

The dashboard displays key metrics prominently at the top:

* **Total Conversations**: Count of all conversations in the selected time period
* **Average Response Time**: How quickly your agent responds
* **Resolution Rate**: Percentage of conversations resolved without human help
* **Active Now**: Number of users currently in conversation

### Conversation Timeline

Visual representation of conversation volume over time:

* See peaks and valleys in customer inquiries
* Identify busy times of day
* Plan staffing accordingly
* Track growth trends

### Channel Breakdown

View performance by channel:

<Tabs>
  <Tab title="Chat">
    * Number of chat conversations
    * Average chat duration
    * Most common questions
    * User satisfaction ratings
  </Tab>

  <Tab title="Voice">
    * Total calls received
    * Average call duration
    * Call resolution rate
    * Missed calls
  </Tab>

  <Tab title="Text/SMS">
    * Text messages exchanged
    * Response time
    * Opt-out rate
    * Popular topics
  </Tab>

  <Tab title="Email">
    * Emails processed
    * Response time
    * Escalation rate
    * Customer replies
  </Tab>
</Tabs>

## Time Range Selection

Filter data by different time periods:

* **Today**: Real-time data for the current day
* **Yesterday**: Previous day's performance
* **Last 7 Days**: Week-over-week trends
* **Last 30 Days**: Monthly overview
* **Last 90 Days**: Quarterly analysis
* **Custom Range**: Select specific dates

<Note>
  The time range selector affects all metrics and charts on the dashboard.
</Note>

## Quick Actions

Access common tasks directly from the dashboard:

<CardGroup>
  <Card title="View All Conversations" icon="inbox">
    Jump to the full inbox to see all conversations
  </Card>

  <Card title="Add Context" icon="file-lines">
    Quickly add to what your agent knows
  </Card>

  <Card title="Adjust Settings" icon="gear">
    Modify agent configuration
  </Card>

  <Card title="View Contacts" icon="users">
    Access your CRM contacts
  </Card>
</CardGroup>

## Recent Activity Feed

See latest interactions:

* New conversations started
* Messages sent by the agent
* Human takeovers
* Escalations
* Completed conversations

Each activity item shows:

* **Timestamp**: When it occurred
* **Channel**: Where it happened (chat, voice, text, email)
* **Quick Preview**: Snippet of the conversation
* **Status**: Active, completed, or needs attention

Click any activity to view the full conversation.

## Performance Indicators

Visual indicators help you quickly assess performance:

### Status Indicators

* 🟢 **Green**: Everything operating normally
* 🟡 **Yellow**: Minor issues or areas needing attention
* 🔴 **Red**: Critical issues requiring immediate action

### Trend Arrows

* ↗️ **Up Arrow**: Metric increasing compared to previous period
* ↘️ **Down Arrow**: Metric decreasing
* → **Flat Arrow**: No significant change

## Notifications

The dashboard displays important notifications:

<AccordionGroup>
  <Accordion title="Agent Needs Attention">
    Conversations waiting for human takeover.
  </Accordion>

  <Accordion title="Unanswered questions">
    Questions the agent could not answer, waiting in Context > Q\&A.
  </Accordion>

  <Accordion title="System Alerts">
    Integration issues, payment problems, or configuration warnings.
  </Accordion>

  <Accordion title="Milestones">
    Achievements like "1000th conversation" or high satisfaction ratings.
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Check Daily">
    Make the dashboard part of your daily routine to stay on top of agent performance.
  </Accordion>

  <Accordion title="Watch Trends">
    Pay attention to trends over time rather than day-to-day fluctuations.
  </Accordion>

  <Accordion title="Act on Insights">
    When you notice patterns (busy times, common questions), adjust your agent or staffing.
  </Accordion>

  <Accordion title="Compare Channels">
    Look at performance across channels to see which are most effective for your business.
  </Accordion>

  <Accordion title="Set Goals">
    Track specific metrics relevant to your business goals (e.g., lead capture rate, resolution time).
  </Accordion>
</AccordionGroup>

## Customizing Your Dashboard

While the default dashboard layout works for most users, you can customize:

* Which metrics appear at the top
* Time range defaults
* Notification preferences
* Data refresh frequency

<Card title="Dashboard Settings" icon="sliders" href="/features/settings/overview">
  Customize your dashboard experience
</Card>

## Mobile Access

Access your dashboard on mobile:

* Responsive design works on any device
* Mobile app provides optimized view
* Real-time notifications on your phone
* Quick actions available

<Card title="Get Mobile App" icon="mobile" href="/features/settings/mobile-app">
  Download the Clarky mobile app
</Card>

## Exporting Data

Export dashboard data for reports:

* Download as CSV or Excel
* Schedule automated reports
* Share with stakeholders
* Integrate with BI tools

<Note>
  Data exports respect your selected time range and filters.
</Note>

## Next Steps

<CardGroup>
  <Card title="View Detailed Metrics" icon="chart-line" href="/features/dashboard/metrics">
    Explore individual performance metrics
  </Card>

  <Card title="Analyze Performance" icon="chart-bar" href="/features/dashboard/analytics">
    Deep dive into analytics
  </Card>

  <Card title="Check Inbox" icon="inbox" href="/features/inbox/overview">
    Review conversations
  </Card>

  <Card title="Improve Agent" icon="file-lines" href="/features/context/overview">
    Enhance your agent's knowledge
  </Card>
</CardGroup>


# Embedding Forms
Source: https://docs.clarky.ai/features/forms/embedding

Embed forms on your website and pre-fill values with query parameters

## Sharing and Embedding Options

Every Clarky form has a public URL and a ready-to-paste iframe embed. You can use whichever is most convenient:

<CardGroup>
  <Card title="Public URL" icon="link">
    Share a direct link to the hosted form on `clarky.ai/f/[form-id]`.
  </Card>

  <Card title="Iframe Embed" icon="code">
    Drop a snippet of HTML onto your own website to embed the form inline.
  </Card>
</CardGroup>

## The Public Form URL

Every form has a public, shareable URL of the form:

```
https://clarky.ai/f/[form-id]
```

You can find the URL and copy it from the form's view/preview page. It works in any browser and automatically renders the right experience based on the form's style — traditional or survey.

<Tip>
  The public URL is great for sharing on social media, in emails, or in QR codes. No technical setup required.
</Tip>

### Short links and custom domains

Give the form a **URL slug** in Form Settings and the link becomes `https://clarky.ai/f/onboarding` instead of a long ID. On Pro and higher you can also serve the form from a domain you own, so the same form lives at `forms.yourcompany.com/onboarding`. The view page has a host selector that switches the public link and every embed snippet below between `clarky.ai` and your live custom domains.

<Card title="Custom Domains" icon="globe" href="/features/settings/custom-domains">
  Add your domain, set slugs, and brand each domain with a favicon and social preview image.
</Card>

## Iframe Embed Code

The form editor's view page includes copy-paste embed code for both styles. Pick the snippet that matches your form.

<Tabs>
  <Tab title="Traditional">
    Traditional forms work well at a fixed height inside an existing page layout:

    ```html theme={null}
    <iframe
      src="https://clarky.ai/f/[form-id]?embed=true"
      width="100%"
      height="600"
      style="border: none;">
    </iframe>
    ```

    The `?embed=true` flag adjusts the form for in-page embedding (no extra padding around the edges).
  </Tab>

  <Tab title="Survey">
    Surveys are full-screen experiences and need room to breathe. Give the iframe full width and a generous minimum height:

    ```html theme={null}
    <iframe
      src="https://clarky.ai/f/[form-id]"
      width="100%"
      height="100%"
      style="border: none; min-height: 600px;">
    </iframe>
    ```
  </Tab>
</Tabs>

<Note>
  Replace `[form-id]` with the actual form ID. The form's view page already shows the snippet with the correct ID filled in — copy directly from there.
</Note>

## Pre-Filling Values via Query Parameters

You can pre-populate any field by passing its ID as a query parameter on the form URL. This is incredibly useful for things like:

* Linking from a marketing email and pre-filling the recipient's name and email
* Tracking the source of a lead by pre-filling a custom "source" field
* Personalizing forms based on what a user clicked to get there

### Example

```
https://clarky.ai/f/[form-id]?first_name=John&emails=john@example.com
```

In this example, the **First name** and **Email** fields will be filled in with "John" and "[john@example.com](mailto:john@example.com)" before the user even sees the form.

### Standard Field IDs

Use these IDs for standard contact fields:

| Field          | Query parameter |
| -------------- | --------------- |
| First name     | `first_name`    |
| Last name      | `last_name`     |
| Email          | `emails`        |
| Phone          | `phone_numbers` |
| Company        | `company`       |
| Job title      | `job_title`     |
| Address line 1 | `address_line1` |
| Address line 2 | `address_line2` |
| City           | `city`          |
| State          | `state`         |
| Postal code    | `postal_code`   |
| Country        | `country`       |

### Custom Field IDs

Each custom field also has a unique ID (visible in the form editor). Pass that ID as a query parameter the same way:

```
https://clarky.ai/f/[form-id]?cf_referral_code=PROMO2025
```

<Tip>
  Pre-filling works with both traditional and survey forms. On surveys, pre-filled answers appear when the user reaches the matching question.
</Tip>

## Common Embedding Patterns

<AccordionGroup>
  <Accordion title="Marketing Email Personalization">
    Build the form URL dynamically in your email tool:

    ```
    https://clarky.ai/f/[form-id]?first_name={{contact.first_name}}&emails={{contact.email}}
    ```

    When recipients click through, their info is pre-filled — they only have to fill in what's missing.
  </Accordion>

  <Accordion title="Lead Source Tracking">
    Add a hidden custom field for "lead source" and pass it via query string from each landing page or campaign:

    ```
    https://clarky.ai/f/[form-id]?cf_source=homepage-hero
    ```

    Now every submission tells you exactly where the lead came from.
  </Accordion>

  <Accordion title="Embedded on a Landing Page">
    Drop the iframe snippet inside any landing page, blog post, or marketing site. The embedded form picks up the same submission flow as the public URL — contacts, pipeline stages, tags, and notifications all behave identically.
  </Accordion>

  <Accordion title="QR Codes and SMS">
    The public form URL works perfectly in QR codes for printed materials, business cards, or in-store signage. Surveys are especially good here because the full-screen experience feels native on mobile.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Review Submissions" icon="table" href="/features/forms/submissions">
    See how your embedded form's responses are tracked
  </Card>

  <Card title="Traditional Forms" icon="rectangle-list" href="/features/forms/traditional">
    Build a standard form
  </Card>

  <Card title="Survey Forms" icon="message-question" href="/features/forms/survey">
    Build a one-question-at-a-time experience
  </Card>

  <Card title="Forms Overview" icon="circle-info" href="/features/forms/overview">
    Back to the Forms overview
  </Card>
</CardGroup>


# Forms Overview
Source: https://docs.clarky.ai/features/forms/overview

Capture leads and survey responses with traditional and survey-style forms

## What are Forms?

Forms let you collect leads, gather feedback, and capture survey responses directly into your Clarky CRM. Every submission becomes a contact (or updates an existing one) and can automatically land on a pipeline stage with default tags applied.

Clarky offers two distinct form styles, so you can pick the experience that fits your audience and use case.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Traditional Forms" icon="rectangle-list" href="/features/forms/traditional">
    Standard multi-field forms with all questions visible at once
  </Card>

  <Card title="Survey Forms" icon="message-question" href="/features/forms/survey">
    Typeform-style, one-question-at-a-time experience with keyboard shortcuts
  </Card>

  <Card title="Embedding" icon="code" href="/features/forms/embedding">
    Embed forms on your site and pre-fill values via query params
  </Card>

  <Card title="Submissions" icon="table" href="/features/forms/submissions">
    View, export, and manage submitted responses
  </Card>
</CardGroup>

## The Two Form Styles

<Tabs>
  <Tab title="Traditional">
    A familiar, single-page form with all fields visible at the same time. Best for:

    * Contact forms and lead capture
    * Job applications
    * Anything where users want to scan all the fields before answering
    * Forms embedded inside an existing page layout

    Traditional forms support standard contact fields (name, email, phone, address, company, job title) plus custom fields you define yourself.
  </Tab>

  <Tab title="Survey">
    A full-screen, one-question-at-a-time experience inspired by Typeform. Best for:

    * Quizzes and questionnaires
    * Multi-step lead qualification
    * Feedback or NPS-style surveys
    * High-engagement experiences where you want focus on one question

    Survey forms include a progress bar, keyboard shortcuts, auto-advance, and seven question types including a powerful nested form-fields question.
  </Tab>
</Tabs>

## What Happens on Submission

<Steps>
  <Step title="Validation">
    Required fields, email formats, and phone numbers (10+ digits) are validated.
  </Step>

  <Step title="Contact Created or Updated">
    Clarky dedupes by email and phone. New contacts are created automatically; existing ones are updated.
  </Step>

  <Step title="Pipeline Card Added">
    If the form has a default pipeline stage, the contact lands there with any default deal value and tags applied.
  </Step>

  <Step title="Submission Recorded">
    The full submission is saved to the form's submissions table for review and export.
  </Step>

  <Step title="Notification Sent">
    Team members receive an email summary with all submitted answers.
  </Step>

  <Step title="Success or Redirect">
    The submitter sees your custom success message, or is redirected to a URL you configure.
  </Step>
</Steps>

## Form Defaults

Each form can be configured with defaults that apply to every new contact it creates:

<AccordionGroup>
  <Accordion title="Pipeline Stage">
    Choose the stage where new contacts will land. Useful for routing form leads directly into a "New Lead" or "Inbound" stage.
  </Accordion>

  <Accordion title="Default Deal Value">
    Pre-populate a deal value on the pipeline card. Helpful when a specific form (like a "Request a Quote" page) corresponds to a known average deal size.
  </Accordion>

  <Accordion title="Default Tags">
    Apply tags automatically to new contacts. Great for tracking lead source ("webinar-signup", "homepage-form", etc.).
  </Accordion>

  <Accordion title="Submit Button Text">
    Customize the submit button label.
  </Accordion>

  <Accordion title="Success Message or Redirect">
    Show a custom thank-you message or send users to any URL after they submit.
  </Accordion>
</AccordionGroup>

## Getting Started

<Steps>
  <Step title="Open Forms">
    Navigate to **CRM > Forms** in your workspace.
  </Step>

  <Step title="Create a Form">
    Click **New Form** and pick a name and description.
  </Step>

  <Step title="Choose a Style">
    Switch between **Traditional** and **Survey** at the top of the editor.
  </Step>

  <Step title="Build Your Fields or Questions">
    Add standard fields, custom fields, or survey questions.
  </Step>

  <Step title="Configure Defaults">
    Set a pipeline stage, default tags, and your success message.
  </Step>

  <Step title="Embed or Share">
    Copy the embed code or share the public form URL.
  </Step>
</Steps>

<Tip>
  You can preview any form before publishing. Test submissions are flagged with an internal badge in the submissions table so they don't pollute your real data.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Build a Traditional Form" icon="rectangle-list" href="/features/forms/traditional">
    Standard fields and custom field types
  </Card>

  <Card title="Build a Survey" icon="message-question" href="/features/forms/survey">
    Question types, shortcuts, and auto-advance
  </Card>

  <Card title="Embed on Your Site" icon="code" href="/features/forms/embedding">
    Iframe code and pre-fill via URL
  </Card>

  <Card title="Review Submissions" icon="table" href="/features/forms/submissions">
    Export to JSON or CSV
  </Card>
</CardGroup>


# Form Submissions
Source: https://docs.clarky.ai/features/forms/submissions

View, manage, and export form responses

## The Submissions Table

Every form has its own submissions page where you can review every response that's come in. Open it from the form editor or from **CRM > Forms**, then click the **Submissions** link on the form you want to review.

The submissions table shows all responses with sortable columns, an internal/test badge, quick links to the contact record, and an export menu.

## What's in the Table

### Standard Columns

Every submissions table includes these columns by default:

* **Submitted** — date and time of the submission
* **Contact name** — name of the contact created or updated
* **Email** — email captured from the submission
* **Phone** — phone number captured from the submission

### Response Columns

The remaining columns depend on the form's style:

<Tabs>
  <Tab title="Traditional Forms">
    A column for each custom field on the form. Standard contact fields populate the existing name/email/phone columns.
  </Tab>

  <Tab title="Survey Forms">
    A column for each question. Form fields questions are automatically expanded — each standard or custom field inside a form fields question becomes its own column, so you can see all the data at a glance instead of a single nested blob.
  </Tab>
</Tabs>

### Internal Submission Badge

Submissions made through the **preview** in the form editor are tagged with an **Internal** badge in the table. This makes it easy to identify test data and keep it separate from real responses.

<Tip>
  Filter or visually scan for the Internal badge when you're reviewing real lead activity. Test submissions never trigger external automations like notifications.
</Tip>

## Actions on Each Submission

For each row in the submissions table you can:

<CardGroup>
  <Card title="View Contact" icon="user">
    Jump straight to the contact's record in the CRM to see their full history
  </Card>

  <Card title="Delete Submission" icon="trash">
    Remove a submission you no longer want to keep
  </Card>
</CardGroup>

<Warning>
  Deleting a submission removes the response record but doesn't remove the contact it created. Use the CRM if you also want to delete the contact.
</Warning>

## Exporting Submissions

The submissions page has an **Export** dropdown with two formats:

<Tabs>
  <Tab title="Export as JSON">
    Downloads all submissions as a JSON array, formatted for readability. Use this when you want a structured, machine-readable snapshot of all responses.
  </Tab>

  <Tab title="Export as CSV">
    Downloads all submissions as a CSV file that opens cleanly in Excel, Numbers, or Google Sheets. Use this for spreadsheet analysis or sharing with non-technical teammates.
  </Tab>
</Tabs>

Both formats include:

* Submitted date and time
* Contact name, email, and phone
* The internal/test flag
* Every response column, including form fields expanded into individual fields

## Contact Creation Behavior

Every submission either creates a new contact or updates an existing one:

<Steps>
  <Step title="Dedupe by Email and Phone">
    Clarky checks the submission's email and phone against existing contacts.
  </Step>

  <Step title="Update or Create">
    If a match is found, the existing contact is updated with any new info from the submission. If not, a brand-new contact is created.
  </Step>

  <Step title="Apply Form Defaults">
    For new contacts, the form's default tags are added.
  </Step>

  <Step title="Add to Pipeline">
    If the form has a default pipeline stage, a pipeline card is created (with the default deal value, if set).
  </Step>
</Steps>

<Note>
  Updates only add or refresh information — they don't overwrite tags or pipeline stages on contacts that already exist. This protects long-term contacts from being reset every time they fill out a form.
</Note>

## Email Notifications

When notifications are enabled for a form, your team gets an email every time someone submits. The email includes:

* The form name and submitter's contact info
* All submitted answers with proper formatting
* Each question and answer pair on its own line for easy scanning
* Form fields questions broken out field-by-field (no nested blobs)

<Tip>
  Make sure each form's notifications are routed to the right team. A "Contact Sales" form should notify your sales team; a "Customer Feedback" form might notify support.
</Tip>

## Pipeline Cards from Submissions

If you set a **default pipeline stage** on the form, every new contact created from a submission will automatically appear as a card on that stage in your sales pipeline.

The card includes:

* Contact name
* Default deal value (if configured)
* Default tags (if configured)
* A link back to the contact and the original submission

<Check>
  This is the fastest path from "lead form on website" to "card in your pipeline" — no manual data entry required.
</Check>

## Next Steps

<CardGroup>
  <Card title="Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
    See how form submissions land on your pipeline
  </Card>

  <Card title="Manage Contacts" icon="users" href="/features/crm/contacts">
    Work with the contacts your forms create
  </Card>

  <Card title="Embed a Form" icon="code" href="/features/forms/embedding">
    Get more responses by embedding on your site
  </Card>

  <Card title="Forms Overview" icon="circle-info" href="/features/forms/overview">
    Back to the Forms overview
  </Card>
</CardGroup>


# Survey Forms
Source: https://docs.clarky.ai/features/forms/survey

Build Typeform-style, one-question-at-a-time experiences with keyboard shortcuts and auto-advance

## What is a Survey Form?

A survey form presents one question at a time in a full-screen, focused experience. It's modeled after Typeform: progress bar at the top, big readable text, smooth keyboard navigation, and auto-advance on single-choice questions. Survey forms are great for quizzes, lead qualification flows, onboarding questionnaires, and feedback surveys.

## Building a Survey

<Steps>
  <Step title="Create a New Form">
    Go to **CRM > Forms** and click **New Form**.
  </Step>

  <Step title="Set the Style to Survey">
    At the top of the editor, switch to the **Survey** tab.
  </Step>

  <Step title="Add Questions">
    Use the **Add Question** dropdown to add any of the seven question types.
  </Step>

  <Step title="Reorder and Edit">
    Drag or use up/down arrows to reorder. Edit each question's text, subtitle, choices, and required setting.
  </Step>

  <Step title="Configure Defaults">
    Set the pipeline stage, default tags, and success message.
  </Step>

  <Step title="Save and Share">
    Save the form, then embed it or share the public link.
  </Step>
</Steps>

## Editor View Modes

The survey editor has two view modes you can toggle between:

<Tabs>
  <Tab title="Slideshow View">
    Edit one question at a time, just like respondents will see it. This is the default view and is best for fine-tuning copy and choice wording.
  </Tab>

  <Tab title="List View">
    See all questions at once in a stacked layout. Best for reordering, adding, or removing questions quickly.
  </Tab>
</Tabs>

<Note>
  Your view mode preference is remembered between sessions.
</Note>

## Question Types

<CardGroup>
  <Card title="Single Choice" icon="circle-dot">
    Radio-style selection. Auto-advances after the user picks an option.
  </Card>

  <Card title="Multiple Choice" icon="square-check">
    Checkbox-style. User picks any number of options and clicks **OK** to continue.
  </Card>

  <Card title="Short Text" icon="input-text">
    Single-line text input.
  </Card>

  <Card title="Long Text" icon="align-left">
    Multi-line textarea for longer responses.
  </Card>

  <Card title="Email" icon="envelope">
    Validated email field.
  </Card>

  <Card title="Phone" icon="phone">
    Validated phone field (10+ digits).
  </Card>

  <Card title="Form Fields" icon="rectangle-list">
    Embed a full traditional form (multiple fields) inside a single survey question.
  </Card>
</CardGroup>

### Single Choice

Single choice questions show a list of options. The user picks one, and the survey automatically advances to the next question.

* Up to **8 choices** per question
* Each choice gets an **auto-assigned letter shortcut** (A through H)
* Smart Yes/No detection: if your choices are exactly "Yes" and "No", the shortcuts switch to **Y** and **N** for a more natural experience

### Multiple Choice

Use multiple choice when respondents can pick more than one option:

* Selected items show a checkmark
* The hint "Choose as many as you like" appears below
* The user clicks **OK** (or presses Enter) to advance — there's no auto-advance
* Letter shortcuts (A-H) toggle each choice on or off

### Text, Long Text, Email, Phone

Text-based questions show a clean underlined input field. Email and phone fields are validated automatically — invalid entries can't proceed.

## Auto-Advance

When a respondent picks a single-choice option, Clarky automatically moves them to the next question:

<Steps>
  <Step title="Selection Recorded">
    The choice is saved as soon as the user clicks or presses its shortcut key.
  </Step>

  <Step title="Choices Lock Briefly">
    The options visually lock for 700ms so the user can see what they picked and avoid accidental double-taps.
  </Step>

  <Step title="Advance to Next Question">
    The survey transitions to the next question automatically.
  </Step>
</Steps>

<Tip>
  Auto-advance only applies to **single choice** questions. Text, multiple choice, and form-fields questions all wait for the user to confirm before advancing.
</Tip>

## Keyboard Shortcuts

The survey experience is fully keyboard-navigable. This is one of the biggest reasons respondents enjoy survey-style forms — they can blast through them quickly.

| Key            | Action                                                |
| -------------- | ----------------------------------------------------- |
| **A** – **H**  | Select a choice by its letter shortcut                |
| **Y** / **N**  | Select Yes or No (on auto-detected Yes/No questions)  |
| **Enter**      | Advance to the next question, or submit on the last   |
| **Arrow Up**   | Go back to the previous question                      |
| **Arrow Down** | Advance to the next question (if the answer is valid) |

<Info>
  Letter shortcuts work for both single choice and multiple choice questions. On multiple choice, pressing the shortcut toggles that option on or off.
</Info>

### Smart Yes/No Shortcuts

If a question has exactly two choices labeled "Yes" and "No" (case-insensitive), the shortcuts automatically switch from A/B to **Y**/**N**. This is much more intuitive for binary questions and overrides any letter shortcuts that would otherwise apply.

## The Form Fields Question Type

The **form fields** question type is unique to survey forms — it lets you embed a full traditional-style form into a single survey slide. Instead of asking one question, you ask several at once, all on the same screen.

### When to Use Form Fields

Form fields questions are perfect for:

* Capturing all contact info (name, email, phone, company) at the end of a survey
* Collecting an address as a group of fields
* Any moment in a survey where breaking up multiple short fields into separate slides would feel tedious

### What You Can Add

Inside a form fields question, you have access to the same fields available in traditional forms:

<AccordionGroup>
  <Accordion title="Standard Fields">
    All standard contact fields, including first name, last name, email, phone, company, job title, and the full address fields. These map directly to the contact record on submission.
  </Accordion>

  <Accordion title="Custom Fields">
    All six custom field types: text, textarea, dropdown, radio, checkbox, and checkbox group. Each can be marked required and reordered independently.
  </Accordion>
</AccordionGroup>

### Configuring a Form Fields Question

<Steps>
  <Step title="Add the Question">
    From the **Add Question** dropdown, choose **Form Fields**.
  </Step>

  <Step title="Add Standard Fields">
    Use the standard-fields dropdown to add any of the built-in contact fields. Only fields you haven't added yet appear in the dropdown.
  </Step>

  <Step title="Add Custom Fields">
    Use the custom-fields dropdown to add new custom fields by type. Set the label, placeholder, options (if applicable), and required toggle for each.
  </Step>

  <Step title="Reorder">
    Use up/down arrows to put fields in the right order.
  </Step>

  <Step title="Set Per-Field Required Status">
    Toggle the required switch for each field individually. The question-level required setting doesn't apply here.
  </Step>
</Steps>

<Note>
  On a form fields question, **required is set per field**, not on the question as a whole. This gives you fine-grained control over which inputs are mandatory.
</Note>

## Survey-Wide Settings

Just like traditional forms, survey forms support form-level defaults:

* **Submit button text** (shown on the final question)
* **Success message** displayed after submission
* **Redirect URL** to send respondents elsewhere after submitting
* **Pipeline stage** for new contacts
* **Default deal value** and **default tags**

## Previewing Your Survey

The form editor includes a live survey preview so you can experience the survey exactly as a respondent will, including keyboard shortcuts and auto-advance. Test submissions are flagged with an internal badge in the submissions table.

<Tip>
  Run through your survey on a phone before publishing. Surveys are mobile-first and look great on small screens, but it's worth confirming each question reads well before you ship.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Embed on Your Site" icon="code" href="/features/forms/embedding">
    Iframe code and pre-fill via query parameters
  </Card>

  <Card title="Traditional Forms" icon="rectangle-list" href="/features/forms/traditional">
    Standard multi-field forms
  </Card>

  <Card title="Review Submissions" icon="table" href="/features/forms/submissions">
    View and export survey responses
  </Card>

  <Card title="Forms Overview" icon="circle-info" href="/features/forms/overview">
    Back to the Forms overview
  </Card>
</CardGroup>


# Traditional Forms
Source: https://docs.clarky.ai/features/forms/traditional

Build standard multi-field forms with standard and custom fields

## What is a Traditional Form?

A traditional form shows all of its fields on a single page, exactly the way you'd expect a typical web form to behave. Visitors can scan every field, fill them out in any order, and submit when they're ready.

Traditional forms are ideal for contact forms, lead capture, applications, or anywhere you want a familiar, scannable layout.

## Building a Traditional Form

<Steps>
  <Step title="Create a New Form">
    Go to **CRM > Forms** and click **New Form**.
  </Step>

  <Step title="Set the Style to Traditional">
    At the top of the editor, make sure the **Traditional** tab is selected.
  </Step>

  <Step title="Add Standard Fields">
    Pick from Clarky's pre-built contact fields (these map directly to your CRM).
  </Step>

  <Step title="Add Custom Fields">
    Define any additional fields your form needs.
  </Step>

  <Step title="Configure Defaults">
    Set a pipeline stage, default tags, success message, and optional redirect URL.
  </Step>

  <Step title="Save and Embed">
    Save the form and copy the embed code or share the public link.
  </Step>
</Steps>

## Standard Fields

Standard fields are pre-built fields that map directly to contact records in your CRM. Because they're standardized, the values flow into the right place automatically.

<AccordionGroup>
  <Accordion title="Name">
    * **First name**
    * **Last name**
  </Accordion>

  <Accordion title="Contact">
    * **Email** — validated for proper email format
    * **Phone** — validated for at least 10 digits
  </Accordion>

  <Accordion title="Professional">
    * **Company**
    * **Job title**
  </Accordion>

  <Accordion title="Address">
    * **Address line 1**
    * **Address line 2**
    * **City**
    * **State**
    * **Postal code**
    * **Country**
  </Accordion>
</AccordionGroup>

For each standard field you can:

* Customize the **label** and **placeholder**
* Toggle whether it's **required**
* Reorder it relative to other fields

<Tip>
  Always include either an email or phone field on lead-capture forms. Clarky uses these to dedupe contacts, so without them every submission creates a brand-new contact.
</Tip>

## Custom Fields

Custom fields let you collect information beyond the standard contact data. Each custom field has a label, optional placeholder, required toggle, and a type.

### Available Custom Field Types

<CardGroup>
  <Card title="Text" icon="input-text">
    Single-line text input. Good for short answers like a referral code or website URL.
  </Card>

  <Card title="Textarea" icon="align-left">
    Multi-line text input. Use for longer responses, like "How can we help?"
  </Card>

  <Card title="Dropdown" icon="caret-down">
    A select menu where users pick one option from a list you define.
  </Card>

  <Card title="Radio" icon="circle-dot">
    Radio button group — one selection from a visible list of options.
  </Card>

  <Card title="Checkbox" icon="square-check">
    A single yes/no checkbox. Useful for terms acceptance or opt-ins.
  </Card>

  <Card title="Checkbox Group" icon="list-check">
    Multiple checkboxes — users can select any number of options.
  </Card>
</CardGroup>

### Configuring Options for Choice Fields

Dropdown, radio, and checkbox group fields require a list of options. In the field editor, enter one option per line in the options textarea.

<Note>
  Single checkboxes don't take options — they're a simple yes/no toggle.
</Note>

## Form Defaults

Configure what happens when a contact submits the form:

<AccordionGroup>
  <Accordion title="Submit Button Text">
    Change the default "Submit" label to something more specific like "Get a Quote" or "Sign Me Up".
  </Accordion>

  <Accordion title="Success Message">
    The message shown after submission. Keep it short and clear.
  </Accordion>

  <Accordion title="Redirect URL">
    Optionally redirect users to a thank-you page or a related resource after they submit.
  </Accordion>

  <Accordion title="Pipeline Stage">
    Choose which CRM pipeline stage new contacts land on.
  </Accordion>

  <Accordion title="Default Deal Value">
    Pre-populate a deal value on the new pipeline card.
  </Accordion>

  <Accordion title="Default Tags">
    Tags applied automatically to every contact created by this form.
  </Accordion>
</AccordionGroup>

## Previewing and Testing

The form editor includes a live preview where you can fill out and submit the form to see exactly how it behaves. Submissions made through the preview are flagged with an internal badge so you can keep test data separate from real responses.

<Tip>
  Always submit at least one test entry to confirm validation, your success message, and that the new contact lands in the right pipeline stage.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Embed on Your Site" icon="code" href="/features/forms/embedding">
    Iframe code and pre-fill via query parameters
  </Card>

  <Card title="Try Survey Style" icon="message-question" href="/features/forms/survey">
    One-question-at-a-time experience
  </Card>

  <Card title="Review Submissions" icon="table" href="/features/forms/submissions">
    View and export form responses
  </Card>

  <Card title="Sales Pipeline" icon="chart-line" href="/features/crm/sales-pipeline">
    Where new contacts land in your pipeline
  </Card>
</CardGroup>


# Managing Conversations
Source: https://docs.clarky.ai/features/inbox/conversations

View, respond to, and organize customer conversations

## Viewing Conversations

Each conversation displays:

* **Complete message history** - All messages in chronological order
* **Customer information** - Name, contact details, previous interactions
* **Conversation metadata** - Channel, timestamp, duration, status
* **AI confidence scores** - How confident the agent was in responses

## Message Types

Conversations can include various message types:

<Tabs>
  <Tab title="Text Messages">
    Standard text communication with formatting support
  </Tab>

  <Tab title="Images and Attachments">
    Visual content shared by users or agent
  </Tab>

  <Tab title="System Messages">
    Automated notifications (user joined, transferred, etc.)
  </Tab>

  <Tab title="Quick Replies">
    Button-based responses for easy selection
  </Tab>
</Tabs>

## Conversation Actions

### Quick Actions

Perform common tasks directly from the conversation view:

<CardGroup>
  <Card title="Take Over" icon="hand">
    Assume control of the conversation
  </Card>

  <Card title="Add to CRM" icon="user-plus">
    Create or link a CRM contact
  </Card>

  <Card title="Add Note" icon="note">
    Attach internal notes
  </Card>

  <Card title="Mark Complete" icon="check">
    Close the conversation
  </Card>
</CardGroup>

### Responding to Messages

When you take over a conversation:

1. Agent pauses automatic responses
2. You type and send messages manually
3. User sees smooth transition
4. You can hand back to AI when done

## Organizing Conversations

### Tags

Add custom tags to categorize conversations:

* **By Topic**: billing, support, sales
* **By Priority**: urgent, normal, low
* **By Outcome**: resolved, escalated, pending
* **Custom Tags**: Create your own categories

### Notes

Add internal notes that customers don't see:

* Context about the conversation
* Follow-up requirements
* Special customer needs
* Resolution details

## Next Steps

<Card title="Learn Human Takeover" icon="hand" href="/features/inbox/human-takeover">
  Master taking over conversations
</Card>


# Search and Filtering
Source: https://docs.clarky.ai/features/inbox/filtering

Find conversations quickly with powerful search

## Search Functionality

Find any conversation instantly using the search bar.

### Search By

* **Customer Name**: Find all conversations with a specific person
* **Email or Phone**: Search by contact information
* **Keywords**: Search message content
* **Conversation ID**: Look up specific conversation
* **Date Range**: Find conversations in a time period

### Search Examples

```
Search: "billing issue"
Results: All conversations mentioning billing issues

Search: john@example.com
Results: All conversations with that email

Search: after:2024-01-01
Results: Conversations since January 1, 2024
```

## Filters

Narrow down conversations using filters:

### By Channel

* Chat
* Voice
* Text/SMS
* Email

### By Status

* Active
* Completed
* Needs Attention
* Escalated
* Archived

### By Date

* Today
* Yesterday
* Last 7 days
* Last 30 days
* Custom range

### By Rating

* 5 stars
* 4 stars
* 3 stars or below
* Unrated

### By Tags

Filter by any custom tags you've created.

## Saved Filters

Create and save commonly used filter combinations:

<Steps>
  <Step title="Set Up Filters">
    Apply the filters you want to save.
  </Step>

  <Step title="Click 'Save Filter'">
    Give it a descriptive name.
  </Step>

  <Step title="Access Anytime">
    Your saved filter appears in the sidebar for quick access.
  </Step>
</Steps>

### Common Saved Filters

* "Needs My Attention" - Escalated conversations
* "High Priority" - Urgent tagged conversations
* "This Week's Chats" - Recent chat conversations
* "Unresolved" - Open conversations

## Sorting Options

Sort conversations by:

* **Most Recent**: Newest first (default)
* **Oldest First**: Address old conversations
* **Rating**: Highest or lowest rated first
* **Duration**: Longest or shortest conversations
* **Channel**: Group by communication method

<Tip>
  Combine search, filters, and sorting to find exactly what you need quickly.
</Tip>

## Bulk Actions

Select multiple conversations to:

* Apply tags in bulk
* Mark as complete
* Export data
* Assign to team members

<Card title="Back to Inbox" icon="inbox" href="/features/inbox/overview">
  Return to Inbox overview
</Card>


# Human Takeover
Source: https://docs.clarky.ai/features/inbox/human-takeover

Seamlessly take control of conversations when needed

## What is Human Takeover?

Human takeover allows you to step into an ongoing conversation with your AI agent, providing personalized assistance when needed.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## When to Take Over

Consider taking over when:

* Customer explicitly requests a human
* Issue is complex or sensitive
* Agent confidence is low
* Special circumstances arise
* Upsell or sales opportunity

## How to Take Over

<Steps>
  <Step title="Spot the Conversation">
    Conversations needing attention are highlighted in your inbox.
  </Step>

  <Step title="Click 'Take Over'">
    Select the "Take Over" button in the conversation view.
  </Step>

  <Step title="Review Context">
    Read the full conversation history quickly.
  </Step>

  <Step title="Respond">
    Type your message - the customer sees it's from a human.
  </Step>
</Steps>

## Auto-Escalation Triggers

Configure your agent to automatically request human help when:

* Negative sentiment detected
* Multiple failed response attempts
* Specific keywords mentioned ("speak to manager")
* Complex scenarios identified
* High-value customer detected

Set up in **Settings > Agent > Escalation Rules**.

## Best Practices

<AccordionGroup>
  <Accordion title="Respond Quickly">
    When you take over, respond within 1-2 minutes. Users expect faster responses from humans.
  </Accordion>

  <Accordion title="Acknowledge the Transition">
    Start with "Hi, I'm \[Name] from the team. I'm here to help you with..."
  </Accordion>

  <Accordion title="Use Agent Context">
    Review what the agent already discussed to avoid repeating questions.
  </Accordion>

  <Accordion title="Return to AI When Appropriate">
    Once resolved, you can hand back to the AI for follow-up questions.
  </Accordion>
</AccordionGroup>

## Collaboration Features

* **Team Notifications**: Alert specific team members
* **Internal Chat**: Discuss with colleagues without customer seeing
* **Transfer**: Pass conversation to another team member
* **Consult Mode**: Get help from AI while you control the conversation

<Card title="Configure Notifications" icon="bell" href="/features/settings/notifications">
  Set up human takeover alerts
</Card>


# Inbox Overview
Source: https://docs.clarky.ai/features/inbox/overview

Manage all your customer conversations in one place

## What is the Inbox?

The Inbox is your central hub for viewing and managing all customer conversations across chat, voice, text/SMS, and email channels. Every interaction is organized, searchable, and easily accessible.

<Frame>
  <img alt="Clarky Inbox" />
</Frame>

## Key Features

<CardGroup>
  <Card title="Unified View" icon="inbox">
    All channels in one place
  </Card>

  <Card title="Real-Time Updates" icon="bolt">
    See conversations as they happen
  </Card>

  <Card title="Human Takeover" icon="hand">
    Jump into conversations when needed
  </Card>

  <Card title="Search & Filter" icon="filter">
    Find any conversation quickly
  </Card>
</CardGroup>

## Inbox Layout

### Conversation List

The left panel shows all conversations:

* **Most Recent First**: Newest conversations appear at the top
* **Channel Icons**: Identify the communication channel
* **Preview Text**: See the latest message
* **Unread Counts**: Number of unread messages

### Conversation View

The main panel displays the selected conversation:

* **Full Message History**: Complete conversation thread
* **Customer Info**: Contact details and history
* **Quick Actions**: Take over, link to CRM, add notes
* **Channel Context**: Specific details for the channel

### Sidebar

The right panel shows contextual information:

* **Sentiment Analysis**: Conversation sentiment over time
* **Contact Profile**: Customer name, email, phone
* **Conversation Details**: Duration, status, channel
* **CRM Link**: Associated contact record
* **Tags and Notes**: Custom labels and annotations

## Accessing the Inbox

<Steps>
  <Step title="Navigate to Inbox">
    Click **"Inbox"** in the main navigation.
  </Step>

  <Step title="Browse Conversations">
    Scroll through the list or use search and filters.
  </Step>

  <Step title="Open a Conversation">
    Click any conversation to view the full details.
  </Step>
</Steps>

## Real-Time Features

### Live Conversation Indicators

See when users are actively chatting:

* **Active**: User is currently in the conversation
* **Typing Indicator**: Agent or user is typing
* **Last Seen**: Time of last message

### Notifications

Get notified when:

* New conversation starts
* User sends a message in an active conversation
* Conversation needs human attention
* User has been waiting too long

Configure notifications in **Settings > Notifications**.

## Next Steps

<CardGroup>
  <Card title="View Conversations" icon="messages" href="/features/inbox/conversations">
    Learn about managing conversations
  </Card>

  <Card title="Human Takeover" icon="hand" href="/features/inbox/human-takeover">
    Take control when needed
  </Card>

  <Card title="Filter & Search" icon="filter" href="/features/inbox/filtering">
    Find conversations quickly
  </Card>

  <Card title="Link to CRM" icon="users" href="/features/crm/overview">
    Connect conversations to contacts
  </Card>
</CardGroup>


# A2P 10DLC Registration
Source: https://docs.clarky.ai/features/settings/a2p

Register your business to send compliant SMS in the United States

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

A2P 10DLC ("Application-to-Person on 10-digit long codes") is the registration program every US business has to complete before sending text messages to customers. Clarky walks you through it on the **Texting** settings page and previews exactly what to copy into Twilio.

## Why It's Required

US mobile carriers require every business that texts consumers to register their brand and the kinds of messages they plan to send. The goal is to cut down on spam and to give customers a reliable way to opt out.

<Warning>
  If you send messages without registering, carriers will filter or block your texts and Twilio may suspend your number. Complete A2P registration before launching any SMS use case.
</Warning>

## What You'll Need

Before you start, gather:

<CardGroup>
  <Card title="Business identity" icon="briefcase">
    Legal business name as it appears on your IRS EIN documents, plus a DBA / brand name if you use one.
  </Card>

  <Card title="EIN entity type" icon="id-card">
    Whether your business is a private company, public company, non-profit, sole proprietor, or government entity.
  </Card>

  <Card title="Website" icon="globe">
    A live website with a Privacy Policy and Terms of Service page. Required.
  </Card>

  <Card title="Support contacts" icon="headset">
    A support email and phone number customers can reach you at.
  </Card>

  <Card title="Industry" icon="tag">
    The vertical that best describes your business (healthcare, retail, real estate, etc.).
  </Card>

  <Card title="Use case details" icon="message">
    What kind of messages you'll send (marketing, customer care, or both), how often, and how customers opt in.
  </Card>
</CardGroup>

## Filling Out the Form

<Steps>
  <Step title="Pick your business entity type">
    This must match the entity type on your IRS EIN documentation exactly.
  </Step>

  <Step title="Enter your business name and DBA">
    If your customers know you by a different name than your legal name, mark "Yes, I use a DBA" and provide the public brand name.
  </Step>

  <Step title="Describe your business">
    A few sentences about what you do. Click **Generate from Context** to have Clarky draft a description from your agent's Context documents — you can edit it from there.
  </Step>

  <Step title="Pick an industry">
    Search the list and choose the industry that best fits. Healthcare verticals trigger an extra HIPAA reminder.
  </Step>

  <Step title="Add website and support details">
    Make sure your site has reachable Privacy Policy and Terms of Service pages before submitting.
  </Step>

  <Step title="Choose how customers opt in">
    Website form, paper form, Facebook lead form, QR code, kiosk, or verbal. Pick whichever matches reality.
  </Step>

  <Step title="Pick message types">
    Most businesses send both marketing and customer care messages. Selecting both keeps you flexible.
  </Step>

  <Step title="Pick a campaign use case">
    "Low Volume Mixed" is the recommended option for most small businesses.
  </Step>

  <Step title="Pick a message frequency">
    Pick a slightly higher tier than you think you need to stay compliant if volume grows.
  </Step>

  <Step title="Save">
    Clarky stores your registration, generates a compliant opt-in form for you, and shows the exact Twilio fields to copy in the live preview panel.
  </Step>
</Steps>

## Live Twilio Preview

As you fill out the form, Clarky shows the exact text to paste into each Twilio field on the right side of the page:

* A2P Campaign Use Case
* Campaign Description
* Two sample messages
* Consent description ("How do end-users consent?")
* Privacy Policy and Terms of Service URLs
* Opt-in keywords, opt-in message, STOP response, HELP response

Click any field to copy it, then paste it into the matching field in the [Twilio A2P onboarding](https://console.twilio.com/us1/develop/sms/regulatory-compliance/a2p-onboarding) console.

## Approval Timing

Once submitted to Twilio, brand verification typically takes a few business days, and campaign approval typically takes another few days on top of that. Carriers occasionally take longer during high-volume periods.

<Tip>
  Start the registration process before you actually need to send messages. Approval can take a week or more end-to-end.
</Tip>

## Healthcare and HIPAA

If you select a healthcare-related industry, Clarky shows a HIPAA reminder. Never include Protected Health Information (PHI) in SMS — appointment reminders and replies should stay generic ("You have an appointment tomorrow at 2 PM" rather than anything diagnostic).

<Card title="Back to Texting Settings" icon="message" href="/features/settings/texting">
  Return to Texting Settings
</Card>


# Agent Settings
Source: https://docs.clarky.ai/features/settings/agent

Configure your AI agent's properties and behavior

## Agent Properties

### Basic Information

<ParamField type="string">
  Your agent's display name (e.g., "Support Bot", "Sales Assistant")
</ParamField>

<ParamField type="string">
  Internal description for your reference
</ParamField>

<ParamField type="string">
  URL-friendly identifier for your agent
</ParamField>

## Human Takeover

<ParamField type="boolean">
  Enable/disable human agents taking over conversations
</ParamField>

## Advanced Settings

<AccordionGroup>
  <Accordion title="Response Timeout">
    Maximum time agent takes to generate a response (default: 30 seconds)
  </Accordion>

  <Accordion title="Context Window">
    How many previous messages to consider (default: 10 messages)
  </Accordion>

  <Accordion title="Confidence Display">
    Show confidence scores to human agents (hidden from customers)
  </Accordion>
</AccordionGroup>

<Card title="Next: Integrations" icon="puzzle" href="/features/settings/integrations">
  Connect your business tools
</Card>


# Sentiment Analysis & Escalation
Source: https://docs.clarky.ai/features/settings/analysis

Detect frustrated users, hand off to humans, and act before conversations go sideways

<Info>
  **Plan availability:** Startup or higher for sentiment analysis. Escalation detection and human takeover require Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Overview

The Analysis settings page brings together three related features that help you keep an eye on conversations and step in when it matters:

<CardGroup>
  <Card title="Sentiment Analysis" icon="face-smile">
    Score each conversation and alert you when the mood turns negative.
  </Card>

  <Card title="Escalation Detection" icon="bell">
    Notice when a user explicitly asks for a human and trigger an alert.
  </Card>

  <Card title="Human Takeover" icon="user-headset">
    Let a teammate jump into the conversation and take over from the AI.
  </Card>
</CardGroup>

You'll find all of these under **Settings > Analysis** for the agent you want to configure.

## Sentiment Analysis

Clarky analyzes the tone of every conversation in the background and assigns a **sentiment score** from 0 (very negative) to 100 (very positive). When a conversation drops below the threshold you set, Clarky raises a **bad sentiment alert** so you can review what went wrong — or reach out before the user churns.

### Enabling Sentiment Analysis

<Steps>
  <Step title="Open Analysis settings">
    Go to **Settings > Analysis** for the agent you want to configure.
  </Step>

  <Step title="Toggle Sentiment Analysis on">
    Use the switch next to **Sentiment Analysis**. It's on by default for most agents.
  </Step>

  <Step title="Adjust the threshold">
    Drag the **Positive Sentiment Threshold** slider to set the score below which a conversation is flagged. The default is **60**, and the slider runs from 1 to 100.
  </Step>

  <Step title="Save your changes">
    Click **Save** at the bottom of the page once you're happy with the values.
  </Step>
</Steps>

### Choosing a Threshold

* **Lower values (around 30–50)** flag only clearly negative conversations. Good if you only want alerts for serious issues.
* **Default (60)** is a balanced starting point — flags conversations that are noticeably frustrated or unsatisfied.
* **Higher values (70–80)** flag anything that isn't clearly positive. Good for high-touch customer success teams who want to follow up on lukewarm conversations.

<Tip>
  You can reset the threshold to the default value of 60 at any time using the **Reset to default** button in the upper-right corner of the section.
</Tip>

### What Happens When a Conversation Is Flagged

When a conversation's sentiment score drops below your threshold:

* It's marked as a **bad sentiment** conversation in the inbox
* A notification can be sent to your team (configured in [Notifications](/features/settings/notifications))
* A `conversation.bad_sentiment` event fires, which can trigger a [webhook](/features/settings/webhooks)

## Escalation Detection

<Info>
  Escalation detection requires the **Standard** plan or higher.
</Info>

Even when an agent is doing its job well, some users specifically want to talk to a human. **Escalation Detection** watches conversations for those moments and raises an alert so a teammate can jump in.

### Enabling Escalation Detection

Toggle the **Escalation Detection** switch on. By default, Clarky uses its built-in rules to recognize phrases like "Can I talk to a human?" or "Is there an agent available?"

When triggered:

* The conversation is flagged in the inbox
* An `conversation.escalation_requested` event fires for [webhooks](/features/settings/webhooks)
* Notifications are sent according to your [Notifications](/features/settings/notifications) preferences

### Custom Detection Rules

If the default rules are too sensitive — or not sensitive enough — you can replace them with your own.

<Steps>
  <Step title="Toggle Custom Detection Rules">
    Inside the Escalation Detection section, switch on **Custom Detection Rules**. The text area pre-fills with Clarky's default rules so you have a starting point.
  </Step>

  <Step title="Edit the rules">
    Update the conditions to match how you want escalations to work. Be explicit — describe the kinds of phrases or situations that should and shouldn't count as a request for a human.
  </Step>

  <Step title="Save">
    Click **Save** to apply your custom rules.
  </Step>
</Steps>

<Tip>
  If you want to go back to the defaults, simply turn the **Custom Detection Rules** toggle off — Clarky will resume using the built-in rules.
</Tip>

### Timeout Message

When a user asks for a human and no teammate responds quickly, you can have Clarky send an automated reassurance message so the user isn't left hanging.

<Steps>
  <Step title="Enable Timeout Message">
    Inside the Escalation Detection section, toggle **Timeout Message** on.
  </Step>

  <Step title="Set the wait time">
    Choose how long Clarky should wait before sending the message. Allowed values are **1 to 10 minutes**.
  </Step>

  <Step title="Write the message">
    Enter the text the agent should send if no human joins in time. A common pattern:

    > I'm sorry we haven't responded yet. We have your contact information and someone will be in touch shortly.
  </Step>

  <Step title="Save">
    Click **Save**. The message is sent automatically as an assistant response when the wait time elapses without a human takeover.
  </Step>
</Steps>

<Note>
  If you clear the message field and save, the timeout feature is automatically disabled — there's no separate "off" state to manage.
</Note>

## Human Takeover

<Info>
  Human takeover requires the **Standard** plan or higher.
</Info>

**Human Takeover** allows a teammate to step into a live conversation and respond as a human, pausing the AI agent. It's the natural pairing for escalation detection — once you know a user wants a human, your team needs a way to step in.

### Enabling Human Takeover

In the Human Takeover section, toggle the **Human Takeover** switch on, then click **Save**.

When enabled:

* Teammates can take over any active conversation from the inbox
* The AI pauses while a human is actively responding
* The user sees messages from the human teammate in the same conversation thread
* Either the human can hand control back to the AI, or the conversation can simply end

<Tip>
  Pair Human Takeover with **Escalation Detection** and a **Timeout Message** for the smoothest workflow: Clarky catches escalation requests, alerts your team, sends a holding message if no one responds in time, and lets a teammate take over the moment they're available.
</Tip>

## Saving Changes

Changes on the Analysis page are batched. A **Save** button only appears when you have unsaved changes — once you click it, the new settings take effect immediately for new conversations.

<Card title="Webhooks for analysis events" icon="webhook" href="/features/settings/webhooks">
  Forward bad sentiment and escalation events to Slack, Zapier, or your own systems.
</Card>

<Card title="Notification preferences" icon="bell" href="/features/settings/notifications">
  Decide which alerts go to your inbox, mobile app, or browser.
</Card>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# CRM Basics & Custom Fields
Source: https://docs.clarky.ai/features/settings/crm-basics

Control how contacts are captured and define custom fields for contacts and companies

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

CRM Basics controls how your agent captures people who contact you and lets you tailor the data you keep on contacts and companies.

## Contact Scope

Choose whether contacts are shared across every agent in the workspace or kept private to a single agent.

<CardGroup>
  <Card title="Workspace" icon="building">
    Every agent in this workspace sees the same contacts. Useful when multiple agents serve the same customers and you want a unified record.
  </Card>

  <Card title="Just this agent" icon="user">
    Contacts are isolated to this agent only. Useful when agents serve completely separate audiences and you don't want their records mixed.
  </Card>
</CardGroup>

<Tip>
  Most teams should start with **Workspace** so a customer who calls one agent and texts another shows up as a single contact.
</Tip>

## Auto-Capture Settings

Toggle whether the agent automatically saves a new contact whenever someone reaches out on a given channel.

<AccordionGroup>
  <Accordion title="Phone Calls">
    When enabled, an inbound call will create a contact using the caller's phone number. The contact is saved even if the call is brief.
  </Accordion>

  <Accordion title="Text Messages">
    When enabled, an inbound text creates a contact using the sender's phone number.
  </Accordion>

  <Accordion title="Emails">
    When enabled, an inbound email creates a contact using the sender's email address. Their name is captured too if it's available in the message.
  </Accordion>
</AccordionGroup>

<Note>
  Auto-capture only adds the basics — phone number or email. Richer details (full name, company, custom fields) are filled in by the agent during the conversation or by you on the contact page.
</Note>

## Custom Fields

Custom fields let you store extra information on contacts and companies that's specific to your business — things like lead score, account type, or referral source.

### Field Types

<CardGroup>
  <Card title="Text">Single-line text</Card>
  <Card title="Number">Numeric values</Card>
  <Card title="Date">A date</Card>
  <Card title="Date & Time">A specific date and time</Card>
  <Card title="Dropdown">Pick one option from a list you define</Card>
  <Card title="Multi-select">Pick multiple options from a list you define</Card>
  <Card title="Checkbox">A simple yes / no toggle</Card>
  <Card title="URL">A web address</Card>
  <Card title="Email">An email address</Card>
  <Card title="Phone">A phone number</Card>
</CardGroup>

### Adding a Custom Field

<Steps>
  <Step title="Open Settings > CRM Basics">
    Find the **Contact Custom Fields** or **Company Custom Fields** card.
  </Step>

  <Step title="Click Add">
    A dialog opens for the new field.
  </Step>

  <Step title="Name the field">
    Enter a clear label (e.g., "Lead Score" or "Account Type") and an optional description to help your team understand when to use it.
  </Step>

  <Step title="Pick a field type">
    Choose the type that matches the data you'll store. For Dropdown or Multi-select, list each option on its own line.
  </Step>

  <Step title="Mark it required (optional)">
    Toggle "Required field" if the field must be filled in to save a contact or company.
  </Step>

  <Step title="Create">
    The field appears immediately on every contact or company in the workspace.
  </Step>
</Steps>

### Editing and Deleting Fields

You can rename a field, edit its description, change its options (for dropdowns), or toggle whether it's required at any time. The field type itself can't be changed once created — delete the field and create a new one if you need a different type.

<Warning>
  Deleting a field removes it from your forms and contact pages. Existing values stored in that field are preserved on each record but become read-only.
</Warning>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Custom Domains
Source: https://docs.clarky.ai/features/settings/custom-domains

Serve your forms, surveys, and chat pages from a domain you own, with your own branding

<Info>
  **Plan availability:** Pro or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What Are Custom Domains?

By default, public Clarky pages live at `clarky.ai`. With a custom domain you point a hostname you own, such as `forms.yourcompany.com`, at Clarky and your forms, surveys, and chat pages are served from it instead. Visitors see your brand in the address bar, links are short and easy to remember, and nothing on the page references Clarky.

Once a domain is live, these URLs work on it:

| URL                           | What it shows                                                    |
| ----------------------------- | ---------------------------------------------------------------- |
| `yourdomain.com/`             | The home page you choose for the domain (a form or a chat agent) |
| `yourdomain.com/onboarding`   | The form or survey whose URL slug is `onboarding`                |
| `yourdomain.com/c/your-agent` | A full-screen chat page for one of your agents                   |

Custom domains only serve public pages. The admin app and your Clarky login always stay at `clarky.ai`.

## Adding a Domain

<Steps>
  <Step title="Open Custom Domains">
    Go to **Settings > Custom Domains** and click **Add domain**.
  </Step>

  <Step title="Enter your hostname">
    Type the domain or subdomain you control, for example `forms.yourcompany.com`. Subdomains are the easiest to set up. Root domains (`yourcompany.com`) work too, but require an A record instead of a CNAME.
  </Step>

  <Step title="Add the DNS record">
    Clarky shows the exact record to add at your domain provider (GoDaddy, Cloudflare, Namecheap, and so on). Every field is click-to-copy.

    * **Subdomain**: a `CNAME` record pointing at `cname.vercel-dns.com`
    * **Root domain**: an `A` record pointing at `76.76.21.21`

    If the domain is already registered with another hosting account, Clarky may also ask for a `TXT` record to prove you own it.
  </Step>

  <Step title="Re-check until it is live">
    DNS changes usually take a few minutes to propagate. Click the refresh icon next to the domain to re-check. The badge changes from **Pending DNS** to **Live** as soon as the record is detected, and Clarky provisions an SSL certificate automatically.
  </Step>
</Steps>

<Tip>
  You can add more than one domain. A recruiting team might use `apply.yourcompany.com` for application forms and `help.yourcompany.com` for a chat agent.
</Tip>

## Choosing a Home Page

Each domain has a **Home page** setting that controls what loads at the root URL. Pick any form, survey, or chat agent in your workspace. If you leave it empty, the root returns a not-found page and only the specific form and chat paths respond.

## Form URL Slugs

Forms and surveys can have a short URL slug so the link reads `forms.yourcompany.com/onboarding` instead of a long ID.

<Steps>
  <Step title="Open the form">
    Go to **CRM > Forms** and open the form you want to share.
  </Step>

  <Step title="Set the slug in Form Settings">
    In the **Form Settings** card, enter a slug made of lowercase letters, numbers, and hyphens (for example `onboarding` or `event-rsvp`). Slugs must be unique within your workspace.
  </Step>

  <Step title="Share the short link">
    The **View** tab shows the public link. Use the host selector to switch between `clarky.ai` and any of your live custom domains; the link, iframe snippet, and script snippet all update to match.
  </Step>
</Steps>

<Note>
  A few words are reserved and cannot be used as slugs because Clarky uses them for routing: `f`, `c`, `api`, `cd`, `form`, `embed`, `b`, `p`, and `admin`.
</Note>

## Branding Each Domain

Under each live domain you can set what visitors and link previews see:

<CardGroup>
  <Card title="Site name" icon="signature">
    The name shown in browser tabs and link previews. Defaults to the hostname.
  </Card>

  <Card title="Favicon" icon="star">
    The small icon in the browser tab. Upload a 512 x 512 PNG.
  </Card>

  <Card title="Social preview image" icon="image">
    The image shown when the link is shared on LinkedIn, Slack, iMessage, and similar. Upload a 1200 x 630 PNG or JPG.
  </Card>
</CardGroup>

If you do not upload a favicon or preview image, the page simply has none. Clarky never substitutes its own branding on a custom domain.

## Powered by Clarky

Public chat pages, the chat widget, forms, and surveys show a small "Powered by Clarky" link by default. On Pro and higher you can hide it:

* **Chat**: the **Powered by Clarky** card at the bottom of **Settings > Custom Domains** has a **Show on chat** switch for the current agent.
* **Forms and surveys**: open the form, then **Form Settings > Design and Branding**, and turn off the branding switch for that form.

The switch works on `clarky.ai` links as well as custom domains, so you can go white-label either way.

## Embedding From Your Domain

The share and embed screens are domain-aware:

* **Forms**: the **View** tab of a form has a host selector. Choose a custom domain and the public link, iframe embed, and script embed all use it. The embed script itself is served from your domain.
* **Chat**: **Settings > Share / Embed** has the same selector for the chat page link and the `chat.js` embed tag.

Embed code copied this way never mentions `clarky.ai`, so the pages you paste it into stay fully on-brand.

<AccordionGroup>
  <Accordion title="Why is my domain still Pending DNS?">
    Most often the record has not propagated yet, or it was added on the wrong name (for example `forms.yourcompany.com.yourcompany.com`). Double-check the **Name** and **Value** fields against what Clarky shows, wait a few minutes, and re-check. Some providers cache DNS for up to an hour.
  </Accordion>

  <Accordion title="Can I use my domain for booking pages?">
    Not yet. Custom domains currently cover forms, surveys, and chat pages. Booking pages continue to use `clarky.ai` links.
  </Accordion>

  <Accordion title="What happens if I downgrade my plan?">
    Domains stay saved, but they stop serving pages until the workspace is back on a plan that includes custom domains. Your `clarky.ai` links keep working the whole time.
  </Accordion>

  <Accordion title="What happens when I remove a domain?">
    Clarky detaches it from hosting and deletes any favicon or preview image you uploaded for it. Links on that domain stop working immediately; the underlying forms and agents are untouched.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Embedding Forms" icon="code" href="/features/forms/embedding">
    Public URLs, iframe, and script embeds for forms and surveys.
  </Card>

  <Card title="Share & Embed Chat" icon="share-nodes" href="/features/settings/share">
    Chat page links and the chat widget embed.
  </Card>
</CardGroup>


# Email Settings
Source: https://docs.clarky.ai/features/settings/email-setup

Set up inbound and outbound email for your agent

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

The Email Settings page configures both halves of your agent's email channel: receiving messages (inbound) and sending replies (outbound).

## Inbound Email

Every agent gets a unique inbound email address you can forward messages to. Anything sent to that address shows up as a conversation in Clarky and can be answered by the agent or by you.

<Steps>
  <Step title="Enable Inbound Email">
    Toggle the switch on. Inbound is on by default.
  </Step>

  <Step title="Copy your agent's email address">
    Click the copy button next to the address.
  </Step>

  <Step title="Forward to it">
    Set up forwarding from your existing inbox (Gmail, Outlook, your support address, etc.) to your agent's address — or hand the address out directly to customers.
  </Step>
</Steps>

<Tip>
  A common pattern is forwarding `support@yourdomain.com` to your agent's address. The agent triages incoming messages, replies to the easy ones, and lets you take over the rest.
</Tip>

## Outbound Email

To let your agent send email replies, connect a [Resend](https://resend.com) account. Resend handles delivery from your own verified domain, which means recipients see emails coming from `you@yourdomain.com` rather than a generic Clarky address.

### Connect Resend

<Steps>
  <Step title="Toggle on Outbound Email">
    Switch on **Enable Outbound Email**. The configuration form appears.
  </Step>

  <Step title="Paste your Resend API key">
    Get a key from [resend.com/api-keys](https://resend.com/api-keys). The key needs **full access** so Clarky can verify your domain and send on your behalf.
  </Step>

  <Step title="Set the sender name">
    The name that shows up in the "From" field — e.g., "John Smith" or "Acme Support."
  </Step>

  <Step title="Set the sender email">
    A real address on a domain you've verified in Resend. When you click out of the field, Clarky verifies the domain automatically.
  </Step>

  <Step title="Save">
    Once the domain shows as verified, the Save button is enabled.
  </Step>
</Steps>

### Verifying Your Domain

The sender email has to be on a domain you've verified in Resend. If verification fails, head to [resend.com/domains](https://resend.com/domains), add the DNS records Resend provides, and try again once they've propagated.

<Warning>
  Outbound won't save until the domain is verified. This protects your deliverability — sending from an unverified domain is a fast track to the spam folder.
</Warning>

### AI Auto-Reply

Once outbound is configured, you can toggle **AI Auto-Reply** on. With it enabled, your agent will automatically reply to inbound emails when it has a confident answer based on its knowledge base. Anything ambiguous still goes to your inbox so a human can take over.

<Tip>
  Start with auto-reply off, watch your inbound conversations for a few days, and turn it on once you're comfortable with the answers your agent is drafting.
</Tip>

## Disabling Outbound

Turning off outbound clears your saved Resend API key, sender name, and sender email. You'll need to re-enter them if you turn it back on later. Inbound email continues to work either way.

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Integrations
Source: https://docs.clarky.ai/features/settings/integrations

Connect Clarky to your business tools

## Available Integrations

Clarky integrates with popular business tools to enhance your agent's capabilities.

<Info>
  **Plan availability:** Startup or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## E-commerce

### Shopify

Connect your Shopify store:

* Check order status
* Track shipments
* Process returns
* Answer product questions

<Steps>
  <Step title="Click 'Connect Shopify'">
    In Settings > Integrations
  </Step>

  <Step title="Authorize">
    Log in to your Shopify admin and approve access
  </Step>

  <Step title="Configure">
    Choose what data the agent can access
  </Step>
</Steps>

## CRM

### GoHighLevel

Integrate with GoHighLevel:

* Create contacts
* Log activities
* Trigger workflows
* Access customer data

## Email

<Tabs>
  <Tab title="Gmail">
    Connect Gmail or Google Workspace:

    * Send and receive emails
    * Access contact lists
    * Calendar integration
  </Tab>

  <Tab title="Outlook">
    Connect Outlook or Office 365:

    * Email management
    * Contact sync
    * Calendar access
  </Tab>
</Tabs>

## Calendar

### Google Calendar

Enable appointment booking:

* Check availability
* Schedule appointments
* Send confirmations
* Handle rescheduling

### Calendly

Connect Calendly for:

* Share booking links
* Check availability
* Manage event types

### Cal.com

Integrate Cal.com:

* Booking management
* Multiple calendar support
* Team scheduling

## Communication

### Phone (Built-in)

Twilio integration for voice and SMS:

* Automatic provisioning
* No configuration needed
* Included in subscription

## Custom Integrations

Need a custom integration?

* API access available
* Webhook support
* Custom tool creation
* Contact support for assistance

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Interface Settings
Source: https://docs.clarky.ai/features/settings/interface

Customize your chat widget appearance

## Chat Widget Customization

Make your chat widget match your brand.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Widget Layout

Choose how the chat presents itself on your website when embedded. Colors, greeting, avatar, and starters apply to every layout.

<CardGroup>
  <Card title="Chat widget (default)" icon="comment">
    A round launcher in the bottom-right corner that opens the chat panel.
  </Card>

  <Card title="Answer bar" icon="magnifying-glass">
    An always-visible "Ask a question" bar centered at the bottom of the page. The conversation rises above it once a visitor asks something. Cmd+I (Ctrl+I on Windows) focuses the bar from anywhere on the page.
  </Card>

  <Card title="Docked widget" icon="window-maximize">
    A "Chat with ..." tab flush with the bottom edge of the page that expands into a panel anchored to the bottom-right corner.
  </Card>
</CardGroup>

<Note>
  The layout applies to the embedded widget on your site. The shareable full-screen chat page always uses the standard chat view.
</Note>

## Colors

<ParamField type="color">
  Background color of the chat widget header
</ParamField>

<ParamField type="color">
  Text color in the header
</ParamField>

<ParamField type="color">
  Primary accent color for buttons and highlights
</ParamField>

<ParamField type="color">
  Main chat background color
</ParamField>

## Branding

### Avatar

Upload a custom avatar image:

* Recommended size: 200x200px
* Formats: PNG, JPG, GIF
* Appears next to agent messages

### Chat Greeting

Customize the initial message users see:

```
👋 Hi there! I'm here to help. What can I assist you with today?
```

### Welcome Message

Set what appears before users start chatting:

```
Welcome to Acme Support! Ask me anything about our products and services.
```

## Starter Prompts

Add quick-click options for common questions:

<Steps>
  <Step title="Navigate to Interface Settings">
    Go to Settings > Interface
  </Step>

  <Step title="Add Starter Prompts">
    Enter suggested questions users can click
  </Step>

  <Step title="Save">
    Prompts appear in the chat widget
  </Step>
</Steps>

### Example Starters

* "What are your hours?"
* "Tell me about your services"
* "I need help with an order"
* "How do I contact you?"

## Preview

Use the live preview to see changes in real-time before saving.

<Card title="Share Widget" icon="share" href="/features/settings/share">
  Get embed code for your website
</Card>


# Mobile App
Source: https://docs.clarky.ai/features/settings/mobile-app

Install and use the Clarky Progressive Web App (PWA)

## Clarky Mobile App

Stay connected to your agent's conversations on the go with the Clarky Progressive Web App (PWA). The Clarky mobile app is not available in app stores—it's a PWA that you can install directly on your device.

## Features

<CardGroup>
  <Card title="Real-Time Notifications" icon="bell">
    Get instant alerts for new conversations
  </Card>

  <Card title="Take Over Conversations" icon="hand">
    Jump into chats from your phone
  </Card>

  <Card title="View Analytics" icon="chart-line">
    Monitor performance anywhere
  </Card>

  <Card title="Manage CRM" icon="users">
    Access contacts and pipeline
  </Card>
</CardGroup>

## Install the PWA

The Clarky mobile app is a Progressive Web App (PWA) that you can install on iPhone, Android, iPad, Mac, and Windows. It's not available in app stores—you install it directly from your browser.

<Tabs>
  <Tab title="iPhone / iPad">
    Install on iOS:

    1. Open Safari and navigate to your Clarky workspace
    2. Tap the Share button (square with arrow)
    3. Scroll down and tap "Add to Home Screen"
    4. Tap "Add" to confirm
    5. The app icon will appear on your home screen
    6. Tap the icon to open the PWA
  </Tab>

  <Tab title="Android">
    Install on Android:

    1. Open Chrome and navigate to your Clarky workspace
    2. Tap the menu (three dots) in the top right
    3. Tap "Add to Home screen" or "Install app"
    4. Tap "Install" to confirm
    5. The app icon will appear on your home screen
    6. Tap the icon to open the PWA
  </Tab>

  <Tab title="Mac / Windows">
    Install on Desktop:

    1. Open Chrome, Edge, or Safari and navigate to your Clarky workspace
    2. Look for the install icon in the address bar (or menu)
    3. Click "Install" or "Add to Home Screen"
    4. The app will open in its own window
    5. You can pin it to your taskbar or dock for quick access
  </Tab>
</Tabs>

## Setting Up the App

<Steps>
  <Step title="Install the PWA">
    Follow the installation steps for your device (iPhone, Android, iPad, Mac, or Windows) above
  </Step>

  <Step title="Sign In">
    Use your Clarky account credentials
  </Step>

  <Step title="Enable Notifications">
    Allow push notifications for real-time alerts
  </Step>

  <Step title="Select Workspace">
    Choose which workspace to monitor
  </Step>
</Steps>

## Mobile Features

### Conversation Management

* View all conversations
* Respond to messages
* Take over from AI agent
* Add notes and tags

### Notifications

Configure mobile-specific notifications:

* New conversations
* Human takeover requests
* Mentions and escalations
* Daily summaries

### Quick Actions

Fast access to common tasks:

* View active conversations
* Check today's metrics
* Search contacts
* Access knowledge base

## Security

Your data is secure:

* End-to-end encryption
* Biometric login (Face ID / Touch ID / Fingerprint)
* Automatic session timeout
* Remote device management

## Troubleshooting

<AccordionGroup>
  <Accordion title="Not receiving notifications">
    1. Check app notification settings
    2. Verify notification preferences in Clarky dashboard
    3. Ensure "Do Not Disturb" is off
    4. Restart the app
  </Accordion>

  <Accordion title="Can't sign in">
    1. Verify your credentials
    2. Check internet connection
    3. Try resetting password
    4. Contact support if issues persist
  </Accordion>

  <Accordion title="App is slow or crashing">
    1. Clear browser cache and data
    2. Refresh the PWA (pull down on mobile or refresh on desktop)
    3. Restart device
    4. Reinstall the PWA if necessary
  </Accordion>
</AccordionGroup>

<Card title="Configure Notifications" icon="bell" href="/features/settings/notifications">
  Set up your notification preferences
</Card>


# Notifications
Source: https://docs.clarky.ai/features/settings/notifications

Configure alert preferences

## Notification Types

Choose what notifications you want to receive.

## Email Notifications

<ParamField type="boolean">
  New conversation started
</ParamField>

<ParamField type="boolean">
  Agent requests human help
</ParamField>

<ParamField type="boolean">
  Negative sentiment detected
</ParamField>

<ParamField type="boolean">
  Daily performance summary
</ParamField>

## Push Notifications

Mobile and browser push notifications:

<ParamField type="boolean">
  When users are actively chatting
</ParamField>

<ParamField type="boolean">
  When conversations need attention
</ParamField>

<ParamField type="boolean">
  When you're mentioned by team members
</ParamField>

<ParamField type="boolean">
  Messages, DMs, and @mentions in [Team Chat](/features/team-chat/overview)
</ParamField>

<ParamField type="boolean">
  AI prep briefs before meetings, for event types with [Meeting Briefs](/features/booking/meeting-briefs) turned on
</ParamField>

<Note>
  Team Chat also respects your per-channel notification level (all messages, mentions only, or muted). If you're DMed or @mentioned and have no push device set up, Clarky emails you instead, at most once per channel every 30 minutes.
</Note>

## Notification Channels

Configure how you receive notifications:

* **Email**: Sent to your account email
* **Mobile App**: Push notifications on your phone
* **Browser**: Desktop browser notifications
* **SMS**: Text message alerts (premium)

<Card title="Get Mobile App" icon="mobile" href="/features/settings/mobile-app">
  Download the Clarky mobile app
</Card>


# Settings Overview
Source: https://docs.clarky.ai/features/settings/overview

Configure your AI agent, channels, CRM, and workspace

## Settings Navigation

Settings are organized by topic. Below is the full landscape — most pages are scoped to the current bot, but **Workspace**, **Users**, and **Plans & Billing** are shared across the workspace.

### Agent

<CardGroup>
  <Card title="Agent Properties" icon="robot" href="/features/settings/agent">
    Name, behavior, and core configuration
  </Card>

  <Card title="Schedule" icon="clock" href="/features/settings/schedule">
    Working hours and after-hours behavior
  </Card>

  <Card title="Sentiment & Escalation" icon="chart-pulse" href="/features/settings/analysis">
    Sentiment analysis, escalation rules, and human takeover
  </Card>

  <Card title="Integrations" icon="puzzle" href="/features/settings/integrations">
    Connect to third-party tools and services
  </Card>

  <Card title="Webhooks" icon="webhook" href="/features/settings/webhooks">
    Send real-time event notifications to external systems
  </Card>
</CardGroup>

### CRM & Analytics

<CardGroup>
  <Card title="CRM Basics" icon="address-book" href="/features/settings/crm-basics">
    Auto-capture, contact scope, and custom fields
  </Card>

  <Card title="Pixel Tracking" icon="chart-line" href="/features/settings/pixel-tracking">
    Configure visitor analytics and blocked paths
  </Card>
</CardGroup>

### Chat Widget

<CardGroup>
  <Card title="Interface" icon="palette" href="/features/settings/interface">
    Customize chat widget appearance
  </Card>

  <Card title="Share" icon="share" href="/features/settings/share">
    Get embed code and sharing options
  </Card>

  <Card title="Privacy" icon="shield" href="/features/settings/privacy">
    Privacy and data handling settings
  </Card>
</CardGroup>

### Voice, Text & Email

<CardGroup>
  <Card title="Voice" icon="microphone" href="/features/settings/voice">
    Phone numbers, greetings, and voices
  </Card>

  <Card title="Texting" icon="comment-sms" href="/features/settings/texting">
    SMS/MMS channel configuration
  </Card>

  <Card title="A2P Registration" icon="id-badge" href="/features/settings/a2p">
    Register your business for SMS sending in the US
  </Card>

  <Card title="Email Setup" icon="envelope" href="/features/settings/email-setup">
    Connect Resend for inbound and outbound email
  </Card>
</CardGroup>

### Workspace

<CardGroup>
  <Card title="Workspace" icon="building" href="/features/settings/workspace">
    Workspace name and configuration
  </Card>

  <Card title="Users" icon="users" href="/features/settings/users">
    Team member management
  </Card>

  <Card title="Plans & Billing" icon="credit-card" href="/features/settings/plans">
    Subscription, pricing, and the feature matrix
  </Card>

  <Card title="Notifications" icon="bell" href="/features/settings/notifications">
    Alert preferences
  </Card>

  <Card title="Mobile App" icon="mobile" href="/features/settings/mobile-app">
    Push notifications and the mobile experience
  </Card>
</CardGroup>

## Plan availability

Some settings only appear once your workspace is on the right plan. Each gated page has a callout at the top showing its minimum plan. The full feature matrix is on [Plans & Billing](/features/settings/plans).

## Quick Settings

Access frequently used settings quickly:

* **Agent Name**: Click to edit from the dashboard
* **Status**: Enable/disable your agent from Settings, under Properties
* **Quick Actions**: Every section (Inbox, CRM, Calendar, Context, Settings) is one click away in the sidebar

## Settings Changes

Most settings changes take effect immediately. Some may require:

* Refreshing your chat widget
* Re-deploying the embed code
* Clearing browser cache
* Waiting for cache expiration (under 5 minutes)

<Note>
  Changes to agent knowledge and behavior are instant. Interface changes may take a few minutes to propagate.
</Note>


# Pixel Tracking
Source: https://docs.clarky.ai/features/settings/pixel-tracking

Track visitor analytics and build profiles before they start chatting

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What Pixel Tracking Does

When pixel tracking is enabled, the Clarky widget on your website acts like a lightweight analytics tool — similar to HubSpot or other visitor intelligence platforms. It quietly observes how people use your site so your agent has rich context the moment they start a conversation, and so you can review traffic trends in the [Traffic dashboard](/features/traffic/overview).

Pixel tracking captures:

<CardGroup>
  <Card title="Page Views" icon="eye">
    Every page a visitor views on your website.
  </Card>

  <Card title="Widget Interactions" icon="hand-pointer">
    When visitors open, close, or interact with the chat widget.
  </Card>

  <Card title="Visitor Profiles" icon="user">
    Comprehensive profiles built across multiple sessions.
  </Card>

  <Card title="UTM Attribution" icon="chart-line">
    First-touch and last-touch marketing attribution.
  </Card>

  <Card title="Geographic Data" icon="globe">
    IP-based country, region, and city.
  </Card>

  <Card title="Device Information" icon="desktop">
    Browser, OS, screen size, and connection type.
  </Card>
</CardGroup>

## Enabling Pixel Tracking

<Steps>
  <Step title="Open Pixel Tracking settings">
    Go to **Settings > Traffic > Pixel Tracking**.
  </Step>

  <Step title="Toggle it on">
    Flip the **Pixel Tracking** switch. The status badge updates to **Enabled** and tracking begins on the next page load.
  </Step>

  <Step title="Review the Traffic dashboard">
    Visit the [Traffic dashboard](/features/traffic/overview) to see incoming page views, visitor profiles, and attribution data.
  </Step>
</Steps>

You can disable pixel tracking at any time by toggling the switch off. New page views stop being recorded immediately, but historical data is preserved unless you delete it explicitly (see [Blocked Paths](#blocked-paths)).

## Blocked Paths

Some pages shouldn't be tracked — admin areas, internal staging routes, or pages where tracking would be inappropriate. Blocked paths let you exclude specific URLs or URL patterns from analytics.

### Adding a Blocked Path

<Steps>
  <Step title="Enter a path or pattern">
    In the **Blocked Paths** section, type a path into the input field. Paths must start with `/` (a literal path) or `*` (a wildcard pattern).
  </Step>

  <Step title="Click Block">
    The path is added to the list and immediately excluded from tracking.
  </Step>
</Steps>

### Pattern Examples

<AccordionGroup>
  <Accordion title="Block a section of your site">
    `/admin/*` blocks `/admin`, `/admin/users`, `/admin/settings`, and any other path under `/admin`.
  </Accordion>

  <Accordion title="Block all internal pages">
    `/internal/*` blocks every URL beginning with `/internal/`.
  </Accordion>

  <Accordion title="Block paths ending with a suffix">
    `*/preview` blocks any URL ending in `/preview` — useful for content preview routes.
  </Accordion>

  <Accordion title="Block paths containing a keyword">
    `*staging*` blocks any URL that contains the word "staging" anywhere in the path.
  </Accordion>
</AccordionGroup>

### Removing a Blocked Path

Click the **X** icon next to a path to remove it from the block list. Tracking resumes for matching pages on the next visit.

### Deleting Existing Data

Adding a blocked path stops *future* tracking — it does not retroactively remove data. If you want to clear historical analytics for a path you've blocked, click **Delete Data** next to it. Clarky will permanently remove all page views matching that pattern.

<Warning>
  Deleting analytics data cannot be undone. Make sure you really want to remove the historical record before confirming.
</Warning>

## Privacy Considerations

Pixel tracking collects visitor data — including IP addresses for geolocation — that may be regulated in your jurisdiction.

<Warning>
  Make sure your privacy policy reflects this data collection. Depending on where your visitors are located, you may need to obtain consent under regulations such as GDPR or CCPA before tracking is enabled.
</Warning>

For controls on what your agent stores about individual users (email, phone, name), see [Privacy Settings](/features/settings/privacy).

<Card title="Open the Traffic dashboard" icon="chart-line" href="/features/traffic/overview">
  See the visitor data you've collected.
</Card>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Plans & Billing
Source: https://docs.clarky.ai/features/settings/plans

Choose the plan that fits your business and manage your subscription

## Plan Tiers

Clarky offers five plan tiers, each unlocking additional features and higher limits.

<CardGroup>
  <Card title="Free" icon="seedling">
    Get started with chat, booking, and the core agent
  </Card>

  <Card title="Startup" icon="rocket">
    Add the CRM, integrations, and sentiment analysis
  </Card>

  <Card title="Standard" icon="building">
    Unlock voice, text, email, human takeover, and pixel tracking
  </Card>

  <Card title="Pro" icon="trophy">
    Webhooks, multiple websites, and advanced control
  </Card>

  <Card title="Enterprise" icon="building-shield">
    White-label, custom solutions, dedicated support
  </Card>
</CardGroup>

## Feature Matrix

The table below shows which plan unlocks each feature. Each higher tier includes everything from the tiers below it.

| Feature                                                                                                              |    Free   |  Startup  |  Standard |    Pro    | Enterprise |
| -------------------------------------------------------------------------------------------------------------------- | :-------: | :-------: | :-------: | :-------: | :--------: |
| **Chat channel**                                                                                                     | <Check /> | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Booking**                                                                                                          | <Check /> | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Clarky Notetaker** (built-in AI meeting recorder: joins Meet, Zoom, and Teams calls, records, and writes AI notes) |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Meeting Recording Support** (via notetaker apps like Fellow: sync, transcripts, AI meeting chat)                   | <Check /> | <Check /> | <Check /> | <Check /> |  <Check /> |
| **AI Meeting Briefs** (pre-meeting research on every guest, delivered before the call)                               |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **CRM** (Contacts, Companies, Pipeline, Forms, Activity, Ask Clarky)                                                 |     —     | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Integrations** (Gmail, Outlook, Calendly, Cal.com, Google Calendar, etc.)                                          |     —     | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Sentiment Analysis**                                                                                               |     —     | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Voice Calls**                                                                                                      |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Text / SMS**                                                                                                       |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Email**                                                                                                            |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Sequences**                                                                                                        |     —     |     —     |     —     | <Check /> |  <Check /> |
| **Prospecting** (People Data Labs search; pay-as-you-go prospect credits, packs on any paid plan)                    |     —     | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Email Validation** (ZeroBounce deliverability checks; pay-as-you-go credits, packs on any paid plan)               |     —     | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Human Agent Takeover**                                                                                             |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Widget Customization**                                                                                             |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Advanced Analytics**                                                                                               |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Pixel Tracking / Traffic Analytics**                                                                               |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **API Access** (`/api/v1/*`)                                                                                         |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **MCP Server** (Claude, Codex & AI tools)                                                                            |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Text Clarky** (text your CRM over iMessage, RCS, or SMS; group-chat meeting booking)                               |     —     |     —     | <Check /> | <Check /> |  <Check /> |
| **Team Chat** (Slack-style channels, DMs, threads, files, @Clarky in channels)                                       |  Limited  | <Check /> | <Check /> | <Check /> |  <Check /> |
| **Webhooks**                                                                                                         |     —     |     —     |     —     | <Check /> |  <Check /> |
| **Multiple Websites**                                                                                                |     —     |     —     |     —     | <Check /> |  <Check /> |
| **Custom Domains** (forms, surveys, and chat pages on your own hostname)                                             |     —     |     —     |     —     | <Check /> |  <Check /> |
| **Remove Clarky Branding**                                                                                           |     —     |     —     |     —     | <Check /> |  <Check /> |

<Note>
  When a feature requires a higher plan, the relevant settings page shows an upgrade prompt with a link to plans. On the Free plan, Team Chat is limited to 3 public channels and the last 30 days of history, without file sharing or @Clarky. See [Team Chat](/features/team-chat/overview).
</Note>

## Free Trial

Every new workspace starts with a free trial that includes all features. No credit card is required to start. You can upgrade to a paid plan at any time during or after the trial.

## Upgrading Your Plan

<Steps>
  <Step title="Open Settings > Plans">
    Navigate to **Settings > Plans & Billing** in your workspace.
  </Step>

  <Step title="Choose a plan">
    Compare plans and pick the one that matches your needs.
  </Step>

  <Step title="Enter payment info">
    Add a credit card. Subscriptions are managed by Stripe.
  </Step>

  <Step title="Confirm upgrade">
    Your new plan takes effect immediately and gated features unlock right away.
  </Step>
</Steps>

## Billing & Invoices

From **Settings > Plans & Billing** you can:

* View your current plan and renewal date
* Update your payment method
* Switch between monthly and annual billing
* Download past invoices as PDF
* Update billing email and tax info

## Usage Tracking

Some plans include conversation, message, and call limits. Your current usage and percentage-of-limit are shown on the Plans page so you know when to consider upgrading.

## Cancellation

You can cancel anytime from **Settings > Plans & Billing**. Your plan stays active until the end of the current billing period, after which the workspace returns to the Free tier (gated features become read-only).

<Note>
  Have questions about a custom Enterprise quote, volume pricing, or migration? Contact us at [support@clarky.ai](mailto:support@clarky.ai).
</Note>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Privacy Settings
Source: https://docs.clarky.ai/features/settings/privacy

Control privacy and data handling

## Privacy Controls

Configure how your agent handles customer data.

## Data Collection

<ParamField type="boolean">
  Allow agent to ask for and store email addresses
</ParamField>

<ParamField type="boolean">
  Allow agent to ask for and store phone numbers
</ParamField>

<ParamField type="boolean">
  Allow agent to ask for and store customer names
</ParamField>

## Privacy Policy

<ParamField type="string">
  Link to your privacy policy
</ParamField>

<ParamField type="boolean">
  Display privacy notice in chat widget
</ParamField>

## Data Retention

<ParamField type="select">
  How long to keep conversation data:

  * 30 days
  * 90 days
  * 1 year
  * Forever
</ParamField>

## GDPR Compliance

Enable GDPR features:

* Cookie consent banner
* Right to be forgotten
* Data export requests
* Opt-out options

## User Consent

<ParamField type="boolean">
  Require users to accept terms before chatting
</ParamField>

<Tip>
  Consult with legal counsel to ensure compliance with applicable privacy laws in your jurisdiction.
</Tip>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Schedule
Source: https://docs.clarky.ai/features/settings/schedule

Set your agent's working hours, timezone, and time off

The Schedule page tells your agent when your business is open. The agent uses these hours when deciding how to handle calls, texts, and emails outside of business hours, and when offering appointment times.

## Timezone

Pick the timezone your business operates in. All working hours and time-off dates are interpreted in this timezone.

Available timezones:

* Eastern Time (ET)
* Central Time (CT)
* Mountain Time (MT)
* Pacific Time (PT)
* Alaska Time (AKT)
* Hawaii Time (HT)

<Tip>
  Clarky picks a sensible default based on your browser timezone the first time you visit the page. You can change it any time.
</Tip>

## Working Hours

Set the days you're open and the start and end time for each day.

<Steps>
  <Step title="Toggle a day on">
    Use the switch next to each day to mark it as a working day. Disabled days are treated as closed.
  </Step>

  <Step title="Set start and end times">
    Each enabled day defaults to 9:00 AM – 5:00 PM. Adjust the time pickers to match your hours.
  </Step>

  <Step title="Save">
    The Save button appears at the bottom of the page once you've made changes.
  </Step>
</Steps>

### What Happens Outside Business Hours

When someone reaches out outside your working hours, the agent is aware that you're closed and can change its behavior accordingly:

* **Voice calls** can be routed to voicemail or a fallback message instead of going through the full conversation flow.
* **Booking** flows only offer appointment times that fall inside your working hours.
* **Text and email replies** still work, but the agent can let the customer know you're closed and set expectations on response time.

<Note>
  Working hours describe when your business is open — not when the agent is "running." The agent itself is always available; the schedule simply gives it context about when humans are around.
</Note>

## Time Off

Add specific dates when you're closed even though they fall on a normal working day — holidays, company offsites, planned closures, etc.

<Steps>
  <Step title="Pick a date">
    Use the date picker in the Time Off card.
  </Step>

  <Step title="Add a reason">
    A short label like "Thanksgiving" or "Office closed" is enough.
  </Step>

  <Step title="Click Add">
    The date appears in the list, sorted chronologically.
  </Step>
</Steps>

Past time-off dates are cleaned up automatically when you save, so the list stays focused on what's still ahead.

<Tip>
  Time off behaves the same way as a closed day — the agent treats those dates as outside business hours, including for booking availability.
</Tip>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Share Settings
Source: https://docs.clarky.ai/features/settings/share

Get embed code and sharing options

## Embed Code

Get the code to add Clarky to your website.

### Standard Embed

```html theme={null}
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

<Steps>
  <Step title="Copy Code">
    Click "Copy" to copy the embed code
  </Step>

  <Step title="Paste Before </body>">
    Add the code just before the closing `</body>` tag on your website
  </Step>

  <Step title="Save and Publish">
    Save your changes and publish your website
  </Step>
</Steps>

## Shareable Link

Direct link to chat with your agent:

```
https://clarky.ai/c/your-bot-id
```

Share this link to:

* Test your agent
* Share with team members
* Use in marketing materials
* Embed as an iframe

On Pro and higher, the host selector on this screen can swap `clarky.ai` for a [custom domain](/features/settings/custom-domains) you own, so the chat page and the embed tag both live at `yourdomain.com/c/your-agent`.

<Card title="Customize Interface" icon="palette" href="/features/settings/interface">
  Personalize your chat widget
</Card>


# Texting Settings
Source: https://docs.clarky.ai/features/settings/texting

Configure your agent's SMS channel and register for A2P 10DLC

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

The Texting page is where you set up SMS for your agent. In the United States, sending business text messages requires registration with carriers — known as **A2P 10DLC** — before any messages are delivered. Most of this page is the registration flow.

## Your Texting Number

Every agent on a paid plan with the Standard plan or higher gets a dedicated phone number that can both make and receive calls and texts. The same number is used for SMS and voice. You can see and manage your number from [Voice Settings](/features/settings/voice).

## A2P 10DLC Registration

Before your agent can send any text messages to customers in the US, you have to register your business with the carriers. Texting Settings walks you through every field Twilio will ask for, generates compliant copy from your agent's Context, and creates an opt-in form for you.

<Card title="A2P Registration Guide" icon="message" href="/features/settings/a2p">
  Step-by-step guide to filling out the A2P registration form
</Card>

## Opt-In and Opt-Out

US carriers require that every recipient has explicitly agreed to receive text messages, and that they can stop receiving them at any time.

<AccordionGroup>
  <Accordion title="Opt-in keywords">
    Customers can text **START** or **SUBSCRIBE** to your number to opt in. Clarky generates a confirmation message automatically.
  </Accordion>

  <Accordion title="Opt-out keywords">
    Customers can text **STOP** to your number at any time. Once they do, your agent will stop sending them messages and confirm the opt-out.
  </Accordion>

  <Accordion title="HELP">
    Customers can text **HELP** to receive your support contact info. The response is generated from the business details you provide during A2P registration.
  </Accordion>
</AccordionGroup>

<Warning>
  Sending unsolicited messages — or messages to recipients who have opted out — can lead to carrier filtering, fines, and the loss of your texting number. Keep your opt-in process clean and respect STOP requests immediately.
</Warning>

## Compliant Opt-In Form

When you finish your A2P registration, Clarky also generates a public opt-in form that's wired into your CRM. Share the link, embed it on your website, or include it in marketing materials so new contacts have a clear, documented way to opt in.

<Card title="Forms" icon="clipboard" href="/features/forms">
  Learn more about Clarky forms
</Card>

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# User Management
Source: https://docs.clarky.ai/features/settings/users

Manage team members and permissions

## Team Members

View and manage all users with access to your workspace.

## Inviting Users

<Steps>
  <Step title="Click 'Invite User'">
    Button in Settings > Users
  </Step>

  <Step title="Enter Email">
    Provide the user's email address
  </Step>

  <Step title="Select Role">
    Choose their access level:

    * Admin
    * Member
    * Viewer
  </Step>

  <Step title="Send Invitation">
    User receives email with invitation link
  </Step>
</Steps>

## User Roles

<Tabs>
  <Tab title="Admin">
    **Full Access**

    * Manage agents
    * Invite/remove users
    * Access billing
    * Modify all settings
  </Tab>

  <Tab title="Member">
    **Standard Access**

    * View conversations
    * Take over chats
    * Manage knowledge
    * View analytics

    Cannot: Manage users or billing
  </Tab>

  <Tab title="Viewer">
    **Read-Only**

    * View conversations
    * See analytics
    * Read knowledge

    Cannot: Modify anything or respond to conversations
  </Tab>
</Tabs>

## Chat Access

Each member row has a **Chat** toggle that controls whether that member can see and use [Team Chat](/features/team-chat/overview). It's on by default, admins always have access, and you can also set it when sending an invite.

## Removing Users

1. Find user in list
2. Click "Remove"
3. Confirm removal
4. User loses access immediately

<Warning>
  Removed users cannot be restored. You'll need to re-invite them.
</Warning>

<Card title="Workspace Settings" icon="building" href="/features/settings/workspace">
  Configure workspace details
</Card>


# Voice Settings
Source: https://docs.clarky.ai/features/settings/voice

Configure phone greeting, voices, and phone numbers

## Phone Greeting

Set what your agent says when answering calls.

<ParamField type="text">
  The message callers hear first

  **Example:**
  "Thank you for calling Acme Services. I'm here to help. What can I assist you with today?"
</ParamField>

<Tip>
  Keep greetings brief (10-15 seconds) and natural. Write how you'd speak, not how you'd write.
</Tip>

## Voice Selection

Choose the voice for your agent:

* **Professional voices**: Formal, clear
* **Friendly voices**: Warm, approachable
* **Energetic voices**: Upbeat, enthusiastic
* **Calm voices**: Soothing, measured

### Available Voices

Preview and select from multiple high-quality AI voices in different languages and styles.

<Steps>
  <Step title="Go to Settings > Voices">
    Access voice configuration
  </Step>

  <Step title="Preview Voices">
    Click play to hear each voice
  </Step>

  <Step title="Select Voice">
    Choose the voice that represents your brand
  </Step>

  <Step title="Test">
    Call your number to hear it in action
  </Step>
</Steps>

## Phone Numbers

### Your Phone Number

View and manage your dedicated phone number:

* **Voice Calls**: Automatically enabled
* **SMS/Text**: Enabled by default
* **Number Porting**: Contact support to port existing number

### Additional Numbers

Need more numbers?

* Multiple numbers for different locations
* Vanity numbers
* Toll-free numbers (800, 888, etc.)
* International numbers

<Card title="Set Up Voice Channel" icon="phone" href="/guides/channels/voice">
  Learn more about voice configuration
</Card>


# Webhooks
Source: https://docs.clarky.ai/features/settings/webhooks

Send real-time event notifications from Clarky to external systems

<Info>
  **Plan availability:** Pro or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What Are Webhooks?

Webhooks let Clarky push real-time notifications to your own systems whenever something interesting happens — a new conversation starts, a contact is created, a booking is confirmed, or sentiment turns negative. Instead of polling for updates, your services receive an HTTP request the moment an event occurs.

Common use cases:

* Notify a Slack channel when a user asks to speak with a human
* Sync new contacts into your data warehouse
* Trigger an automation in Zapier, Make, or n8n
* Update a custom CRM when a booking is confirmed
* Alert on-call staff when a conversation is flagged with negative sentiment

## Adding a Webhook

<Steps>
  <Step title="Open Webhooks settings">
    Go to **Settings > Webhooks** and click **Add Webhook**.
  </Step>

  <Step title="Name and describe it">
    Give the webhook a clear name (for example, "Notify Slack on Escalation") and an optional description so teammates know what it does.
  </Step>

  <Step title="Enter the destination URL">
    Paste the URL of the endpoint that should receive the event. This is usually provided by the service you're integrating with — a Slack incoming webhook, a Zapier catch hook, or your own server endpoint.
  </Step>

  <Step title="Choose an HTTP method">
    Most destinations expect **POST**, which is the default. **PUT**, **PATCH**, **GET**, and **DELETE** are also supported for special cases.
  </Step>

  <Step title="Select the events to trigger it">
    Pick one or more events from the list (see [Available Events](#available-events) below). The webhook will only fire when one of these events occurs.
  </Step>

  <Step title="Scope to specific agents (optional)">
    By default, a webhook applies to **all agents** in the workspace. You can narrow it to one or more specific agents if you only want notifications for a subset.
  </Step>

  <Step title="Save">
    Click **Create Webhook**. New webhooks are enabled by default and will start firing immediately.
  </Step>
</Steps>

## Available Events

Clarky can send a webhook for any of the following events:

<AccordionGroup>
  <Accordion title="Contact events">
    * **Contact Created** — When a new contact is created
    * **Contact Updated** — When a contact is updated
    * **Contact Deleted** — When a contact is deleted
  </Accordion>

  <Accordion title="Conversation events">
    * **Conversation Started** — When a new conversation starts
    * **Conversation Updated** — When a conversation is updated
    * **Conversation Bad Sentiment** — When a conversation is flagged with negative sentiment
    * **Escalation Requested** — When a user asks to speak with a human
  </Accordion>

  <Accordion title="Message events">
    * **Message Sent (Outbound)** — When the agent sends a message
    * **Message Received (Inbound)** — When a user sends a message
  </Accordion>

  <Accordion title="Booking events">
    * **Booking Created** — When a new booking is made
    * **Booking Confirmed** — When a booking is confirmed
    * **Booking Cancelled** — When a booking is cancelled
    * **Booking Rescheduled** — When a booking is rescheduled
    * **Booking Completed** — When a booking is marked as completed
    * **Booking No Show** — When an attendee doesn't show up
    * **Booking Reminder Sent** — When a booking reminder is sent
  </Accordion>
</AccordionGroup>

## Authentication

If your destination requires authentication, add a **Bearer Token** when creating or editing the webhook. Clarky will include it as an `Authorization` header on every request to that endpoint.

<Tip>
  The token is masked in the UI by default. Use the eye icon next to the field to reveal or hide it while editing.
</Tip>

<Warning>
  Treat bearer tokens like passwords. Anyone with the token can post to your endpoint as Clarky. If a token is exposed, rotate it on the receiving service and update the webhook.
</Warning>

## Customizing the Payload

By default, Clarky sends a structured JSON payload that includes the event name, a timestamp, and details about the conversation, contact, and agent. You can override this with your own template if the receiving service expects a specific shape (for example, Slack's `text` field).

The payload editor supports inserting variables that are replaced at delivery time. Click any variable to drop it at your cursor:

| Variable               | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `{{event}}`            | Event name (for example, `conversation.started`) |
| `{{timestamp}}`        | ISO 8601 timestamp of the event                  |
| `{{botId}}`            | The agent's unique ID                            |
| `{{botName}}`          | The agent's display name                         |
| `{{conversationId}}`   | Unique conversation ID                           |
| `{{conversationUrl}}`  | Direct link to the conversation in your inbox    |
| `{{firstMessage}}`     | The user's first message                         |
| `{{type}}`             | Conversation type — chat, text, voice, or email  |
| `{{phoneNumber}}`      | Phone number (for voice and text conversations)  |
| `{{firstName}}`        | Contact's first name                             |
| `{{lastName}}`         | Contact's last name                              |
| `{{email}}`            | Contact's email                                  |
| `{{sentimentScore}}`   | Sentiment score from 0 to 100                    |
| `{{sentimentSummary}}` | Short summary of the conversation sentiment      |

Clarky validates your template as you type and won't let you save invalid JSON.

<Tip>
  Leave the payload template empty to use the default payload, which includes all standard fields. Only customize it when the receiving service expects a specific format.
</Tip>

## Enabling and Disabling Webhooks

Each webhook has a toggle switch on its card. Turn a webhook off temporarily — for example, while you're debugging a downstream system — without deleting it. Disabled webhooks don't fire and don't count toward delivery activity.

## Testing a Webhook

The simplest way to verify a webhook is to trigger one of its events in a sandbox conversation:

<Steps>
  <Step title="Pick a low-impact event">
    For example, **Conversation Started** or **Message Received (Inbound)**.
  </Step>

  <Step title="Open your widget or send a message">
    Start a test conversation with the agent the webhook is scoped to.
  </Step>

  <Step title="Check the receiving system">
    Confirm the request arrived in Slack, Zapier, your server logs, or wherever the URL points.
  </Step>
</Steps>

For destinations like Webhook.site or RequestBin, you can paste a temporary inspection URL into the **URL** field while you build out your real integration.

## Managing Existing Webhooks

From the Webhooks list you can:

* **Toggle** a webhook on or off without deleting it
* **Edit** the URL, events, agent scope, or payload template
* **Delete** a webhook you no longer need

Deleting a webhook is permanent — once removed, no further events will be sent to that endpoint.

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>


# Workspace Settings
Source: https://docs.clarky.ai/features/settings/workspace

Configure your workspace

## Workspace Information

<ParamField type="string">
  Your workspace display name
</ParamField>

<ParamField type="string">
  URL-friendly identifier (appears in dashboard URLs)
</ParamField>

## Updating Workspace

Changes to workspace name and slug:

<Steps>
  <Step title="Navigate to Settings > Workspace">
    Access workspace configuration
  </Step>

  <Step title="Update Fields">
    Modify name or slug as needed
  </Step>

  <Step title="Save Changes">
    Changes apply immediately
  </Step>
</Steps>

<Warning>
  Changing your workspace slug will update your dashboard URLs. Update any bookmarks accordingly.
</Warning>

## Workspace Members

View all team members with access to this workspace. To manage members, go to **Settings > Users**.

<Card title="Manage Users" icon="users" href="/features/settings/users">
  Add or remove team members
</Card>


# Team Chat
Source: https://docs.clarky.ai/features/team-chat/overview

Slack-style channels and DMs for your team, with Clarky in the room

Team Chat is Clarky's internal messaging surface: a place for your team to talk that lives in the same app as your customers, calendar and CRM. It is staff-to-staff only and completely separate from customer conversations in the Inbox. And because Clarky is in the room, your CRM is one @mention away from any conversation.

<Info>
  **Plan availability:** Startup or higher for the full experience. Free workspaces get Team Chat too, limited to 3 public channels and the last 30 days of history, without file sharing or @Clarky. See [Plans & Billing](/features/settings/plans).
</Info>

<CardGroup>
  <Card title="Channels" icon="hashtag">
    Public rooms anyone can join, private channels for sensitive topics
  </Card>

  <Card title="Direct Messages" icon="message">
    1:1 and group DMs with anyone in your workspace
  </Card>

  <Card title="@Clarky in Channels" icon="robot">
    Mention @Clarky anywhere to pull CRM answers into the conversation
  </Card>

  <Card title="Threads and Reactions" icon="comments">
    Keep side discussions tidy and react with emoji
  </Card>
</CardGroup>

## Where to find it

Chat is the first item in the sidebar (tagged "Internal") and the default screen after you log in. Your channels and direct messages are listed right in the sidebar, with unread and @mention badges so you can see what needs attention at a glance.

<Note>
  Clarky itself is pinned at the top of your Direct messages. That conversation is [Ask Clarky](/features/crm/ask-clarky), your 1:1 line to the CRM assistant.
</Note>

## Channels

<Steps>
  <Step title="Create a channel">
    Click the **+** next to **Channels** in the sidebar. Give it a name and an optional description.
  </Step>

  <Step title="Choose public or private">
    Public channels are visible to everyone in the workspace and anyone can join. Private channels are invite-only and invisible to non-members.
  </Step>

  <Step title="Invite people">
    Open the member list in the channel header to add teammates. Posting in a public channel joins it automatically.
  </Step>
</Steps>

Channels can be renamed, given a new description, or archived from the channel menu. Archiving hides the channel from every list but keeps its history.

## Direct messages

Click the **+** next to **Direct messages** to start a DM. Pick one person for a 1:1 or several for a group DM. Starting a DM with the same people always lands you back in the same conversation, so history never splits.

## Threads, reactions, and mentions

<AccordionGroup>
  <Accordion title="Threads">
    Hover any message and choose **Reply in thread** to branch off a side conversation. Threads open in a panel on the right and keep the main channel readable.
  </Accordion>

  <Accordion title="Reactions">
    Hover a message to react with an emoji. Reactions stack, and you can tap an existing one to add yours.
  </Accordion>

  <Accordion title="@Mentions">
    Type **@** to bring up an autocomplete of your teammates. Mentioned people get a notification even if they've turned the channel down to mentions-only.
  </Accordion>

  <Accordion title="Editing and deleting">
    You can edit or delete your own messages from the hover menu. Deleted messages leave a placeholder so threads stay coherent.
  </Accordion>
</AccordionGroup>

## Clarky is a teammate

Mention **@Clarky** in any channel or thread and Clarky answers right there, visible to everyone in the room. It's the same assistant as [Ask Clarky](/features/crm/ask-clarky), with the same access to your contacts, companies, pipeline, bookings, and analytics.

Examples of what to ask in a channel:

* "@Clarky who is on the calendar tomorrow?"
* "@Clarky which quotes have gone quiet this week?"
* "@Clarky what's in the pipeline for Acme Corp?"
* "@Clarky pull up Jordan Smith's contact details"

<Note>
  @Clarky answers with the CRM visibility of the person who mentioned it, and the reply is visible to everyone in the channel. Available on paid plans.
</Note>

## File sharing

Attach files to any message in a channel or DM. Images preview inline; everything else shows as a downloadable file. Uploads count toward your workspace storage and are available on paid plans, up to 25 MB per file.

## Notifications

You're in control of the noise at two levels.

Each channel has its own setting in the header:

| Level    | Behavior                                                         |
| -------- | ---------------------------------------------------------------- |
| All      | Every message notifies you (the default for channels you create) |
| Mentions | Only @mentions notify you (the default when you are invited)     |
| Muted    | No notifications; unread counts still accrue                     |

DMs always notify. The **Team chat** row on [Notifications](/features/settings/notifications) is the global on/off for Team Chat push notifications.

Notifications arrive as push messages on your devices. If someone DMs or @mentions you and you don't have a push device set up, Clarky emails you instead (at most one email per channel every 30 minutes, so a busy conversation never floods your inbox).

## Who can use Chat

Every workspace member has Chat access by default. Admins can turn it off per member with the **Chat** toggle on [Settings > Users](/features/settings/users), including when sending an invite. Admins always have access.

## Free plan limits

Free workspaces get a real, working Team Chat with a few limits:

|                                   | Free         | Startup and up      |
| --------------------------------- | ------------ | ------------------- |
| Public channels                   | 3            | Unlimited           |
| Private channels                  | —            | Included            |
| Message history                   | Last 30 days | Everything, forever |
| File sharing                      | —            | Included            |
| @Clarky in channels               | —            | Included            |
| DMs, threads, reactions, mentions | Included     | Included            |

<Note>
  Older messages on the Free plan are hidden, not deleted. Upgrade and your full history reappears.
</Note>

## Next steps

<CardGroup>
  <Card title="Ask Clarky" icon="wand-magic-sparkles" href="/features/crm/ask-clarky">
    Your pinned 1:1 conversation with the CRM assistant
  </Card>

  <Card title="Plans & Billing" icon="credit-card" href="/features/settings/plans">
    See what each plan includes
  </Card>
</CardGroup>


# Traffic Overview
Source: https://docs.clarky.ai/features/traffic/overview

Track website visitors, page views, and chat engagement in real time

## What is Traffic?

Traffic gives you full visibility into who's visiting your website and how they engage with your AI agent. A lightweight pixel is bundled with your chat widget, so the moment your widget is live, tracking starts. There's nothing extra to install.

Use Traffic to understand which pages drive the most attention, how visitors find you, what devices they use, and which conversations come from which sources.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What gets tracked

<CardGroup>
  <Card title="Page Views" icon="eye">
    Every page a visitor loads while your widget is on the site
  </Card>

  <Card title="Sessions" icon="clock">
    Distinct browsing sessions across visits
  </Card>

  <Card title="Unique Visitors" icon="users">
    Individual people coming to your site, not just raw visits
  </Card>

  <Card title="Widget Opens" icon="hand-pointer">
    How often visitors open the chat widget to look around
  </Card>

  <Card title="Chats Started" icon="messages">
    Conversations that actually began with your agent
  </Card>

  <Card title="Messages Sent" icon="paper-plane">
    Total messages exchanged across all conversations
  </Card>
</CardGroup>

<Note>
  Traffic only tracks visitors on pages where your Clarky chat widget is loaded. The widget itself is the pixel.
</Note>

## Accessing Traffic

<Steps>
  <Step title="Open your agent">
    Pick the agent whose website you want to analyze.
  </Step>

  <Step title="Click 'Traffic'">
    Find Traffic in the left sidebar.
  </Step>

  <Step title="Pick a time period">
    Use the date range selector in the top right to switch between the last 7, 30, or 60 days.
  </Step>
</Steps>

## Enabling tracking

If you open the Traffic page and see a "Pixel Tracking is Disabled" message, tracking has been turned off for this agent. To turn it back on:

<Steps>
  <Step title="Open Settings">
    Click **Settings** in the sidebar, then go to the **Analytics** section.
  </Step>

  <Step title="Enable tracking">
    Toggle pixel tracking on. New page views and sessions will start flowing in within seconds.
  </Step>
</Steps>

<Tip>
  You can disable tracking at any time without removing the chat widget. The widget keeps working — only analytics collection stops.
</Tip>

## The dashboard

The Traffic dashboard is laid out so you can scan it top to bottom and get a complete picture of your site's activity.

### Summary cards

Six metric cards across the top show your headline numbers for the selected time period:

* **Page Views** — Total page loads
* **Visitors** — Unique people who came to your site
* **Widget Opens** — Times someone clicked open the chat widget
* **Chats Started** — Conversations that actually began
* **Messages** — Total messages sent across all conversations
* **Chat Rate** — Percentage of visitors who ended up chatting with your agent

<Info>
  Chat Rate is one of the most useful numbers on the page. It tells you how well your widget converts passive visitors into active conversations.
</Info>

### Devices

A breakdown of what visitors are using to browse your site:

<CardGroup>
  <Card title="Desktop" icon="desktop">
    Visitors on laptops and desktop computers
  </Card>

  <Card title="Mobile" icon="mobile">
    Visitors on phones
  </Card>

  <Card title="Tablet" icon="tablet">
    Visitors on tablets
  </Card>
</CardGroup>

Each row shows the raw count and a percentage of total visits, so you can see at a glance whether your audience leans desktop or mobile.

### Top Pages

A ranked list of the five pages with the most views during the selected period. Each page is clickable — click through to open the live page in a new tab so you can review the content visitors are actually seeing.

### Recent Visitors

A live list of the most recent visitors, with their location, page count, conversation count, and how long ago they were last seen. Click any visitor to open their full profile, or click **View All** to jump to the full Visitors list.

<Card title="Browse all visitors" icon="users" href="/features/traffic/visitors">
  See profiles, browsing history, and attribution for every visitor
</Card>

### Engagement chart

A daily bar chart showing three trends side by side:

* **Page Views** (blue)
* **Visitors** (green)
* **Chats** (purple)

Use this chart to spot patterns — peak traffic days, the impact of a marketing push, or whether your chat engagement is keeping up with traffic growth.

## Time period filters

The date selector in the top right of the dashboard lets you switch between three windows:

<Tabs>
  <Tab title="Last 7 days">
    Best for spotting day-of-week patterns and the impact of recent campaigns or content launches.
  </Tab>

  <Tab title="Last 30 days">
    The default view. Gives you a stable monthly baseline without too much noise.
  </Tab>

  <Tab title="Last 60 days">
    Best for spotting longer-term trends and comparing month over month.
  </Tab>
</Tabs>

All summary cards, breakdowns, and the engagement chart update to reflect whichever range you select.

<Tip>
  Use the refresh button next to the date selector to pull the latest numbers without reloading the page.
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="Do I need to install anything to start tracking?">
    No. As long as your Clarky chat widget is embedded on your site and tracking is enabled in Settings, page views and visitors are recorded automatically.
  </Accordion>

  <Accordion title="What's the difference between Visitors and Sessions?">
    A **visitor** is one unique person — even if they come back tomorrow, they're still the same visitor. A **session** is a single browsing window. One visitor can have many sessions over time.
  </Accordion>

  <Accordion title="Why is Widget Opens higher than Chats Started?">
    Many visitors open the widget to look around — read the welcome message, see what kind of agent it is — without sending a message. Chats Started only counts conversations that actually began.
  </Accordion>

  <Accordion title="Will tracking slow down my website?">
    No. The pixel is part of the chat widget, which already loads asynchronously and is built to stay out of the way of your page's performance.
  </Accordion>

  <Accordion title="Can I see what each individual visitor did?">
    Yes. Click any visitor in the Recent Visitors list, or open the full Visitors list to see complete browsing histories, device info, location, and conversations for each person.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Explore Visitors" icon="users" href="/features/traffic/visitors">
    Drill into individual visitor profiles and journeys
  </Card>

  <Card title="Review Conversations" icon="inbox" href="/features/inbox/overview">
    Read the chats that came out of your traffic
  </Card>

  <Card title="Connect Contacts" icon="address-book" href="/features/crm/overview">
    See how visitors become CRM contacts
  </Card>

  <Card title="Adjust Settings" icon="gear" href="/features/settings/overview">
    Enable, disable, or fine-tune tracking
  </Card>
</CardGroup>


# Visitors
Source: https://docs.clarky.ai/features/traffic/visitors

Browse visitor profiles, browsing history, and marketing attribution

## What is the Visitors list?

The Visitors list is a complete record of every person who's been to your website while the chat widget was loaded. Each entry is a real human journey — every page they viewed, every chat they started, the device they used, and where they came from.

Use Visitors to understand individual leads, follow up on warm prospects, and see how marketing campaigns translate into actual conversations.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Opening Visitors

<Steps>
  <Step title="Go to Traffic">
    Click **Traffic** in the left sidebar.
  </Step>

  <Step title="View all visitors">
    Click **View All** in the Recent Visitors card on the Traffic dashboard.
  </Step>

  <Step title="Open a profile">
    Click any row to see that visitor's full profile.
  </Step>
</Steps>

## The visitors list

Each row in the list shows a quick snapshot of the visitor:

* **Visitor** — Their name or email if they've connected to a contact, or "Anonymous" if not
* **Location** — City, region, and country (when available)
* **Pages** — How many pages they've viewed across all visits
* **Chats** — How many conversations they've started, if any
* **Last Seen** — How recently they were active

### Filtering

Use the filter dropdown at the top of the page to narrow the list:

<Tabs>
  <Tab title="All Visitors">
    Everyone who's visited your site, regardless of whether they've chatted.
  </Tab>

  <Tab title="Engaged (Chatted)">
    Just the visitors who actually started a conversation with your agent. These are your warm leads.
  </Tab>

  <Tab title="Silent Visitors">
    Visitors who browsed but never opened a chat. A useful pool to study for understanding what content brings people in but doesn't convert.
  </Tab>
</Tabs>

<Tip>
  The Engaged filter is a great place to start when you're looking for follow-up opportunities. Every person in this list raised their hand and talked to your agent.
</Tip>

## Visitor profiles

Click any visitor to open their full profile. The profile is built around an activity timeline so you can see the visitor's journey in chronological order.

### Header

The top of the profile shows:

* **Name or "Anonymous Visitor"** — Their contact name if linked, otherwise an anonymous placeholder
* **Location** — City, region, and country
* **First seen** — The first time they ever visited your site

### Stats row

Four cards summarize the visitor's overall engagement:

<CardGroup>
  <Card title="Pages Viewed" icon="eye">
    Total pages they've loaded across all visits
  </Card>

  <Card title="Sessions" icon="calendar">
    Distinct browsing sessions over time
  </Card>

  <Card title="Conversations" icon="messages">
    Chats they've started with your agent
  </Card>

  <Card title="Engagement Score" icon="chart-line">
    A quick numeric measure of how active this visitor has been
  </Card>
</CardGroup>

### Activity timeline

The main column shows every session this visitor has had, newest first. Each session is grouped together and shows:

* The session date and time (e.g., "Today at 2:34 PM" or "Yesterday at 10:15 AM")
* The device and browser they used
* Total pages viewed in that session
* A badge if they started a conversation during this session

Inside each session, you'll see:

* **Conversations** — Highlighted in green, with a preview of the latest message and a **View** button that takes you straight to the conversation in your inbox
* **Page views** — Every page they loaded during that session, clickable so you can see what they were reading

<Info>
  Sessions are listed newest first, but pages within each session are listed in reverse chronological order so you can read the visitor's most recent activity at a glance.
</Info>

### Marketing attribution

If the visitor arrived through a UTM-tagged link, the right column shows their attribution:

<CardGroup>
  <Card title="First Touch" icon="flag">
    The first UTM source, medium, and campaign that brought this visitor to your site. This is who originally introduced them to you.
  </Card>

  <Card title="Last Touch" icon="bullseye">
    The most recent UTM source, medium, and campaign. This is what brought them back this time.
  </Card>
</CardGroup>

<Tip>
  First-touch attribution is great for measuring top-of-funnel campaigns. Last-touch attribution is great for seeing what closed the deal — what finally pulled the visitor back to convert.
</Tip>

If the visitor never arrived through a UTM-tagged link, the attribution card simply doesn't appear.

### Conversations

A list of every conversation this visitor has had with your agent, with the date and a preview of the most recent message. Click any conversation to open it in your inbox.

### Most Visited Pages

A ranked list of the pages this visitor has spent the most time on across all their sessions. Each page is clickable so you can review the actual content.

### Details

A reference card with:

* **First seen** — Their very first visit
* **Last seen** — Their most recent visit
* **IP Address** — The IP they connected from (when available)
* **Visitor ID** — A unique identifier for this visitor across sessions

## How visitors connect to contacts

Visitors start out anonymous. They become connected to a CRM contact the moment they share identifying information — typically by starting a conversation and providing their name or email, filling out a form, or booking an appointment.

Once a visitor is linked to a contact:

* Their name and email show up in the Visitors list instead of "Anonymous"
* Their browsing history is associated with that contact's CRM record
* Future visits from the same browser are automatically tied to the same contact

<Note>
  Connecting visitors to contacts gives your sales team incredible context. When a known lead returns to your pricing page, you'll know — and you can see exactly what they looked at before, during, and after their first conversation.
</Note>

<Card title="Learn about CRM contacts" icon="address-book" href="/features/crm/overview">
  How contacts work and how they connect to conversations
</Card>

## UTM attribution

UTM parameters are tags you add to links so you can track where traffic comes from. When a visitor clicks a link with UTM parameters, Clarky records them automatically.

### What gets captured

For each visitor, Clarky tracks two layers of attribution:

* **First touch** — The very first UTM-tagged link that ever brought this visitor to your site
* **Last touch** — The most recent UTM-tagged link that brought them in

Each layer captures three pieces:

* **Source** — Where the traffic came from (e.g., `google`, `newsletter`, `twitter`)
* **Medium** — The type of channel (e.g., `cpc`, `email`, `social`)
* **Campaign** — A specific campaign name (e.g., `spring-launch`, `black-friday`)

### Example UTM link

A link like:

```
https://yoursite.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=spring-launch
```

would show up on the visitor's profile as:

* Source: `newsletter`
* Medium: `email`
* Campaign: `spring-launch`

<Tip>
  Use consistent UTM naming across all your campaigns. It makes it much easier to compare first-touch vs. last-touch attribution and understand which channels actually drive conversations.
</Tip>

## Common questions

<AccordionGroup>
  <Accordion title="What does 'Anonymous' mean?">
    A visitor is anonymous until they share enough information to link them to a contact — usually a name or email through a chat, form, or booking. Anonymous visitors still have full browsing histories; you just don't know who they are yet.
  </Accordion>

  <Accordion title="Can a returning visitor be recognized?">
    Yes. As long as the same browser is used, the visitor is recognized across visits and their entire history is preserved on a single profile.
  </Accordion>

  <Accordion title="Why do some visitors have no location?">
    Location is derived from the visitor's IP address. In some cases — VPN use, privacy networks, or unusual network configurations — Clarky can't determine a reliable location.
  </Accordion>

  <Accordion title="What happens if a visitor clears their cookies?">
    Clearing cookies will typically result in the visitor being treated as a new, anonymous visitor on their next visit. If they later identify themselves through a chat, form, or booking, they can be re-linked to their existing contact.
  </Accordion>

  <Accordion title="Can I delete a visitor?">
    Visitor records are tied to your tracking data. To stop collecting new visitor data, disable tracking from Settings. To delete a contact and their associated visitor history, manage them through your CRM.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Traffic Overview" icon="chart-line" href="/features/traffic/overview">
    Back to the main Traffic dashboard
  </Card>

  <Card title="Inbox" icon="inbox" href="/features/inbox/overview">
    Open conversations that came from these visitors
  </Card>

  <Card title="CRM" icon="address-book" href="/features/crm/overview">
    See how visitors become contacts
  </Card>

  <Card title="Settings" icon="gear" href="/features/settings/overview">
    Enable, disable, or fine-tune tracking
  </Card>
</CardGroup>


# Chat
Source: https://docs.clarky.ai/guides/channels/chat

Deploy an AI-powered chat widget on your website

## Overview

The Chat channel provides a customizable web chat widget that you can embed on your website. It enables real-time conversations with your visitors powered by your AI agent.

<Info>
  **Plan availability:** Available on all plans. See [Plans & Billing](/features/settings/plans).
</Info>

## Features

<CardGroup>
  <Card title="Instant Responses" icon="bolt">
    Your agent responds to visitors immediately, 24/7
  </Card>

  <Card title="Customizable Design" icon="palette">
    Match your brand with custom colors and styling
  </Card>

  <Card title="Human Takeover" icon="user">
    Seamlessly take over conversations when needed
  </Card>

  <Card title="Rich Media" icon="image">
    Support for images, links, and formatted text
  </Card>
</CardGroup>

## Installing the Chat Widget

### Basic Installation

Add the following code to your website, just before the closing `</body>` tag:

```html theme={null}
<!-- Clarky Chat Widget -->
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

<Note>
  You can find your bot ID in **Settings > Share** in your Clarky dashboard.
</Note>

### Configuration Options

Customize the widget behavior with additional options:

```javascript theme={null}
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

### Advanced Integration

<Tabs>
  <Tab title="WordPress">
    For WordPress sites:

    <Steps>
      <Step title="Access Theme Editor">
        Go to **Appearance > Theme Editor** in your WordPress admin.
      </Step>

      <Step title="Edit Footer Template">
        Find and edit your `footer.php` file.
      </Step>

      <Step title="Add Code">
        Paste the Clarky embed code before the closing `</body>` tag.
      </Step>

      <Step title="Save Changes">
        Save the file and test your site.
      </Step>
    </Steps>

    <Warning>
      Always create a backup before editing theme files.
    </Warning>
  </Tab>

  <Tab title="Shopify">
    For Shopify stores:

    <Steps>
      <Step title="Go to Theme Editor">
        Navigate to **Online Store > Themes > Customize**.
      </Step>

      <Step title="Edit theme.liquid">
        Click **Actions > Edit code** and find `theme.liquid`.
      </Step>

      <Step title="Add Code">
        Paste the embed code before `</body>`.
      </Step>

      <Step title="Save and Test">
        Save changes and test on your store.
      </Step>
    </Steps>
  </Tab>

  <Tab title="React/Next.js">
    For React or Next.js applications:

    ```jsx theme={null}
    import { useEffect } from 'react';

    function App() {
      useEffect(() => {
        // Load Clarky script
        const script = document.createElement('script');
        script.src = 'https://clarky.ai/embed/<bot-id>/chat.js';
        script.async = true;
        document.body.appendChild(script);

        return () => {
          document.body.removeChild(script);
        };
      }, []);

      return <div>Your App</div>;
    }
    ```
  </Tab>

  <Tab title="Google Tag Manager">
    Using Google Tag Manager:

    <Steps>
      <Step title="Create New Tag">
        In GTM, create a new **Custom HTML** tag.
      </Step>

      <Step title="Paste Code">
        Add the Clarky embed code to the tag.
      </Step>

      <Step title="Set Trigger">
        Set trigger to **All Pages** or specific pages.
      </Step>

      <Step title="Publish">
        Save and publish your GTM container.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing Appearance

### Colors and Branding

Customize your chat widget to match your brand:

<Steps>
  <Step title="Navigate to Interface Settings">
    Go to **Settings > Interface** in your dashboard.
  </Step>

  <Step title="Customize Colors">
    Configure:

    * **Header Background**: The color of the chat widget header
    * **Header Text**: The color of text in the header
    * **Primary Color**: Buttons and accents
    * **Background**: Chat background color
  </Step>

  <Step title="Upload Avatar">
    Add a custom avatar image that appears in the chat.
  </Step>

  <Step title="Save Changes">
    Changes apply immediately to your widget.
  </Step>
</Steps>

### Greeting Message

Set a welcoming first message:

1. Go to **Settings > Interface**
2. Edit the **Chat Greeting** field
3. This message appears when users open the chat

**Example:**

```
👋 Hi there! I'm here to help. What can I assist you with today?
```

### Starter Prompts

Add quick-click options for common questions:

```json theme={null}
[
  "What are your business hours?",
  "Tell me about your services",
  "How can I contact you?",
  "I need help with an order"
]
```

Users can click these to start a conversation quickly.

## Chat Widget Features

### Real-Time Messaging

* **Instant delivery**: Messages send and receive in real-time
* **Typing indicators**: Show when the agent is typing
* **Read receipts**: Know when messages are read
* **Message history**: Conversations persist across sessions

### Rich Content

Your agent can send various content types:

<AccordionGroup>
  <Accordion title="Text Messages">
    Standard text responses with formatting support (bold, italic, lists, etc.)
  </Accordion>

  <Accordion title="Links and Buttons">
    Interactive elements that direct users to relevant pages or actions.
  </Accordion>

  <Accordion title="Images">
    Product photos, diagrams, or helpful visuals.
  </Accordion>

  <Accordion title="Cards">
    Structured information like product cards or feature highlights.
  </Accordion>
</AccordionGroup>

### Human Takeover

When a conversation needs human attention:

1. You'll receive a notification
2. Click to join the conversation
3. The user is notified a human has joined
4. You can take over or assist the AI agent

<Info>
  The AI agent continues to suggest responses even during human takeover, helping you respond faster.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Position Strategically">
    Place the chat widget where it's visible but not intrusive. Bottom-right is most common, but bottom-left works well for RTL languages.
  </Accordion>

  <Accordion title="Set Expectations">
    In your greeting, clearly state what the agent can help with. This prevents frustration and improves user experience.
  </Accordion>

  <Accordion title="Use Starter Prompts">
    Well-crafted starter prompts guide users toward topics your agent handles well and reduce confusion.
  </Accordion>

  <Accordion title="Monitor and Iterate">
    Review conversations regularly to identify areas where your agent struggles, then add knowledge to improve responses.
  </Accordion>

  <Accordion title="Enable Human Takeover">
    Always have a human agent available to take over when needed, especially during business hours.
  </Accordion>

  <Accordion title="Test Mobile Experience">
    Ensure your chat widget works well on mobile devices, as many users will access it from phones.
  </Accordion>
</AccordionGroup>

## Testing Your Chat Widget

Before going live:

<Steps>
  <Step title="Test on Staging">
    If you have a staging or test site, deploy there first.
  </Step>

  <Step title="Try Different Scenarios">
    Ask various types of questions:

    * Common questions (hours, location)
    * Product inquiries
    * Support requests
    * Edge cases
  </Step>

  <Step title="Test on Multiple Devices">
    Check desktop, tablet, and mobile devices.
  </Step>

  <Step title="Verify Handoff">
    Test the human takeover feature to ensure smooth transitions.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget Not Appearing">
    If the widget doesn't show:

    1. Verify the embed code is in the HTML
    2. Check browser console for JavaScript errors
    3. Ensure the bot ID is correct
    4. Clear browser cache and reload
  </Accordion>

  <Accordion title="Styling Issues">
    If the widget looks wrong:

    1. Check for CSS conflicts with your site
    2. Verify custom colors are valid hex codes
    3. Try disabling site-wide CSS temporarily
  </Accordion>

  <Accordion title="Messages Not Sending">
    If messages fail to send:

    1. Check your internet connection
    2. Verify the bot is active in Clarky dashboard
    3. Check browser console for errors
  </Accordion>
</AccordionGroup>

## Analytics and Insights

Track chat widget performance:

* **Conversations started**: How many users engage
* **Response time**: How quickly the agent responds
* **Completion rate**: Percentage of conversations resolved
* **Popular questions**: Most common user inquiries
* **Handoff rate**: How often human agents take over

<Card title="View Analytics" icon="chart-line" href="/features/dashboard/analytics">
  Learn more about tracking your chat performance
</Card>

## Next Steps

<CardGroup>
  <Card title="Customize Interface" icon="palette" href="/features/settings/interface">
    Match your brand with custom styling
  </Card>

  <Card title="Monitor Conversations" icon="messages" href="/features/inbox/overview">
    See what users are asking
  </Card>

  <Card title="Improve Context" icon="file-lines" href="/features/context/overview">
    Add documents, files and Q\&A your agent can use
  </Card>

  <Card title="Enable Voice" icon="phone" href="/guides/channels/voice">
    Add phone support to complement chat
  </Card>
</CardGroup>


# Email
Source: https://docs.clarky.ai/guides/channels/email

Manage email conversations with AI assistance

## Overview

The Email channel enables your AI agent to read and respond to emails automatically. Perfect for handling common inquiries, providing information, and routing complex questions to the right team members.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Key Features

<CardGroup>
  <Card title="Auto-Responses" icon="reply">
    Automatically reply to common email inquiries
  </Card>

  <Card title="Smart Routing" icon="route">
    Direct emails to appropriate team members
  </Card>

  <Card title="Rich Formatting" icon="text">
    Send well-formatted emails with images and links
  </Card>

  <Card title="Thread Management" icon="thread">
    Maintain conversation context across email threads
  </Card>
</CardGroup>

## Setting Up Email

<Steps>
  <Step title="Connect Email Account">
    Link your business email account from the [Integrations](https://clarky.ai/features/settings/integrations) page:

    **Supported Providers:**

    * Gmail / Google Workspace
    * Microsoft Outlook / Office 365
    * Resend (Custom)
  </Step>

  <Step title="Test the Setup">
    Send a test email to verify everything works.
  </Step>
</Steps>

## Email Account Integration

### Connecting Gmail

<Steps>
  <Step title="Click 'Connect Gmail'">
    In **Settings > Integrations**, find the Gmail integration.
  </Step>

  <Step title="Authorize Access">
    Sign in with your Google account and grant permissions.

    <Info>
      Clarky requests read and send permissions for your inbox. You can revoke access anytime from your Google Account settings.
    </Info>
  </Step>

  <Step title="Select Handling Options">
    Choose which emails to auto-respond to:

    * All emails to this address
    * Specific folders/labels
    * Emails matching certain criteria
  </Step>

  <Step title="Configure Notifications">
    Set up alerts for when emails need human attention.
  </Step>
</Steps>

### Connecting Outlook

<Steps>
  <Step title="Click 'Connect Outlook'">
    In **Settings > Integrations**, find the Outlook integration.
  </Step>

  <Step title="Microsoft Authorization">
    Sign in with your Microsoft account and grant permissions.
  </Step>

  <Step title="Configure Folder Rules">
    Specify which Outlook folders the agent should monitor.
  </Step>

  <Step title="Set Up Escalation">
    Define when emails should be forwarded to team members.
  </Step>
</Steps>

## Email Response Configuration

### Response Style

Configure how your agent writes emails:

<Tabs>
  <Tab title="Professional">
    Formal tone suitable for corporate communication.

    **Example:**

    ```
    Dear Mr. Smith,

    Thank you for reaching out to Acme Corporation.
    I would be happy to assist you with your inquiry
    regarding our product specifications.

    [Details...]

    Please let me know if you need any additional information.

    Best regards,
    Acme Support Team
    ```
  </Tab>

  <Tab title="Friendly">
    Warm, approachable tone for customer service.

    **Example:**

    ```
    Hi John!

    Thanks so much for getting in touch! I'd be happy
    to help you with that.

    [Details...]

    Let me know if you have any other questions!

    Cheers,
    The Acme Team
    ```
  </Tab>

  <Tab title="Concise">
    Brief, to-the-point responses.

    **Example:**

    ```
    Hi,

    [Direct answer to question]

    Thanks,
    Acme Support
    ```
  </Tab>
</Tabs>

Set your preferred style in a pinned Context document with only **Email** checked.

### Email Signature

Give your agent a rich HTML signature with your logo, links, and contact details. It is appended automatically to agent replies and to emails your team sends from the CRM.

<Steps>
  <Step title="Open Email settings">
    Go to **Settings > Email** for your agent.
  </Step>

  <Step title="Build the signature">
    Write the signature in the editor. The live preview shows exactly how it will render in the recipient's inbox.
  </Step>

  <Step title="Save">
    From then on, every outbound email carries the signature.
  </Step>
</Steps>

### Open Tracking

Want to know when a contact opens your email? Turn on open tracking in **Settings > Email**. When a recipient views a tracked message, Clarky logs an opened activity on the contact's timeline.

<Note>
  Open tracking is off by default and applies only to messages sent after you enable it.
</Note>

### Sending Domains

Outbound email is sent from a verified domain connected to your account. The sender field is a local part (for example `hello`) plus a dropdown of every domain you have verified, so one workspace can send as `hello@acme.com` for one agent and `team@acmeoutreach.com` for another.

If you run outbound Sequences, you can select several verified domains at launch and Clarky rotates enrollments across them. Each contact is pinned to one domain for the whole sequence, keeping follow-ups and replies in the same thread. See [Sequences](/features/crm/sequences) for details.

## Response Capabilities

### What the Agent Can Do

<AccordionGroup>
  <Accordion title="Answer Common Questions">
    Respond to FAQ-style inquiries instantly:

    * Business hours
    * Location and directions
    * Pricing information
    * Product availability
    * Service descriptions
  </Accordion>

  <Accordion title="Provide Information">
    Send relevant information based on inquiry:

    * Product specifications
    * Service details
    * Documentation links
    * How-to guides
    * Policy information
  </Accordion>

  <Accordion title="Collect Information">
    Gather details needed to process requests:

    * Contact information
    * Order details
    * Account information
    * Specific requirements
  </Accordion>

  <Accordion title="Schedule and Confirm">
    Handle appointment-related emails:

    * Check availability
    * Book appointments
    * Send confirmations
    * Handle rescheduling requests
  </Accordion>

  <Accordion title="Route Complex Inquiries">
    Identify when human help is needed and escalate appropriately.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails Not Being Processed">
    If the agent isn't reading emails:

    1. Check integration connection status
    2. Verify email account permissions
    3. Review filtering rules
    4. Check for authentication expiration
  </Accordion>

  <Accordion title="Wrong Responses">
    If agent sends incorrect information:

    1. Review the email thread in your inbox
    2. Update knowledge base with correct info
    3. Add specific examples for similar scenarios
    4. Consider adjusting auto-response rules
  </Accordion>

  <Accordion title="Too Many Escalations">
    If too many emails are escalated:

    1. Review why emails are being escalated
    2. Add knowledge to handle common escalations
    3. Adjust confidence thresholds
    4. Refine filtering rules
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Connect Email Account" icon="envelope" href="/features/settings/integrations">
    Link Gmail or Outlook to get started
  </Card>

  <Card title="Email-only documents" icon="file-lines" href="/features/context/documents">
    Give email its own instructions in Context
  </Card>

  <Card title="Monitor Email Conversations" icon="inbox" href="/features/inbox/overview">
    View and manage email threads
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/features/dashboard/analytics">
    Track email performance metrics
  </Card>
</CardGroup>


# Text/SMS
Source: https://docs.clarky.ai/guides/channels/text-sms

Respond to text messages automatically with AI

## Overview

The Text/SMS channel allows your AI agent to have conversations via text message. Customers can text your business number and receive instant, intelligent responses.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

<Info>
  Text/SMS typically uses the same phone number as your Voice channel, allowing customers to choose how they want to communicate.
</Info>

## Key Features

<CardGroup>
  <Card title="Instant Responses" icon="bolt">
    Reply to texts immediately, 24/7
  </Card>

  <Card title="Persistent Conversations" icon="messages">
    Conversation history maintained across messages
  </Card>

  <Card title="Rich Messaging" icon="sparkles">
    Send links, emojis, and formatted text
  </Card>

  <Card title="Two-Way Communication" icon="arrows-left-right">
    Customers can reply and have ongoing conversations
  </Card>
</CardGroup>

## Setting Up Text/SMS

<Steps>
  <Step title="Enable Text Channel">
    When creating your agent or in Settings, enable the Text/SMS channel.
  </Step>

  <Step title="Get SMS Number">
    Your phone number (same as Voice) is automatically SMS-enabled.

    If you need a dedicated SMS-only number, contact support.
  </Step>

  <Step title="Configure Auto-Responses">
    Set up how your agent responds to texts.
  </Step>

  <Step title="Test the Number">
    Send a test text to verify everything works.
  </Step>
</Steps>

## Conversation Handling

### Message Flow

1. **Customer Texts**: Sends a message to your number
2. **Instant Processing**: Clarky receives and analyzes the message
3. **AI Response**: Agent generates and sends a response
4. **Ongoing Dialogue**: Conversation continues as needed
5. **Context Maintained**: All messages linked to the conversation

### Context and Memory

Your AI agent remembers the conversation:

* Previous messages in the thread
* Customer's name and information
* Any data collected during the conversation
* Links to CRM contact record

This enables natural, contextual responses rather than treating each text as independent.

### Handling Multiple Customers

Clarky manages unlimited simultaneous text conversations, each with its own context and history.

## Auto-Response Configuration

Configure how your agent handles texts:

### Response Settings

<ParamField type="boolean">
  Automatically respond to incoming texts.
</ParamField>

<ParamField type="number">
  Optional delay before sending (in seconds). Makes responses feel more human.
</ParamField>

<ParamField type="number">
  Maximum length of responses. Clarky auto-splits long messages.
</ParamField>

### Business Hours

Configure different behaviors based on time:

* **During Hours**: Full AI responses
* **After Hours**: Auto-reply with hours and callback option
* **Holidays**: Custom messages for special closures

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings > Agent** in your dashboard.
  </Step>

  <Step title="Set Business Hours">
    Configure your operating hours and time zone.
  </Step>

  <Step title="Customize After-Hours Message">
    Set what to send when you're closed.

    **Example:**

    ```
    Thanks for texting! We're currently closed but will respond
    when we open at 9 AM. For urgent matters, call (555) 123-4567.
    ```
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Responses Concise">
    Text messages should be brief and to the point. If a response is getting long, offer to:

    * Continue the conversation by phone
    * Send a link to more detailed information
    * Email additional details
  </Accordion>

  <Accordion title="Use Clear Language">
    Avoid jargon and complex terms. Write at a 6th-grade reading level for maximum comprehension.
  </Accordion>

  <Accordion title="Respond Quickly">
    Customers expect faster responses via text than email. Configure your agent to reply within seconds.
  </Accordion>

  <Accordion title="Provide Options">
    When appropriate, give customers clear choices:

    "I can help you with:

    1. Scheduling
    2. Pricing info
    3. Directions

    Just reply with a number!"
  </Accordion>

  <Accordion title="Confirm Important Details">
    For appointments, orders, or critical information, always confirm what was understood:

    "Got it! You want to schedule for Tuesday at 2 PM. Is that correct?"
  </Accordion>

  <Accordion title="Know When to Call">
    Some things are better handled by voice. Train your agent to suggest a phone call for:

    * Complex issues
    * Emotional/sensitive matters
    * Long explanations
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Appointment Scheduling

Perfect for booking appointments via text:

**Customer:** "I need a haircut appointment"

**Agent:** "I'd be happy to help! What day works best for you?"

**Customer:** "Thursday"

**Agent:** "Great! I have openings at 10 AM, 2 PM, or 4 PM on Thursday. Which time?"

**Customer:** "2pm"

**Agent:** "Perfect! You're all set for Thursday at 2 PM. I'll send a reminder the day before. See you then! 💇"

### Order Status

Handle order inquiries efficiently:

**Customer:** "Where's my order?"

**Agent:** "I can help check that! What's your order number?"

**Customer:** "#12345"

**Agent:** "Order #12345 shipped yesterday via UPS. Tracking: 1Z999AA10123456784. Expected delivery: Tomorrow by 8 PM. Anything else I can help with?"

### Quick Questions

Answer common questions instantly:

**Customer:** "Are you open tomorrow?"

**Agent:** "Yes! We're open tomorrow from 9 AM to 6 PM. Can I help you with anything else?"

### Lead Capture

Collect information from potential customers:

**Customer:** "How much for a consultation?"

**Agent:** "Initial consultations are free! I can help you schedule one. May I get your name and email?"

**Customer:** "John Smith, [john@email.com](mailto:john@email.com)"

**Agent:** "Thanks John! What days work well for you?"

## Message Templates

Create templates for common responses:

* **Hours**: "We're open Mon-Fri 9-6, Sat 10-4, closed Sunday."
* **Location**: "We're at 123 Main St, Downtown. \[Google Maps Link]"
* **Pricing**: "Prices start at \$XX. Want details on a specific service?"
* **Appointment Confirm**: "✓ Confirmed! \[Date] at \[Time]. Reply CANCEL to cancel."

Put templates in a Context document; check only **Text** on it to keep them text-specific.

## Human Takeover

When a conversation needs human attention:

### When It Happens

* Customer requests to speak with someone
* Agent confidence is low
* Sensitive or complex issue
* Manual escalation by monitoring staff

### How It Works

<Steps>
  <Step title="Notification Sent">
    Team members receive a notification about the conversation needing attention.
  </Step>

  <Step title="Agent Notifies Customer">
    "I'm connecting you with a team member who can better help you..."
  </Step>

  <Step title="Human Takes Over">
    Team member responds via the Clarky dashboard or mobile app.
  </Step>

  <Step title="Seamless Transition">
    Customer continues texting the same number—no interruption.
  </Step>
</Steps>

## Compliance and Regulations

<Warning>
  Text message marketing is regulated by laws like TCPA (US), CASL (Canada), and GDPR (EU). Ensure you have proper consent before texting customers.
</Warning>

### Opt-In Requirements

* Get explicit consent before texting marketing messages
* Provide clear opt-out instructions
* Honor opt-out requests immediately
* Keep records of consent

### Auto-Response Requirements

Include in your initial response:

* Your business name
* How to opt-out (usually "Reply STOP to unsubscribe")
* Help instructions (usually "Reply HELP for help")

**Example Initial Response:**

```
Hi from Acme Services! I'm here to help. Reply STOP to opt out or HELP for assistance.
```

### Opt-Out Handling

Clarky automatically handles:

* **STOP**: Unsubscribes the contact
* **UNSUBSCRIBE**: Same as STOP
* **HELP**: Sends help information
* **INFO**: Provides business information

<Info>
  Opt-outs are instant and apply to all future messages, except transactional confirmations.
</Info>

## Analytics and Metrics

Track text message performance:

* **Total Messages**: Incoming and outgoing volume
* **Response Time**: How quickly the agent replies
* **Resolution Rate**: Conversations handled without escalation
* **Opt-Out Rate**: Percentage of contacts unsubscribing
* **Popular Topics**: Most common customer inquiries
* **Conversion Rate**: Texts leading to appointments/sales

<Card title="View SMS Analytics" icon="chart-line" href="/features/dashboard/analytics">
  Access detailed text messaging metrics
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Messages Not Delivering">
    If customers report not receiving texts:

    1. Verify their number is correct
    2. Check if they've opted out
    3. Confirm they can receive texts from short codes/long codes
    4. Check message sending limits for your plan
  </Accordion>

  <Accordion title="Images Not Sending">
    If MMS images fail:

    1. Verify recipient's carrier supports MMS
    2. Check image size (max 5MB)
    3. Ensure image format is supported (JPG, PNG, GIF)
    4. Try sending as a link instead
  </Accordion>

  <Accordion title="Wrong Auto-Responses">
    If agent sends incorrect replies:

    1. Review conversation in your inbox
    2. Update knowledge base with correct information
    3. Add specific examples to improve understanding
    4. Consider adding keyword-based templates
  </Accordion>
</AccordionGroup>

## Mobile App Integration

Respond to texts on the go with the Clarky mobile app:

* Receive real-time notifications
* Take over conversations
* View full message history
* Send texts from your device

<Card title="Get Mobile App" icon="mobile" href="/features/settings/mobile-app">
  Download and configure the Clarky mobile app
</Card>

## Next Steps

<CardGroup>
  <Card title="Set Up Voice" icon="phone" href="/guides/channels/voice">
    Enable voice calls on the same number
  </Card>

  <Card title="Monitor Messages" icon="inbox" href="/features/inbox/overview">
    View and manage text conversations
  </Card>

  <Card title="Text-only documents" icon="file-lines" href="/features/context/documents">
    Give texting its own short instructions in Context
  </Card>

  <Card title="View Analytics" icon="chart-bar" href="/features/dashboard/analytics">
    Track text message performance
  </Card>
</CardGroup>


# Voice/Phone
Source: https://docs.clarky.ai/guides/channels/voice

Handle phone calls with natural AI voice

## Overview

The Voice channel enables your AI agent to answer phone calls using natural-sounding voice AI. Your customers can call a dedicated phone number and have conversations just like they would with a human agent.

<Info>
  **Plan availability:** Standard or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## Key Capabilities

<CardGroup>
  <Card title="Natural Conversations" icon="comments">
    Engage in fluid, natural-sounding phone conversations
  </Card>

  <Card title="Multilingual Support" icon="language">
    Handle calls in multiple languages automatically
  </Card>

  <Card title="Real-Time Translation" icon="globe">
    Translate conversations for agents in real-time
  </Card>

  <Card title="Call Recording" icon="microphone">
    All calls are recorded for quality and training
  </Card>
</CardGroup>

## Setting Up Voice

<Steps>
  <Step title="Enable Voice Channel">
    When creating your agent or in Settings, enable the Voice channel.
  </Step>

  <Step title="Get a Phone Number">
    Clarky will provision a dedicated phone number for your agent.

    You can:

    * Choose from available numbers
    * Request a specific area code
    * Port an existing number (enterprise)
  </Step>

  <Step title="Configure Greeting">
    Set up what your agent says when answering calls.

    Navigate to **Settings > Phone Greeting** to customize.
  </Step>

  <Step title="Select Voice">
    Choose from multiple natural-sounding voices.

    Go to **Settings > Voices** to preview and select.
  </Step>

  <Step title="Test Your Setup">
    Call your new number to test the experience.
  </Step>
</Steps>

## Phone Greeting Configuration

The phone greeting is the first thing callers hear. Make it count!

### Best Practices for Greetings

<AccordionGroup>
  <Accordion title="Keep It Brief">
    Aim for 10-15 seconds maximum. Callers want to get to their question quickly.

    **Good Example:**

    ```
    Thank you for calling Acme Services. I'm here to help.
    What can I assist you with today?
    ```

    **Too Long:**

    ```
    Thank you so much for calling Acme Services, the premier provider
    of business solutions since 1995. We're so glad you called today.
    Please tell us how we can help you...
    ```
  </Accordion>

  <Accordion title="Set Expectations">
    Briefly mention what the agent can help with.

    **Example:**

    ```
    Thanks for calling Acme Dental. I can help you schedule appointments,
    answer questions about our services, or provide office hours.
    How can I help?
    ```
  </Accordion>

  <Accordion title="Sound Natural">
    Write as you would speak, not as you would write.

    Use contractions and casual language:

    * "I'm" instead of "I am"
    * "can't" instead of "cannot"
    * "How can I help?" instead of "How may I assist you?"
  </Accordion>

  <Accordion title="Include Business Name">
    Always mention your business name so callers know they reached the right place.
  </Accordion>
</AccordionGroup>

### Greeting Configuration

In **Settings > Phone Greeting**, you can configure:

<ParamField type="string">
  The initial message callers hear when the agent answers.
</ParamField>

<ParamField type="string">
  What the agent says before transferring to a human agent.

  **Example:** "Let me connect you with someone who can help. Please hold."
</ParamField>

<ParamField type="string">
  Message played when the agent needs to take a message.

  **Example:** "I'll make sure someone gets back to you. Please leave your name and number."
</ParamField>

## Voice Selection

Choose from multiple high-quality AI voices to represent your brand.

### Available Voices

Clarky offers a variety of voices in different styles:

* **Professional**: Formal, clear, suitable for corporate settings
* **Friendly**: Warm, approachable, great for customer service
* **Energetic**: Upbeat, enthusiastic, works well for sales
* **Calm**: Soothing, measured, ideal for support

<Tabs>
  <Tab title="English">
    Multiple English voices available:

    * American English (various regional accents)
    * British English
    * Australian English
    * Canadian English
  </Tab>

  <Tab title="Spanish">
    Spanish voice options:

    * Latin American Spanish
    * European Spanish
  </Tab>

  <Tab title="Other Languages">
    Additional languages supported:

    * French
    * German
    * Italian
    * Portuguese
    * And more...
  </Tab>
</Tabs>

### Changing Your Voice

<Steps>
  <Step title="Navigate to Voice Settings">
    Go to **Settings > Voices**.
  </Step>

  <Step title="Preview Voices">
    Click the play button next to each voice to hear a sample.
  </Step>

  <Step title="Select Voice">
    Choose the voice that best represents your brand.
  </Step>

  <Step title="Test with a Call">
    Call your agent to hear the new voice in action.
  </Step>
</Steps>

<Tip>
  Consider testing different voices with team members to get feedback before making a final choice.
</Tip>

## Phone Number Management

### Getting Your Number

Your dedicated phone number is provisioned automatically when you enable Voice. You can:

1. **Choose Area Code**: Select a local area code for your business
2. **Toll-Free**: Request a toll-free (800, 888, etc.) number
3. **International**: Get numbers in different countries

### Number Settings

Configure how your phone number behaves:

<ParamField type="object">
  Set when your agent answers calls vs. when to route to voicemail.
</ParamField>

<ParamField type="string">
  Forward unanswered calls to a backup number.
</ParamField>

<ParamField type="boolean">
  Enable/disable call recording (required in some jurisdictions to notify callers).
</ParamField>

## Call Handling Features

### Intelligent Routing

Your AI agent can:

* **Answer Questions**: Handle common inquiries instantly
* **Book Appointments**: Integrate with calendars to schedule
* **Transfer Calls**: Route to specific departments or people
* **Take Messages**: Capture contact information and requests
* **Provide Information**: Share hours, location, pricing, etc.

### Human Handoff

When a call needs human attention:

<Steps>
  <Step title="Agent Detects Need">
    The AI recognizes when it can't help or when the caller requests a human.
  </Step>

  <Step title="Notification Sent">
    Available team members receive a notification.
  </Step>

  <Step title="Smooth Transfer">
    The agent says the transfer message and connects the call.
  </Step>

  <Step title="Context Provided">
    The human agent sees the full conversation context.
  </Step>
</Steps>

### After-Hours Handling

Configure what happens outside business hours:

* **Voicemail**: Take messages for follow-up
* **Emergency Line**: Transfer urgent calls to an on-call number
* **Auto-Response**: Provide information and hours without taking messages
* **Always Available**: Keep the AI agent active 24/7

## Multilingual Capabilities

One of Clarky Voice's most powerful features is automatic language detection and multilingual support.

### How It Works

1. **Caller Speaks**: In any supported language
2. **Auto-Detection**: Clarky identifies the language
3. **Natural Response**: Agent responds in that language
4. **Real-Time Translation**: Transcripts translated for you

### Supported Languages

Clarky Voice supports 50+ languages including:

* Spanish
* French
* German
* Mandarin
* Japanese
* Arabic
* And many more...

<Info>
  No configuration needed! Language detection and multilingual responses work automatically.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Test Thoroughly">
    Call your agent multiple times with different scenarios before promoting the number. Test:

    * Common questions
    * Requests for human transfer
    * After-hours calls
    * Background noise conditions
  </Accordion>

  <Accordion title="Monitor Early Calls">
    Listen to recordings of the first calls to identify areas for improvement in your agent's knowledge or greeting.
  </Accordion>

  <Accordion title="Keep Prompts Natural">
    Write your phone greeting and knowledge base in conversational language, as it sounds better when spoken.
  </Accordion>

  <Accordion title="Provide Clear Options">
    If callers can do multiple things, briefly mention them in your greeting:
    "I can help you schedule, get directions, or answer questions about our services."
  </Accordion>

  <Accordion title="Have a Backup Plan">
    Always configure call forwarding or human handoff so callers can reach someone if needed.
  </Accordion>
</AccordionGroup>

## Analytics and Reporting

Track voice channel performance:

* **Total Calls**: Volume of incoming calls
* **Call Duration**: Average and total talk time
* **Resolution Rate**: Calls handled without transfer
* **Top Inquiries**: Most common questions
* **Transfer Rate**: Percentage requiring human agent
* **Language Distribution**: Which languages callers use

<Card title="View Call Analytics" icon="chart-line" href="/features/dashboard/analytics">
  Access detailed voice channel metrics
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Poor Call Quality">
    If callers report audio issues:

    1. Check your internet connection
    2. Verify Clarky system status
    3. Ask caller to try from different location
    4. Contact support if issues persist
  </Accordion>

  <Accordion title="Agent Not Understanding">
    If the agent misunderstands callers:

    1. Review call recordings
    2. Add specific knowledge about problematic topics
    3. Adjust greeting to guide callers better
    4. Consider adding synonym variations to knowledge
  </Accordion>

  <Accordion title="Calls Not Connecting">
    If calls don't go through:

    1. Verify number is active in your dashboard
    2. Check if you've exceeded plan limits
    3. Ensure payment information is current
    4. Contact support for assistance
  </Accordion>
</AccordionGroup>

## Compliance and Legal

<Warning>
  Call recording laws vary by jurisdiction. Clarky automatically plays a recording notice in jurisdictions that require it, but you should verify compliance with local laws.
</Warning>

### Recording Consent

* Callers are notified when calls are recorded
* Recordings stored securely and encrypted
* Access limited to workspace administrators
* Retention configurable (default: 90 days)

## Next Steps

<CardGroup>
  <Card title="Configure Greeting" icon="microphone" href="/features/settings/voice">
    Set up your phone greeting message
  </Card>

  <Card title="Choose Voice" icon="volume" href="/features/settings/voice">
    Select the perfect voice for your brand
  </Card>

  <Card title="Review Calls" icon="headset" href="/features/inbox/conversations">
    Listen to call recordings in your inbox
  </Card>

  <Card title="Add Text/SMS" icon="comment-sms" href="/guides/channels/text-sms">
    Enable text messaging on the same number
  </Card>
</CardGroup>


# Creating Your First Agent
Source: https://docs.clarky.ai/guides/creating-agent

Build and configure your AI agent in minutes

## Agent Creation Overview

Creating an AI agent with Clarky is straightforward and fast. Your agent can be up and running in just a few minutes.

## Starting the Creation Process

<Steps>
  <Step title="Access the Agent Creator">
    Navigate to [clarky.ai/create](https://clarky.ai/create) or click **"Create Agent"** from the homepage.
  </Step>

  <Step title="Enter Your Website">
    Provide your website URL so Clarky can automatically learn about your business.

    ```
    Example: https://yourbusiness.com
    ```

    <Tip>
      Clarky will crawl your website and extract relevant information to train your agent automatically.
    </Tip>
  </Step>

  <Step title="Configure Basic Settings">
    Set up your agent's identity:

    * **Agent Name**: What your agent will be called (e.g., "Support Bot", "Sales Assistant")
    * **Greeting Message**: The first message users see when they interact
    * **Agent Role**: What your agent's purpose is (support, sales, information, etc.)
  </Step>
</Steps>

## Agent Configuration Options

### Website Crawling

When you provide your website URL, Clarky:

1. **Crawls Your Pages**: Automatically visits and reads your website content
2. **Extracts Information**: Pulls relevant text, FAQs, and product information
3. **Builds Context**: Turns every page into a document your agent can use
4. **Generates Summary**: Creates a comprehensive summary of your business

<Info>
  The initial crawl typically takes 2-5 minutes depending on your website size. You'll see a progress indicator during this process.
</Info>

### Channel Selection

<Tabs>
  <Tab title="Chat">
    **Best for**: Website visitors, instant support, lead capture

    **Setup includes**:

    * Customizable chat widget
    * Chat greeting message
    * Starter prompts for common questions
    * Widget appearance customization
  </Tab>

  <Tab title="Voice">
    **Best for**: Phone support, appointment booking, order status

    **Setup includes**:

    * Phone greeting script
    * Voice selection (multiple natural-sounding voices)
    * Phone number provisioning
    * Call routing options
  </Tab>

  <Tab title="Text/SMS">
    **Best for**: Mobile-first customers, appointment reminders, quick updates

    **Setup includes**:

    * SMS-optimized responses
    * Phone number for texting
    * Message templates
    * Auto-reply configuration
  </Tab>

  <Tab title="Email">
    **Best for**: Detailed inquiries, documentation requests, follow-ups

    **Setup includes**:

    * Email response templates
    * Signature configuration
    * Integration with email providers (Gmail, Outlook)
    * Auto-reply settings
  </Tab>
</Tabs>

## Testing Your Agent

After creation, you can immediately test your agent:

<Steps>
  <Step title="Open Test Interface">
    Use the built-in chat interface to have a conversation with your agent.
  </Step>

  <Step title="Try Different Questions">
    Ask questions related to your business to see how the agent responds.

    <Tip>
      Start with basic questions about your products, services, or hours of operation.
    </Tip>
  </Step>

  <Step title="Refine Context">
    If responses aren't quite right, you can immediately adjust what your agent knows in the Context section.
  </Step>
</Steps>

## Deployment Options

### Chat Widget Deployment

To add the chat widget to your website:

```html theme={null}
<!-- Add this before the closing </body> tag -->
<script src="https://clarky.ai/embed/<bot-id>/chat.js"></script>
```

### Voice Deployment

For voice channels:

1. Get your dedicated phone number from the Settings
2. Update your business listings with the new number
3. Configure call forwarding if needed
4. Set up voicemail and after-hours handling

### Text/SMS Deployment

For text messaging:

1. Use your dedicated SMS number
2. Add it to your marketing materials
3. Configure auto-responses for common keywords
4. Set up notification preferences

### Email Deployment

For email channels:

1. Connect your email account (Gmail or Outlook)
2. Configure which emails should be handled by the agent
3. Set up escalation rules for complex inquiries
4. Customize email templates and signatures

## Best Practices

<AccordionGroup>
  <Accordion title="Start Simple">
    Begin with a single channel (usually Chat) and ensure it's working well before adding more channels. This allows you to refine your agent's knowledge and behavior without spreading too thin.
  </Accordion>

  <Accordion title="Review What It Learned">
    After website crawling, review the About document that was generated and the pages in Context. Disable irrelevant pages and add documents for anything that is missing.
  </Accordion>

  <Accordion title="Set Clear Expectations">
    In your greeting message, clearly communicate what the agent can help with. This sets proper expectations for users.
  </Accordion>

  <Accordion title="Test Thoroughly">
    Before going live, test your agent with various scenarios including:

    * Common customer questions
    * Edge cases and unusual requests
    * Handoff scenarios requiring human support
  </Accordion>

  <Accordion title="Enable Human Takeover">
    Always have a clear path for human agents to take over when needed. Enable the human takeover feature in your settings.
  </Accordion>
</AccordionGroup>

## Common Issues

<Warning>
  If your website crawl fails, check that:

  * Your website is publicly accessible
  * There are no robots.txt restrictions blocking crawlers
  * Your website loads properly without errors
</Warning>

<Check>
  Your agent is now created and ready to handle conversations! Monitor the inbox to see how it performs.
</Check>

## Next Steps

<CardGroup>
  <Card title="Customize Appearance" icon="palette" href="/features/settings/interface">
    Personalize your chat widget colors and styling
  </Card>

  <Card title="Add More Context" icon="file-lines" href="/features/context/overview">
    Enhance your agent with additional information
  </Card>

  <Card title="Set Up Integrations" icon="plug" href="/features/settings/integrations">
    Connect to your existing business tools
  </Card>

  <Card title="Monitor Performance" icon="chart-line" href="/features/dashboard/overview">
    Track your agent's conversations and metrics
  </Card>
</CardGroup>


# Signing Up for Clarky
Source: https://docs.clarky.ai/guides/signup

Create your Clarky account and get started

## Creating Your Account

Clarky offers simple, secure authentication without the need to manage passwords.

### Authentication Methods

<Tabs>
  <Tab title="Magic Link">
    The easiest way to sign up and log in to Clarky.

    <Steps>
      <Step title="Enter Your Email">
        Go to [clarky.ai](https://clarky.ai/) and enter your email address.
      </Step>

      <Step title="Check Your Inbox">
        You'll receive an email with a secure login link.

        <Note>
          The link expires after a short time for security. If it expires, simply request a new one.
        </Note>
      </Step>

      <Step title="Click the Link">
        Click the link in the email to complete authentication and access your account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Google Sign-In">
    Sign up using your existing Google account for even faster access.

    <Steps>
      <Step title="Click 'Continue with Google'">
        On the signup page, select the Google sign-in option.
      </Step>

      <Step title="Choose Your Account">
        Select the Google account you want to use with Clarky.
      </Step>

      <Step title="Grant Permissions">
        Authorize Clarky to access your basic profile information.

        <Info>
          Clarky only accesses your name and email address—nothing more.
        </Info>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Complete Your Profile

After authenticating, you'll need to complete your profile with a few key details.

### Required Information

<ParamField type="string">
  Your full name as you'd like it to appear in the system.
</ParamField>

<ParamField type="string">
  The name of your organization or workspace. This will be visible to team members you invite.

  **Examples:**

  * Acme Corporation
  * Tyler's Marketing Agency
  * Downtown Dental
</ParamField>

### What Happens Next

When you submit your profile information:

1. **User Profile Created**: Your personal profile is saved with your name and email
2. **Workspace Generated**: A new workspace is created with a unique URL slug (automatically generated from your workspace name)
3. **Trial Started**: Your account begins with a trial subscription
4. **Redirect to Demo**: You're taken to the agent creation page to build your first AI agent

<Check>
  Your account is now active! You can start creating AI agents right away.
</Check>

## Account Features

Your Clarky account includes:

<CardGroup>
  <Card title="Free Trial" icon="gift">
    Start with a trial to explore all features
  </Card>

  <Card title="Unlimited Workspaces" icon="building">
    Create separate workspaces for different projects or clients
  </Card>

  <Card title="Team Collaboration" icon="users">
    Invite team members to collaborate in your workspace
  </Card>

  <Card title="Multi-Channel Support" icon="messages">
    Access chat, voice, text, and email channels
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I didn't receive the magic link email">
    If you don't see the email within a few minutes:

    1. Check your spam/junk folder
    2. Verify you entered the correct email address
    3. Request a new magic link
    4. Try signing up with Google instead
  </Accordion>

  <Accordion title="The magic link expired">
    Magic links expire after 10 minutes for security. Simply request a new one by entering your email again on the login page.
  </Accordion>

  <Accordion title="I can't access my workspace">
    If you're having trouble accessing your workspace:

    1. Make sure you're signed in with the same account you used to create the workspace
    2. Check if you have the correct workspace URL
    3. Contact support if you need to recover access
  </Accordion>

  <Accordion title="Can I change my workspace name later?">
    Yes! You can update your workspace name anytime in the Workspace Settings. The URL slug can also be customized.
  </Accordion>
</AccordionGroup>

## Next Steps

<Card title="Create Your First Agent" icon="rocket" href="/guides/creating-agent">
  Now that your account is set up, create your first AI agent
</Card>


# Workspace Management
Source: https://docs.clarky.ai/guides/workspace-management

Organize your agents and collaborate with your team

## What is a Workspace?

A workspace in Clarky is your organizational container for agents, team members, and settings. Think of it as your company's account where everything is centralized.

### Workspace Benefits

<CardGroup>
  <Card title="Multiple Agents" icon="robot">
    Create and manage multiple AI agents within one workspace
  </Card>

  <Card title="Team Collaboration" icon="users">
    Invite team members to work together
  </Card>

  <Card title="Shared Resources" icon="share">
    Share integrations, contacts, and knowledge across agents
  </Card>

  <Card title="Unified Billing" icon="credit-card">
    One subscription covers all agents in your workspace
  </Card>
</CardGroup>

## Workspace Settings

Access workspace settings by navigating to **Settings > Workspace** from your dashboard.

### Basic Information

<ParamField type="string">
  Your workspace display name. This is visible to all team members.
</ParamField>

<ParamField type="string">
  The URL-friendly identifier for your workspace. This appears in your dashboard URLs.

  **Example:** `acme-corp` → `https://clarky.ai/admin/acme-corp`
</ParamField>

### Workspace URL Structure

Your workspace URLs follow this pattern:

```
https://clarky.ai/admin/{workspace-slug}/{agent-slug}
```

<Info>
  You can customize both your workspace slug and individual agent slugs for easy access.
</Info>

## Managing Team Members

### Inviting Users

To invite team members to your workspace:

<Steps>
  <Step title="Navigate to Users">
    Go to **Settings > Users** in your dashboard.
  </Step>

  <Step title="Click 'Invite User'">
    Select the invite button to open the invitation form.
  </Step>

  <Step title="Enter Email">
    Provide the email address of the person you want to invite.
  </Step>

  <Step title="Set Permissions">
    Choose the appropriate role for this team member:

    * **Admin**: Full access to all workspace features
    * **Member**: Can manage agents and view conversations
    * **Viewer**: Read-only access to conversations and reports
  </Step>

  <Step title="Send Invitation">
    The invited user will receive an email with a link to join your workspace.
  </Step>
</Steps>

### User Roles and Permissions

<Tabs>
  <Tab title="Admin">
    **Full Access** to all workspace features including:

    * Create, edit, and delete agents
    * Manage team members and invitations
    * Configure billing and subscription
    * Access all conversations and CRM data
    * Modify workspace settings
    * Set up integrations
  </Tab>

  <Tab title="Member">
    **Standard Access** for day-to-day operations:

    * View and respond to conversations
    * Manage CRM contacts
    * Edit agent Context
    * Configure agent settings
    * View analytics and reports

    **Cannot:**

    * Manage team members
    * Delete agents
    * Modify billing settings
  </Tab>

  <Tab title="Viewer">
    **Read-Only Access** for monitoring:

    * View conversations
    * See CRM contacts
    * Access analytics dashboards

    **Cannot:**

    * Respond to conversations
    * Edit any settings
    * Manage contacts
    * Create or modify agents
  </Tab>
</Tabs>

### Removing Users

To remove a user from your workspace:

1. Go to **Settings > Users**
2. Find the user in the list
3. Click the **Remove** button
4. Confirm the removal

<Warning>
  Removed users will immediately lose access to your workspace. This action cannot be undone.
</Warning>

## Multiple Workspaces

You can create and belong to multiple workspaces:

### When to Use Multiple Workspaces

<AccordionGroup>
  <Accordion title="Multiple Businesses">
    If you run separate businesses, create a workspace for each one to keep agents, conversations, and data completely separate.
  </Accordion>

  <Accordion title="Client Work">
    Agencies can create separate workspaces for each client, maintaining clear boundaries and access control.
  </Accordion>

  <Accordion title="Development vs Production">
    Keep a test workspace for experimentation separate from your production workspace.
  </Accordion>

  <Accordion title="Different Departments">
    Large organizations might want separate workspaces for Sales, Support, and other departments.
  </Accordion>
</AccordionGroup>

### Switching Between Workspaces

<Steps>
  <Step title="Open Workspace Selector">
    Click your workspace name at the bottom of the sidebar.
  </Step>

  <Step title="Choose Workspace">
    Select the workspace you want to switch to from the dropdown.
  </Step>

  <Step title="Access Agents">
    You'll see all agents and data for the selected workspace.
  </Step>
</Steps>

## Workspace Billing

Each workspace has its own subscription and billing:

### Subscription Details

* **Free Trial**: All new workspaces start with a trial period
* **Paid Plans**: Upgrade to access more features and higher limits
* **Per-Workspace Billing**: Each workspace requires its own subscription

<Card title="View Plans" icon="credit-card" href="/features/settings/plans">
  Learn more about available subscription plans
</Card>

### What's Included

Your workspace subscription covers:

* All agents within the workspace
* All team members (no per-user fees)
* All conversations across all channels
* CRM and contact management
* Integrations and add-ons

## Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    Choose clear workspace names that make it obvious what the workspace is for, especially if you manage multiple workspaces.
  </Accordion>

  <Accordion title="Start with Admin Access Sparingly">
    Only grant admin access to users who truly need it. Most team members work well with Member access.
  </Accordion>

  <Accordion title="Regular User Audits">
    Periodically review your user list and remove users who no longer need access.
  </Accordion>

  <Accordion title="Organize Agents Logically">
    Create separate agents for different purposes (e.g., "Sales Agent", "Support Agent") rather than one agent handling everything.
  </Accordion>

  <Accordion title="Document Workspace Conventions">
    If working with a team, establish naming conventions and organizational standards for your workspace.
  </Accordion>
</AccordionGroup>

## Workspace Data

### What Data is Stored

Each workspace contains:

* All agent configurations and knowledge bases
* Conversation history across all channels
* CRM contacts and sales pipeline data
* Integration settings and connections
* Team member information and access logs
* Analytics and performance data

### Data Privacy

<Info>
  Data in one workspace is completely isolated from other workspaces. Team members can only access workspaces they've been invited to.
</Info>

### Data Export

You can export workspace data including:

* Conversation transcripts
* Contact lists
* Analytics reports
* Agent configurations

<Note>
  Contact support for assistance with bulk data exports.
</Note>

## Next Steps

<CardGroup>
  <Card title="Invite Your Team" icon="user-plus" href="/features/settings/users">
    Add team members to collaborate
  </Card>

  <Card title="Create More Agents" icon="plus" href="/guides/creating-agent">
    Build additional agents for different purposes
  </Card>

  <Card title="Set Up Integrations" icon="plug" href="/features/settings/integrations">
    Connect your business tools
  </Card>

  <Card title="Manage Subscription" icon="credit-card" href="/features/settings/plans">
    Review and upgrade your plan
  </Card>
</CardGroup>


# Welcome to Clarky
Source: https://docs.clarky.ai/introduction

Create AI agents for chat, voice, text/SMS, and email—instantly

## What is Clarky?

Clarky is an all-in-one AI agent platform that enables you to create intelligent conversational agents across multiple channels. Whether your customers reach out via web chat, phone call, text message, or email, Clarky provides a unified, intelligent response powered by AI.

<CardGroup>
  <Card title="Web Chat" icon="message" href="/guides/channels/chat">
    Embed an AI-powered chat widget on your website
  </Card>

  <Card title="Voice" icon="phone" href="/guides/channels/voice">
    Handle phone calls with natural voice AI
  </Card>

  <Card title="Text/SMS" icon="comment-sms" href="/guides/channels/text-sms">
    Respond to SMS and text messages automatically
  </Card>

  <Card title="Email" icon="envelope" href="/guides/channels/email">
    Manage email conversations with AI assistance
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Multi-Channel Support">
    Clarky seamlessly handles conversations across chat, voice, text, and email—all from a single platform. Your customers can reach you through their preferred channel, and you manage everything from one unified inbox.
  </Accordion>

  <Accordion title="Context">
    Teach your AI agent with your website, uploaded files, written documents and Q\&A. Each document can be used on chat, voice, text or email, and questions your agent could not answer are collected for you to fill in.
  </Accordion>

  <Accordion title="Built-in CRM">
    Track contacts and manage your sales pipeline with Clarky's integrated CRM. Automatically capture leads from conversations and move them through your sales process.
  </Accordion>

  <Accordion title="Human Takeover">
    When your AI agent needs help, you can seamlessly take over conversations. See when users are live in chat and jump in to provide personalized support.
  </Accordion>

  <Accordion title="Powerful Integrations">
    Connect Clarky to your existing tools including Shopify, GoHighLevel, Outlook, Gmail, Google Calendar, and more. Your AI agent becomes even more powerful with access to your business data.
  </Accordion>

  <Accordion title="Multilingual Support">
    Clarky understands and responds in multiple languages, enabling you to serve a global customer base effortlessly.
  </Accordion>
</AccordionGroup>

## How It Works

<Steps>
  <Step title="Sign Up">
    Create your account and set up your workspace in minutes.
  </Step>

  <Step title="Create Your Agent">
    Enter your website URL and let Clarky automatically learn about your business, or manually configure your agent's knowledge.
  </Step>

  <Step title="Deploy">
    Embed the chat widget on your website, set up phone numbers, or connect email—choose the channels that work for you.
  </Step>

  <Step title="Manage">
    Monitor conversations in your inbox, track leads in the CRM, and continuously improve your agent's knowledge.
  </Step>
</Steps>

## Getting Help

<CardGroup>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get up and running with Clarky in under 5 minutes
  </Card>

  <Card title="Contact Support" icon="headset" href="https://clarky.ai">
    Reach out to our support team for assistance
  </Card>
</CardGroup>

<Note>
  Clarky is designed to be intuitive and easy to use. If you ever need help, our support team is here to assist you.
</Note>


# Quickstart
Source: https://docs.clarky.ai/quickstart

Get started with Clarky in under 5 minutes

## Create Your Account

Getting started with Clarky is quick and easy. Follow these steps to create your first AI agent.

<Steps>
  <Step title="Sign Up">
    Visit [clarky.ai](https://clarky.ai) and click "Get Started" to begin the signup process.

    You can sign up using:

    * **Magic Link**: Enter your email and receive a one-time login link
    * **Google**: Sign in with your Google account

    <Note>
      No password required! Clarky uses secure authentication methods for easy access.
    </Note>
  </Step>

  <Step title="Complete Your Profile">
    After authenticating, you'll be asked to provide:

    * **Your Name**: This helps personalize your experience
    * **Workspace Name**: This is your organization's workspace (e.g., "Acme Inc")
  </Step>

  <Step title="Create Your First Agent">
    Once your workspace is created, you'll be taken to the agent creation page where you can:

    1. Enter your **website URL** - Clarky will automatically crawl and learn from your website
    2. Choose which **channels** to enable (Chat, Voice, Text, Email)
    3. Customize your agent's **name** and **greeting**

    <Tip>
      Start with just the chat channel to test things out. You can always enable more channels later!
    </Tip>
  </Step>

  <Step title="Deploy Your Agent">
    After creating your agent, you can immediately:

    * **Embed the chat widget** on your website using the provided code snippet
    * **Test your agent** using the built-in chat interface
    * **Set up phone numbers** for voice and text channels
    * **Connect email** accounts for email support
  </Step>
</Steps>

## Next Steps

Now that you have your agent up and running, explore these features:

<CardGroup>
  <Card title="Customize Your Agent" icon="sliders" href="/features/settings/agent">
    Adjust your agent's properties, integrations, and behavior
  </Card>

  <Card title="Add Context" icon="file-lines" href="/features/context/overview">
    Teach your agent with documents, files, your website and Q\&A
  </Card>

  <Card title="Monitor Conversations" icon="messages" href="/features/inbox/overview">
    View and manage customer conversations
  </Card>

  <Card title="Manage Contacts" icon="users" href="/features/crm/overview">
    Track leads and contacts in the built-in CRM
  </Card>
</CardGroup>

## Try the Demo

Want to experience Clarky before signing up? Try our demo:

<CardGroup>
  <Card title="Call Clarky" icon="phone">
    Call **(813) 851-3831** to speak with a live demo agent
  </Card>

  <Card title="Text Clarky" icon="comment-sms">
    Text **(813) 851-3831** to chat via SMS
  </Card>

  <Card title="Email Clarky" icon="envelope">
    Email **[hello@clarky.ai](mailto:hello@clarky.ai)** to test email responses
  </Card>

  <Card title="Chat with Clarky" icon="message">
    Visit [clarky.ai](https://clarky.ai) and open the chat widget
  </Card>
</CardGroup>

<Check>
  You're now ready to start using Clarky! Your AI agent is live and ready to handle customer conversations.
</Check>