# Multi-Factor Authentication (MFA)
Source: https://docs.apten.ai/account-security/multi-factor-authentication
Learn how to set up multi-factor authentication to secure your account, and how admins can enforce MFA across the organization.
## Overview
Multi-Factor Authentication (MFA) adds an extra layer of security to your account by requiring a second form of verification in addition to your password. This tutorial will guide you through setting up two-step verification using an authenticator app.
## Step 1: Sign In to Your Account
Sign in to your account using username and password like normal. Make sure you're signed in with the account you want to secure with MFA.
## Step 2: Navigate to Manage Account Page
1. Click on your profile icon in the bottom left corner
2. Select **Manage Account** from the menu
3. You'll be redirected to your account management dashboard
![Account Management Navigation]()
## Step 3: Setup Two-Step Verification
### Access Security Settings
1. In the account management page, click on the **Security** section
2. Click Add **two-step verification**
3. Follow the prompts to add authenticator app MFA
![Security Settings Page]()
### Save Recovery Codes
1. **Download Recovery Codes**: After successful setup, you'll be presented with backup recovery codes
2. **Store Safely**: Save these codes in a secure location (password manager, secure note, etc.)
3. **Important**: These codes can be used to access your account if you lose access to your authenticator app
Recovery codes are crucial for account recovery. Each code can only be used
once, so store them securely and don't share them with anyone.
## Managing Your MFA Settings
### Disabling MFA (Not Recommended)
1. Go to **Security Settings**
2. Find the **Two-Step Verification** section
3. Click **Remove**
4. Confirm your decision (you may need to enter a current MFA code)
Disabling MFA reduces your account security. Only disable if absolutely
necessary, and consider re-enabling it as soon as possible.
## Organization MFA Enforcement (Admins)
Organization admins can require all members to enable MFA. When enforcement is turned on, members without MFA will be blocked from using the app until they complete setup.
### Viewing Member MFA Status
1. Navigate to **Organization Settings > Members**
2. The **MFA** column shows whether each member has MFA enabled or disabled
### Enabling MFA Enforcement
You must have MFA enabled on your own account before you can require it for the organization. If you haven't set it up yet, follow the steps above first.
1. Navigate to **Organization Settings > Security**
2. Toggle **Require MFA** on
3. All members without MFA will immediately see a setup screen the next time they load the app
### What Members See When MFA Is Required
Members who haven't enabled MFA will see a full-screen setup flow that walks them through:
1. **Getting started** — explains they need an authenticator app
2. **Scanning a QR code** — or entering a secret key manually into their authenticator app
3. **Entering a verification code** — the 6-digit code from their authenticator app
4. **Saving backup codes** — one-time recovery codes in case they lose access to their authenticator
Once setup is complete, the blocking screen disappears and they can use the app normally.
### Disabling MFA Enforcement
1. Navigate to **Organization Settings > Security**
2. Toggle **Require MFA** off
3. Members will no longer be required to have MFA, though any existing MFA setup remains active on their accounts
Disabling enforcement does not remove MFA from member accounts — it only stops
requiring it. Members who have already set up MFA will keep it active.
## How MFA Works Once Setup
1. **Sign In**: Enter your username and password as usual
2. **Second Factor**: Provide a time-based code from your authenticator app
3. **Access Granted**: Successfully access your account with verified identity
# User Roles & Permissions
Source: https://docs.apten.ai/account-security/user-roles
Understand the different user roles and their access levels in Apten.
## Overview
Apten uses a role-based access control system to manage what users can see and do within your organization. There are three roles available:
* **Admin** - Full access to all features and settings
* **Analyst** - Access to data, reports, and analytics
* **Member** - Basic access to view conversations
## Role Permissions
| Feature | Admin | Analyst | Member |
| - | :-: | :-: | :-: |
| View Conversations | ✅ | ✅ | ✅ |
| Build & Automations | ✅ | ❌ | ❌ |
| Guardrails | ✅ | ❌ | ❌ |
| Tags Management | ✅ | ❌ | ❌ |
| Notifications | ✅ | ❌ | ❌ |
| Export Data | ✅ | ✅ | ❌ |
| Import Leads | ✅ | ✅ | ❌ |
| Manage Leads | ✅ | ✅ | ❌ |
| Reports | ✅ | ✅ | ❌ |
| Metrics | ✅ | ✅ | ❌ |
| Integrations | ✅ | ❌ | ❌ |
| Developer Portal | ✅ | ❌ | ❌ |
| Organization Settings | ✅ | ❌ | ❌ |
| Security Settings (MFA Enforcement) | ✅ | ❌ | ❌ |
| Manage Members | ✅ | ❌ | ❌ |
## Managing Members
Only Admins can manage organization members. To invite or manage users:
1. Navigate to **Organization Settings > Members**
2. Click **Invite Member** to add a new user
3. Enter their email address and select a role
4. Click **Send Invite**
To change a member's role:
1. Find the member in the Members list
2. Click on their current role
3. Select the new role from the dropdown
Changing a user's role takes effect immediately. The user may need to refresh
their browser to see their updated permissions.
## Best Practices
* **Use the principle of least privilege** - Assign users the minimum role needed for their job function
* **Limit Admin access** - Only give Admin access to users who need to manage automations and settings
* **Use Analyst for data teams** - The Analyst role is ideal for team members who need to review performance data and export reports without modifying AI behavior
* **Use Member for stakeholders** - The Member role works well for stakeholders who need visibility into conversations but shouldn't modify anything
# Get call
Source: https://docs.apten.ai/api-reference/calls/get-call
get /calls/{callId}
Fetch full details for a call by ID — transcript, AI summary, and transfer metadata.
## When to use this endpoint
Call webhooks include `data.callId` and basic metadata (direction, duration, transfer flags). `CALL` events from [`GET /leads/{leadId}/events`](/api-reference/leads/list-events) carry the same metadata, and the event's top-level `id` field is the call ID. Neither includes the full transcript or every transfer detail.
Use `GET /calls/{callId}` to enrich a call after a webhook fires — for example, to pull the AI-generated summary and full transcript into your CRM or data warehouse. After a transfer, `transferStatus` and `transferFailureCode` match the final outcome in [`call.completed`](/webhooks/call-completed) and the dedicated transfer webhooks.
For failed transfers, `transferInitiatedAt` records when Apten began the transfer attempt and `transferWaitDurationSeconds` records the elapsed time until Apten recorded the terminal failure. `midCallTransferDuration` is different: it measures time connected to a transfer recipient after a successful mid-call transfer.
## Recordings
This endpoint never returns a recording URL. To download a completed recording, use [`GET /calls/{callId}/recording`](/api-reference/calls/get-recording). The download URL is temporary; store the downloaded file, not the URL.
## Webchat calls
For webchat voice calls, the response includes `sessionId` instead of `leadId`.
# Get recording
Source: https://docs.apten.ai/api-reference/calls/get-recording
get /calls/{callId}/recording
Create a temporary download URL for a completed call recording.
## When to use this endpoint
Use the `callId` from a `call.completed` webhook or CALL event to download a completed call recording. This endpoint returns a temporary URL for one recording; it does not return a list of calls or recordings.
## Recording availability
Call completion and recording availability are separate. If the recording is still being prepared, the endpoint returns `409 Recording is not ready yet.` Retry only after a `409`, using backoff and an application-defined attempt or time limit. Stop retrying and handle every other response according to its documented status.
## Downloading recordings
The `url` expires after 15 minutes. Download the MP3 immediately and store the file in your own retention system. Do not save the URL; request a new one when it expires.
# Remove from DNC List
Source: https://docs.apten.ai/api-reference/dnc/delete-dnc
delete /dnc/{phone_number}
Removes a phone number from the DNC list
# Check DNC Status
Source: https://docs.apten.ai/api-reference/dnc/get-dnc
get /dnc/{phone_number}
Checks if a phone number is in the DNC list
# Add to DNC List
Source: https://docs.apten.ai/api-reference/dnc/register
post /dnc/register
Adds a phone number to the Do Not Contact (DNC) list to prevent it from being imported.
# Introduction
Source: https://docs.apten.ai/api-reference/introduction
An overview of the Apten API, including the base URL, authentication, and response codes.
## Base URL
Our API is built around a RESTful architecture. All requests are made to the base URL:
```
https://api.attent.app/v1
```
## Authentication
All API endpoints are authenticated using an API key in the header.
You may obtain an API key from the [Developer Portal](https://platform.attent.app/developer).
The API key is passed in the `x-api-key` header:
```json theme={null}
{
"x-api-key": "your-api-key"
}
```
## Response Codes
HTTP response codes are used to indicate the success or failure of an API request. The following response codes are used:
| Code | Description |
| - | - |
| `200` | Successful Request |
| `400` | Bad Request - check that input parameters are correctly formatted. |
| `403` | Forbidden - the supplied API key is missing or invalid. |
| `404` | Not Found - the requested resource does not exist. |
| `409` | Conflict - request is valid but conflicts with system state. |
| `429` | Too Many Requests - you have exceeded a quota or the rate limit. |
| `500` | Server Error - this indicates an error within Apten servers. |
# Add context to a lead
Source: https://docs.apten.ai/api-reference/leads/add-context
post /leads/{leadId}/addContext
Adds context or a timeline event to a lead. Use `event` for things that happened at a point in time (a status change, a completed step, an update from your system) — Apten places it in the conversation timeline so the AI knows when it occurred relative to the lead's messages and can react to it. Use `context` for standing facts and instructions that should always apply regardless of when they were added (preferences, rules, background). At least one of `context`, `event`, `additionalInfo`, or `command` is required; they can be combined in one call.
# Add tags
Source: https://docs.apten.ai/api-reference/leads/add-tags
post /leads/{leadId}/tags
Add tags to a lead (will not remove existing tags)
# Create a lead
Source: https://docs.apten.ai/api-reference/leads/create
post /leads/create
Creates a new lead
# Delete a lead
Source: https://docs.apten.ai/api-reference/leads/delete
delete /leads/{leadId}
Deletes a specific lead
# Get lead
Source: https://docs.apten.ai/api-reference/leads/get-lead
get /leads/{leadId}
Fetches details of a specific lead. Returns 404 if the lead has been deleted; use `GET /leads` to enumerate deleted leads (which surface with `deleted: true`) for incremental sync.
# Get messages
Source: https://docs.apten.ai/api-reference/leads/get-messages
get /leads/{leadId}/messages
Fetches messages sent to and received from a lead
# List leads
Source: https://docs.apten.ai/api-reference/leads/list
get /leads
Incrementally list leads. Requires `updatedSince` and/or `createdSince`. Soft-deleted leads are included (`deleted: true`); treat as removals. Use `lastActivityAt` to decide whether to fetch events.
# List events for a lead
Source: https://docs.apten.ai/api-reference/leads/list-events
get /leads/{leadId}/events
List interaction events for a lead — messages, calls, emails, tool calls, custom events, compliance blocks, and other types documented in this reference.
Apten may add new `type` values over time without a version bump or prior notice. Clients should treat unknown types as forward-compatible (skip or store opaquely) unless they filter with the `types` query parameter.
## Incremental sync
Pair this endpoint with [`GET /leads`](/api-reference/leads/list):
1. Poll `GET /leads?updatedSince=…` for leads whose profile or activity changed.
2. When `lastActivityAt` moves forward, call `GET /leads/{leadId}/events?since=…` for that lead.
3. Paginate with `nextToken` until it is `null`.
Events are ordered by `updatedAt` ascending. Use the largest `updatedAt` from the page as the next `since` cursor for that lead.
## Event types and forward compatibility
The `type` field identifies each event (`MESSAGE`, `CALL`, `EMAIL`, and others documented in the API reference). **Apten may add new event types at any time** as the product evolves. We do not treat new types as a breaking API change and do not guarantee advance notice before they appear in production responses.
Build integrations to be forward-compatible:
* **Prefer an explicit `types` filter** when you only need a fixed set of shapes for your pipeline.
* **Otherwise, tolerate unknown `type` values** — persist the raw event, skip it, or route it to a generic handler. Do not fail the entire sync or reject the payload because `type` is unrecognized.
* **Use `type` plus `id`** as the stable key; do not assume every event is a message, call, or email.
The OpenAPI schema lists event types Apten documents today; it is not an exhaustive guarantee of all types you may receive over time.
## Compliance blocks (`COMPLIANCE_BLOCKED`)
When [external compliance](/compliance/external-checks) is enabled and an outbound SMS, email, or voice attempt is **suppressed**, Apten writes a `COMPLIANCE_BLOCKED` room event. It appears on this endpoint like any other interaction event.
| Expectation | Detail |
| - | - |
| No outbound message/call/email row | A blocked send does **not** create a `MESSAGE`, `EMAIL`, or `CALL` for that attempt — only `COMPLIANCE_BLOCKED`. |
| Allowed checks are omitted | Pass results are stored in Apten's internal audit log only; they are **not** returned by this API. |
| Filter | `?types=COMPLIANCE_BLOCKED` (or include it in a comma-separated list). |
| PII | `data` includes channel, outreach type, reason, source, block type, and optional `triggeredBy` — not phone, email, or full provider payloads. |
Example event:
```json theme={null}
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"roomId": "room_abc",
"orgId": "org_123",
"type": "COMPLIANCE_BLOCKED",
"timestamp": "2026-05-20T05:50:12.000Z",
"updatedAt": "2026-05-20T05:50:12.000Z",
"data": {
"channel": "sms",
"outreachType": "follow_up",
"reason": "STATE_DNC",
"source": "http",
"blockType": "permanent",
"triggeredBy": "llm"
}
}
```
The event `id` is the stable identifier for the block (same UUID as the internal audit row). `data` does not repeat it — same pattern as `MESSAGE` / `CALL` / `EMAIL`.
`reason` is either an Apten system code (e.g. `COMPLIANCE_TARGET_MISSING`, `DNC`) or a string returned by your compliance HTTP API when `allowed` is `false`. `source` indicates which check leg blocked (`http`, `apten-dnc`, `configuration`, `provider-error`, etc.). `blockType` is `permanent` when later follow-ups on this channel will be skipped, or `temporary` when only this send was blocked and the next send will be checked again (see [Permanent and temporary blocks](/compliance/external-checks#permanent-and-temporary-blocks)). It may be absent on older events.
Treat `COMPLIANCE_BLOCKED` in your warehouse as **suppressed outreach** — not a delivery failure on an existing message.
## Call events and enrichment
`CALL` events include direction, status, duration, and transfer flags — but **not** the transcript or AI summary. Webhook payloads that include `callId` behave the same way (except `call.completed`, which may include a short `summary`).
To fetch the full transcript and call metadata, call [`GET /calls/{callId}`](/api-reference/calls/get-call) using the event's top-level `id` (for CALL events) or `data.callId` (for webhook payloads). To download a completed recording, call [`GET /calls/{callId}/recording`](/api-reference/calls/get-recording) and store the downloaded file rather than its temporary URL.
# Look up lead by phone
Source: https://docs.apten.ai/api-reference/leads/lookup
get /leads/lookup
Looks up a lead by phone number
## Usage Notes
Use `phone` to look up a lead by their phone number. If exactly one active lead matches that phone number, the response returns the lead ID.
When the same lead phone number is associated with multiple outbound phone numbers, include `outboundPhone` to identify which lead to return. The outbound phone number must be one of the phone numbers configured for your organization.
# Remove tags
Source: https://docs.apten.ai/api-reference/leads/remove-tags
post /leads/{leadId}/tags/remove
Remove specific tags from a lead
# Replace tags
Source: https://docs.apten.ai/api-reference/leads/replace-tags
put /leads/{leadId}/tags
Replace all tags on a lead
# Resubscribe a lead
Source: https://docs.apten.ai/api-reference/leads/resubscribe
post /leads/{leadId}/resubscribe
Resubscribes a lead to one or more channels (SMS, voice, email) they previously unsubscribed from. Also clears the lead's do-not-contact status, and removes the phone number from the Do Not Contact (DNC) list when SMS is resubscribed. Does not change whether Apten is on for the lead.
### Notes
Resubscribes a lead to one or more channels they previously unsubscribed from. Pass a `channels` array (`sms`, `voice`, `email`) in the request body to target specific channels. When `channels` is omitted, Apten resubscribes every channel the lead can actually receive: SMS and voice if the lead has a phone number, email if the lead has an email address.
The `200` response `channels` array is the set that was applied, not the set that was requested. A lead with a phone number and no email who sends `{}` is resubscribed on SMS and voice, and the response is `["sms", "voice"]`.
When SMS consent cannot be completed, requests that include other available channels still succeed for those channels. The response is `200`, `channels` lists only the channels successfully resubscribed, and `failedChannels` lists the channels that could not be resubscribed, including whether the failure is retryable. For an SMS-only request, the API returns `502` or `503`. SMS remains unsubscribed, and no SMS opt-in event or phone-number DNC removal is applied.
If every requested channel is missing on the lead, the request fails with a `400`. An explicit `{"channels":["email"]}` on a lead with no email returns `Lead has no email`. An explicit request that includes at least one reachable channel still succeeds for those channels.
**Side effects:**
* Clears the lead's do-not-contact status, if set.
* Removes the lead's phone number from your Do Not Contact (DNC) list when SMS is resubscribed.
* Emits an [opt-in webhook event](/webhooks/opt-in) for each channel that transitions from unsubscribed to subscribed.
This API does not change whether Apten is on for the lead. If you previously turned the lead off, also call [Turn on a lead](/api-reference/leads/turn-on) to resume messaging.
# Send message to a lead
Source: https://docs.apten.ai/api-reference/leads/send-message
post /leads/{leadId}/sendMessage
Sends a message to a lead
# Switch lead's customer profile
Source: https://docs.apten.ai/api-reference/leads/switch-customer-profile
post /leads/{leadId}/switchCustomerProfile
Switches the customer profile of a lead. Any pending scheduled follow-up for the lead (automated follow-up steps, dynamic AI-scheduled follow-ups, etc.) is always canceled as part of the switch. Manually scheduled messages (created via "Schedule Message" in the dashboard) are preserved. If `sendMessage` is `true`, a new follow-up message for the new profile is scheduled in its place (see `sendMessage` below); if `sendMessage` is `false` (the default), no replacement follow-up is scheduled — the lead simply has no pending follow-up until the new profile's own follow-up config or your own logic schedules one.
# Turn off a lead
Source: https://docs.apten.ai/api-reference/leads/turn-off
post /leads/{leadId}/turnOff
Turns Apten off for a lead
# Turn on a lead
Source: https://docs.apten.ai/api-reference/leads/turn-on
post /leads/{leadId}/turnOn
Turns Apten on for a lead
# Unsubscribe a lead
Source: https://docs.apten.ai/api-reference/leads/unsubscribe
post /leads/{leadId}/unsubscribe
Unsubscribes a lead from one or more channels (SMS, voice, email). Does not change whether Apten is on for the lead or add the lead's phone number to the Do Not Contact (DNC) list.
### Notes
Unsubscribes a lead from one or more channels. Pass a `channels` array (`sms`, `voice`, `email`) in the request body to target specific channels. When `channels` is omitted, Apten unsubscribes every channel the lead can actually receive: SMS and voice if the lead has a phone number, email if the lead has an email address.
The `200` response `channels` array is the set that was applied, not the set that was requested. A lead with a phone number and no email who sends `{}` is unsubscribed from SMS and voice, and the response is `["sms", "voice"]`.
SMS and voice opt-outs may be coupled according to your organization's settings. When those channels are coupled, requesting either one unsubscribes both.
If every requested channel is missing on the lead, the request fails with a `400`. An explicit `{"channels":["email"]}` on a lead with no email returns `Lead has no email`. An explicit request that includes at least one reachable channel still succeeds for those channels.
Repeated requests converge on the same subscription state. Channels that are already unsubscribed remain unchanged, and no duplicate opt-out webhook is emitted for those channels.
**Choose the right control:**
* **Pause the AI:** Use [Turn off a lead](/api-reference/leads/turn-off). This pauses Apten for the lead but does not change their subscription status.
* **Opt out of contact:** Use this endpoint. It changes the lead's subscription status for the selected channels.
* **Never contact this number:** Use the [Do Not Contact API](/api-reference/dnc/register). This adds the phone number to your organization's DNC list.
**Side effects:**
* Emits an [opt-out webhook event](/webhooks/opt-out) for each channel that transitions to unsubscribed.
* Does not change whether Apten is on for the lead.
* Does not add the lead's phone number to the DNC list.
To undo an SMS opt-out, the lead can text `START`, or you can use [Resubscribe a lead](/api-reference/leads/resubscribe) for the applicable channels.
# Update lead
Source: https://docs.apten.ai/api-reference/leads/update
patch /leads/{leadId}
Updates properties of a specific lead
## Usage Notes
### Updating additionalInfo
The `additionalInfo` field uses merge/upsert behavior:
* New keys are added to the existing additionalInfo
* Existing keys are updated with new values
* To **delete** a key, set its value to `null`
```json theme={null}
{
"additionalInfo": {
"newKey": "newValue", // Adds new key
"existingKey": "updated", // Updates existing key
"oldKey": null // Removes this key
}
}
```
### Follow-up Configuration
The `followUpConfig` defines the follow-up schedule. Each step must include `channel` and a delay — use `delayValue` with `delayUnit` (preferred), or legacy `hours`.
```json theme={null}
{
"useStrategiesForFollowUps": true,
"followUpConfig": {
"1": { "delayValue": 24, "delayUnit": "hours", "channel": "text", "strategyIds": "auto" },
"2": { "delayValue": 30, "delayUnit": "minutes", "channel": "email" },
"3": { "delayValue": 168, "delayUnit": "hours", "channel": "call", "voicemailEnabled": true, "strategyIds": ["550e8400-e29b-41d4-a716-446655440000"] }
}
}
```
**Properties:**
* `delayValue` (number) - positive integer value. Minutes must be between 1 and 60 inclusive. Amount of time to wait before this follow-up step runs. Use with delayUnit.
* `delayUnit` (string) — preferred delay format. either "hours" or "minutes".
* `hours` (number) - see note below.
* `channel` — the outreach channel for this step
Each follow-up step must use either `delayValue` and `delayUnit` (preferred), or hours — not both.
**Legacy `hours` field:**
Still supported, but deprecated in favor of `delayValue` + `delayUnit`. Must be greater than 0.
```json theme={null}
{
"followUpConfig": {
"1": { "hours": 24, "channel": "text" }
}
}
```
**Allowed channels:** `text`, `call`, `email`
**Optional properties:**
* `voicemailEnabled` (boolean): Only valid for `call` channel. If true, leaves a voicemail when call is not answered.
* `strategyIds` (string or string array): Strategy IDs to use for this follow-up step. Use `"auto"` for automatic selection, or provide an array of specific strategy IDs. Requires `useStrategiesForFollowUps` to be set to `true` on the lead.
Channel requirements: - **text**: Always available (SMS) - **call**: Requires
voice to be enabled on the customer profile - **email**: Requires email to be
enabled on both the customer profile and organization
To stop all follow-ups for a lead, set `followUpConfig` to an empty object `{}
`. This will cancel any scheduled follow-ups and set the lead to STOPPED state.
### Follow-up Scheduling Behavior
When updating `followUpStep` and/or `followUpConfig`, the timer always resets to **now + the step's configured delay**:
1. **Update followUpStep only**: Schedules that specific step
2. **Update followUpConfig only**: Reschedules with new timing, preserving the current step
3. **Update both**: Full reset with the new config starting at the specified step
#### Special followUpStep Values
* **Positive integers (1, 2, 3, ...)**: Schedule that specific follow-up step
* **-1 (STOPPED)**: Stops all follow-ups for this lead
* **-2 (LONG\_TERM)**: Moves lead to long-term nurture mode
# Get tags
Source: https://docs.apten.ai/api-reference/tags/get-tags
get /tags
Retrieve all custom tags defined for the organization
# Get usage
Source: https://docs.apten.ai/api-reference/usage/get-usage
get /usage
Retrieve the current usage limit status for the organization. Today the only tracked usage dimension is the per-organization lead limit; additional dimensions may be added in the future under sibling keys.
# Actions
Source: https://docs.apten.ai/automations/actions
Everything an automation step can do — create and update leads, send messages, and read or update CRM records.
## Overview
Actions are the steps that do the work in an automation. They come in two groups in the **Add step** dialog:
* **Apten Actions** — operate on leads in Apten.
* **CRM Actions** — look up a record in your connected CRM and expose its fields to later steps, or write field updates back to a record.
### The find-then-act pattern
Most Apten actions need an **Apten lead ID** to know which lead to operate on. The standard pattern is to start with a **Find Lead** step, then reference its output in later steps: type **/** in the **Apten lead ID** field and pick the Find Lead step's **Apten lead ID** output. A **Create Lead** step works the same way — later steps can reference the ID of the lead it just created.
## Apten Actions
### Find Lead
Looks up an existing Apten lead by CRM record ID, Apten lead ID, or phone number. Provide at least one; if you set multiple, they're tried in order — **Apten lead ID → CRM record ID → Phone** — and the first match wins, which makes a useful fallback chain.
Outputs include whether a lead was found, the Apten lead ID, name, phone, email, customer profile, and status flags such as whether the lead has replied, is marked hot, or has unsubscribed. Pair it with a [Filter step](/automations/control-steps) on the **Lead found?** output to stop runs for unknown leads.
### Create Lead
Creates a new lead in Apten and starts outreach. Required fields: **First name**, **Phone**, and **Customer profile**. Optional fields include **Last name**, **Email**, and **Link to CRM record** — set the link so the new lead syncs back to the CRM record that triggered the run (typically `{{trigger.Id}}`).
Under **Advanced** you can also set:
* **Time zone** — an IANA identifier like `America/New_York`. If your CRM doesn't store time zones in this format, add a [Resolve Timezone](#resolve-timezone) step first and reference its **Timezone** output here.
* **Scheduled import time** — defer Apten's first outbound message until a future timestamp (up to 365 days out)
* **Outbound phone** — override the phone number Apten texts from
* **Custom fields** — extra key-value data stored on the lead
The keys `integrationSource`, `salesforceId`, and `dynamicsId` are reserved — use the **Link to CRM record** field instead.
Creating a lead follows the same rules as every other import path: numbers on your Do Not Contact list are rejected, duplicates by phone number are rejected, and your organization's lead quota applies.
### Turn Off Lead
Pauses outreach for a lead — Apten stops sending messages until the lead is [turned back on](#turn-on-lead). Takes an **Apten lead ID** (not a CRM record ID).
### Turn On Lead
Re-enables outreach for a lead that was previously turned off — Apten resumes sending messages. Takes an **Apten lead ID** (not a CRM record ID).
### Send Message
Sends a text message to a lead. Fields:
* **Apten lead ID** — the lead to message.
* **Message** — the message body. Besides **/** references to trigger and step data, you can template lead variables with double braces, e.g. `{{firstName}}`. Variables with no value render as `[MISSING VALUE]` in the sent message, so make sure the fields you reference are set.
![Send Message step]()
Under **Advanced**:
* **Scheduled time** — send at a future time instead of immediately
* **Send when lead is off** — deliver even if the lead is currently turned off
* **Schedule follow-ups** — have the AI continue following up after this message
* **Override business hours** — send outside the lead's business hours; otherwise delivery waits for the next window
Messages from automations go through the same compliance checks as all Apten outreach — unsubscribed leads and Do Not Contact numbers are never messaged.
### Switch Profile
Moves a lead to a different **Customer profile**. Under **Advanced** you can **Clear memory** (start the conversation fresh) and **Send a message after switch**, optionally with a **Delay before message** in hours or minutes.
Switching profiles always cancels any pending scheduled follow-up for the lead (manually scheduled messages are preserved). **Send a message after switch** is off by default — if you leave it off, no new follow-up is scheduled, so the lead has **no pending outreach** until some other event re-triggers follow-up logic (e.g. the lead replies, or a later step/automation schedules a message). The new profile's follow-up cadence does not start automatically just from the switch. Turn on **Send a message after switch** if you want the new profile to reach out on a delay after the switch.
### Add Context
Appends information to a lead for the AI to use. Provide at least one of:
* **Context** — free-text background, e.g. notes from the CRM record
* **Command** — an instruction for the AI, e.g. "Schedule a follow-up for tomorrow at 9am."
* **Custom fields** — key-value data stored on the lead
### Add Tags
Adds one or more of your organization's tags to a lead. Pick the tags from the **Tags** dropdown — every tag defined in your organization is available, including tags marked as manual-only (that setting only controls what the AI can apply on its own).
Adding a tag the lead already has is a no-op. If you've configured tag syncing for your CRM, tags added here sync to the linked CRM record the same way as tags applied anywhere else in Apten.
### Remove Tags
Removes one or more of your organization's tags from a lead. Removing a tag the lead doesn't have is a no-op. Works with tag syncing the same way as [Add Tags](#add-tags).
### Register DNC
Adds a phone number to your organization's Do Not Contact list, blocking all future outreach to it across every lead. A common pattern is to reference the **Phone** output of a Find Lead step.
Registering a number on the DNC list blocks outreach to that number but does not turn the lead off. Pair **Register DNC** with a **Turn Off Lead** step to do both.
### Resolve Timezone
Converts location data you already have into a time zone Apten can use — so leads are contacted at the right local hours even when your CRM doesn't store time zones. Provide at least one input; if you set multiple, they're tried in order — **Timezone value → Zip code → Phone → State** — and the first match wins. A value the step doesn't recognize isn't an error; it just falls through to the next input.
* **Timezone value** — a field that already holds time zone information, in any common format: an IANA identifier (`America/New_York`), a Dynamics **Time Zone** field (the numeric codes those fields store bind directly), or a Salesforce/Microsoft time zone label like `(GMT-08:00) Pacific Standard Time (America/Los_Angeles)` or `(UTC-08:00) Pacific Time (US & Canada)`.
* **Zip code** — US zip codes, five-digit or ZIP+4. Leading zeros stripped by numeric CRM fields or spreadsheets are repaired automatically (`2108` is read as `02108`).
* **Phone** — US and Canada numbers; the time zone is inferred from the area code. Toll-free numbers carry no location, so they're skipped.
* **State** — a US state, territory, or Canadian province, as a full name or abbreviation in any casing (`California`, `CA`, `ca`). States spanning two time zones use the zone where most of the state's population lives.
Outputs are **Timezone resolved?** and **Timezone**. The typical shape is Resolve Timezone followed by Create Lead, with the new lead's **Time zone** field referencing the **Timezone** output.
If none of the inputs resolve, later steps still run: a Create Lead step referencing the **Timezone** output simply creates the lead without a time zone, and outreach follows your organization's default hours. A miss never blocks lead creation.
Abbreviations like `EST` and bare GMT/UTC offsets are deliberately not recognized — they're ambiguous or unreliable across daylight saving — and fall through to the next input instead.
## CRM Actions
The CRM is fixed when you add the step (each connected CRM appears as its own entry in the **Add step** dialog, e.g. **Find Salesforce Record** or **Update Dynamics Record**). To target a different CRM, delete the step and add the other variant.
### Find CRM Record
Looks up a single record of any object in your connected CRM — for example, the Account behind the Contact that triggered the run, or a lead's next appointment — and exposes its fields to later steps.
* **Object** — the CRM object to search.
* **Search by field** / **Search value** — the record is looked up where this field equals the value; typically an ID or lookup field referencing the trigger record, e.g. `{{trigger.AccountId}}`.
* **Conditions (optional)** — extra conditions the record must meet on top of the search match. Supports [condition groups](/automations/control-steps#condition-groups) for mixed AND/OR logic.
* **If multiple match, pick the record with…** — a tie-breaker: choose a field and **lowest** or **highest** (for example, lowest start date = the soonest upcoming appointment).
The step's outputs are the found record's fields, plus a **Record found?** flag you can filter or branch on.
### Update CRM Record
Writes field updates to an existing record in your connected CRM. The classic use is writing back to the record that triggered the run — for example, stamping the new lead's **Apten lead ID** onto the CRM record after a Create Lead step.
* **Object** — the CRM object the record belongs to.
* **Record ID** — the record to update; typically the trigger record's ID, e.g. `{{trigger.Id}}`.
* **Field updates** — up to 20 field/value rows. The value input matches the field's type: text, number, Yes/No, a picklist of the field's options, or a date picker. Text and number values can reference trigger and step data with **/**.
All the fields in a step are written together in a single update — either the whole update succeeds or none of it is applied. If a referenced output has no value (for example, a Resolve Timezone step that didn't find a time zone), that field is **skipped** rather than written — an empty reference never clears a CRM field. Skipped fields are listed in the run's step details.
#### Relative date values
Date and date/time fields offer two value modes:
* **Specific date** — a fixed date or time.
* **Relative to now** — the moment the step runs, plus or minus an offset: **current date**, *5 hours from now*, *3 days ago*. Use an offset of 0 to stamp the current date or time — for example, an "Entered Apten" date field set to **current date**.
Unlike [relative dates in conditions](/automations/control-steps#relative-dates), which are calculated from when the trigger fired, these values are calculated when the step runs — after a [Delay](/automations/control-steps#delay), a **current date** value stamps the date the update actually happens.
Read-only fields and lookup/reference fields can't be updated and don't appear in the field picker. If the record ID doesn't match an existing record, the step fails — use [Find CRM Record](#find-crm-record) with a Filter on **Record found?** first if the record might not exist.
# Building an Automation
Source: https://docs.apten.ai/automations/building
Create an automation on the visual builder, publish it, and turn it on.
## Overview
Automations are built on a visual canvas: a **Trigger** card at the top, connected to a vertical chain of step cards. You add steps with the **+** buttons on the canvas and configure whichever card is selected in the panel on the right. Edits autosave to a draft; nothing goes live until you click **Publish**.
![Automation builder]()
## Step 1: Create the Automation
1. Go to **Automations** in the sidebar
2. Click **Create Automation**
3. Give it a name — the title field at the top of the page. A name is required to publish.
New automations start as a **Draft**: they exist only for you and never run until published and turned on.
## Step 2: Configure the Trigger
Select the **Trigger** card and choose your **Trigger source** (CRM), **Object**, and **Trigger type** in the right-hand panel. See [Triggers](/automations/triggers) for the full breakdown of trigger types and conditions.
## Step 3: Add Steps
Click the **+** button below the last card (or on a connector between cards, to insert a step in the middle). The **Add step** dialog offers three groups:
* **Apten Actions** — act on leads in Apten: Find Lead, Create Lead, Turn Off Lead, Turn On Lead, Send Message, Switch Profile, Add Context, Add Tags, Remove Tags, Register DNC, Resolve Timezone. See [Actions](/automations/actions).
* **CRM Actions** — look up a record in a connected CRM (for example **Find Salesforce Record**) and expose its fields to later steps, or write field updates back to a record (**Update Salesforce Record**).
* **Control** — **Filter** (stop the run unless conditions match), **Delay** (pause before continuing), and **Branch** (split into multiple paths). See [Control Steps](/automations/control-steps).
![Add step dialog]()
Steps run in order, top to bottom, and each step starts only after the previous one succeeds. To remove a step, hover over its card and click the trash icon.
An automation can have up to **10 top-level steps**, up to **10 steps inside each branch**, and up to **75 steps in total**. Branches can be nested up to **3 levels deep**. Control steps count like any other: a Branch step takes one of the 10 slots in the chain that contains it, and Filter, Delay, and Branch steps count toward the 75-step total.
## Step 4: Reference Data From the Trigger and Earlier Steps
Most step fields accept dynamic references. Type **/** in a field to open a picker of available values:
* **Trigger fields** — data from the CRM record that fired the automation, inserted as `{{trigger.FieldName}}`
* **Step outputs** — results from earlier steps, inserted as `{{steps..output.FieldName}}`
For example, a **Find Lead** step outputs the lead's Apten ID; a **Send Message** step placed after it can use that output as its **Apten lead ID**. This *find, then act* pattern is the backbone of most automations — see [Actions](/automations/actions).
Every step has a **Step ID** shown in its configuration panel — click it to copy, then paste it into a reference by hand if you prefer.
## Step 5: Publish
Click **Publish**. Apten validates the whole automation first — if anything is missing or invalid, a banner lists each issue and the offending cards are outlined in red. Fix the issues and publish again.
While editing a published automation:
* Your changes autosave to a draft; the live version keeps running unchanged, and an **Unpublished changes** pill appears next to the status badge.
* **Publish** replaces the live version with your draft.
* **Discard draft** throws away your edits and keeps the live version as-is.
Runs that are already in progress use the version of the automation they started with, so publishing changes doesn't alter them. Turning off or deleting an automation does not stop other in-flight runs, but if the automation is off or deleted when a Delay ends, that waiting run halts instead of continuing.
## Step 6: Turn It On
Published automations have an **On/Off** toggle at the top of the page. Turn the toggle **On** to start watching your CRM.
Some triggers show an **Activating…** status for a short time while Apten prepares — see [Triggers](/automations/triggers#turning-an-automation-on) for what happens during activation.
## Deleting and Restoring
Deleting an automation stops it immediately and moves it to the **Recently deleted** tab, where it can be restored for **30 days**. Restoring recreates the automation as a draft for you to review and publish — it never comes back turned on automatically.
Run history for a deleted automation is preserved for **90 days** on the [Runs](/automations/runs) page.
# Control Steps
Source: https://docs.apten.ai/automations/control-steps
Steps that shape the flow of a run — stop it with a Filter, pause it with a Delay, or split it into paths with a Branch.
## Overview
**Control** steps shape the flow of a run instead of performing work:
* **Filter** — stop the run unless conditions match.
* **Delay** — pause the run for a set amount of time before continuing.
* **Branch** — split the automation into multiple paths, each with its own rules and steps.
Filter and Branch use the same condition editor described [below](#the-condition-editor).
## Filter
A Filter step checks its conditions when the run reaches it. If they match, the run continues to the next step; if not, the run stops there with the status **Halted**.
Filters can reference anything available at that point in the run — trigger fields and the outputs of earlier steps. A common pattern is a **Find Lead** step followed by a Filter on its **Lead found?** output, so the rest of the automation only runs for leads that exist in Apten.
**Halted is not an error.** It means a Filter (or Branch) decided the run shouldn't continue — exactly what you built it to do. Halted runs are listed on the [Runs](/automations/runs) page so you can confirm your filters behave as expected.
## Delay
A Delay step pauses a run for a set amount of time, then continues to the next step. Enter a positive whole number and choose **Minutes**, **Hours**, or **Days**. Each Delay can last from **1 minute to 30 days**.
You can place a Delay anywhere in an automation, including inside a branch. An automation can include up to **30 days of delays in total**. Apten adds the duration of every Delay in the automation, including Delays in separate branches, because every matching branch runs in order.
A common pattern is to wait before acting on a CRM record: add a Delay, use **Find CRM Record** to fetch the record's latest values, add a Filter to confirm it still matches, and then perform the action.
While paused, the run has the status **Waiting** and shows when it will resume. If the automation is off or deleted when the Delay ends, the run halts instead of continuing. See [Runs & Troubleshooting](/automations/runs) for details.
Relative-date conditions after a Delay are still calculated from when the run's trigger fired, not from when the Delay ends. ([Relative date values](/automations/actions#relative-date-values) in an Update CRM Record step are the exception — those are calculated when the step runs.)
## Branch
A Branch step splits the automation into **2 to 5 branches**. Each branch has its own **Branch rules** (conditions) and its own chain of steps.
![Branch step]()
How branches are evaluated when a run arrives:
* **Every branch whose rules match runs**, one after another, in the order the branches are defined. Branches are not mutually exclusive — if a record matches two branches, both run.
* One branch can be marked as the **Fallback branch**. It has no rules and runs only when no other branch matched.
* If no branch matches and there is no fallback, the run stops with status **Halted**.
* If a step inside one branch fails, the other matching branches still run, but the run's overall status is **Failed**.
A few structural rules:
* A Branch is always the **last step of its chain** — branches don't merge back together, and each branch runs to its own end.
* Branches can contain their own Branch steps, **nested up to 3 levels deep**. Each chain (the top level, or a branch) contains at most one Branch step, always at its end.
* Each branch can hold up to **10 steps**, and the Branch step itself counts as one — a chain that ends in a Branch has room for 9 other steps.
Need "if A do X, otherwise do Y"? Use two branches: one with your rules, plus a **Fallback branch** for everything else.
## The Condition Editor
Conditions appear throughout Automations — trigger **Conditions**, the **Watched field filter**, **Filter conditions**, **Branch rules**, and the optional conditions on **Find CRM Record** — and they all work the same way.
Each condition is a row of three parts:
1. **Field** — searchable dropdown of available fields
2. **Operator** — `=`, `≠`, `contains`, `>`, `<`, `in`, `not in`, `is set`, `is not set` (the list adapts to the field's type)
3. **Value** — a typed input matching the field: text, number, Yes/No, a picklist of the field's options, or a date picker. `in` / `not in` accept multiple values.
With more than one condition, choose how they combine — **AND** (every condition must match) or **OR** (at least one must match). The chosen AND/OR is shown between the rows so the logic reads inline.
### Condition groups
To mix AND and OR logic, add a **group**. A group is a set of conditions with its own AND/OR operator, evaluated as a single condition in the outer list. For example, *Status = Qualified AND (Source = Web OR Source = Referral)* is the outer list combined with **AND**, containing a group combined with **OR**.
* Click **Add group** in the condition editor to create one; add conditions to the group with its own **Add condition** button.
* A group needs at least one condition, and groups can't contain other groups — one level of grouping keeps the logic easy to read.
* Groups work on every condition surface: trigger Conditions, Filter conditions, Branch rules, and Find CRM Record conditions. (The Watched field filter stays a single condition.)
Logic like "(A and B) or (C and D)" is the same idea inverted: combine the outer list with **OR** and add two groups, each combined with **AND**.
### Relative dates
On **Filter**, **Branch**, and **Find CRM Record** conditions, date fields offer two value modes:
* **Specific date** — a fixed date or time
* **Relative to trigger** — an offset from when the run fired, e.g. *3 days after trigger* or *2 hours before trigger*. Use `>` and `<` with relative dates, e.g. `AppointmentDate < 2 days after trigger` to mean "within the next 2 days."
Trigger conditions don't support relative dates — they use fixed values only.
Date fields in an **Update CRM Record** step offer relative values too, anchored to when the step runs rather than the trigger — see [Relative date values](/automations/actions#relative-date-values).
# Automations Overview
Source: https://docs.apten.ai/automations/overview
Build CRM-triggered workflows that create leads, send messages, and manage outreach in Apten automatically.
## Overview
Automations connect your CRM to Apten. When something happens in your CRM — a record is created, or a field changes — an automation can respond automatically: create a lead in Apten, send a message, switch a lead's customer profile, pause outreach, and more.
Common use cases include:
* A new lead lands in Salesforce → create the lead in Apten and start outreach
* An opportunity's stage changes to **Closed Lost** → switch the lead to a re-engagement profile
* A contact is marked do-not-call in your CRM → add the number to your Do Not Contact list and turn the lead off
* An appointment is booked → send the lead a confirmation text with details pulled from the CRM record
Every automation has two parts:
1. **A Trigger** — the CRM event that starts a run. Apten polls your connected CRM on a schedule you control and fires the automation for each matching record. See [Triggers](/automations/triggers).
2. **Steps** — an ordered list of things to do, built visually on a canvas. Steps can act in Apten ([Actions](/automations/actions)), look up records in your CRM, or control the flow with [Control steps](/automations/control-steps).
![Automations list]()
## Key Concepts
| Concept | What it means |
| - | - |
| **Automation** | One trigger plus an ordered list of steps. |
| **Trigger** | The CRM event that starts a run — a new record, or a change to a watched field. |
| **Step** | A single unit of work. Steps come in three kinds: **Apten Actions** (act on leads in Apten), **CRM Actions** (look up a record in your CRM), and **Control** steps (**Filter**, **Delay**, and **Branch**). |
| **Run** | One execution of an automation for one triggering record. Every run is logged on the **Runs** page with per-step detail. |
| **Draft** | Your working copy. Edits autosave to a draft and have no effect until you click **Publish**. |
| **Published** | The live version of the automation — the one that actually runs. |
| **On / Off** | Whether the published automation is actively watching your CRM. Toggle it from the automation's page. |
## Prerequisites
* **Admin access.** Only organization admins can see and manage Automations. Other roles do not see the page.
* **A connected CRM.** Triggers and CRM actions require a connected **Salesforce**, **Salesforce Sandbox**, or **Microsoft Dynamics** integration. Connect one on the **Integrations** page first — see [Salesforce](/integrations/salesforce) or [Microsoft Dynamics](/integrations/dynamics).
Disconnecting a CRM on the Integrations page turns off every automation that depends on that connection. You'll need to re-link and re-enable them after reconnecting.
## Navigating Automations
Open **Automations** in the sidebar. The page has three tabs:
* **Automations** — every automation in your organization, with its status (**Draft**, **Off**, **Activating…**, or **On**), last-modified time, and last run. Click **Create Automation** to start a new one.
* **Runs** — the execution history across all automations, filterable by automation, status, and time range. See [Runs & Troubleshooting](/automations/runs).
* **Recently deleted** — deleted automations stay restorable here for 30 days.
## Learn More
Create, publish, and manage an automation end to end.
New record and Field updated triggers, conditions, and polling.
Everything an automation can do in Apten and in your CRM.
Add conditions, pause a run, or split an automation into multiple paths.
Inspect run history and resolve failed steps.
# Runs & Troubleshooting
Source: https://docs.apten.ai/automations/runs
Inspect automation run history, understand run statuses, and resolve failed steps.
## Overview
Every time a trigger fires, Apten records a **run** — one execution of one automation for one CRM record. The **Runs** tab shows activity across every automation in your organization, with per-step detail for each run.
Run history is retained for **90 days**, including for deleted automations.
![Runs page]()
## The Runs Page
Open **Automations → Runs**, or use **View Runs** in an automation's **⋯** menu to jump there pre-filtered to that automation.
Filters:
* **Automation** — one, several, or all automations
* **Status** — by default **Completed**, **Failed**, and **Halted** are shown; add **Running**, **Waiting**, and **Pending** to see in-flight runs
* **Time** — **Last 24h**, **Last 7d** (default), **Last 30d**, or a custom date range
Each row shows the automation, start time, status, duration, and the trigger — the CRM object and record that fired, including the field change for Field updated triggers (for example `Status: Open → Qualified`).
### Run statuses
| Status | Meaning |
| - | - |
| **Completed** | Every step that should have run succeeded. |
| **Failed** | At least one step failed. Other steps or branches may still have completed — open the run to see exactly where it stopped. |
| **Halted** | A [Filter or Branch](/automations/control-steps) stopped the run because conditions didn't match, or an automation was off or deleted when a Delay ended. This is expected behavior, not an error. |
| **Running** | The run is in progress. |
| **Waiting** | The run is paused at a Delay step. The run row and details show when it will resume. |
| **Pending** | The run is queued and will start shortly. |
## Run Details
Click any run to open the **Run details** panel:
* **Trigger context** — the CRM record data that fired the run.
* **Steps** — each step with its status and duration. Expand a step to see its **Resolved params** (the exact inputs after template references were filled in) and **Output**, or the error if it failed.
* **Delay timing** — the active Delay shows **Waiting until** with its resume time. After it resumes, the step shows **Waited until**. If the automation was off or deleted when the Delay ended, the step explains why the run halted.
* **Branch outcomes** — for runs with a Branch step, each branch shows how it ended: **Completed**, **Failed**, **Stopped by filter**, **Waiting**, **Skipped — rules not met**, or **Fallback — not needed**.
* **Conditions** — Filter steps and branches show the conditions they evaluated (as configured when the run started, groups included), so you can see exactly why a run halted or a branch was skipped.
* **View Run Config** — the full configuration of the automation *as it was when this run started*. Useful when you've edited the automation since.
![Run details]()
## Troubleshooting Failed Steps
When a step fails, the run details show a plain-language error. The most common ones:
| Error | What it means | What to do |
| - | - | - |
| The step's parameters didn't validate. | A required field is missing or malformed after template resolution. | Check the step's **Resolved params** to see what was actually submitted. |
| A template reference couldn't be resolved. | A `{{trigger.…}}` or `{{steps.…}}` reference points to a field that doesn't exist or wasn't produced. | Verify the referenced step ran and that the field name matches its outputs. |
| The lead this step tried to reach couldn't be found. | The **Apten lead ID** didn't match a lead. | Make sure the ID comes from a **Find Lead** / **Create Lead** output, and add a Filter on **Lead found?** before acting. |
| A lead with these details already exists. | **Create Lead** matched an existing lead by phone number. | Use **Find Lead** first, and only create when **Lead found?** is No. |
| The phone number is on the Do Not Contact list. | Outreach to this number is blocked. | Expected behavior — DNC numbers are never contacted. |
| The lead has unsubscribed. | The lead opted out of this channel. | Expected behavior — unsubscribed leads are never messaged. |
| Apten can't send messages to landlines. | The phone number is a landline. | Expected behavior for non-textable numbers. |
| Your account has hit its lead-creation quota. | Your organization reached its monthly lead limit. | Contact your Apten representative to adjust your plan. |
When a trigger matches a very large number of records at once — for example a CRM mass update touching thousands of rows — runs are queued and processed in batches. A large burst can take a while to drain; watch progress on the Runs page with the **Running** and **Pending** statuses enabled.
# Triggers
Source: https://docs.apten.ai/automations/triggers
Start automations when a record is created or a field changes in your CRM.
## Overview
A trigger defines the CRM event that starts an automation. Apten checks your CRM on a regular polling interval and starts one run for each record that matches your trigger since the last check.
Triggers are available for **Salesforce**, **Salesforce Sandbox**, and **Microsoft Dynamics**. Only CRMs connected on the **Integrations** page can be selected.
![Trigger configuration]()
## Configuring a Trigger
Select the **Trigger** card in the builder and fill in:
* **Trigger source** — the CRM to watch.
* **Object** — the CRM object to watch (for example Lead, Contact, or Opportunity — custom objects are supported).
* **Trigger type** — **New record** or **Field updated**.
### New record
Fires once for each record of the chosen object created **after the automation is turned on**. Existing records never fire it — there is no backfill, so this trigger type activates instantly and works on objects of any size.
### Field updated
Fires when a specific field — the **Watched field** — changes value on any matching record. Two properties make it precise:
* **It fires only on real changes.** Apten tracks the watched field's value per record, so a record being saved without the field changing does not fire the trigger.
* **Repeat transitions fire again.** If a Lead's status moves `Qualified → Lost → Qualified`, the second arrival at `Qualified` fires the trigger a second time.
For Field updated triggers you can also add a **Watched field filter** — a single predicate on the watched field itself. The automation then fires only on transitions where the new value matches the filter (for example, `Status equals Qualified` fires only when the field *becomes* Qualified).
## Trigger Conditions
**Conditions** narrow which records can fire the trigger at all, on any field of the object — for example `LeadSource equals Web` or `State in [CA, NY]`. When you add more than one condition, choose how they combine — **AND** (every condition must match) or **OR** (at least one must match). To mix AND and OR — like `LeadSource equals Web AND (State equals CA OR State equals NY)` — add a [condition group](/automations/control-steps#condition-groups).
Trigger conditions are applied inside the CRM query itself, so records outside your conditions are never even polled.
Trigger conditions use fixed values only. Relative date comparisons ("within 7 days of the trigger") are available on [Filter and Branch steps](/automations/control-steps), not on the trigger.
## Poll Interval
By default Apten checks your CRM every **5 minutes**. You can adjust this per automation from the **⋯** menu → **Adjust Poll Interval**, anywhere from **1 to 60 minutes**.
Automations fire on the next poll after a change, not at the instant the change happens in your CRM. With the default interval, expect up to a few minutes between a CRM change and the run appearing on the Runs page.
## Turning an Automation On
What happens when you flip the toggle to **On** depends on the trigger type:
* **New record** triggers activate instantly.
* **Field updated** triggers show **Activating…** while Apten takes an initial snapshot of the watched field across every record matching your conditions. This is what makes exact change detection possible. Activation usually takes seconds to a few minutes depending on how many records match.
### Record limits for Field updated triggers
Because activation snapshots every matching record, Field updated triggers have a size limit on the matching record set:
| CRM | Maximum matching records |
| - | - |
| Salesforce / Salesforce Sandbox | **750,000** |
| Microsoft Dynamics | **1,500,000** |
If your object exceeds the limit, activation fails and the automation returns to **Off**. Two ways to resolve it:
1. **Narrow the trigger conditions** so fewer records match — the limit applies to the records matching your conditions, not the whole object.
2. **Use a New record trigger instead** if you only care about records created going forward — New record triggers have no size limit.
# July 25, 2025
Source: https://docs.apten.ai/changelog/2025-07-25/2025-07-25
## New Features
### Unanswered Questions Section (Optimizations)
* Added new optimization component for analyzing customer flow and improving profiles
* Tracks frequently asked unanswered questions with frequency counts
* UI displays questions with dropdown for different instances
* Helps identify gaps in customer profile knowledge base
![Unanswered Questions Section]()
### Switch Profile Tool
* Implemented ability to switch between customer profiles dynamically
* Added default "Switch Profile" tool, which can be added to any profile
### SharePoint Knowledge Base Sync
* Added SharePoint integration for syncing knowledge base articles
* Supports automatic synchronization of documents (daily sync)
* Configurable through integrations section
### Salesforce Article Sync Enhancement
* Extended Salesforce article sync integration with sandbox support
* Added custom field mapping capabilities
## Improvements
* **Model Reliability / Uptime**: Added more model fallbacks
* **Voice Custom Tools**: Added placeholder speech for custom tool calls in voice conversations
* **Objective Prompt**: Improved performance of objective prompt in message nodes
## Bug Fixes
* **Chat UI Updates**: Fixed issue where chat messages weren't updating live
* **Follow-up Repetition**: Resolved issue with repetitive/similar follow-ups
* **Profile Draft Deployment**: UI update to prevent deployment of unsaved profile drafts
* Improved handling for after-call scenarios where users text back
## API Updates
* **Delete Lead API**: Added soft delete functionality while preserving analytics data
# August 1, 2025
Source: https://docs.apten.ai/changelog/2025-08-01
## New Features
### MFA Support
* Added multi-factor authentication support for enhanced security
* Includes documentation for MFA setup and configuration
### Email Prompt Highlighting
* Added email-specific highlighting to prompt textarea
* Updated text filters to handle email-only tags and content
* Enhanced visual differentiation for email communications
### Voice Call Customization
* Added ability to customize voice call greeting prompts
* Implemented placeholder speech for custom tool calls in voice conversations
## Improvements
* **Follow-up Messages**: Improved reliability of using names in follow-up messages
* **Metrics Enhancement**: Added inbound/outbound message breakdown to metrics
* **Conversation Sorting**: Sort conversations by created/imported date
* **Profile Saving**: Show "saving changes" text when saving new profile draft
## Bug Fixes
* **Graph Deployment**: Fixed issue where graph sometimes disappears during deployment
* **Import Follow-up Config**: Fixed filtering for landline numbers and email
* **Follow-up Message Parsing**: Resolved parsing issues with follow-up messages
* **External Twilio**: Fixed external Twilio account connection display
* **Business Hours Dropdown**: Fixed layout issue in Build Customer Profile page
# August 8, 2025
Source: https://docs.apten.ai/changelog/2025-08-08/2025-08-08
## New Features
### Customer Profile Enhancements
* **Follow-up Disable Option**: Allow customer profiles to have follow-ups disabled entirely
![Follow-up Disable Option UI]()
### Email Attachments
* Added support for email attachments
* Can download files from links and attach to emails
* Can set which Knowledge Base data sources can be sent as email attachments out-of-the-box
![Email Attachments UI]()
### Multi-Factor Authentication
* Added multi-factor authentication support for enhanced security
## Improvements
* **Voice Calls**: Improved performance for high-volume outbound calls
* **Scheduling Tool**: Enhanced scheduling custom tool to allow adding dynamic inputs
* **Email Prompt Highlighting**: Added email-specific highlighting to prompt textarea
* **Channel Highlighting UI**: Improved UI with better dropdown ordering and updated messaging logos
## Bug Fixes
* **UI Newlines**: Fixed issue where newlines weren't saved in profile editor
* **Follow-up Message Formatting**: Improved reliability of follow-up message formatting
# August 15, 2025
Source: https://docs.apten.ai/changelog/2025-08-15/2025-08-15
## New Features
### Lead Limit Notifications
* Added ability to route lead limit notifications to customer Slack channels (contact to enable)
* Provides real-time alerts when lead limits are approaching or exceeded
### International Support
* **International Phone Numbers**: Added support for importing international phone numbers (contact us to enable)
* **International Timezones**: Full support for international timezones across the platform
### New Organization Setting
* **Follow-up Day Selection**: Set specific days of the week for follow-up sequences (in Settings)
![Follow-up Day Selection UI]()
## Improvements
### Voice Call Enhancements
* **Call Direction in Prompt**: Added call direction (inbound/outbound) context to voice agents
* **Reject Calls When Off**: Automatically reject calls when Apten is turned off
### Playground Enhancements
* Added mock delayed transfer tool for playground testing
## Bug Fixes
* Fixed bug caused when switchCustomerProfile API is called during an ongoing AI reply
* Added user existence validation to prevent duplicate org membership
# August 22, 2025
Source: https://docs.apten.ai/changelog/2025-08-22
## New Features
* **Bulk Operations via CSV**: Added support for bulk API operations including switch profile, add context, and turn off lead actions
* **Send Email from Voice**: Added ability for Apten voice AI to send emails to leads directly from the call
* **Async Variable Extraction**: Variables can now be marked as async if not needed on calls, reducing real-time latency
* **Call Recording Downloads**: Users can now download call recordings from the platform
## Improvements
### UI/UX Enhancements
* **No-Reply Indicator**: Added visual feedback when the playground agent decides not to reply
### Voice Call Improvements
* **Call Guardrails**: Added business hours rules for outbound calling
* **Do-Not-Call Instructions**: Voice agents now include opt-out handling in system prompts
* **Call Tag Logic**: Updated to only tag calls when user actually picks up (not voicemail)
### Email Processing
* **Thread History Trimming**: Improved email thread trimming to support Spark email client
### API Enhancements
* **Channel Support in Webhooks**: Added channel information to opt-out, message sent/received, and notification webhooks
## Bug Fixes
* Fixed email receiving issue
* Fixed Switch Customer Profile API to properly delete scheduled follow-ups even when sendMessage is false
# August 29, 2025
Source: https://docs.apten.ai/changelog/2025-08-29
## New Features
* **Email Signature Improvements**: Added support for images/logos and HTML in email signatures for more customizable branding
* **Lead ID in Data Exports**: Added Lead ID as the first column in data exports for easier tracking and reference
## Improvements
### API Enhancements
* **Improved Error Messages**: Create Lead API now returns more descriptive and helpful error messages for invalid inputs
### Voice Call Improvements
* **Enhanced Voicemail Capture**: Improved voicemail message extraction to capture complete messages reliably
# September 5, 2025
Source: https://docs.apten.ai/changelog/2025-09-05
## New Features
* **Voice ID Per Profile**: Added ability to customize the AI voice for individual customer profiles
## Improvements
### Performance Enhancements
* **Start of Call Latency Reduction**: Reduced the time it takes for Apten to speak when connected to a call by \~1.7 seconds. This sounds much more natural when picking up calls.
* **Follow-up Timing Precision**: Follow-ups within the same day are now scheduled more precisely - they will trigger within 30 minutes to the scheduled time, to support more aggressive follow-up sequences
### UI/UX Improvements
* **Build & Test UI Redesign**: Complete redesign of the customer profile builder interface for improved usability and workflow
* **Email Signature Improvements**: Added support for images/logos and HTML in email signatures for more customizable branding
## Bug Fixes
* **Conversation UI Crash Fix**: Resolved critical issue where current node view was causing application crashes
* **New Build UI Fixes**: Fixed various UI bugs in the newly refactored build interface
# September 12, 2025
Source: https://docs.apten.ai/changelog/2025-09-12
## New Features
* **Dynamic Call Transfers**: Added ability to dynamically transfer calls to different numbers based on custom logic and conditions during conversations
## Improvements
### Voice Bot Enhancements
* **Angry Customer Handling**: Added empathy rules to voice bot prompt for better handling of upset customers
* **End Call Interruptibility**: Made end call messages interruptible for better user experience
### Performance & Reliability
* **Knowledge Base Search Placeholder Speech**: Fixed issue where voice bot was repeating search placeholder speech when searching knowledge base
* **Voice Text Tool Timing**: Fixed timing issue where text messages were sent before voicemail detection completed
### UI/UX Improvements
* **Contact Rate Metric**: New cross-channel contact rate metric with breakdown by channel (SMS, email, voice) in the overview dashboard
* **Default Business Hours**: New profiles now default to 9-5 ET business hours for convenience
* **Lead Export Enhancement**: Added Lead ID column as the first column in data exports for easier tracking
## Bug Fixes
* **Double Voicemail Bug**: Resolved issue where voicemails were sometimes sent twice
* **Voicemail Transfer Fix**: Fixed bug where voicemails were being transferred to human agents. Improved voicemail inbox handling.
# September 19, 2025
Source: https://docs.apten.ai/changelog/2025-09-19
## New Features
* **Multiple Webhook Endpoints**: Support for routing webhooks to multiple endpoints (e.g., Zapier and custom backend integrations)
* **Inbound Email Attachments**: Made email attachments downloadable in UI and added webhook indicators for attachment presence
## Improvements
### Voice Bot Enhancements
* **Better Interruption Handling**: Improved voice bot sensitivity to interruptions to prevent false interruptions
* **Faster First Message on Voice**: Voice bot now speaks almost immediately after the call is connected
* **Idle Timeout Configuration**: Made voice bot idle detection timeout configurable per customer profile
* **Improved Summaries**: Enhanced call and conversation summary quality and relevance
* **SMS Tool Reliability**: Voice bots are now better and more accurate at sending text messages mid-call
* **Lead Classification**: Improved "Is Hot" tag logic for better lead qualification and scoring
### UI/UX Improvements
* **Call Duration Filter**: Added ability to filter metrics by call duration (greater than/less than)
* **AI Voice Transfer Indicator**: Added visual indicator for mid-call transfers to human agents
* **Signup Error Screen**: Fixed error screen that shows up during the sign-up process
## Bug Fixes
* **Email for Voice Bots**: Fixed issues where voice bot would incorrectly attempt to send emails
* **Link Request Opt-out**: Fixed "no" to link send incorrectly triggering opt-out status
* **SMS Number Usage**: Use SMS number (not local number) for SMS-initiated outbound calls
* **Node ID Copy Button**: Fixed page refresh when clicking copy button in customer profile
# October 2025
Source: https://docs.apten.ai/changelog/2025-10
## Webchat (Beta)
* **Webchat Widget Launch**: Apten now ships an embeddable web chat widget so the same AI agent that handles SMS, email, and voice can engage visitors directly on your website. Includes session persistence, contact form capture, and full conversation history in the dashboard.
* **Webchat → Voice / SMS Transfers**: Webchat sessions can hand off to a voice call or text-message conversation when the lead opts in.
* **Webchat Guardrails & Rate Limiting**: Per-organization rate limiting and full guardrail support so the same safety rules used in SMS/voice apply to webchat.
* **Webchat Metrics**: Webchat conversations, transfers, and calls now appear in the metrics dashboard with source filters.
* **Session UI**: New screens for browsing, filtering, and tagging webchat sessions, with deep links from rooms to the originating session.
## New Features
* **RCS (Rich Communication Services) Support**: Send-and-receive support for RCS messages on supported carriers, with status indicators in the conversation UI and an RCS filter in the conversation list.
* **Phone Number per Profile Routing**: Assign a specific phone number to a customer profile so outbound and inbound calls can be routed to the right brand or product line.
* **Tag Management APIs**: New public API endpoints to add, remove, and replace tags on a lead programmatically.
* **AND/OR Tag Filtering**: The conversation list and exports now support nested AND/OR logic when filtering by multiple tags.
* **Per-Step Voicemail Toggle**: Enable or disable voicemail drop on a per-step basis within a phone follow-up sequence.
* **Configurable Long-Term Follow-Up**: The long-term follow-up cadence can now be configured per organization instead of using the platform default.
* **Email on Lead Exports & Conversation Header**: Lead email is included in CSV exports and shown in the conversation header for quick reference.
## Improvements
### Voice Bot Enhancements
* **Smarter Voice Model**: Voice and chat agents now run on a newer underlying language model with lower latency and improved reasoning.
* **Voicemail-Aware Mid-Call Transfers**: When a transferred call hits a voicemail or answering machine, Apten now detects it and falls back gracefully instead of leaving a partial transfer.
* **Faster Turn-Taking on Calls**: Tuned speech-to-text timing for snappier back-and-forth on voice calls.
* **Multilingual Voice Bots**: New speech-recognition pipeline with improved support for multilingual voice agents.
### Metrics & Reporting
* **Time Filters on Metrics**: Filter every metric on the dashboard by custom time ranges.
* **Leads Imported Over Time**: New chart showing lead import volume over time.
* **Unsubscribe & Qualified Metric Fixes**: Corrected unsubscribe-rate and qualified-lead calculations and added clarifying tooltips.
### UI/UX Improvements
* **Form Validation Before Deploy / Test**: The customer profile builder validates required fields before allowing Deploy or Test actions.
* **Rich-Text Editor Resize Fix**: Resolved a regression that broke the rich-text editor's resize behavior in the profile builder.
* **Conditional Transfer Number Validation**: Transfer number is no longer required when both voice and SMS transfer are disabled.
## Bug Fixes
* Fixed inbound call routing for certain carrier configurations.
* Fixed custom-tool parameter parsing for tools defined on the starting node of a profile.
* Fixed idle-timeout handling on long voice calls.
* Fixed voicemail completion ending a call prematurely when voicemail is disabled.
# November 2025
Source: https://docs.apten.ai/changelog/2025-11
## New Features
* **Warm Transfer over Voice**: Apten now supports warm-transfer mid-call hand-offs on the voice channel, briefing the human agent on the conversation before bridging the lead through.
* **Bulk Send-Message via CSV**: Send a personalized first message to many leads at once by uploading a CSV. The bulk endpoint also supports variables.
* **Common Objections Analytics**: A new optimization view clusters customer replies into common objections so you can see what leads push back on most often, and refine your prompts in response.
* **Backup Transfer Number**: Configure a fallback transfer number that Apten will dial if the primary agent leg goes to voicemail or doesn't pick up.
* **Profile-Level SMS Transfer**: SMS transfer is now configured per customer profile (previously a single org-wide flag) so different brands or teams can route to different agents.
* **Update Lead API**: New API endpoint for updating arbitrary lead properties without re-importing.
* **Email Forwarding for Attachments**: Inbound emails with attachments can now be forwarded to a configured destination address (useful for routing into ticketing or CRM systems).
* **Configurable Short-Transfer Threshold**: Define how short a transferred call has to be before Apten treats it as a non-connection and re-engages the lead.
* **One-Click Unsubscribe in Outbound Emails**: Outbound emails now include the headers required for native one-click unsubscribe in the recipient's inbox. This brings outbound email into compliance with bulk-sender requirements from major email providers and helps protect deliverability.
* **2026 SMS Holiday Calendar**: Holidays are automatically applied to outbound SMS scheduling so messages don't go out on major US holidays.
## Improvements
### Voice Bot Enhancements
* **Faster Guardrail Decisions**: Critical guardrail and reply-decision steps are now sub-second with automatic fallback for higher reliability.
* **Business Hours in Voice Agent**: The voice agent is now aware of your configured business hours so it answers scheduling questions correctly mid-call.
* **Smarter Voicemail Detection**: New voicemail detection on outbound AI calls for higher accuracy across carriers.
* **Phone Number Validation**: Invalid phone numbers and unsupported regions are caught and surfaced as clear errors instead of silent failures.
* **Cold Transfer Greeting**: Leads now hear a customizable greeting on the SMS-initiated cold-transfer path.
### Conversations & Automations
* **Follow-Up Reply Tracking**: Each follow-up step (SMS, email, call) now tracks whether it produced a reply, powering richer analytics.
* **Email Bounce Handling**: Bounce-back emails no longer raise errors and are filtered out of the conversation thread.
* **Inbound Email 100-Message Limit**: Long inbound email threads are now safely capped to prevent runaway processing.
* **Stay-on-Node Behavior**: When a node has no children, the agent stays on that node instead of transitioning to an end-state, supporting open-ended branches.
### UI/UX Improvements
* **Webhook Secrets in Settings**: Webhook URLs and signing secrets are now displayed (with copy buttons) in the developer settings table.
* **Email Unsubscribe Field in Integrations**: New CRM-integration setting to map an unsubscribe field, with redesigned integration settings layout.
* **Customer Profile List Pagination**: The customer-profile list now paginates correctly for large workspaces.
* **Phone Number Type Badges**: Improved visual badges and explanatory copy for phone-number types in settings.
## Bug Fixes
* Fixed double-texting on inbound SMS in some edge cases.
* Fixed dynamic transfer prompt for delayed-transfer scenarios.
* Fixed unanswered-question form failing to load custom knowledge.
* Fixed CSV upload errors not being surfaced clearly to the user.
* Fixed current date/time not being available to playground sessions.
# December 2025
Source: https://docs.apten.ai/changelog/2025-12
## New Features
* **Email-Based Weekly Reports**: Schedule weekly performance reports delivered via email, with configurable recipient lists and week-over-week comparison.
* **Follow-Up Patterns Analytics**: A new optimization view automatically clusters follow-up message themes, surfaces sample messages, and highlights which themes are correlated with replies. Includes an analysis report with takeaways and recommendations.
* **Configurable Voice Speed per Profile**: Adjust how fast the AI voice speaks at the customer-profile level, with a live preview.
* **Transfer Rate Metric**: Track the rate at which conversations end up successfully transferring to a human agent, broken down by channel.
* **Conversation Attachment Filter**: New filter and visual indicator on the conversation list for rooms that contain attachments (e.g., images, PDFs sent via SMS or email).
* **Set Long-Term Follow-Up Action**: New conversation dropdown action to immediately move a lead into long-term follow-up cadence.
* **Outbound Phone Number on Lead Creation**: Specify the outbound phone number when creating a lead via the API, overriding the profile default for that lead.
* **Disable Text-After-No-Answer**: New per-profile setting to skip the automatic SMS that goes out after a missed call.
* **Bring Your Own Telephony Account**: Customers with their own carrier sub-accounts can now connect them to Apten without rebuilding routing infrastructure.
* **New Scheduled-Call Strategy**: Added a follow-up call strategy that schedules at a delayed time (rather than immediately) for better connection rates.
## Improvements
### Voice Bot Enhancements
* **Bot-Ready-Before-Dial**: Calls now wait for the voice bot to be fully initialized before dialing, eliminating cold-start dead air at the top of calls.
* **Voicemail Mid-Greeting Recovery**: When voicemail is detected mid-greeting, the bot now interrupts itself cleanly and switches to voicemail handling.
* **Voicemail Handling Without Carrier Detection**: Even when carrier-side answering-machine detection is disabled, the bot now ends the call cleanly when voicemail is detected.
### Conversations & Automations
* **AI Calls Without Human Response**: Calls where Apten speaks but the lead never responds are now classified separately, with a visual indicator in the conversation view and a dedicated metric.
* **Last-Activity Timestamp**: Conversations now track a last-activity timestamp, exposed in exports and the data table for easier triage.
* **Reply-Attribution Backfill**: Historical follow-up data has been backfilled with correct reply attribution and excludes opt-out messages.
* **Future-Scheduled Lead Guard**: Added a check to prevent message sends to leads scheduled for a future date.
### UI/UX Improvements
* **Reports Page**: New top-level Reports page for viewing, configuring, and scheduling automated reports.
* **CSV File-Size Validation**: Frontend now validates CSV size before upload so large files are caught with a clear error.
* **View Room from Sample Messages**: Sample messages in the Follow-Ups analytics tab now have a "View Room" button that opens the source conversation in a new tab.
* **Replied Indicator on Sample Messages**: Visual indicator on sample messages showing whether they got a reply.
* **Tool Name Validation**: Custom-tool names and parameter names are now validated against AI agent tool naming requirements before save.
## Bug Fixes
* Fixed bug where voicemails were occasionally transferred to the human agent.
* Fixed primary-phone-number query in cases where multiple numbers are assigned to a lead.
* Fixed inline-attachment filtering so quoted attachments aren't reprocessed in email replies.
* Fixed AI-call-without-human-response classification in metrics and exports.
# January 2026
Source: https://docs.apten.ai/changelog/2026-01
## New Features
* **Follow-Up Strategies**: Apten can now choose between multiple follow-up message strategies for each lead, automatically preferring strategies that haven't been used yet on that lead and avoiding using the same strategy twice in a row. Strategies can be configured at the profile level, overridden per room, and are honored on manually scheduled follow-ups.
* **Strategy Performance Insights**: The Follow-Ups analytics view now shows a per-strategy breakdown of reply rate so you can see which messaging variants land best.
* **Auto-Generated Strategy Proposals**: For profiles without strategies, Apten now generates strategy proposals that you can review and accept in one click to bootstrap a strategy library.
* **Slack Lead-Limit Buttons**: Lead-limit Slack notifications now include interactive buttons to bump a customer's daily lead cap directly from Slack — no dashboard trip required.
* **Reports Page (GA)**: The Reports page is now generally available with view, configure, and email-distribution controls. Weekly reports include transfer-rate and week-over-week comparison.
* **Backup Transfer Number (Voicemail Fallback)**: When the agent leg of a transfer hits voicemail, Apten now dials the configured backup transfer number instead of dropping the lead.
* **Cross-Channel Opt-Out**: When a lead explicitly asks to be removed from all channels, opt-out is applied across SMS, voice, and email instead of only the originating channel.
* **Set-Long-Term-Follow-Up Action**: New action — available both from the conversation dropdown and via API — to move a lead immediately into long-term follow-up cadence.
* **Refer-A-Friend Field Sync**: Added support for refer-a-friend referrer fields in CRM sync.
## Improvements
### Voice Bot Enhancements
* **Warm-Transfer Hold-Music & Wait Messages**: Leads on hold during a warm transfer now hear a "Thank you for waiting, we are still trying to connect you to an agent" message, with retry-on-no-keypress fallback to the configured backup transfer number.
* **Smarter Voicemail Detection (Default)**: The new voicemail detection system rolled out as the default for outbound AI calls.
* **Voice Transfer Reliability**: Multiple fixes for transfer timing, agent-missed-transfer handling, voicemail-disabled scenarios, and accuracy of who-ended-the-call attribution on connected transfers.
### Conversations & Automations
* **Idempotent New-Lead Scheduler**: Prevents duplicate follow-up scheduling when a lead is created twice in quick succession.
* **Follow-Up Hours / Days-of-Week Enforcement**: Scheduled messages now respect both follow-up hours and days-of-week before sending.
* **Manual-Follow-Up Strategy Support**: Manually scheduled follow-ups now run through the same strategy-selection logic as automated ones.
* **CSV Import — Landline Tolerance**: When voice is enabled on a profile, landline numbers are now allowed in CSV imports.
* **Transfer-Failed Event in History**: Failed transfers now leave a clear transfer-failed entry in the conversation history so you can see exactly what happened.
### UI/UX Improvements
* **Per-Room Strategy Selection**: Edit Schedule dialog now lets you pick which strategies are eligible for a specific lead's follow-ups.
* **Read-Only Mode Polish**: Business-hours expand buttons and copy-ID buttons now work correctly in read-only views.
* **Layout & Spacing Cleanup**: Multiple fixes to settings/build page scrolling, dashboard banner spacing, double-scrollbar issues, and Edit Schedule dialog layout.
* **Announcement Banner**: New in-app announcement banner system for highlighting major releases.
* **Removed Members Visible**: Organization page no longer shows users who have been removed from your org.
## Bug Fixes
* Fixed strategy-toggle handling on CSV imports.
* Fixed scrolling regressions on the Settings and Build pages.
* Fixed the "no strategy" default incorrectly showing as "Auto" in the profile editor.
* Fixed inbound messages occasionally being processed twice in quick-burst scenarios.
# February 2026
Source: https://docs.apten.ai/changelog/2026-02
## New Features
* **Microsoft Dynamics 365 Integration**: Native two-way sync with Dynamics 365 — leads, tags, conversation history, and unsubscribe state. Includes a guided setup wizard in the dashboard.
* **MFA Visibility & Enforcement**: Organization admins can now see which members have multi-factor authentication enabled and require MFA across the org.
* **Optimization Reports with Profile Context**: The optimization view (objections + follow-up patterns) now includes a profile-name header, simpler observation copy, rejection-reason capture for proposals, and a streamlined review flow.
* **Agent-Missed-Transfer Webhook**: New webhook event fires when a warm transfer is initiated but the human agent misses the call, so you can trigger your own retry/notification logic.
* **Server-Side Announcements**: In-app announcements are now stored server-side with per-org dismissal so all team members see new feature highlights consistently.
* **Common-Objections Refinement**: Optimization view now batches and refines common objection clusters with better topic labels for more actionable insights.
## Improvements
### Voice Bot Enhancements
* **Faster Reply Decisions**: The reply-or-not and stop-contacting decisions are now sub-second with a high-availability fallback for more responsive conversations at scale.
* **Live-Line Detection on Voicemail**: New detection identifies when a "voicemail" is actually a live person picking up mid-greeting and switches the bot back to live-call mode automatically.
* **Call Screening Pass-Through**: Voicemail detector now correctly routes carrier call-screening prompts (e.g., Verizon Call Filter) through to the bot rather than treating them as voicemail.
* **Voicemail Transfer Block**: The agent will no longer attempt to transfer a voicemail to a human.
* **Faster Tool-Call Pipeline**: Internal optimizations remove duplicate work and parallelize webhook execution to keep the conversation loop snappy.
### Conversations & Automations
* **Funnel-Optimization Action History**: Optimization analysis agent now uses past actions as context, leading to better proposals over time.
* **Contextual Opt-Out Detection**: Stop-contacting decisions now consider full conversation context rather than just the latest message.
* **Holiday Pause for SMS Transfers**: SMS transfers are paused on US holidays automatically.
* **Tag Event Metrics**: Tag-event metrics now correctly filter by the requested tags and support larger time-bucket sizes.
### UI/UX Improvements
* **Dynamics 365 Mock UI**: Preview the Dynamics 365 setup flow before connecting your tenant.
* **Mid-Call Transfer Attribution**: Conversation UI now shows the correct who-ended-the-call attribution for calls that end via mid-call transfer.
* **Voice Call Screening Indicator**: Visual indicator in the call list and call detail when call screening was hit.
* **Scheduling Tool Filter in Build**: Scheduling and availability tools are filtered out of the per-node tool selector to prevent them from being added to the wrong agent.
* **Edit Schedule – Voicemail Checkbox**: Added a per-step voicemail checkbox to the Edit Schedule dialog for call follow-up steps.
## Bug Fixes
* Fixed an infinite-loop bug in call status retry logic.
* Fixed a race condition that dropped call-attempted events for voicemail calls.
* Fixed knowledge-base context cleanup occasionally removing in-progress tool calls from the agent.
* Fixed current date/time not being available to voice agent prompts in some flowchart configurations.
# March 2026
Source: https://docs.apten.ai/changelog/2026-03
## New Features
* **Warm Transfer Bot**: When Apten warm-transfers a call to a human, an AI bot now greets the agent on the line, summarizes the conversation, and answers their questions (e.g., "what's the lead's email?") before bridging the lead through. The bot uses the same voice and prompt configuration as the main bot for a seamless hand-off.
* **Channel-Separated Opt-Outs (SMS / Voice / Email)**: Opt-outs are now tracked per channel with optional channel coupling, so a lead who unsubscribes from SMS can still receive emails (or vice versa) when configured. New voice-channel opt-out metrics, events table, and exports on the Metrics page.
* **Rejected Call Status**: Calls rejected at the carrier (e.g., spam-blocked, wrong number) now create a "rejected" call record with full visibility in the conversation UI and exports — previously they disappeared silently.
* **Webchat Opt-In Consent**: The webchat contact form now supports a customizable opt-in disclosure message so visitors explicitly consent before continuing the conversation.
* **Placeholder Speech for Webhook Nodes**: When a webhook node is hit during a voice call, you can configure custom placeholder speech (e.g., "Let me check on that for you...") that plays while the webhook resolves.
* **Standalone Enum / Multi-Select Variables in Message Nodes**: Message nodes now support standalone enum and multi-select variable types for more controlled branching logic.
* **Cadenced Knowledge-Base Refresh**: Web-scrape knowledge base connectors now support a configurable refresh cadence so external pages stay in sync.
* **Editable Scheduling-Tool Descriptions**: Custom scheduling and availability tools now expose an editable description so you can tune how the agent invokes them.
* **2026 / 2027 Holiday Presets**: Holiday presets updated for 2026 and 2027 (including observed-workday handling for Boxing Day).
* **Background Sound Toggle on Webhook Nodes**: New per-node toggle to enable or disable subtle background sound during webhook latency.
* **Profile-Level Inbound Call Routing**: Inbound calls now use the customer profile's follow-up config rather than a global default.
## Improvements
### Voice Bot Enhancements
* **Warm-Transfer Bot Voice Matching**: The warm-transfer bot uses the same voice as the main agent by default for a consistent agent experience.
* **Default Warm Transfer ON**: New profiles default to having the warm-transfer bot enabled.
* **Off-Topic Recovery**: Voice agent now nudges leads back to the call objective when conversations drift off-topic.
* **Improved Voicemail Detection on Outbound Calls**: Outbound calls now rely entirely on the new voicemail detection system for higher cross-carrier accuracy.
* **Conditional Routing Wait**: Webhook-driven conditional routing now waits for variable extraction to complete before evaluating conditions.
### Conversations & Automations
* **Voice Capacity Headroom**: Auto-scaling improvements on the voice infrastructure to better absorb traffic spikes.
* **Duplicate-Lead Webchat Conversion**: When a webchat session converts and matches an existing lead, Apten now handles the duplicate gracefully instead of erroring.
* **Tag Sync to HubSpot**: New and renamed tags now sync to HubSpot automatically.
### UI/UX Improvements
* **Opt-Out Badges in Conversation List**: Opt-out badges replace the on/off status in the conversation list for clearer at-a-glance visibility.
* **Voice Description Truncation**: Long voice descriptions in the customer-profile editor no longer push the "Select Voice" button off-screen.
* **Strategy "Auto" State**: Profile editor now shows the actual strategy state instead of always defaulting to "Auto," with backfill on toggle.
* **Pagination for Org Members**: Organization members list now paginates correctly for large workspaces.
* **Schedule-Strategy Empty State**: Edit Schedule dialog now shows "No strategy assigned" instead of "Auto (all strategies)" when no strategies are configured.
* **Profile Flow Editor Polish**: Multiple bug fixes in the new profile flow editor for button states, scheduling-tool clearing, and node validation.
## Bug Fixes
* Fixed strategies not copying when duplicating a customer profile.
* Fixed reliability issues in the optimization analytics pipeline that could fail on very large message volumes.
* Improved reply-decision behavior to better handle leads who explicitly decline interest.
* Fixed Salesforce lead imports failing when only an email (no phone) is provided.
# April 2026
Source: https://docs.apten.ai/changelog/2026-04
## New Features
* **Webhooks for Webchat**: All webchat-specific events — session started, message sent/received, contact form submitted, session converted, guardrail triggered, and call transferred — are now available as webhooks. Routes through the same multi-endpoint webhook configuration as lead webhooks.
* **Webchat Human Messaging Takeover**: A teammate can take over a webchat session in real time, with a 3-state session status badge (active / human-handled / closed) and live agent name display. AI responses pause while the human is in the seat and resume cleanly when the agent ends the takeover.
* **Webchat Mobile Layout**: The webchat widget now switches to a fullscreen layout on mobile devices for a native app-like experience, and cleans up properly when closed.
* **Call Transfer Connected Webhook**: New webhook event fires the moment a transfer call successfully bridges to a human agent — useful for kicking off CRM updates or attribution at the right moment.
* **Personalized First Follow-Up**: After an AI call (or after a lead's first reply), the next follow-up message is now personalized based on what was discussed instead of using the generic templated outreach. This noticeably improves continuity in multi-touch sequences.
* **Custom Warm-Transfer Hold Music**: Upload your own hold music for warm-transfer wait periods, with an inline upload helper in the profile editor.
* **Branded Lead-Transfer Greeting**: The greeting played to the lead at the start of a transfer is now spoken in the customer profile's selected AI voice for consistent branding. Cold transfers also get this treatment.
* **Split First Outreach into Multiple Texts**: New per-profile toggle to split the first outbound text into multiple shorter messages — useful when you want to lead with a quick hook before the full pitch.
* **Apology Audio for Missed Warm Transfers**: When a warm transfer is initiated but the human agent misses it, Apten plays a brief apology audio to the lead and triggers a follow-up SMS instead of dropping the call silently.
* **External Lead ID on Get Lead API**: The Get Lead API endpoint now returns the external lead ID you set when creating the lead, so you can round-trip your own identifiers.
* **Read-Only API Access**: The public API now respects member roles, so teammates with read-only roles can call read endpoints without being able to make changes. Useful for multi-user accounts that want to give analysts or external collaborators safe access.
## Improvements
### Voice Bot Enhancements
* **Faster Warm-Transfer Hand-Offs**: Warm-transfer latency dropped via internal pre-warming and parallelization improvements.
* **Reliability Fixes for Warm Transfer**: Multiple fixes including aborted-response handling, fallback on no-keypress, and stale-state cleanup so warm transfers behave predictably under load.
* **AI-Call History in Voice Agent**: Voice bot is now aware of whether a lead has previously had an AI call, so it can vary its opening accordingly.
* **Smarter Background Models**: Background tasks (variable extraction, summary generation) upgraded to a newer model for higher accuracy and lower cost.
* **No Call-Reminder Language in First Follow-Up**: The first post-call follow-up message no longer includes call-reminder phrasing if the call already connected.
* **Apology SMS for Failed Scheduled Transfers**: When a scheduled transfer fails, the lead receives an apology SMS automatically instead of being dropped silently.
* **AI Date-Math Fix**: Voice bot no longer attempts its own date arithmetic — all scheduling logic now routes through the dedicated scheduling agent for accuracy.
### Webchat
* **Reliable Reconnection**: Webchat widget now reconnects cleanly with the live session and replays buffered messages, fixing rare message-loss edge cases.
* **Off-Center Styling Fix**: Chat window now fills its container regardless of the configured position.
### Conversations & Automations
* **Dynamics Tag Sync — Async Setup**: Dynamics 365 tag sync now runs in the background with progress polling, so you don't have to wait on the setup screen for it to finish.
* **Copy Strategy ID**: Each strategy card has a copy-ID button for easier cross-referencing in API calls.
* **Strategy Performance Loading State**: Strategy performance table no longer shows a false empty state while the data is loading.
* **Conversation Header Polish**: Improved conversation header layout for contact info and badges.
* **Floating Save/Discard Bar**: Integration settings pages now expose a floating save/discard bar for unsaved changes.
### UI/UX Improvements
* **CRM Unsubscribe Field Alerts**: Setup alerts now dynamically show only the missing CRM unsubscribe fields and gate alerts on whether the relevant channel (SMS/voice/email) is enabled.
* **Build & Test UI**: Continued polish across the customer profile builder including voice + transfer settings layout, collapsible-summary readability, and time-formatting deduplication.
## Bug Fixes
* Fixed a crash in the variables dialog when CRM custom fields couldn't be fetched.
* Fixed a duplicate pre-generated message occasionally appearing in voice transcripts.
* Fixed a false unsubscribe trigger when a lead replied "no" to a link-send request.
* Fixed Tags and Notifications pages not respecting member role permissions.
# May 2026
Source: https://docs.apten.ai/changelog/2026-05
## New Features
* **External Compliance Checks**: Gate every outbound SMS, email, and voice attempt through your own compliance endpoint before it sends. Suppressed sends appear as `COMPLIANCE_BLOCKED` events in the conversation timeline and events export. See [External Compliance Checks](/compliance/external-checks).
* **Smarter SMS / Webchat Transfers (call-screening safe)**: SMS and webchat transfers now connect reliably for leads behind call-screening services like Google Voice, Hiya, and RoboKiller, which previously caused failures.
* **Custom Hold Music for Webchat Warm Transfers**: Upload custom hold music for warm-transfer wait periods in webchat sessions.
* **Per-Lead Events Endpoint**: New `GET /leads/{leadId}/events` returns every interaction on a lead — messages, calls (with inline transcripts), emails, tags, opt-outs, and compliance blocks. See [List events for a lead](/api-reference/leads/list-events).
* **Stable Call Recording URLs**: Call recordings are now exposed at stable URLs in the events feed, so integrations can pull audio without dashboard access.
* **Incremental Data Export Endpoints**: Pair `GET /leads?updatedSince=…` with per-lead `GET /leads/{leadId}/events?since=…` for incremental syncs into your CRM or data warehouse.
* **Knowledge Folders + Sources Explorer**: Group connected sources into folders and assign folders per customer profile. A new Sources Explorer view makes it easy to browse what's been indexed.
* **Bulk URL Submission for Web Scrape**: Paste a list of URLs at once when seeding the web-scrape knowledge base.
* **Multi-Domain Email**: Add, retire, and switch between multiple verified sending domains under **Settings → Email**.
* **Per-Key Webchat Settings**: Each webchat API key carries its own widget settings — useful for embedding the widget on multiple sites with different branding.
* **Retrievable Webchat API Keys**: Reveal webchat API keys in the dashboard after creation, instead of regenerating to re-copy.
* **Tags Scoped Per Profile**: Tags can now be scoped to specific customer profiles instead of being global.
* **`GET /v1/usage` Endpoint**: Returns your organization's current lead usage and configured limit. See [Get usage](/api-reference/usage/get-usage).
* **Lead Usage Email Alerts**: Get notified by email as you approach your monthly lead limit.
* **`lead.additionalInfo.updated` Webhook**: Fires whenever variables on a lead are set, changed, or removed. See [Lead Additional Info Updated](/webhooks/lead-additional-info-updated).
* **Delete Webhook Config from the UI**: Remove a configured webhook endpoint directly in the dashboard.
* **Profile-Level Voice Tuning**: Pacing, interruption sensitivity, and other voice settings are now configured per customer profile instead of org-wide.
* **XML / SOAP Custom Tools**: Custom Tools now accept XML / SOAP request and response bodies in addition to JSON.
* **`hasTransferCall` Sync to CRM**: New mappable boolean indicating whether the lead has ever been transferred to a human on a call.
* **External CRM Lead ID in Dashboard**: The external lead ID you set when creating the lead is now shown in the conversation header.
## Improvements
### AI & Conversation Quality
* **Personalized First Follow-Up Polish**: Reads more naturally and no longer repeats phrasing from the previous turn.
* **Smarter Reminder Handling**: When a lead replies to a reminder over multiple turns, replies now route correctly and the AI properly cancels any pending follow-up steps.
* **Apology SMS for Missed Scheduled Calls**: If an AI-scheduled follow-up call fails to connect, the lead now receives a brief apology SMS instead of being dropped silently.
* **Channel-Aware Opt-Out**: Opt-out classification now broadens when a lead explicitly references a different channel (e.g. "stop emailing me" while on SMS).
* **Live Mid-Turn Variable Updates**: Custom tool responses can now update lead variables mid-turn and the AI sees the new values in the same response.
* **Call-Screening Disclaimer**: The voice agent delivers its recording disclaimer correctly when a call hits a screener, and no longer attempts to transfer while still on the screener.
* **Warm-Transfer Hold IVR**: The warm-transfer bot now correctly classifies a human cutting in over hold-music IVR prompts.
* **Webchat Warm Transfer Cleanup**: Prevents the warm-transfer bot from fabricating capabilities or sending a duplicate first message.
* **Same-Day Follow-Up Scheduling**: You can now schedule a follow-up message for later the same day from the conversation view.
* **Significantly Faster Inbound Call Pickup**: Inbound calls connect noticeably faster.
* **Faster AI Responses**: AI reply latency across messaging, analytics, and follow-up scheduling is noticeably faster.
### Dashboard & Settings
* **Settings Redesign**: All settings tabs redesigned with a consistent section-card layout.
* **Tags + Notifications Pages**: Both list pages redesigned with a Create New dialog, empty state, and resizable condition textareas.
* **Compliance Settings in Settings Page**: Compliance configuration is now a tab inside Settings.
* **Compliance: Blocked-Outreach Indicator**: Suppressed outbound messages show inline in the conversation timeline so you can see why a send didn't go out.
* **CSV Uploads Accept Windows-1252**: Lead-import CSVs encoded in Windows-1252 (a common Excel default) now upload cleanly.
* **Click-Blocked UI Fixes**: Selects, popovers, and the file picker no longer become unclickable inside dialogs.
* **Voice Picker Polish**: Highlights Apten-recommended voices in a cleaner browsing layout.
## Bug Fixes
* Fixed a premature outbound call being created when a lead replied positively to a reminder before the scheduled time.
* Editing one step in a follow-up config no longer resets metadata on the other steps.
* Default follow-up cadence no longer continues to schedule after a lead is cancelled.
* Deduplicated custom notifications so identical conditions don't fire twice.
* Profile duplication now reflects the latest strategies and config on the source profile.
* Fixed default voice-tuning churn that could overwrite saved per-profile values.
# June 2026
Source: https://docs.apten.ai/changelog/2026-06
## New Features
* **`GET /calls/{callId}`**: Fetch full call details — transcript, AI summary, transfer metadata — by call ID. See [Get call](/api-reference/calls/get-call).
* **Do Not Contact Flag**: When a lead explicitly asks to never be contacted on any channel, Apten now sets a do-not-contact flag and fires a new `doNotContact` webhook. The flag clears automatically when the lead opts back in or is resubscribed via the API. See [Do Not Contact](/webhooks/do-not-contact).
* **Do Not Contact Field Mapping**: The `isDoNotContact` boolean can now be mapped to any boolean field in your CRM (HubSpot, Salesforce, Dynamics 365).
* **`isDoNotContact` on Opt-Out Webhooks**: All `optOut` payloads now include `isDoNotContact` indicating whether the lead has an active do-not-contact flag at the time the per-channel opt-out fires.
* **Transfer Detail Fields in Call Metrics**: Transfer leg duration, outcome, and type are now available as columns and filters in the Calls table.
* **`transferFallbackTriggered` Webhook**: Fires when a warm-transfer fallback agent is successfully dispatched, so you can alert your on-call team in real time. See [Transfer Fallback Triggered](/webhooks/transfer-fallback-triggered).
* **`scheduledImportAt` on Create Lead**: New optional parameter that defers Apten's first outbound message until a specific timestamp.
* **Profile Filter on Data Export**: Multi-select profile filter on the Data Export page so you can export by profile.
* **Profile + Tags in Conversation Info**: The conversation info dialog now shows the customer profile and tags on the lead.
* **Follow-Up Type + Flex Window on Schedule Buttons**: The Edit Schedule UI now surfaces each follow-up's type and flex window inline.
* **Map Apten Fields to Your Own CRM Fields**: Each Apten concept (tags, AI summary, is-qualified, is-hot, has-replied, has-been-transferred, per-channel unsubscribe) can now be mapped to an existing field you own in HubSpot, Salesforce, or Dynamics 365. Replaces the previous model that required Apten to auto-create fields inside your CRM.
* **Day-by-Day Outreach Hours**: Set different outreach windows for each day of the week so scheduled follow-ups and new outreach follow the hours you actually allow.
* **Additional Lead Context for Compliance Checks**: External compliance requests now include the lead's `additionalInfo`, so your endpoint can make context-aware decisions before outreach is sent.
* **Salesforce Article Field Selection**: Salesforce article imports can now use fields from the selected page layout by default, with manual field selection still available when you need it.
## Improvements
* **Reserved Variable Names Blocked**: The flow editor now rejects variable names that conflict with reserved system variables.
* **Multi-Segment IANA Timezones**: Lead imports now accept timezones like `America/Argentina/Buenos_Aires` and `America/Indiana/Indianapolis`.
* **Voice Bot — Links Sent as Text, Not Spoken Aloud**: The voice agent now texts links to the lead during a call instead of trying to read URLs out loud.
* **Deferral vs Opt-Out**: Statements like "not right now" or "call me later" are no longer misclassified as opt-outs.
* **Link Safety Setting**: Optionally suppress outbound links unless they come from a tool result or a source you provided.
* **Clearer Knowledge Upload Conflicts**: Uploads now identify duplicate file names within a folder so you can resolve conflicts before replacing existing content.
## Bug Fixes
* Fixed a data export edge case where group filters were not applied to the underlying query, producing inflated results.
* Fixed a rare case where the first follow-up could be dropped if the message took too long to send.
* Fixed condition-node prompts breaking when natural-language brace characters appeared in the prompt body.
* Fixed an edge case where the voice agent could tell the lead it had texted them without the text actually being sent.
* RCS messages that fail to deliver now fall back to SMS when possible.
# July 2026
Source: https://docs.apten.ai/changelog/2026-07
## New Features
* **Automations — Resolve Timezone action**: Convert location data you already have — a CRM time zone value in any common format, a zip code, a phone number, or a state — into a time zone Apten can use, so leads are contacted at the right local hours. Inputs are tried in order and unrecognized values fall through; pair it with Create Lead's **Time zone** field. See [Resolve Timezone](/automations/actions#resolve-timezone).
* **Nested branches in Automations**: Branch steps can now contain their own Branch steps, up to 3 levels deep — split a path, then split it again — and you can insert a Branch into an existing automation without rebuilding the flow. The total step limit per automation is now 75 (up from 30). See [Control Steps](/automations/control-steps).
* **Automations**: Build CRM-triggered workflows on a visual canvas — when a record is created or a field changes in Salesforce or Microsoft Dynamics, Apten can create leads, send messages, switch customer profiles, register Do Not Contact numbers, and more, with filters and branching to control each path. Available to admins under **Automations** in the sidebar. See [Automations](/automations/overview).
* **Automations — condition groups**: Mix AND and OR logic in one condition list, like *Status = Qualified and (Source = Web or Source = Referral)*. Add a group from the condition editor on trigger conditions, Filter steps, Branch rules, and Find CRM Record conditions. See [Condition groups](/automations/control-steps#condition-groups).
* **Recover Deleted Automations**: Deleted automations now stay in a Recently deleted view for 30 days so you can restore them as drafts instead of rebuilding them.
* **Minute-Based Follow-Up Schedules**: Set follow-up delays in minutes as well as hours from the profile editor and Edit Schedule controls.
* **AI Lead Transfer for SMS and Webchat**: SMS, webchat, and scheduled transfers can now confirm that a lead is ready before connecting them with a person, with an option for immediate transfer instead.
* **Expanded Automation Actions**: Automations can now add or remove tags during a run.
* **Interested-Lead Channel Breakdown**: The Metrics page now shows how interested leads divide across SMS, voice, and email, including the underlying counts.
* **Custom-Field Filters in Data Explorer**: Filter leads by text, number, or boolean values in custom fields, then manage the results with clearer table controls and saved column preferences.
* **Read-Only Analyst Access**: Analysts can now view Build & Test, customer profiles, sources, and custom knowledge without changing production configuration.
## Improvements
* **Source Links in AI Responses**: When AI uses web-scraped knowledge, it can now include the original source link so your team can verify the information.
# August 2026
Source: https://docs.apten.ai/changelog/2026-08
## New Features
* **Timeline events on Add Context**: The [Add Context](/api-reference/leads/add-context) API now accepts an `event` field for things that happen at a point in time — a status change in your system, a completed application step, a booked meeting. Unlike `context` (standing facts and instructions), an event is recorded in the conversation timeline with a timestamp, so the AI knows when it happened relative to the lead's messages, treats it as news the lead hasn't seen yet, and can bring it up naturally or move the flow-chart conversation forward in response. Send `event`, `context`, or both in one call.
* **State-Specific TCPA Controls**: Store a lead's state and configure state-level outreach windows, holidays, blackout dates, and rolling contact limits in **Settings → Compliance**; Apten applies the more restrictive rule for leads with a recognized state. See [State-Specific TCPA Compliance](/compliance/state-specific-tcpa).
* **Webchat Branding Builder**: Customize your widget's logo, header text, launcher style, color, and position with a live preview, then copy the generated installation code.
* **Metrics Saved Views and Advanced Filters**: Save shared metric views with profile, tag, custom-field, include, exclude, date, and tab filters, and apply the same filters to exports.
* **Inbound SMS Attachments**: Messages with inbound SMS attachments are now identified in conversations and can be filtered in the dashboard.
* **Archived Customer Profiles**: Move profiles between Active and Archived lists so older configurations stay available without cluttering the active workspace.
* **Update CRM Records in Automations**: Write values back to writable Salesforce or Dynamics 365 fields during an automation run.
* **Webchat Notifications**: Notifications from webchat conversations now appear in the inbox with a direct link back to the relevant session.
* **Use Your Own Salesforce App**: Connect Salesforce with your organization's own connected app when your security or governance policies require it.
* **Per-Step Webchat Auto-Conversion**: Message steps can now keep an eligible webchat session from auto-converting while that step is active.
## Improvements
* **Time-of-Day Export Filters**: Filter Data Explorer results by start time, end time, and UTC or local timezone instead of whole days only.
* **Dataverse Lookup Fields in Automations**: Use lookup fields when choosing watched fields, filters, and branch conditions in Dynamics 365 automations.
* **CRM IDs in Lead Exports**: Lead exports now include the external CRM record ID when one is available.
* **More Relevant Search**: Dashboard and webchat search now update as you type and return results in a more useful order.
* **Accessibility Improvements**: Updated dashboard controls and navigation for more reliable keyboard and assistive-technology use. See [Accessibility](/compliance/accessibility).
## Bug Fixes
* Fixed live message delivery so new messages appear faster and retry cleanly when a connection briefly drops.
* Fixed cross-channel opt-out handling so a lead's request is routed to the channel they actually referenced.
* Fixed date wording in event reminders so relative dates stay accurate.
# September 2026
Source: https://docs.apten.ai/changelog/2026-09
## New Features
* **`call.transfer.failed` webhook**: Subscribe to [Call Transfer Failed](/webhooks/call-transfer-failed) to learn that a transfer was started and did not connect. The event includes the failure reason and, when available, when the transfer attempt started and how many seconds elapsed before Apten recorded the failure. A dedicated transfer call the lead never answered still uses [`call.attempted`](/webhooks/call-attempted).
## Improvements
* **Email and call engagement on the Lead API**: Lead responses from [Get Lead](/api-reference/leads/get-lead) and [List Leads](/api-reference/leads/list) now include `hasRepliedEmail` and `hasAiCall` alongside `hasReplied`, so you can tell how a lead has engaged: by text, by email, or by speaking with Apten on a call.
# October 2026
Source: https://docs.apten.ai/changelog/2026-10
## Improvements
* **Temporary external compliance blocks**: Return `blockType: "temporary"` to block only the current send and let the lead's follow-up sequence continue on its normal cadence, including when a voice call is blocked immediately before dialing. Fail-closed provider errors are temporary; missing `blockType` keeps the existing permanent-block behavior. See [External Compliance Checks](/compliance/external-checks).
# Accessibility
Source: https://docs.apten.ai/compliance/accessibility
Apten's accessibility features, assistive-technology compatibility, known limitations, and how to request help or accommodations.
## Our commitment
Apten is committed to making our platform usable by everyone, including people who
rely on assistive technologies. We design and build against the
**Web Content Accessibility Guidelines (WCAG) 2.1, Level AA**, which are also the
basis for **Section 508** of the U.S. Rehabilitation Act. Accessibility is an
ongoing effort: we test as we build, remediate issues we find, and continue to
expand coverage.
**Conformance report (VPAT).** We maintain a Voluntary Product Accessibility
Template (VPAT®, Revised Section 508 edition) describing how the Apten web
application measures against each criterion. It is available on request —
contact [founders@apten.ai](mailto:founders@apten.ai).
## Accessibility features
The Apten dashboard includes the following features. Most are provided
automatically by the standards-based components the app is built on; no special
configuration is required.
### Keyboard navigation
The dashboard is operable with a keyboard alone:
* **Skip to content** — press `Tab` when a page loads and the first focusable
element is a "Skip to main content" link that bypasses the navigation.
* **Logical focus order and visible focus** — interactive elements are reachable
in a sensible order, each with a visible focus indicator.
* **Menus, dialogs, and pop-ups** — open and close with the keyboard, trap focus
while open, and close on `Escape`.
* **Reordering lists** — drag-and-drop lists (for example, follow-up sequences and
customer-profile fields) can also be reordered from the keyboard: focus the drag
handle, press `Space` to pick up, use the arrow keys to move, and `Space` again
to drop.
### Screen reader support
* **Labeled controls** — buttons, icons, form fields, and toggles expose
text labels to assistive technology.
* **Landmarks and page titles** — the main navigation is exposed as a navigation
landmark, the primary content is a main landmark, and each page has a unique,
descriptive title.
* **Forms** — fields are programmatically associated with their labels, required
fields are announced as required, and validation errors are announced and tied
to the field they describe.
* **Status updates** — notifications (toasts) and loading states are announced so
you are informed when content is loading or an action has completed.
* **Call recordings** — recorded calls are accompanied by a full text transcript
with speaker labels and timestamps.
### Visual and display
* **Contrast** — text and interface colors are designed to meet WCAG AA contrast
minimums.
* **Zoom and text size** — the interface supports browser zoom up to 200% and
honors your browser's text-size settings without loss of content.
* **Color is not the only cue** — status and state are conveyed with text and
icons in addition to color.
## Assistive technology and browser compatibility
The Apten dashboard is a standards-based web application and is designed to work
with current assistive technologies, including screen readers such as
**VoiceOver** (macOS/iOS) and **NVDA** (Windows), used with a current version of a
major browser:
* Google Chrome
* Microsoft Edge
* Mozilla Firefox
* Apple Safari
We recommend using the latest version of your browser and assistive technology for
the best experience.
## Known limitations
We believe in being transparent about where we are still improving:
* **Visual flow / automation builder** — the drag-based canvas used to build
conversation and automation flows is not yet fully operable by keyboard or
screen reader. If you need to build or edit flows and this is a barrier, please
contact us — we can assist and are actively working on this area.
* **Charts and graphs** — data visualizations in the Metrics section are
accompanied by data tables that present the same information in text form; the
charts themselves are visual.
This list reflects our current understanding and is updated as we make progress.
## Getting help and giving feedback
If you encounter an accessibility barrier, need information in an alternative
format, or want to request an accommodation, please contact us — we're happy to
help and we treat accessibility feedback as a priority:
Email [founders@apten.ai](mailto:founders@apten.ai). Please include the page or
feature, what you were trying to do, and the assistive technology and browser
you were using, so we can reproduce and address it quickly.
# External Compliance Checks
Source: https://docs.apten.ai/compliance/external-checks
Gate every outbound SMS, email, or call against your own compliance middleware before Apten sends.
## Overview
External Compliance Checks are a **per-organization** product feature: your org can wire a custom HTTPS endpoint into Apten's send pipeline. Before outbound sends on the channels you select, Apten POSTs a check request to your middleware. If your middleware says the contact is not allowed on that channel, Apten suppresses the send, writes an audit record, and surfaces a `COMPLIANCE_BLOCKED` event in the conversation timeline and events export.
Use this when you have an internal compliance system (state DNC lists, litigator scrubbers, vendor-provided suppression sources, internal customer-preference databases) that must be the source of truth for whether a given lead can be contacted right now.
**Apten-managed DNC** runs on every outbound SMS and voice call, regardless of
these settings. Numbers on Apten's standing Do Not Contact list are blocked
before send. Manage that list via the
[Do Not Contact API](/api-reference/dnc/register). This feature composes with
— it does not replace — Apten's built-in
[opt-out handling](/webhooks/opt-out).
## Setup
External compliance is configured per-organization in the **Settings → Compliance** tab. Only users with the **Admin** role can change these settings.
### Apten-managed DNC
Apten always checks outbound **SMS / RCS** and **voice** against our standing DNC list. This is not configurable in the Compliance tab.
### Enable the external API
Toggle **External compliance API** on to POST to your middleware before sends on selected channels.
### External API channels
Select which channels (**SMS / RCS**, **Voice**, **Email**) should also be checked against your middleware. Channels you don't select skip the external check. Unchecking all channels (or turning the external API off) does **not** disable Apten-managed DNC on SMS and voice.
### Failure mode
You must explicitly choose how Apten behaves when your middleware is unreachable, returns a non-2xx response, or times out:
* **Fail Closed** — block the send. Safer for regulatory compliance, but a middleware outage will pause outbound traffic. Fail-closed blocks are always [temporary](#permanent-and-temporary-blocks): the lead's follow-up sequence keeps going, and the next send checks your middleware again.
* **Fail Open** — allow the send. Avoids dropped sends during outages, but a malfunctioning middleware will not suppress contacts.
There is no system default — the trade-off depends on your regulatory posture.
### Endpoint URL
The HTTPS URL of your middleware. Apten will POST every check request here. The URL must use `https://`.
### Signing secret
Apten signs every request with an HMAC-SHA256 of the request body, using a shared secret you control. Your middleware uses this to verify that requests genuinely came from Apten.
In the **Signing Secret** field you can:
* **Generate** — produces a random 32-byte base64url secret in your browser and fills the field. Click before saving and copy the value to your middleware.
* **Paste** — paste a secret you generated elsewhere.
* **View saved** — appears once a secret has been saved. Click to fetch and display the currently saved secret so you can copy it to a new middleware deployment. (Saved secrets are encrypted at rest with AWS KMS and only revealed to admins on demand.)
* **Eye toggle / Copy** — show or hide the secret in the field, or copy it to the clipboard.
Leave the field blank when saving to keep the existing secret unchanged.
### Timeout
How long Apten waits for your middleware to respond before applying the failure mode. Default `1500ms`, configurable from `100ms` to `10000ms`.
## Compliance check API
For every gated send, Apten makes the following request to your endpoint:
```http theme={null}
POST {endpointUrl}
Content-Type: application/json
User-Agent: Apten-Compliance/1.0
X-Apten-Signature: sha256=
X-Apten-Timestamp:
X-Signature-SHA256:
```
```json theme={null}
{
"leadId": "a7e92c5d-f301-4b89-ae16-8f35d02cx9z",
"channel": "sms",
"outreachType": "follow_up",
"phone": "+14155551212",
"email": null,
"externalLeadId": "003XX000004DHPY",
"triggeredBy": "send-text-message",
"additionalInfo": { "dncLastCheck": "2026-06-01", "matchRequestId": "req-123" }
}
```
### Request properties
| Property | Type | Description |
| - | - | - |
| `leadId` | string | The Apten lead ID being contacted. |
| `channel` | string | The channel about to be used. One of `sms` (also covers RCS), `voice`, or `email`. |
| `outreachType` | string | Why the outreach is being sent. One of `initial`, `reply`, `follow_up`, `manual`, `reminder`, `immediate_transfer`, `no_answer_follow_up`, or `scheduled_transfer`. |
| `phone` | string | Lead phone number in E.164 format. Set when `channel` is `sms` or `voice`. `null` for email checks. |
| `email` | string | Lead email address. Set when `channel` is `email`. `null` for SMS / voice checks. |
| `externalLeadId` | string | CRM lead ID, when known (Salesforce / HubSpot / Dynamics / Close CRM). |
| `triggeredBy` | string | Internal label for which send path triggered the check, e.g. `send-text-message`, `queue-call`, `voice-poller-dial`. Useful for diagnostics; not part of a stable contract. |
| `additionalInfo` | object | The lead's custom [`additionalInfo`](/api-reference/leads/get-lead) fields, as a key/value object. `{}` when none are set. |
Only the identifier relevant to the channel is included. SMS / voice checks
send only `phone`; email checks send only `email`. The unused field is
`null`. This minimizes the PII surface forwarded to your middleware.
### Expected response
Apten reads a required top-level `allowed` boolean and, when blocking, an optional `blockType`. The minimum valid response is:
```http theme={null}
200 OK
Content-Type: application/json
```
```json theme={null}
{ "allowed": true }
```
or, to block the send:
```json theme={null}
{ "allowed": false }
```
or, to block only this send and check again next time:
```json theme={null}
{ "allowed": false, "blockType": "temporary" }
```
| Property | Type | Description |
| - | - | - |
| `allowed` | boolean | **Required.** `true` to allow the send; `false` to suppress it. Any other type is treated as a provider error. |
| `blockType` | string | Optional, read only when `allowed` is `false`. `permanent` (default) removes this channel from the lead's follow-up sequence; `temporary` blocks only this send. Missing or unrecognized values are treated as `permanent`. See [Permanent and temporary blocks](#permanent-and-temporary-blocks). |
A non-2xx status, a timeout, or a non-boolean `allowed` field is treated as a **provider error** — your org's configured failure mode then decides whether the send proceeds.
#### Optional extra fields
Anything else you include in the JSON body is recorded verbatim in Apten's audit row for your own debugging. Apten does not use these fields to make decisions. Two conventional fields:
```json theme={null}
{
"allowed": false,
"reason": "internal_dnc",
"metadata": { "matched_list": "litigator-q2" }
}
```
* `reason` — a short tag explaining why you blocked. Stored on Apten's internal audit row so you can correlate the block back to your own systems if you ever request an audit export.
* `metadata` — any additional context you want preserved alongside the audit row.
You don't need to send these. Apten's gating decision is `allowed`; `blockType` only decides whether a block carries over to future sends.
## Permanent and temporary blocks
Every block is either **permanent** or **temporary**. Either way, the current send is suppressed and a `COMPLIANCE_BLOCKED` event is recorded with its `blockType`. They differ in what happens next:
| | Permanent | Temporary |
| - | - | - |
| Produced by | `{ "allowed": false }` or `{ "allowed": false, "blockType": "permanent" }`; Apten-managed DNC | `{ "allowed": false, "blockType": "temporary" }`; provider errors under **Fail Closed**; configuration errors |
| Future sends on this channel | Apten records the channel as blocked for this lead. Remaining scheduled follow-up steps on that channel are skipped without calling your middleware. Other sends on that channel, such as replies to the lead, are still checked individually. | Nothing is remembered. The next send on that channel, whenever it would normally happen, calls your middleware again. |
| Follow-up sequence | Continues on the lead's other channels, if any steps remain on them. | Continues on its normal schedule, including later steps on the same channel. |
Apten does not schedule extra retries for a temporary block — "next time" means the next send the lead's sequence or conversation would have made anyway.
Blocks are per lead **and** per channel. A permanent SMS block does not stop email or voice follow-ups; each of those sends is still checked on its own.
A permanent block stays in place even if your middleware later starts allowing the lead, because scheduled follow-ups on that channel no longer call your middleware. To lift a permanent block, contact Apten support. If a condition might clear on its own, return a temporary block instead.
A permanent block is the default so existing integrations keep their
current behavior. Return `"blockType": "temporary"` for conditions you
expect to clear on their own — for example a pending consent lookup, a
per-day contact cap, or an upstream data source that is briefly
unavailable.
This applies to the first outreach as well. If the first text, email, or
call to a new lead is blocked, the lead's follow-up sequence still starts:
on its normal schedule for a temporary block, or on the next step that
uses a different channel for a permanent one.
Voice calls are checked again immediately before dialing. If that check blocks
a first-contact or follow-up call, Apten does not place the call. Temporary
blocks leave voice eligible for its next normal check; permanent blocks skip
voice and continue on any other configured channels. No `CALL` event is created
for a call that was blocked before dialing; the `COMPLIANCE_BLOCKED` event
records the decision.
Transfer calls are voice sends, including transfers set up from a text
conversation. Apten calls the lead first, so the check uses the `voice`
channel. A permanent voice block stops future transfer calls to that lead as
well as regular calls.
## Verifying the signature
Apten signs the request body with the same HMAC-SHA256 scheme used for [outbound webhooks](/webhooks/verification). Verify in your middleware by recomputing the HMAC using the shared signing secret and comparing it to the `X-Signature-SHA256` header.
Every request also carries an `X-Apten-Signature` header in the form
`sha256=`. It is the same HMAC value as `X-Signature-SHA256` with a
scheme prefix. Verify against **`X-Signature-SHA256`** (raw hex) — that is
the canonical header for this endpoint.
Always use a constant-time comparison (`crypto.timingSafeEqual`,
`hmac.compare_digest`, etc.) — never `==`. Guard against missing or
wrong-length signatures **before** the comparison; both `timingSafeEqual`
and `compare_digest` raise when their inputs aren't both present and of the
same length.
```javascript Node.js theme={null}
import crypto from 'crypto';
// Mount Express with `express.raw({ type: 'application/json' })` (or your
// framework's equivalent) for this route so `req.body` is the raw Buffer
// that Apten signed. Re-serializing a parsed object via JSON.stringify can
// change whitespace and key ordering and will break the signature.
function verifyComplianceRequest(req) {
const secret = process.env.APTEN_COMPLIANCE_SECRET;
const signature = req.headers['x-signature-sha256'];
if (typeof signature !== 'string' || signature.length === 0) {
return false;
}
const expected = crypto
.createHmac('sha256', secret)
.update(req.body) // raw Buffer
.digest('hex');
if (expected.length !== signature.length) {
return false;
}
return crypto.timingSafeEqual(
Buffer.from(expected, 'utf8'),
Buffer.from(signature, 'utf8'),
);
}
```
```python Python theme={null}
import hmac
import hashlib
import os
def verify_compliance_request(request):
secret = os.environ['APTEN_COMPLIANCE_SECRET']
payload = request.get_data() # raw bytes — do not re-serialize
signature = request.headers.get('X-Signature-SHA256')
if not signature:
return False
expected = hmac.new(
secret.encode('utf-8'),
payload,
hashlib.sha256,
).hexdigest()
if len(expected) != len(signature):
return False
return hmac.compare_digest(expected, signature)
```
Always sign and verify the **raw** request body bytes, exactly as they arrived
on the wire. Re-serializing a parsed JSON object can change whitespace and
key ordering and break the signature.
## Provider behavior
### Apten DNC and external HTTP ordering
**Apten-managed DNC** runs first on every outbound **SMS** and **voice** send (phone-keyed list via the [Do Not Contact API](/api-reference/dnc/register)). It does not apply to **email**.
If **External compliance API** is enabled and the channel is in your `channels` set, Apten then POSTs to your middleware. A DNC block returns before that HTTP call. Provider errors on the HTTP leg follow your **Failure Mode**; a definitive DNC block is never overridden by fail-open.
### Per-channel decisions
Each channel is checked independently. If a lead is blocked on `sms` but allowed on `email`, only the SMS send is suppressed. For the first-message **Text + Email** outreach pattern, a block on one channel does not prevent the other from sending.
### No caching
Every send triggers a fresh check against your middleware (the one exception: scheduled follow-ups on a channel with a [permanent block](#permanent-and-temporary-blocks) are skipped without a check). Apten does not cache responses, because follow-up cadences typically space outbound attempts hours or days apart — a useful cache TTL would expire before the next send anyway. Size your middleware capacity for your peak send volume.
### More than one check per send
A single send can reach your middleware more than once, because Apten checks again at each stage before the message or call goes out. A scheduled text is usually checked twice. A call can be checked up to three times: when it is scheduled, when it is queued, and right before dialing. A block at any of these stages stops the send.
Two things follow from this:
* Don't count check requests as sends. Use `leadId` and `channel` to see that requests belong to the same send; `triggeredBy` shows which stage made each one.
* Give the same answer for the same lead and channel unless something has actually changed. If your middleware applies per-day contact caps, count the texts and calls that actually went out, not check requests.
## Audit log
Every check — allowed or blocked — is written to Apten's internal audit table including the request, response, source, channel, and timestamp. This is the system of record for SOC 2 evidence. **Blocked** checks also appear as `COMPLIANCE_BLOCKED` events on [`GET /leads/{leadId}/events`](/api-reference/leads/list-events); allowed checks are audit-only. Contact Apten support if you need a full audit export (including allowed checks) for a specific time range.
## Failure modes at a glance
| Scenario | Outcome |
| - | - |
| Middleware returns `{ "allowed": true }` | Send proceeds. |
| Middleware returns `{ "allowed": false }` | Send is suppressed; audit row written. Permanent block: later follow-ups on this channel are skipped. |
| Middleware returns `{ "allowed": false, "blockType": "temporary" }` | Send is suppressed; audit row written. The next send checks again. |
| Middleware returns 5xx, times out, or non-boolean `allowed` | Provider error — your **Failure Mode** decides whether the send proceeds. Under **Fail Closed** the block is temporary. |
| External API disabled or channel not in `channels` | That channel skips the external middleware check. SMS/voice still run Apten-managed DNC. |
| `phone` and `email` both missing for the requested channel | Send is suppressed with reason `COMPLIANCE_TARGET_MISSING` (temporary). Audit row written. |
## Best practices
* **Always start in fail-open** while bringing your middleware online; flip to fail-closed once you've watched real traffic and tuned your latency.
* **Keep middleware p99 latency well under your configured timeout.** A 1500ms timeout with a 1400ms p99 will produce sporadic fail-mode activations.
* **Rotate the signing secret quarterly** from the Settings UI. Use **View saved** to retrieve the current value before rotation; then **Generate**, save, and deploy the new value to your middleware.
* **Log the `X-Apten-Timestamp` header** and reject requests older than a few minutes to protect against replay if your endpoint is ever publicly reachable.
# State-Specific TCPA Compliance
Source: https://docs.apten.ai/compliance/state-specific-tcpa
Apply state-specific outreach windows, holidays, blackout dates, and rolling contact limits to SMS and voice outreach.
## Overview
State-Specific TCPA Compliance helps your organization apply state-level timing and contact-frequency rules to outbound SMS and voice outreach. Apten provides maintained defaults for all 50 states and Washington, DC, and org admins can customize each jurisdiction from **Settings → Compliance**.
When enforcement is enabled, Apten combines each lead's state rule with your organization's Message Timing settings. State rules can make an outreach window more restrictive, but they never extend your configured organization hours. Email is not affected.
Apten's defaults and controls are compliance tools, not legal advice or a
guarantee of compliance. Your organization remains responsible for reviewing
its outreach practices and configuring rules for the laws and consent
requirements that apply to it.
## How rules are applied
State-specific rules apply only when Apten has a recognized state for the lead. Apten evaluates windows and blocked dates in the lead's local time.
* **Follow-up outreach**: Automated SMS and voice follow-ups always respect organization hours, organization holidays, and enabled state rules.
* **Initial outreach**: State windows follow **Respect Business Hours**, and state holidays and blackout dates follow **Respect Holidays** in Message Timing.
* **Email**: State-specific TCPA rules do not apply to email.
* **Rolling caps**: Caps count SMS and voice follow-up touches together within each conversation over the previous 24 hours.
If an attempt falls outside an allowed window, on a blocked date, or above a rolling cap, Apten delays it until outreach is allowed. Outbound calls are checked again immediately before dialing so time spent waiting to dial does not bypass the applicable window or blackout date.
Leads without a recognized state continue to follow your organization's
Message Timing settings. Confirm that imported lead records contain accurate
location information before relying on state-specific rules.
## Setup
State-Specific TCPA Compliance is configured per organization in **Settings → Compliance**. Only users with the **Admin** role can change these settings.
### Review Message Timing
Open **Message Timing** and review your organization-wide settings before enabling state enforcement:
* **Outreach Hours & Holidays** define the baseline schedule that all follow-ups must respect.
* **Time Zone** provides the organization fallback for scheduling.
* **Respect Business Hours** controls whether outreach windows also apply to initial outreach.
* **Respect Holidays** independently controls whether holidays and blackout dates also apply to initial outreach.
State outreach windows are intersected with organization outreach hours. For example, if organization hours end at 9:00 PM and a state window ends at 8:00 PM, outreach to leads in that state ends at 8:00 PM.
### Enable enforcement
In **State-Specific TCPA Compliance**, click **Configure**, then turn on **Enable enforcement**. Enforcement is off by default.
You can configure and save state overrides while enforcement is off. Apten retains those customizations and labels them **Not currently enforced** until you turn enforcement on.
## Configure state rules
Select a state or Washington, DC, to review its effective rule. States with blocked days, holidays, or caps appear first; states without those restrictions are available under **Show other states**. A **Customized** badge identifies states with saved overrides.
### Outreach windows
Configure an allowed start and end time for each day of the week, or block outreach for the entire day. Times must use a valid start-before-end range.
The saved state schedule must overlap your organization outreach hours on at least one day. Apten validates the combined settings when you save and identifies states that would have no available outreach window.
### Blocked holidays
Select holidays when outreach should be blocked for the state. The editor identifies holidays included in Apten's default rule, and you can add or remove holidays for your organization.
Holiday changes are stored relative to Apten's current defaults. If Apten updates an unmodified default, the effective rule updates automatically.
### Custom blackout dates
Add one-off dates when all SMS and voice outreach should be blocked in the selected state. Custom blackout dates apply in addition to organization holidays and the state's selected holidays.
### Rolling outreach cap
Enter the maximum number of SMS and voice follow-up touches allowed per conversation in a rolling 24-hour period. The cap accepts positive whole numbers; leave it blank to apply no cap.
When a conversation reaches the cap, Apten waits until an earlier touch falls outside the 24-hour window before continuing follow-up outreach.
### Reset a state
Click **Reset to Apten default** to remove your organization's overrides for the selected state. The state will then follow Apten's current default windows, holidays, blackout dates, and cap.
## Defaults and updates
Apten maintains the default state rules and holiday calendar. The settings page displays **Compliance data last updated** so admins can see when the default data was most recently revised.
Avoid copying the current state matrix into external procedures. Review the live settings page for the effective defaults, and save overrides only where your organization's legal guidance requires different behavior.
## How this works with other compliance controls
State-Specific TCPA Compliance adds timing, date, and frequency restrictions; it does not replace consent management or suppression checks.
* **Apten-managed DNC** continues to block numbers on your organization's standing Do Not Contact list. Manage it with the [Do Not Contact API](/api-reference/dnc/register).
* **Opt-out handling** continues to honor channel and linked-channel preferences. See [Opt-Out](/webhooks/opt-out) and [Do Not Contact](/webhooks/do-not-contact).
* **External Compliance Checks** can apply your own suppression sources or policies in addition to state timing rules. See [External Compliance Checks](/compliance/external-checks).
These controls compose with one another. Enabling state-specific enforcement does not weaken or bypass a block from another compliance control.
# Microsoft Dynamics 365
Source: https://docs.apten.ai/integrations/dynamics
Integrate Apten with Microsoft Dynamics 365.
## Overview
Connect your Apten account with Microsoft Dynamics 365 to sync information about leads and conversations in Apten with your Dynamics 365 CRM. Currently, we support syncing:
* **Tags**: sync tags into a multi-select field you select in Dynamics 365.
* **Default Tags**: sync built-in tags (Hot, Qualified, Has Replied, Unsubscribed SMS, Unsubscribed Email) to boolean fields you select.
* **Summaries**: sync lead conversation summaries into a text field you select in Dynamics 365.
* **Variables**: map variables to existing Dynamics 365 fields, which will sync in real-time.
* **Do not contact**: sync a lead's do-not-contact status to a boolean field you select in Dynamics 365.
Dynamics 365 syncing works with AI conversations over SMS, voice, and email.
## Prerequisites
The Microsoft account used to connect must be able to read the selected entity and read or write the fields you want to sync. Apten does not create fields, publishers, or solutions in your Dynamics 365 environment.
## Step 1: Connect Apten to Dynamics 365
1. In Apten, go to **Integrations**
2. Click **Connect** on the Microsoft Dynamics 365 card
3. Enter your Dynamics 365 environment name (the prefix from your Dynamics URL, e.g. if your URL is `yourorg.crm.dynamics.com`, enter `yourorg`)
4. Click **Connect** and authorize with your Microsoft account
5. Click **Manage** to go to the settings page
6. Select the Dynamics 365 object that you want to sync with (Lead, Contact, or Account), and click **Save**
The object selection and environment URL cannot be changed once saved. Choose carefully.
7. If you'd like to sync **Tags**, use the field mappings to choose the existing Dynamics 365 field that should receive tag values.
8. If you'd like to sync **Summaries**, use the field mappings to choose the existing multi-line text field that should receive conversation summaries.
## Step 2: Map Variables (Optional)
When setting up variables in customer profiles in **Build & Test**, you can map them to existing Dynamics 365 fields.
These fields will automatically sync to Dynamics 365 in real-time when Apten talks to a lead.
![Dynamics Variables]()
## Step 3: Import Leads with Dynamics IDs
When importing leads into Apten, you must set the following fields:
* `integrationSource`: Set this to `'dynamics'` to indicate the lead is from Dynamics 365
* `dynamicsId`: Set this to the Dynamics 365 record GUID (e.g. `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`)
Example payload:
```json theme={null}
{
"firstName": "John",
"lastName": "Doe",
"phone": "1234567890",
"customerProfile": "Test Profile",
"integrationSource": "dynamics", // Required for Sync
"dynamicsId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" // Required for Sync
}
```
# Hubspot
Source: https://docs.apten.ai/integrations/hubspot
Integrate Apten with Hubspot.
## Overview
Connect your Apten account with Hubspot to sync information about leads and conversations in Apten with any Hubspot object. Currently, we support syncing:
* **Tags**: sync tags into a HubSpot contact property you select.
* **Summaries**: sync lead conversation summaries into a HubSpot contact property you select.
* **Variables**: map variables to HubSpot contact properties, which will sync in real-time.
* **Do not contact**: sync a lead's do-not-contact status to a boolean property you select in HubSpot.
Hubspot syncing works with AI conversations over SMS, voice, and email.
## Step 1: Connect Apten to Hubspot
1. In Apten, go to **Integrations**.
2. Click **Connect** on the Hubspot card.
3. You will be redirected to Hubspot. If you are not already logged in, you will be prompted to do so.
4. Review the permissions requested by Apten and click **Connect app**. This will install the Apten app in your Hubspot account.
5. You will be redirected back to Apten.
## Step 2: Configure Syncing
If you'd like to sync Tags or Summaries, use the field mappings on the settings page to choose the existing HubSpot contact property that should receive each value. Apten does not create properties in your HubSpot portal.
## Step 3: Map Variables (Optional)
When setting up variables in customer profiles in **Build & Test**, you can map them to HubSpot contact properties.
These fields will automatically sync to Hubspot in real-time when Apten talks to a lead.
![Hubspot Variables]()
## Step 4: Import Leads with Hubspot IDs
When importing leads into Apten, you must set the following fields:
* `integrationSource`: Set this to `'hubspot'` to indicate the lead is from Hubspot.
* `hubspotId`: Set this to the Hubspot object ID of the lead (e.g. the Contact's `vid`).
Example payload:
```json theme={null}
{
"firstName": "John",
"lastName": "Doe",
"phone": "1234567890",
"customerProfile": "Test Profile",
"integrationSource": "hubspot", // Required for Sync
"hubspotId": "12345" // Required for Sync
}
```
## Workflow Actions
Apten provides custom actions that can be used directly within Hubspot workflows. These actions allow you to leverage the full power of the Apten API without leaving your Hubspot environment.
With Apten's Hubspot workflow actions, you can:
* **Create and update Leads**
* **Get information about Leads**
* **Send messages to leads**
* **Manage DNC lists**
These workflow actions enable seamless integration between your Hubspot processes and Apten's AI-powered communication capabilities. In order to utilize workflow actions:
1. Follow the **Connect Apten to Hubspot** direction in Step 1.
2. Within your Hubspot, edit or create a workflow
3. Search for "Apten" within the actions searchbar, and find the actions under **Integrated Apps**
### Create a Lead
The Create a Lead action allows you to automatically create new leads in Apten directly from your Hubspot workflows.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `customer_profile`: The Apten customer profile name to use
* `first_name`: Contact first name
* `last_name`: Contact last name
* `phone`: Phone number (must begin with area code, e.g., +15555555555)
**Optional Parameters:**
* `email`: Email address (valid email format)
* `timezone`: Timezone in tz database format (e.g., America/New\_York)
* `additional_info_1_key` through `additional_info_10_key`: Custom field names
* `additional_info_1_value` through `additional_info_10_value`: Custom field values
**Outputs:**
* `import_status`: Status of the lead import (success or error)
* `lead_id`: ID of the created lead in Apten
### Turn Off Lead
Disables messaging for a specific lead in Apten.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The unique identifier of the lead to turn off
**Outputs:**
* `status`: Operation status (success/error)
### Turn On Lead
Enables messaging for a specific lead in Apten.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The unique identifier of the lead to turn on
**Outputs:**
* `status`: Operation status (success/error)
### Switch Customer Profile
Changes a lead's customer profile and optionally sends a message or clears memory.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The ID of the lead to switch profiles for
* `profile`: The name of the customer profile to switch to
**Optional Parameters:**
* `send_message`: Whether to send a message after switching (true/false)
* `message_delay_hours`: Hours to delay the message
* `message_delay_mins`: Minutes to delay the message
* `clear_memory`: Whether to clear the lead memory (true/false)
**Outputs:**
* `status`: The status of the profile switch operation
* `profile_switched`: The name of the profile that was switched to
* `message_sent`: Whether a message was sent (true/false)
* `memory_cleared`: Whether lead memory was cleared (true/false)
### Get Lead Data
Retrieves detailed information about a specific lead from Apten.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The unique identifier of the lead to retrieve
**Outputs:**
* `first_name`, `last_name`, `phone`, `email`: Lead contact information
* `customer_profile`: The customer profile assigned to the lead
* `is_ai_on`: Whether AI messaging is enabled (true/false)
* `has_replied`: Whether the lead has replied to messages (true/false)
* `is_hot`: Whether the lead is marked as hot (true/false)
* `is_qualified`: Whether the lead is qualified (true/false)
* `is_unsubscribed`: Whether the lead is unsubscribed (true/false)
* `summary`: Summary of the lead conversation
* `tags`: Tags assigned to the lead (JSON format)
* `additional_info`: Additional information about the lead (JSON format)
### Send Message
Sends a message to a lead via Apten with various scheduling and delivery options.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The ID of the lead to send message to
* `message`: The message content to send
**Optional Parameters:**
* `scheduled_time`: Scheduled time for the message (ISO 8601 format)
* `send_when_off`: Whether to send message even when lead is turned off (true/false)
* `schedule_follow_ups`: Whether to schedule follow-up messages (true/false)
* `override_business_hours`: Whether to override business hours restrictions (true/false)
**Outputs:**
* `status`: Status of the send message operation
* `message_id`: ID of the sent message
* `response_message`: Detailed response about the operation
* `scheduled_date`: Date when the message was scheduled (if applicable)
### Look Up Lead
Finds an existing lead in Apten by phone number.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `phone`: The phone number to look up (e.g., +1234567890)
**Optional Parameters:**
* `outbound_phone`: The outbound phone number associated with the lead. Provide this when the same lead phone number may be associated with multiple outbound phone numbers.
**Outputs:**
* `status`: The result status (success, not\_found, or error)
* `lead_id`: The unique identifier of the found lead (empty if not found)
* `phone_number`: The normalized phone number that was searched
If multiple leads match the provided `phone` and no `outbound_phone` is provided, the action returns an error asking you to provide the outbound phone number.
### Add Context
Adds contextual information, commands, and additional data to a lead.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The unique identifier for the lead
**Optional Parameters:**
* `context`: Additional context information to add to the lead
* `command`: Command to queue for execution
* `additional_info_1_key` through `additional_info_10_key`: Keys for additional information fields
* `additional_info_1_value` through `additional_info_10_value`: Values for additional information fields
**Outputs:**
* `status`: The status of the add context operation
* `context_added`: Whether context was successfully added
* `command_queued`: Whether a command was successfully queued
* `additional_info_count`: Number of additional info fields that were added
### Add Event
Creates a custom event record for a lead in Apten.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `lead_id`: The unique identifier for the lead
* `text`: The text content for the custom event
**Outputs:**
* `status`: The status of the add event operation
* `event_id`: The unique identifier of the created event
* `response_message`: Additional information about the operation result
* `timestamp`: The timestamp when the event was created
### Check DNC Status
Checks if a phone number is in the Do Not Call list.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `phone`: The phone number to check in the DNC list
**Outputs:**
* `status`: The status of the get DNC operation
* `found`: Whether the phone number was found in the DNC list
* `phone`: The processed phone number that was checked
* `created_at`: When the phone number was added to DNC (if found)
* `response_message`: Additional information about the operation result
### Register DNC
Adds a phone number to the Do Not Call list in Apten.
**Required Parameters:**
* `api_key`: Your Apten API key for authentication
* `phone`: The phone number to add to the DNC list
**Outputs:**
* `status`: Status of the DNC registration
* `processed_phone`: The processed phone number that was added to DNC
* `response_message`: Detailed response message from the operation
This action will create the lead in Apten and can automatically trigger initial AI conversations based on your customer profile settings.
## Workflow Action Example: Create a Lead
Here's a step-by-step example of how to set up the **Create Apten Lead** action in a Hubspot workflow:
### Step 1: Add the Apten Action
1. In your Hubspot workflow editor, click the **+** button to add a new action
2. In the "Browse all actions" search bar, type `apten`
3. Under **Integrated apps**, you'll see the Apten section with available actions
4. Click **Create Apten Lead** to select this action
![Apten Action Selection]()
### Step 2: Configure the Action Parameters
Once you've selected the Create Apten Lead action, you'll see the configuration form:
![Apten Action Configuration]()
### Step 3: Review and Save
After configuring all required fields and any optional parameters:
1. Click **Save** to add the action to your workflow
2. The action will appear in your workflow as a blue box with the Apten logo
3. The action card will display "Create Apten Lead" with the description "Create lead in Apten with contact information"
![Apten Action in Workflow]()
### Step 4: Test Your Workflow
1. Turn on your workflow to make it active
2. Trigger the workflow conditions (e.g., new contact creation, form submission)
3. Monitor the workflow execution to ensure leads are being created successfully in Apten
4. Check your Apten dashboard to verify the new leads appear with the correct information
This workflow action will automatically create leads in Apten whenever the workflow conditions are met, seamlessly integrating your Hubspot contacts with Apten's AI communication capabilities.
# Power Automate
Source: https://docs.apten.ai/integrations/power-automate
Connect Apten to Microsoft Power Automate to automate lead engagement workflows
## Overview
The Apten Power Automate connector enables you to automate lead engagement workflows directly from Microsoft Power Automate. You can create leads, send messages, and manage lead status without leaving the Power Platform.
Use cases include:
* Automatically create leads in Apten when new contacts appear in SharePoint, Dynamics 365, or other systems
* Send follow-up messages based on triggers from your CRM or email
* Sync lead status between Apten and your other business applications
## Prerequisites
Before getting started, ensure you have:
1. **Power Automate account with Premium license** - Custom connectors require a Power Automate Premium license (\$15/user/month) or a Per Flow license
2. **Apten account with API access** - Contact your Apten account manager if you need API access enabled
3. **Apten API key** - See the next section for how to obtain one
## Getting Your API Key
To use the Apten connector, you need an API key from your Apten dashboard:
1. Log in to your Apten dashboard at [platform.attent.app](https://platform.attent.app)
2. Navigate to **Developer Portal** in the left sidebar
3. Under "Generate New API Key", give your key a descriptive name (e.g., "Power Automate Integration")
4. Click "Request API Key"
5. Copy the generated API key
Keep your API key confidential. Do not share it or commit it to version control.
## Importing the Connector
Download the Apten connector solution:
* [Apten\_1\_0\_1\_0\_managed.zip](https://d2i88m1a7sfaw.cloudfront.net/Apten_1_0_1_0_managed.zip)
Go to [make.powerautomate.com](https://make.powerautomate.com)
In the left navigation, click **Solutions**
Click **Import solution** in the top bar
Click **Browse**, select the downloaded `Apten_1_0_1_0_managed.zip` file, and click **Next**
Review the solution details and click **Import**
The Apten connector is now available in your environment.
## Creating a Connection
Before using the connector in a flow, you need to create a connection with your API key:
1. In Power Automate, go to **Data** > **Connections**
2. Click **+ New connection**
3. Search for "Apten" and select the Apten connector
4. Enter your API key when prompted
5. Click **Create**
You can now use the Apten connector in your flows.
## Available Actions
The Apten connector provides 20 actions organized into four categories.
### Lead Management
Creates a new lead in Apten with the specified contact information.
* **Required:** Customer Profile, First Name, Phone
* **Optional:** Last Name, Email, Timezone, Additional Info
* **Returns:** Lead ID
Retrieves details about an existing lead.
* **Required:** Lead ID
* **Returns:** Lead details (name, phone, email, status, tags, etc.)
Updates an existing lead's information.
* **Required:** Lead ID
* **Optional:** Email, Timezone, Additional Info, Follow-up Config, Follow-up Step
* **Returns:** Confirmation
Permanently deletes a lead.
* **Required:** Lead ID
* **Returns:** Confirmation
Finds a lead by their phone number.
* **Required:** Phone
* **Optional:** Outbound Phone
* **Returns:** Lead ID if found
* If multiple leads match the same phone number, provide Outbound Phone to identify which lead to return.
Resubscribes a lead who previously opted out, allowing messages to be sent again.
* **Required:** Lead ID
* **Returns:** Confirmation
### Messaging & Engagement
Sends a message to a lead via SMS.
* **Required:** Lead ID, Message
* **Optional:** Scheduled Time, Send When Off, Override Business Hours
* **Returns:** Confirmation
Retrieves the message history for a lead.
* **Required:** Lead ID
* **Returns:** Array of messages with content, timestamp, and sender
Enables AI-powered messaging for a lead.
* **Required:** Lead ID
* **Returns:** Confirmation
Disables AI-powered messaging for a lead.
* **Required:** Lead ID
* **Returns:** Confirmation
Adds contextual information to help the AI better engage with the lead.
* **Required:** Lead ID, Context
* **Returns:** Confirmation
Records an event that occurred for the lead (e.g., "clicked email link").
* **Required:** Lead ID, Event
* **Returns:** Confirmation
Changes the customer profile (campaign/persona) for a lead.
* **Required:** Lead ID, New Customer Profile
* **Optional:** Resend First Touch, Reset Follow-up
* **Returns:** Confirmation
### Tags
Retrieves all tags available in your organization.
* **Returns:** Array of tags with name and color
Adds tags to a lead.
* **Required:** Lead ID, Tags (array)
* **Returns:** Updated tag list
Replaces all tags on a lead with a new set.
* **Required:** Lead ID, Tags (array)
* **Returns:** Updated tag list
Removes specific tags from a lead.
* **Required:** Lead ID, Tags (array)
* **Returns:** Updated tag list
### Do Not Contact (DNC)
Adds a phone number to the Do Not Contact list.
* **Required:** Phone Number
* **Returns:** Confirmation
Checks if a phone number is on the DNC list.
* **Required:** Phone Number
* **Returns:** DNC status and date added (if on list)
Removes a phone number from the DNC list.
* **Required:** Phone Number
* **Returns:** Confirmation
## Example Flow
Here is a simple example flow that creates a lead in Apten when a new item is added to a SharePoint list.
### Scenario
When a new contact is added to a "New Leads" SharePoint list, automatically create a corresponding lead in Apten.
### Steps
1. **Create a new flow** in Power Automate
2. **Add trigger:** Search for "SharePoint" and select **When an item is created**
* Site Address: Select your SharePoint site
* List Name: Select your "New Leads" list
3. **Add action:** Search for "Apten" and select **Create Lead**
* Customer Profile: Enter your Apten profile name (e.g., "sales-outreach")
* First Name: Select the First Name column from SharePoint (dynamic content)
* Last Name: Select the Last Name column from SharePoint
* Phone: Select the Phone column from SharePoint
* Email: Select the Email column from SharePoint
4. **Save** your flow
Now, whenever a new item is added to your SharePoint list, a lead will automatically be created in Apten with the contact's information.
## Troubleshooting
**Solution:**
* Verify your API key is correct
* Check that your API key has not been revoked in the Apten dashboard
* Create a new connection with a fresh API key
**Solution:**
* Verify the Lead ID is correct
* Ensure the lead has not been deleted
* Use the Lead Lookup action to find a lead by phone number
**Solution:**
* Add the Outbound Phone field to the Lead Lookup action
* Use the outbound phone number associated with the lead you want to retrieve
**Solution:**
* Use E.164 format for phone numbers (e.g., +15551234567)
* Include the country code
* Remove spaces, dashes, and parentheses
**Solution:**
* Add a delay between actions in your flow
* Reduce the frequency of your automated workflows
* Contact Apten support if you need higher rate limits
**Solution:**
* Check your internet connection
* Verify the Apten API is accessible
* Ensure your API key is valid and has not expired
* Try creating a new connection
**Solution:**
* Review the required fields for the action
* Ensure all required fields have values (not empty or null)
* Check that dynamic content is properly mapped
## Support
If you encounter issues not covered in this guide, contact us at [founders@apten.ai](mailto:founders@apten.ai).
When contacting support, please include:
* Your flow ID or screenshot
* The error message you received
* The action that failed
# Salesforce
Source: https://docs.apten.ai/integrations/salesforce
Integrate Apten with Salesforce.
## Overview
Connect your Apten account with Salesforce to sync information about leads and SMS conversations in Apten with any Salesforce object. Currently, we support syncing:
* **Tags**: sync tags into a field in Salesforce.
* **Summaries**: sync lead conversation summaries into a field in Salesforce.
* **Variables**: map variables to fields in Salesforce, which will sync in real-time.
* **Do not contact**: sync a lead's do-not-contact status to a boolean field in Salesforce.
Salesforce syncing works with AI conversations over SMS, voice, and email.
## Step 1: Create an Integration User in Salesforce
1. Log in to Salesforce as an administrator
2. Navigate to Setup > Users > New User
3. Fill in the required fields:
* First Name: Apten
* Last Name: Integration
* Email: \[email for the integration user]
* Username: \[unique username for integration]
* Role: \[assign an appropriate role]
* User License: Salesforce Integration
* Profile: Salesforce API Only System Integrations
4. Click "Save" to create the Integration User
## Step 2: Create a Permission Set in Salesforce
1. Navigate to Setup > Permission Sets > New
2. Create a new Permission Set:
* Label: Apten Integration Permissions
* API Name: Apten\_Integration\_Permissions
3. Click "Save" to create the Permission Set
4. Configure the Permission Set:
* Under "System Permissions", enable:
* API Enabled
* Under "Object Settings", enable:
* Read, Create, and Edit permissions for the object that you want to sync with Apten (e.g., Lead, Contact, etc.).
* Field-level Read and Edit access for every field Apten should read from or write to, including fields used for tags, summaries, variables, and do-not-contact status.
* Apten does not require "Modify All Data" or "Customize Application" permissions.
5. Assign the Permission Set to the Integration User:
* Go to Setup > Permission Sets
* Click on the "Apten Integration Permissions" Permission Set
* Click "Manage Assignments"
* Click "Add Assignments"
* Select the Apten Integration User
* Click "Assign"
## Step 3: Connect Apten to Salesforce
1. In Apten, go to **Integrations**
2. Click **Connect** on the Salesforce card
3. Authorize with the email and password for the Salesforce Integration User
4. Click **Connect**
5. Select the object that you want to sync with Apten (e.g., Lead, Contact, etc.), and click **Save** (you won't be able to change this later).
6. If you'd like to sync Tags or Summaries, click the **Set up** button next to the relevant section.
* Select the Salesforce field you want Apten to update.
* **Important: The Integration User must have field-level access to the selected field, or syncing will fail.**
## Step 4: Map Variables (Optional)
When setting up variables in customer profiles in **Build & Test**, you can map them to Salesforce fields.
These fields will automatically sync to Salesforce in real-time when Apten talks to a lead.
![Salesforce Variables]()
## Step 5: Import Leads with Salesforce IDs
When importing leads into Apten, you must set the following fields:
* `integrationSource`: Set this to `'salesforce'` to indicate the lead is from Salesforce
* `salesforceId`: Set this to the Salesforce object ID of the lead (e.g. '00Q1a000004XYZ')
Example payload:
```json theme={null}
{
"firstName": "John",
"lastName": "Doe",
"phone": "1234567890",
"customerProfile": "Test Profile",
"integrationSource": "salesforce", // Required for Sync
"salesforceId": "00Q1a000004XYZ" // Required for Sync
}
```
# Introduction
Source: https://docs.apten.ai/introduction
Welcome to the Apten API documentation!
## What is Apten?
Apten is a customizable AI SMS + voice agent that automates sales and marketing for businesses. It qualifies and nurtures leads by proactively reaching out, responding at any time, and it always remembers to follow-up. This documentation will guide you on how to setup Apten and integrate it with your existing systems programmatically.
Here are some of Apten's core features:
Learn how to use the Apten API to communicate with Apten programmatically.
Receive real-time notifications from Apten when certain events occur.
Learn how to setup custom conversational flows for each type of lead.
Learn how to train Apten with information to use in conversations with leads.
## Support
Feel free to reach out to us at any time for support or feedback. Here are some ways to get in touch:
* Email us at [founders@apten.ai](mailto:founders@apten.ai)
* Tweet or DM us at [@Apten\_AI](https://x.com/Apten_AI)
We're always happy to help!
# Call Dispositions
Source: https://docs.apten.ai/tutorials/call_dispositions
Classify completed calls using prioritized system and AI conditions.
## Overview
Call dispositions automatically classify completed voice calls into the categories you define. Use them to identify outcomes such as qualified leads, completed transfers, or calls that need follow-up.
When a call is finalized, Apten evaluates your dispositions from top to bottom. The first disposition whose conditions all match is applied to the call. Calls that do not match any disposition are assigned the built-in **Other/Unknown** disposition.
## Configure Call Dispositions
1. Go to **Call Dispositions** in the left sidebar.
2. Turn on **Enable Call Dispositions**.
3. Click **New Disposition**.
4. Enter a **Name** and optional **Description**, and choose a color.
5. Add one or more conditions that identify calls for this disposition.
6. Click **Save**.
Repeat these steps for each disposition you need. Drag dispositions into priority order: Apten applies the first matching disposition.
**Other/Unknown** is always the final fallback disposition and cannot be edited, deleted, or reordered.
## Choose Conditions
Each disposition can combine call attributes and AI conditions. All conditions on a disposition must match for Apten to apply it.
### Call Attributes
Call Attribute conditions use data already recorded for the call:
* **Call outcome** — matches `No Answer`, `Busy`, or `Voicemail`.
* **Hit call screener** — matches whether the call encountered a call screening service.
* **Successfully transferred** — matches whether the call was successfully transferred.
* **Direction** — matches inbound or outbound calls.
* **Duration in seconds** — matches calls that are greater than, greater than or equal to, less than, or less than or equal to a duration you set.
* **Transfer type** — matches `Cold` or `Warm` transfers.
### AI Conditions
AI conditions evaluate the transcript of a finalized call against reusable criteria you write. For example, you could create an AI condition named **Appointment requested** with the criterion: “The lead agreed to schedule a follow-up appointment.”
To create one:
1. Open the **AI Conditions** tab.
2. Click **New AI Condition**.
3. Enter a name and describe the criterion in plain language.
4. Save the condition, then add it to one or more dispositions.
You can reuse an AI condition across multiple dispositions. If an AI condition is in use, remove it from those dispositions before deleting it.
## Monitor Dispositions
Each classified call stores its disposition name and the time it was classified. To notify another system when a disposition is applied, subscribe to the [`call.dispositioned`](/webhooks/call-dispositioned) webhook event.
# Contact Card
Source: https://docs.apten.ai/tutorials/contact_card
Let Apten text your company contact card so leads can save your details
## Overview
The **Send Contact Card** tool lets Apten share your business contact as a vCard over SMS or during a voice call. Leads receive an MMS attachment that they can open and save directly to their phone’s contacts.
Use it when a lead asks for your number, email, or how to reach you — without pasting a long block of contact text into the chat.
## Enable Send Contact Card
Contact cards are **opt-in per profile**. Add the tool under **Global Tools** on the profile flowchart:
1. Go to **Build & Test** and open the customer profile
2. Click **Edit Profile**
3. On the flowchart, open the **Tools** section
4. Under **Global Tools**, add **Send Contact Card**
5. Open **VCards Settings**, which appears after you add the tool
![Send Contact Card selected under Global Tools]()
Apten only sends a contact card when this tool is enabled for the profile.
Leads who have opted out of SMS will not receive one.
## Configure the Contact Card
Use **VCards Settings** to control how the saved contact appears:
* **Name** is required and defaults to the AI name configured in **Settings**.
* **Company Name** is optional and defaults to your organization name.
* **Contact Card Image** is optional. Upload a **PNG, JPG, or GIF** up to **200KB**.
![VCards Settings with name, company name, and image fields]()
Replace either default if you want to use different profile-specific information. Publish the profile to make the updated card available in conversations and calls.
### Required name validation
Every enabled contact card must have a name. If the field is empty, Apten highlights both the field and the settings section and prevents the profile from being published until you add one.
![Required name validation in VCards Settings]()
Keep the image small (200KB max). Larger files can fail over MMS. WebP is not
supported for contact cards.
## What the Card Includes
The card uses the published settings for the profile assigned to the conversation:
* The name, company name, and optional image from **VCards Settings**
* The business phone number assigned to the conversation, or your organization’s main number
* Your organization’s email address and website when available
Because the settings are profile-specific, different profiles can send different contact identities.
## How It Works in Conversations and Calls
When a lead asks for contact information and the tool is enabled, Apten can send the company contact card and briefly confirm that it was sent.
During a voice call, Apten texts the card to the phone number associated with the caller. Contact cards cannot be delivered to landlines or to leads who have opted out of SMS.
Each successful send is recorded in the conversation history, giving Apten context that the card was already shared.
## What You See in the Dashboard
Sent contact cards appear in the conversation timeline as a **Contact card** entry, not as a long text message.
![Contact card entry in the conversation timeline]()
## What the Lead Sees
On the lead’s phone, the contact card arrives as an MMS attachment they can open and save.
![Contact card attachment received on a phone]()
On some iPhones, the SMS thread may show a letter monogram until the lead
opens the contact. The photo (if you uploaded one) appears when they open or
save the contact — this is normal iPhone MMS behavior, not a missing image.
## Related
* [Customer Profiles](/tutorials/customer_profiles) — profile description, flowchart, and settings
# Custom Knowledge
Source: https://docs.apten.ai/tutorials/custom_knowledge
Learn how to train Apten with information to use in conversations with leads.
## Overview
Custom Knowledge is where you feed Apten with information/instructions you want it to know across conversations with all leads (any customer profile).
There are 2 main components to Custom Knowledge:
1. Description: this is a good place to put things like information about your business, FAQs, any specific instructions you want it to follow.
2. Connect your data: this is a scalable way to pass information to Apten that it then references in lead conversations when leads ask questions.
## Description
There are 2 main types of information you would put into the Custom Knowledge description:
1. Information that you want Apten to know
* Examples:
* General information about your business:
* "Apten is an AI SMS agent that automates sales and marketing. You can customize a conversational flow that it uses to communicate with leads, and you can pass it information about your business for it to reference in conversations. The company's website is [https://www.apten.ai/](https://www.apten.ai/)."
* "Business hours are Monday to Friday, 9 AM to 5 PM PST"
* FAQs (use a format like the example below):
* "Q: Does Apten provide any onboarding/support?
* A: Each Apten customer gets white glove onboarding/support directly from the founders :)"
1. Specific instructions
* You can think of this as any specific prompt you would give to ChatGPT. Usually, they are structured as commands (e.g. "if \_\_, then \_\_\_", "make sure to...", "you must say \_\_ when...")
* Specific examples:
* "If the lead asks about scheduling a demo or meeting, you can share this link for them to self-schedule: [https://calendly.com/daniel-attent/20min](https://calendly.com/daniel-attent/20min)"
* "Make sure to be empathetic and understanding if the lead raises any concerns"
**Custom Knowledge Description in Apten:**
![]()
## Connect Your Data
This part of custom knowledge allows you to **connect entire files** that then serve as Apten's knowledge base when talking to leads/customers.
### How it works:
Anytime a lead asks a question, Apten will:
* First search through the information it has in custom knowledge.
* If it feels it hasn't the found the right information to answer that question, Apten will then search through all the information that's been connected as a file.
* Apten will then extract any info it thinks is relevant to the lead's question, and use that info to give an answer back to the lead.
### Steps for setup:
1. Click the 'Connect your Data' button on the bottom left of the Custom Knowledge section
2. Choose a data source to connect information from (File Upload, Web Scrape, Google Drive, Salesforce)
3. Add any relevant files you want Apten to know
4. Apten will then automatically start syncing those files to its knowledge base
A popup like this should appear when you click 'connect your data'.![]()
Other notes:
* \*When adding files, a good best practice is to split up files by topic, and make sure to name each file accordingly.
* After adding files, you can delete existing files or add new files as needed.
# Customer Profiles
Source: https://docs.apten.ai/tutorials/customer_profiles
Learn how to setup/customize customer profiles for each type of lead
## Overview
A customer profile allows you to customize the conversation Apten has with a specific type of lead. Each customer profile can be thought of as a specific persona. For example, in real estate, some example customer profiles would be 'Buyer', 'Renter', or 'Seller'.
## How Customer Profiles work
There are 3 main components to a customer profile to setup:
1. Profile description: share context with Apten on who it's talking to
2. Conversational flow: define exactly how you want the AI to communicate with the lead depending on their responses
3. Follow-up config: customize the timing and manner in which Apten automatically follows up
## 1. Profile Description
This is where you give Apten info about the specific type of lead it's talking to (example below). You can also share specific instructions or info that Apten should know about that lead.
![]()
## 2. Conversational Flow
This is the most important part of the customer profile, since it is how Apten’s entire conversation with a lead is structured.
A conversational flow is composed of nodes that are connected together. There are 3 main types of nodes:
* Message node: instruct Apten what to say at each stage in the conversation
* Condition node: describe the types of responses from the lead you want Apten to look for
* Webhook node: connect Apten to an external system/API at a specific point in the convo
### Message node
* Each message node can be thought of as an independent AI agent that is trying to accomplish a specific objective. You customize the agent in each message node with a prompt/set of instructions.
* For example: ‘Introduce yourself to the lead and ask if they are still looking for an apartment'
* Objectives for each message node are typically automatically determined by the prompt you give it, but you can also give each message node a specific objective to accomplish.
* For example: Your objective is not complete until the lead has indicated whether or not they are looking for an apartment.
* If the lead asks an off-topic question unrelated to what Apten asks or says in a message node, Apten will automatically address their question/issue first based on what it has in custom knowledge, but will then guide the lead back on topic to its original objective.
* For example:
* Lead: How did you get my information again?
* Apten: You filled out a lead form on our website inquiring about apartments in San Francisco - are you still looking?
* **Variables**
* Apten can dynamically set variables in message nodes. Variables are set as either a string, number, or boolean. Each variable is set based on a description in English that you give.
![]()
* Apten is able to reference variables dynamically in its messages.
* For example: Tell the lead 'Hey (firstName), this is (yourName) from Bob's Real Estate Company. Are you still looking for apartments in (city)?'
What a message node looks like in Apten:
![]()
### **Condition Node:**
* A condition node is a description in English of the type of response you are looking for from a lead after a message node.
* For example:
* Apten asks if lead is looking for an apartment in a message node
* Definition of a condition node after: 'Lead indicates in any sort of way that they are still looking for an apartment/rental'
* Condition nodes are created by dragging the dot below a message node down and then selecting condition node on the top right. You can also add more than one node in a condition node tree.
**\*No condition nodes serve as a catch all for all the other scenarios that are not caught by the condition nodes you've specified.**
(insert creating condition node gif here)
### Webhook Node:
A webhook node allows Apten to connect to an external system/API at a particular point in the conversation to either take an action or pull in relevant info.
See image below for webhook node parameters.
Important note: You can **pass in variables** Apten has collected in a previous message node to the **Body or Query Params** in the webhook, you just need to reference them with double brackets. For example, \{\{city}}.
![]()
You are also able to have Apten reference one of the **Response Variables** that the webhook node returns in a subsequent message node.
Example:
* Apten has collected apartment preferences from a lead through variables in a message node
* Plug in a Zillow API to pull in relevant properties that fit their criteria.
* Use the response variable from the webhook node step in the next message node to have Apten share relevant properties with the lead
![]()
Another common example use case for a webhook node:
* Apten has pre-qualified the lead to a point where they are now ready for a phone call
* Use a webhook node to pass the lead off to a dialer to connect them w/ a human.
![]()
## **3. Follow-up Config**
This optional to configure because there's a default follow-up schedule built into Apten, but adjusting follow-up config allows you to customize the timing and content of Apten's follow-ups.
\*Note: Apten already **automatically uses the context it has about a lead + any past conversations to personalize its follow-up messaging.**
The follow-up schedule can be customized per profile. For each follow-up step, you can customize the timing and the channel (text, call, or email).
![]()
### Timing
Apten will execute each follow-up step in sequential order **if the lead does not respond** to a message.
* You can add additional steps with the '+' sign below, and you can customize the timing of each step.
* You can also move the order of the steps around by dragging around the 3x2 set of dots on the left of each step.
![]()
**Dynamic Follow-ups + Long-Term Followup**s
Both of these are already built into Apten automatically (no setup needed)
* Dynamic follow-ups: Apten is able to dynamically schedule follow-ups based on a lead's message.
* For example:
* If the lead says something like 'I am traveling right now and won't be free for the next couple of weeks' -> Apten will automatically schedule a follow-up for 2 weeks later. This follow-up is **added to the front** of the follow-up schedule as an extra step.
* Long-term follow-ups: Apten is able to automatically determine whether it makes sense to follow-up in a shorter term timeframe or do a longer term follow-up (once per month)
### Email Settings
If email features are enabled for a profile, use **Sender Address** to choose which verified sending domain the profile uses. This setting is available when your organization has enabled multiple sending domains.
* **Use organization default** — the profile follows future changes to the organization's default sender.
* **A specific sending domain** — the profile uses that domain's sender address.
If a profile's selected domain becomes unavailable, Apten uses the organization's default sender until you select another eligible domain.
### Other optional profile settings:
* Messaging style: customize how Apten responds (e.g. keep responses concise, friendly, etc)
* Guardrails: attach any guardrails you've setup to make sure AI messages follow certain guidelines/rules (see[ here](https://docs.apten.ai/tutorials/guardrails) for more info)
* Transfer call number: if you have AI voice enabled, set a number here for Apten to transfer to automatically whenever the lead wants to speak w/ a human
![]()
## Profile variants
Profile variants are independent copies of a base profile that you can use to try different settings with new leads. A base profile can have up to three active variants. You can edit each variant without changing its base or the other variants.
### Create and edit variants
In **Build & Test**, open a base profile and select **Variants**. Choose **Create a variant** and enter a name. The new variant starts as a copy of the base profile. Use the profile selector at the top of the editor to switch between the base and its variants while editing.
![Variants tab on a base profile in Build & Test]()
![Profile selector showing a base profile and its variant]()
### Compare profile settings
Use the **Compare** controls on the Variants tab to compare the base profile with selected variants. Switch between **Settings** and **Flow Chart** to inspect their configurations side by side; differences are highlighted. This view compares profile setup. For lead performance, use **Optimize > Compare Profiles > Variants**.
![Compare controls for a profile and its variant]()
![Side-by-side settings comparison highlighting differences]()
### Set import weights
Set an import weight for the base profile and each active variant. The weights must total 100%, and a new variant starts at 0%. In the example below, new leads are allocated using an 80% base and 20% variant split. During **Import new leads**, enter the base profile name in the CSV’s **Customer Profile** column to use these weights. Changing weights affects new imports, not leads already assigned to a profile.
![Import weights set to 80 percent for the base profile and 20 percent for a variant]()
### Retire and restore variants
Retire an active variant to remove it from future imports. Its import weight returns to the base profile, and existing leads stay assigned to that variant. Retired variants appear in the **Retired** list with their assigned-lead counts. Choose **Restore** to reactivate a variant; it returns at 0% import weight. A base profile can have no more than three active variants.
![Retired variant with its assigned-lead count and Restore action]()
# Guardrails
Source: https://docs.apten.ai/tutorials/guardrails
Learn how to set up AI guardrails to ensure safe and compliant conversations.
## Overview
Guardrails help you control your AI's behavior by preventing unwanted responses. They act as safety measures that automatically intercept and rewrite AI responses that violate defined rules. Common use cases include:
* Preventing unauthorized discounts or promotions
* Protecting sensitive information
* Ensuring compliance with company policies
![]()
## How Guardrails Work
1. **Define Guardrails**: Create rules and examples of what constitutes a violation
2. **Attach to Profiles**: Apply guardrails to specific customer profiles
3. **Automatic Protection**: AI responses are automatically intercepted and rewritten when violations are detected
![Guardrails Page]()
## Step 1: Creating a Guardrail
1. Navigate to **Settings > Guardrails**
2. Click **Create Guardrail**
3. Fill out the following fields:
* **Name**: Enter a short, descriptive name (e.g., "No Discounts")
* **Violation Definition**: Write a clear description of what constitutes a violation
* **Examples**: Add sample messages that would trigger the guardrail
For a discount prevention guardrail, you might configure it like this:
**Name**: Discounts
**Violation Definition**: AI provides discounts or promises of discounts
**Examples**:
* User: "Can you give me a discount?"
* User: "Can I get \$5 off?"
* AI: "Sorry about all the trouble. I'm happy to give you a \$5 off promotion."
## Step 2: Attaching Guardrails to Customer Profiles
1. Go to **Build & Test**
2. Select the customer profile you want to protect
3. In the profile settings, find the **Guardrails** section
4. Select the guardrails you want to apply
5. Click **Save**
You can apply different combinations of guardrails to different customer
profiles, allowing for flexible safety controls across your AI conversations.
## Step 3: Test and Iterate
Test a conversation to see your guardrails in practice and ensure they're working as expected. Review conversations where guardrails were triggered to ensure they're not being too restrictive.
When a guardrail is triggered, there is an indicator. Clicking on the indicator shows the exact message that triggered the guardrail, and what it was rewritten to.
![Guardrail Example]()
## Monitoring Guardrails
You can monitor guardrail performance in the **Metrics > Guardrails** page. Here you can see all guardrail violations across all conversations, with details on the exact message that triggered the guardrail, and what it was rewritten to.
![Guardrail Metrics]()
## Best Practices
1. **Clear Definitions**: Write violation definitions that are specific and clear
2. **Diverse Examples**: Include various examples of both user messages and AI responses that would trigger the guardrail
3. **Regular Testing**: Test your guardrails to ensure they're working as expected
4. **Avoid Negatives**: When writing definitions, use positive language about what should happen rather than what shouldn't
5. **Monitor Performance**: Review conversations where guardrails were triggered to ensure they're not being too restrictive
## Example Guardrails
Here are some example guardrails:
### Data Privacy
**Name**: Data Privacy
**This guardrail is violated when...**: AI requests sensitive customer information or shares sensitive customer information.
**Examples**:
* AI: "Could you share your social security number?"
* AI: "I can see your full credit card number is..."
# Lead Management
Source: https://docs.apten.ai/tutorials/lead_management
Select leads in bulk to turn them off, stop follow-ups, add context, switch profiles, or send messages
## Overview
The **Lead Management** page lets you act on many leads at once. Filter to find the leads you want, select them, and run a bulk action. If you already have a list of lead IDs, you can upload a CSV instead.
Available actions:
* **Turn off leads** — stop all outreach to the selected leads
* **Switch to no follow-up** — stop follow-ups but keep answering replies
* **Add context** — attach standing facts or instructions to each lead
* **Switch profile** — move leads to a different profile
* **Send message** — send a personalized first message
* **Import new leads** — add leads that don't exist in Apten yet (CSV only)
## Selecting Leads
1. Go to **Lead Management** and stay on the **Table** tab
2. Narrow the list using the **Created at date range** picker or the **Advanced filters** button
3. Check the leads you want to act on
![]()
To act on more leads than fit on a single page, use the **Select all … matching your filters** link above the table. It selects every lead matching your current filters and date range, not just the rows on screen.
Use **Select all … matching your filters** for large operations. If your filters match 3,000 leads across 60 pages, all 3,000 are included — you don't need to page through and check them one by one.
## Running an Action
1. With leads selected, open the **Actions** menu above the table and pick an action
2. Fill in any details the action needs, such as the context to add or the profile to switch to
3. Confirm
Actions run in the background, so you can leave the page. Progress and past runs appear on the **CSV import** tab, in the section for that action.
Each action has a limit per run:
| Action | Leads per run |
| - | - |
| Turn off leads | 10,000 |
| Switch to no follow-up | 5,000 |
| Add context | 5,000 |
| Switch profile | 5,000 |
| Send message | 5,000 |
| Import new leads | 4,000 |
If your selection is larger than the limit, narrow your filters and run the action in batches.
## Switch to No Follow-Up
Apten stops sending follow-ups to the selected leads and cancels any that are already scheduled. Unlike turning a lead off, Apten still reads and answers their replies.
![]()
Use it when you want to stop chasing a set of leads without going silent on them. To stop outreach entirely, use **Turn off leads** instead.
## Using a CSV Instead
Every action also accepts a CSV upload, which is useful when your list comes from another system:
1. Go to the **CSV import** tab
2. Find the action you want and download its template
3. Fill in the template and upload it
The template shows exactly which columns the action expects.
### Import New Leads Across Profile Variants
For a profile with variants, enter the **parent profile name** in the CSV’s **Customer Profile** column. Apten assigns each new lead to the base profile or an active variant according to the group’s saved import weights.
## Exporting Leads
The **Export Data** page uses the same table, filters, and selection. On the **Leads** tab, narrow and select the leads you want, then click **Export**.
![]()
Choose a scope in the **Export Options** dialog:
* **Current filters** — every lead matching your filters and date range
* **Selected** — only the leads you checked
* **All leads** — every lead in your organization, ignoring filters
![]()
You can also choose to include text transcripts. Exports run in the background and appear on the **Past exports** tab with a download link when they finish.
The **Selected** scope accepts up to 99 individually checked leads per export. To export more than that, use **Current filters**, or use **Select all … matching your filters** on the table.
# Custom Notifications
Source: https://docs.apten.ai/tutorials/notifications
Set up custom notifications to get alerted when important events happen in lead conversations.
## Overview
Custom notifications let you define alerts that fire when Apten detects a specific condition during a conversation with a lead. Instead of manually reviewing every conversation, you can have Apten watch for the moments that matter most and notify your team automatically.
Common use cases include:
* Lead expresses high buying intent or readiness to purchase
* Lead requests to speak with a human
* Lead mentions a competitor
* A compliance-sensitive topic comes up in conversation
## How It Works
1. **Define a notification** with a name and a plain-English condition
2. **Apten monitors every conversation** and evaluates your conditions automatically
3. **When a condition is met**, your team is notified via email (and optionally via [webhook](/webhooks/notification-created))
## Step 1: Create a Custom Notification
1. Navigate to the **Notifications** page in the sidebar
2. In the **Create New** panel, fill in:
* **Name** — a short, descriptive label (e.g., "Demo Request" or "Competitor Mention")
* **Condition** — a plain-English description of when this notification should fire
3. Click **Submit**
Conditions are written in natural language. Apten interprets them automatically — no code or special syntax required.
**Example conditions:**
* "The lead asks to speak with a human or requests a callback"
* "The lead expresses interest in scheduling a demo or meeting"
* "The lead mentions a competitor by name"
* "The lead shares a budget or price expectation"
![Notifications Page]()
Only admin users can create, edit, or delete custom notifications.
## Step 2: Configure Email Delivery
By default, all notifications are sent to the email addresses configured for your organization.
1. Go to the **Settings** page
2. Add recipient email addresses in the **Notification Emails** field
3. Optionally, toggle **Filter Notifications** to choose which specific notifications trigger emails — useful if you only want certain alerts delivered to inboxes
## Step 3: Monitor Notification Activity
You can track how your notifications are performing in the **Metrics** page:
* **Notification chart** — shows how often each notification fires over time
* **Events table** — lists individual notification events with the lead's name, phone number, notification type, and the message that triggered it
This helps you fine-tune your conditions and understand which alerts are most valuable.
## Managing Notifications
You can edit or delete existing notifications at any time from the **Notifications** page:
* Click the **edit** icon to update a notification's name or condition
* Click the **delete** icon to remove a notification
Changes take effect immediately for all future conversations.
## Webchat Notifications
Custom notifications can also monitor webchat conversations. To enable them:
1. Go to **Settings → General**
2. Find the **Notifications** section
3. Turn on **Enable Webchat Notifications**
4. Click **Save**
Webchat notifications appear in the notification bell and link directly to the relevant webchat session. They can also be delivered to configured email recipients or through the [`webchat.notification.created`](/webhooks/webchat/notification-created) webhook. This is separate from the lead [`notification`](/webhooks/notification-created) webhook and uses webchat session fields instead of lead fields.
## Best Practices
1. **Be specific with conditions** — "The lead asks about pricing for the enterprise plan" works better than "The lead talks about money"
2. **Use descriptive names** — notification names appear in emails and metrics, so make them easy to identify at a glance
3. **Start small** — begin with 2-3 high-value notifications and expand over time. Too many alerts can cause notification fatigue
4. **Review metrics regularly** — if a notification fires too often, tighten the condition. If it never fires, the condition may be too narrow
5. **Combine with webhooks** — for programmatic integrations, configure the [notification webhook](/webhooks/notification-created) for lead conversations or the [webchat notification webhook](/webhooks/webchat/notification-created) for webchat alerts
# Common Objections
Source: https://docs.apten.ai/tutorials/optimize/common-objections
Review recurring lead objections and improve how Apten handles them.
## Common Objections
Common Objections shows recurring reasons leads hesitate or push back during conversations.
An objection is more than a simple "no." It includes a reason that explains what is blocking the lead from moving forward.
Examples of objections:
* "It's too expensive for us right now."
* "We already have a vendor for this."
* "I need approval from my manager before moving forward."
Examples that are usually not objections:
* "No thanks."
* "I'm driving, call me later."
* "How much does it cost?"
### What you can review
Each objection group shows:
* A representative summary of the concern
* The profiles where it appeared
* How many leads raised a similar concern
* The first and latest times the concern appeared
Expanding a group shows individual examples and links to the original conversations.
### How to use objections
1. Go to **Optimize > Common Objections**.
2. Review the highest-volume objection groups first.
3. Open example conversations to understand the context.
4. Update the relevant customer profile, follow-up strategy, or Custom Knowledge with better handling for the objection.
5. Archive groups that are no longer useful.
Good objection handling usually means giving Apten clearer positioning, stronger qualification logic, or better instructions for how to respond when the concern comes up.
## FAQ
### Why did the same question or objection show up under multiple profiles?
Similar objections can be grouped across profiles when the underlying concern is the same. Use the profile badges and profile filter to decide whether the fix should be shared or profile-specific.
### Can I review the original conversation?
Yes. Objection examples link back to the source conversation when available.
# Compare Profiles
Source: https://docs.apten.ai/tutorials/optimize/compare-profiles
Compare customer profile performance with an A/B testing view.
## Overview
Compare Profiles lets you compare two or three customer profiles, or a parent profile with one to three of its active variants. Both modes use the same performance metrics and lead activity to show how profiles perform with similar leads.
Compare Profiles is read-only. It helps you evaluate profile performance but does not change profile instructions, traffic allocation, or follow-up settings.
## Compare profiles
1. Go to **Optimize > Compare Profiles**.
2. Select two or three customer profiles.
3. Choose a comparison goal:
* **Voice Transfer Rate**: higher is better.
* **Hot Lead Rate**: higher is better.
* **All-Channel Opt-Out Rate**: lower is better.
4. Review the current results, traffic split, and six-week trend for each profile.
The comparison marks a profile as the winner so far when there is enough imported lead activity to compare at least two profiles. If there is not enough activity, continue collecting results before drawing a conclusion.
## A/B testing
Use Compare Profiles to evaluate profile variants during an A/B test:
* Keep the profiles focused on the same type of lead or business goal.
* Compare profiles with similar amounts of imported lead traffic.
* Choose a success metric before reviewing the results.
* Use the six-week trend to check whether a result is consistent over time.
* Review the profile instructions and conversation examples before making a change.
Avoid treating a profile as the winner when it has little or no imported lead activity. A higher rate from a small sample may not represent a reliable difference.
## Compare profile variants
Use **Variants** mode to compare a parent profile with its active variants:
1. Go to **Optimize > Compare Profiles** and choose **Variants**.
2. Select a parent profile; it is included automatically. Choose one to three of its active variants to compare with it.
3. Choose a comparison goal:
* **Voice Transfer Rate**: higher is better.
* **Hot Lead Rate**: higher is better.
* **All-Channel Opt-Out Rate**: lower is better.
4. Review the results, traffic split, and six-week trend for the parent profile and selected variants.
Create variants and set their import weights in the profile’s **Variants** tab under **Build & Test**. Retired variants can be restored from that tab. Comparisons are read-only; they do not change import weights. Only leads assigned to each selected profile contribute to its results.
## Available metrics
The comparison includes:
* Leads imported
* Positive engagement and hot lead rates
* Voice transfer rate
* SMS, voice, and email engagement
* All-channel, SMS, voice, and email opt-out rates
* Traffic split across the selected profiles
# Follow-ups
Source: https://docs.apten.ai/tutorials/optimize/follow-ups
Review follow-up performance and improve automated follow-up strategies.
## Follow-ups
Follow-ups shows weekly insights into automated follow-up performance. It helps you understand which follow-up strategies, message patterns, and schedule choices are driving replies.
### What you can review
The Follow-ups report includes:
* **Recommended Actions**: suggested changes you can review, apply, or reject
* **Strategy Performance**: reply metrics for each follow-up strategy
* **Detected Patterns**: recurring message themes in follow-up content
* **Key Observations**: trends, concerns, opportunities, and anomalies
Use the **Period** selector to switch between weekly reports. Use **Sort by** to sort metrics by message volume or reply rate.
### Recommended Actions
Recommended actions can include:
* **Update Strategy**: revise the instructions for an existing follow-up strategy
* **Optimize Schedule**: change follow-up timing, channel, or strategy assignment for a step
* **Delete Strategy**: remove a redundant or underperforming strategy
* **Create Strategy**: add a new strategy for a missing follow-up approach
* **Set Up Strategies**: add follow-up strategies for profiles that do not have them yet
Click **Review** to inspect the rationale, evidence, and exact proposed change. From the review dialog, you can apply the change or reject it with a reason.
Applying a recommendation changes live follow-up configuration. Review the proposed change and evidence before applying it.
### What applying a recommendation changes
* Applying an instruction update changes the selected follow-up strategy's instructions.
* Applying a strategy deletion removes the selected follow-up strategy.
* Applying a strategy creation adds a new follow-up strategy for the profile.
* Applying a schedule change updates the profile's follow-up configuration for the proposed step.
* Rejecting a recommendation records your decision so Apten can avoid repeating the same recommendation without stronger evidence.
### Strategy Performance
Strategy Performance compares follow-up strategies for the selected week.
Each strategy can show:
* Message count
* Reply count
* Reply rate
* Average response time
* Sample messages
* Links to source conversations
Deleted strategies can still appear in historical reports if they were active when the messages were sent.
### Detected Patterns
Detected Patterns groups follow-up messages by what the message says, not just which strategy generated it.
Each pattern can show:
* A pattern label and keywords
* Message count
* Reply rate
* Strategy breakdown
* Sample messages and reply status
Patterns are useful when strategy-level metrics are too broad. For example, one strategy might perform well overall but struggle with a specific message pattern, or a low-volume pattern might reveal a promising angle to test.
## Interpreting reply rates
Follow-up reply rates depend on where a message appears in the sequence.
A later follow-up usually reaches harder-to-convert leads because those leads already ignored earlier messages. That means a strategy used later in the sequence can have a lower reply rate and still be valuable if it uses a different angle and gets replies from people who ignored earlier messages.
Good follow-up optimization usually means:
* Put the broadest-appeal strategy earlier in the sequence.
* Use meaningfully different approaches across steps.
* Keep niche or experimental approaches for later steps.
* Remove strategies that are redundant or consistently weak after enough volume.
* Create new strategies when the data shows an uncovered message angle.
## FAQ
### Why does a rejected recommendation still appear?
Rejected recommendations remain visible in the weekly report as history. Future recommendations take that decision into account.
### Can I review the original conversation?
Yes. Strategy samples and pattern samples link back to the source conversation when available.
# Unanswered Questions
Source: https://docs.apten.ai/tutorials/optimize/unanswered-questions
Review unanswered questions and identify knowledge gaps in your AI agent.
## Overview
The **Optimize** page helps you improve Apten with real conversation data. It shows where the AI needs more information, what leads are pushing back on, and which follow-up approaches are getting replies.
Optimize has four sections:
* **Compare Profiles**: compare profile performance as an A/B testing view
* **Unanswered Questions**: questions Apten could not answer confidently
* **Common Objections**: recurring concerns or barriers raised by leads
* **Follow-ups**: weekly insights into follow-up strategy and message performance
Use the **Profile** filter at the top of the page to review all profiles or focus on one customer profile.
Optimize is most useful when you review it regularly and make small, targeted changes. For example, add one missing FAQ, adjust one customer profile instruction, or apply one follow-up recommendation, then compare future results.
## Unanswered Questions
Unanswered Questions shows questions Apten was not confident enough to answer during a conversation.
Similar questions are grouped together so you can fix the knowledge gap once instead of reviewing the same issue multiple times.
### What you can review
Each question group shows:
* A representative question
* The profiles where the question appeared
* How many times similar questions were asked
* Whether the group is active, addressed, or archived
Expanding a group shows the individual lead questions and a link to open the original conversation.
### How to address a question
1. Go to **Optimize > Unanswered Questions**.
2. Open an active question group.
3. Review the example questions and source conversations.
4. Click **Address**.
5. Add the missing answer, FAQ, instruction, or business detail.
6. Click **Save Changes**.
Saving changes updates your Custom Knowledge and marks the group as addressed.
You can also click **Mark addressed without changes** if the question is already handled somewhere else.
### Best practices
* Add Custom Knowledge only when the answer applies across your account.
* If the answer only applies to one customer profile, update that profile in **Build & Test** instead.
* Use **Archive** for old or irrelevant groups you no longer want in the active list.
* Use **Show archived** if you need to review archived groups later.
## FAQ
Why don't I see any Optimize data?
There may not be enough matching conversation or follow-up activity yet. Follow-up reports appear after the weekly report is available.
### Should every answer go into Custom Knowledge?
No. Use Custom Knowledge for facts and instructions that apply broadly. Use profile edits in **Build & Test** when the answer only applies to one profile.
### Can I review the original conversation?
Yes. Question examples link back to the source conversation when available.
# Settings
Source: https://docs.apten.ai/tutorials/settings
Configure your organization settings including AI behavior, phone numbers, email, and webchat.
## Overview
The Settings page is where you configure organization-wide preferences for your Apten account. It's organized into six tabs: **General**, **Phone Numbers**, **Email**, **Webchat**, **Voice**, and **Compliance**.
Only users with the **Admin** role can access the Settings page.
## General
The General tab controls your AI's core behavior and communication preferences.
### AI Name & Response Time
* **AI Name** — the name your AI introduces itself as in conversations.
* **Response Time Delay** — how long (in seconds) the AI waits before responding to an incoming message. This can make conversations feel more natural.
### Long-Term Follow-Ups
Toggle whether your AI should schedule follow-up messages over longer time periods to re-engage leads that haven't responded.
### Calendly Link
Add your Calendly URL so the AI can share it with leads when scheduling is relevant.
### Notifications
* **Notification Emails** — add email addresses that receive notifications when important events occur (e.g., a lead requests to speak with a human).
* **Filter Notifications** — when enabled, only sends notifications for events you've selected.
* **Notification Preferences** — choose which event types trigger email notifications, including any custom notifications you've created.
For more on setting up notifications, see [Notifications](/tutorials/notifications).
### Unsubscribe Settings
* **Custom Unsubscribe Keywords** — define additional keywords (beyond the defaults) that trigger an opt-out when a lead sends them.
* **Linked Opt-Out Channels** — when a lead unsubscribes from one channel (e.g., SMS), automatically unsubscribe them from other channels (e.g., voice) as well.
## Phone Numbers
The Phone Numbers tab lets you manage the phone numbers associated with your organization.
### Your Numbers
View all your phone numbers in a table showing the number, its type (**Primary** or **Inbound**), and the customer profile it's assigned to. Your primary number is used for outbound messages by default. Inbound numbers can each be assigned to a specific customer profile so that calls or texts to that number use the right AI configuration.
To change a number's assigned profile, click the edit button next to it.
### Purchasing Numbers
Click **Purchase Number** to search for and buy a new phone number. You can search by area code or region to find a number that matches your business location.
### Local Presence Bundles
Local presence bundles let you purchase a set of phone numbers across different area codes. When reaching out to leads, Apten automatically uses a number with a local area code matching the lead's location, which can improve answer rates.
## Email
The Email tab lets you set up verified sending domains so your AI can send emails on behalf of your organization.
### Domain Verification
1. Enter your domain name and click **Add Domain**
2. Apten provides DNS records (DKIM and SPF) that you need to add to your domain's DNS settings
3. After adding the records, click **Verify** to confirm your domain
Each domain shows its current verification status for both DKIM and SPF. Repeat these steps to add additional sending domains.
### Sending Domains
For each domain, configure a **sender prefix** (the part before the `@`) to create the sender address your emails will come from.
Choose one eligible, verified domain as the **Default sender**. Profiles using the organization default follow this choice. You can also:
* Select **Enable multiple sending domains** to allow individual customer profiles to use different eligible sending domains.
* **Retire** a sending domain that is no longer needed. The default sender cannot be retired.
* **Reactivate** a retired domain without making it the default sender.
Changing the default sender or a domain's sender prefix can change the From address on emails sent by profiles using that domain. If a profile's selected domain becomes unavailable, emails use the organization's default sender until you choose another eligible domain for that profile.
## Webchat
The Webchat tab manages API keys and configuration for your [embedded webchat widget](/webchat/overview).
### API Keys
API keys authenticate your webchat widget. Each key has:
* **Allowed Domains** — the websites where the widget can be used
* **Status** — active or inactive
You can create, edit, regenerate, deactivate, or delete keys as needed.
### Webchat Configuration
* **Webchat Customer Profile** — the customer profile used for webchat conversations.
* **Lead Conversion Profile** — optionally assign a different profile when converting webchat leads to phone outreach.
* **Greeting Message** — the first message displayed when a visitor opens the widget.
* **Auto-Conversion** — automatically convert inactive webchat conversations to phone outreach after a configurable inactivity timeout.
* **Opt-In Consent Message** — text displayed above the contact form's submit button for compliance purposes.
For detailed webchat configuration options, see [Webchat Settings](/webchat/settings).
## Compliance
The Compliance tab lets **org admins** control when Apten may contact leads and configure additional outreach checks.
### Message Timing
Configure the organization-wide schedule that automated follow-ups always respect:
* **Outreach Hours & Holidays** — set the allowed hours and days for follow-ups, and add dates when outreach should pause.
* **Time Zone** — set the organization fallback timezone for scheduling.
* **Respect Business Hours** — apply outreach windows to initial outreach as well as follow-ups.
* **Respect Holidays** — independently apply holidays and blackout dates to initial outreach.
### State-Specific TCPA Compliance
Apply state-level outreach windows, holidays, custom blackout dates, and rolling 24-hour contact limits to SMS and voice. State rules make Message Timing more restrictive for leads with a recognized state; they do not affect email. See [State-Specific TCPA Compliance](/compliance/state-specific-tcpa).
### External Compliance Checks
Configure an optional external compliance API on selected channels while Apten-managed DNC continues to apply to outbound SMS and voice. See [External Compliance Checks](/compliance/external-checks) for configuration, request signing, and failure-mode behavior.
# Tags
Source: https://docs.apten.ai/tutorials/tags
Learn how to create and manage tags to organize and categorize your leads
## Overview
Tags let you label and categorize your leads. You can use them to track lead status, segment conversations, filter exports, and trigger webhooks. There are two types of tags:
* **Manual tags** — applied by you or your team directly on a conversation
* **Condition-based tags** — applied automatically by Apten's AI when a conversation meets a condition you define
## Creating a Tag
![]()
1. Go to **Tags** in the left sidebar
2. On the right side of the page, fill in the following:
* **Name** — a label for the tag (e.g., "Interested", "Scheduled", "Not Qualified")
* **Color** — pick a color to visually distinguish the tag
3. Choose whether the tag is **manual** or **condition-based**:
* **Manual**: Toggle the manual switch on. You'll apply this tag yourself from conversations.
* **Condition-based**: Leave the manual switch off and enter a **condition** — a plain-English description of when the tag should be applied.
4. Click **Create Tag**
For condition-based tags, write the condition as a natural language statement. For example: "The lead has expressed interest in scheduling a tour" or "The lead mentioned they have a budget over \$500k". Apten will evaluate each conversation against this condition and apply the tag automatically.
## Managing Tags on Leads
![]()
You can add or remove tags directly from any conversation:
1. Open a conversation from the **Dashboard**
2. Click the **Actions** dropdown button at the top of the conversation
3. Select **Manage Tags**
4. Search for and select tags to add, or click an applied tag to remove it
You can also create new tags on the fly from the Manage Tags menu without leaving the conversation.
Tags appear as colored badges on each conversation card, making it easy to see how leads are categorized at a glance.
## Tag Metrics
Track how often tags are being applied over time from the **Metrics** page. Select the tags you want to monitor to see a chart of tag activity across a date range. This is useful for tracking trends like how many leads are being qualified or expressing interest over time.
## Integration Sync
Tags can automatically sync to your CRM when an integration is connected. Apten supports tag syncing with:
* **Salesforce**
* **HubSpot**
* **Dynamics 365**
To enable tag sync, go to **Integrations**, select your connected CRM, and toggle tag syncing on in the integration settings. See [Integrations](/integrations/salesforce) for more details.
# Warm Transfer
Source: https://docs.apten.ai/tutorials/warm_transfer
Set up AI-assisted warm transfers to brief human agents before connecting them with leads.
## Overview
A warm transfer connects a lead to a human agent through a live conference call, rather than a simple cold transfer. When enabled with the **AI Transfer Bot**, an AI voice agent calls the human agent first to brief them on the lead's context — including their name, conversation summary, and any relevant details — before connecting the call. This ensures agents are prepared and leads experience a seamless handoff.
The transfer bot is fully customizable — you can provide custom instructions
to control the briefing flow (e.g., verify agent identity, relay specific lead
details) and assign tools so the bot can look up information or take actions
during the handoff conversation.
## How It Works
1. Apten determines a transfer is needed and places the lead on hold with music (and an optional custom message)
2. The AI transfer bot calls the human agent and briefs them on the lead
3. The agent confirms they're ready to take the call
4. The bot connects the agent to the lead in a live conference
If the primary agent doesn't answer within the configured timeout, Apten can automatically try a fallback number.
The transfer bot uses voice detection to distinguish between human agents and
automated systems (voicemail, hold queues, IVRs). The bot won't begin its
briefing until it hears a human agent speak. This means if the agent's number
routes through a queue or hold system, the bot waits silently until a real
person picks up — ensuring the briefing is never wasted on a machine.
## Setup
*Configure the warm transfer bot in Profile Voice and Transfer Settings*
![]()
### Step 1: Enable Warm Transfer
1. Go to **Build & Test**
2. Select the customer profile you want to configure
3. In the profile settings, find the **Transfer** section
4. Toggle **Warm Transfer** on
### Step 2: Set a Custom Hold Message (Optional)
Once warm transfer is enabled, you can set a **Custom warm transfer hold message**. This message is read to the lead before they are placed on hold.
**Example:** "Please hold while I connect you with one of our team members."
### Step 3: AI Transfer Bot
The AI Transfer Bot is enabled by default. It uses an AI voice agent to brief the human agent on the lead's context before connecting the call. If you prefer a simple keypress prompt instead, you can toggle **Enable AI Transfer Bot** off.
### Step 4: Configure Bot Instructions (Optional)
Add custom instructions to control what the bot says or does when briefing the agent. The bot will complete these steps before asking the agent if they're ready for the transfer.
**Example:** "Ask the agent for their full name before connecting them to the lead."
### Step 5: Assign Bot Tools (Optional)
Select any tools you want available to the transfer bot during the briefing conversation. This allows the bot to look up information or take actions while speaking with the agent.
Scheduling and availability tools are not available for the transfer bot.
### Step 6: Set the Agent Response Timer
Configure how long to keep the lead on hold while waiting for a human agent to answer. The default is 60 seconds, with a maximum of 1800 seconds (30 minutes). If the timer expires and no agent has connected, the call ends — unless a fallback number is configured.
### Step 7: Set a Fallback Transfer Number (Optional)
Add a backup phone number that Apten will try if the primary agent doesn't answer within the timeout. When configured, a separate **Fallback Agent Response Timer** appears to control the timeout for the fallback attempt.
## Monitoring
When a warm transfer fails because no agent answered, Apten fires an `agent.missed_transfer` webhook event. See [Agent Missed Transfer](/webhooks/agent-missed-transfer) to set up monitoring for failed transfers.
If you have a fallback transfer number configured, Apten also fires a [`transferFallbackTriggered`](/webhooks/transfer-fallback-triggered) webhook the moment the fallback is dispatched, which is useful for real-time on-call alerting before the terminal outcome is known. This event is only emitted for warm transfers.
# Webchat Agent Capabilities
Source: https://docs.apten.ai/webchat/capabilities
Understand what your Apten webchat agent can do
## Overview
Your webchat agent uses the customer profile you selected on your API key. It follows the same conversational flow as your SMS and voice leads, but adapts its responses for chat-style conversations with concise, natural messaging.
The agent is designed to engage visitors, answer questions, and collect contact information—all while maintaining a natural, helpful conversation.
## Conversation Management
### Multi-Language Support
The webchat agent automatically detects and responds in the visitor's language, supporting the same languages available across the Apten platform.
### Context Awareness
Your agent maintains full context throughout the conversation, remembering:
* Previous questions and answers
* Information already collected
* The visitor's expressed interests and needs
* Where they are in the conversation flow
### Embedded Links
Webchat automatically converts links in agent messages into clickable links. This includes AI-generated responses and manual messages sent by your team from the Apten dashboard.
Supported link formats:
* Bare URLs, such as `https://example.com`
* Markdown links, such as `[Visit our site](https://example.com)`
Only `http://` and `https://` links are clickable. Other link types are displayed as plain text. If a URL is followed by punctuation, such as a period or comma, the punctuation is kept outside the clickable link.
Links open in a new browser tab.
Visitor messages are displayed as plain text, so URLs sent by website visitors are not clickable in the current webchat experience.
### Session Persistence
Conversations persist even when visitors navigate to different pages or refresh their browser. When a visitor returns to your site, they can continue their previous conversation without starting over.
Sessions remain active and can be resumed as long as the visitor uses the same browser and hasn't cleared their cookies.
## Contact Information Collection
When ready to collect information, the agent displays a structured form within the chat interface. Visitors fill out the form fields, which include:
**Required Fields:**
* First name
* Last name
* Phone number
**Optional Fields:**
* Email address (if enabled in customer profile settings)
### Phone Number Validation
When international phone validation is enabled in your customer profile:
* The agent validates phone number format
* Supports international phone numbers
* Requests correction if format is invalid
* Ensures contact information is accurate before proceeding
## Knowledge Base Integration
### Intelligent Information Retrieval
Your webchat agent can search and reference your connected files and knowledge base to answer visitor questions:
* Searches relevant documentation automatically
* Provides accurate answers based on your content
* Cites specific information when available
* Maintains conversation context while referencing knowledge
Connect your documentation, PDFs, and other files in **Settings > Custom Knowledge** to enhance your agent's ability to answer product or service questions.
### Handling Off-Topic Questions
When visitors ask questions outside your knowledge base or business scope:
* The agent politely acknowledges the question
* Redirects to relevant topics when possible
* Admits when it doesn't know the answer
* Focuses back on helping the visitor with their needs
### Accuracy and Reliability
The agent is designed to provide accurate information:
* Only answers questions when confident in the response
* References your documentation rather than guessing
* Falls back to "I don't know" if information isn't available
* Never fabricates or makes up information
## Human Transfer
When your customer profile has a transfer phone number configured, the webchat agent can initiate a phone call to connect visitors with your sales team.
### Transfer Requirements
To enable human transfer:
* A transfer phone number must be set in your customer profile
* The visitor must provide their phone number
* The agent determines the visitor is ready for human contact
### Transfer Process
1. Visitor requests to speak with someone or agent determines they're ready
2. Agent confirms the visitor's phone number
3. Agent checks if the transfer is within business hours (if configured)
4. Agent initiates the call and notifies the visitor
5. Your sales team receives the call with context about the conversation
### Business Hours
If business hours are configured in your customer profile:
* Transfers only occur during specified hours
* Outside hours, the agent collects contact information for follow-up
* Agent communicates expected callback timing
## Automatic Lead Conversion
When automatic lead conversion is enabled on your API key, sessions with collected contact information automatically convert to leads after a period of inactivity.
### How Auto-Conversion Works
1. **Contact Collection** - Visitor provides contact information through the contact form
2. **Inactivity Timer** - Timer starts after the visitor's last message (default: 60 minutes)
3. **Automatic Conversion** - After the timeout period, the session converts to a lead
4. **Follow-Up** - The new lead enters your automated outreach system using the lead conversion profile
### What Gets Transferred
When a session converts to a lead:
* Full chat transcript summary
* Collected contact information (name, phone, email)
* Conversation notes and context
* Visitor interests and expressed needs
* Timestamp and session duration
### Timer Reset
The inactivity timer resets whenever:
* The visitor sends a new message
* The visitor reopens the chat after closing it
* The visitor navigates to a new page and continues chatting
You can customize the inactivity timeout on your API key in **Settings > Webchat > API Keys** when enabling auto-conversion. The default is 60 minutes.
## Conversation Guardrails
Your webchat agent respects all guardrails configured in your customer profile:
* Content restrictions and topic boundaries
* Language and tone requirements
* Information disclosure policies
* Compliance and regulatory requirements
These guardrails ensure your agent maintains appropriate conversations that align with your brand and legal requirements.
## Next Steps
Customize your webchat behavior and appearance
Optimize your agent's conversation flow
Add documentation for better answers
# Webchat Overview
Source: https://docs.apten.ai/webchat/overview
Engage website visitors with AI-powered webchat conversations
## What is Webchat?
Apten's webchat widget is an embeddable chat interface that enables real-time, AI-powered conversations with your website visitors. The webchat agent automatically engages visitors, follows your conversation flow, collects contact information, and seamlessly integrates with your existing Apten platform.
Once installed on your website, the webchat widget appears as a chat bubble that visitors can click to start a conversation. Your AI agent responds instantly, answering questions and guiding visitors through your sales process—all while you focus on other priorities.
## Key Features
Engage every website visitor instantly, even outside business hours
Guide visitors through your custom conversation flow
Gather contact information through conversational forms
Conversations continue seamlessly across page reloads
Convert sessions with contact information to leads for follow-up outreach
Transfer hot leads to your sales team in real-time
Answer questions using your documentation and files
Match your brand with custom colors, themes, and positioning
## How It Works
1. **Visitor Engagement** - A visitor clicks the chat bubble on your website
2. **AI Conversation** - Your Apten agent greets them and starts a natural conversation
3. **Conversation Flow** - The agent follows your customer profile's conversation flow
4. **Contact Collection** - The agent collects contact information through a form
5. **Lead Conversion** - The session converts to a lead for automated follow-up
6. **Dashboard Management** - Monitor all conversations in your Apten dashboard
## Getting Started
Ready to add webchat to your website? Follow our [setup guide](/webchat/setup) to get started in minutes.
Want to understand what the agent can do? Explore [webchat capabilities](/webchat/capabilities).
Need to customize settings? Check the [configuration reference](/webchat/settings).
Building a real-time integration? See the [Webhooks Overview](/webhooks/overview) for the webchat events your system can subscribe to.
# Configuration Settings
Source: https://docs.apten.ai/webchat/settings
Complete reference for webchat configuration options
## Webchat Key Settings
Each webchat API key holds its own configuration. Manage keys in **Settings > Webchat > API Keys** and edit these fields in the Create or Edit key dialog.
### Webchat Customer Profile
The customer profile used for conversations on this key. Defines your agent's behavior, tone, and conversational flow.
### Lead Conversion Profile
A separate customer profile used when converting webchat leads to phone outreach, so you can use different messaging for chat versus follow-up calls.
**Default:** Uses the webchat customer profile.
### Greeting Message
The first message displayed when a visitor opens the chat, shown before the agent responds.
**Default:** "How can I help?"
### Opt-In Message
A consent message displayed above the submit button on the contact form. Use this to collect explicit consent before capturing contact information — commonly required for [TCPA](https://www.fcc.gov/general/telemarketing-and-robocalls) compliance.
**Default:** None
### Enable Auto-Conversion
Automatically convert webchat sessions with collected contact information to leads after a period of inactivity. When disabled, sessions must be manually converted.
**Default:** Disabled
### Inactivity Timeout
Minutes of inactivity before a session auto-converts to a lead. Only applies when auto-conversion is enabled. The timer resets whenever the visitor sends a message.
**Default:** 60 minutes
**Range:** 15-1440 minutes (1 day)
### Send SMS on Duplicate Conversion
When a webchat session converts and the contact already exists as a lead, send that existing lead an SMS.
**Default:** Disabled
### Allowed Domains
Whitelist of domains authorized to use this API key. This prevents
unauthorized use of your webchat widget.
**Domain Format Options:**
| Format | Example | Matches |
| - | - | - |
| Exact domain | `example.com` | Only `example.com` |
| With subdomain | `www.example.com` | Only `www.example.com` |
| Wildcard subdomains | `*.example.com` | `www.example.com`, `app.example.com`, `blog.example.com`, etc. |
| Multiple domains | `example.com`, `example.org` | Both domains |
**Security Note:** `example.com` does NOT automatically include
`www.example.com`. Add both or use `*.example.com` to cover all subdomains.
**Best Practices:**
* Add all domains where you'll deploy the widget
* Use wildcards for subdomain flexibility
* Don't add domains you don't control
* Review and remove old domains when sites are retired
### Active Status
Enable or disable this API key. Inactive keys cannot authenticate requests.
**Default:** Active when created
**Use Cases for Disabling:**
* Temporarily disable webchat on specific sites
* Rotate keys by creating new key before disabling old one
* Respond to security concerns quickly
* Control access without deleting key history
### Usage Tracking
Monitor your API key activity:
* **Request Count** - Total number of authenticated requests
* **Last Used** - Timestamp of most recent usage
* **Created** - When the key was generated
Use this information to:
* Identify unused keys
* Monitor webchat traffic
* Detect unusual activity
* Track deployment across multiple sites
## Widget Appearance Settings
Configure widget appearance in your website's integration code by setting `window.AptenWidget` properties.
### theme
Controls the overall color scheme of the widget.
**Options:** `"light"`, `"dark"`
**Default:** `"light"`
The theme automatically adjusts:
* Background colors
* Text colors
* Border colors
* Shadow styles
* Icon colors
**Light Theme:** Best for bright, clean websites
**Dark Theme:** Best for dark-themed sites or evening/night users
### position
Controls where the chat bubble appears on the page.
**Options:** `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`
**Default:** `"bottom-right"`
**Choosing Position:**
* **Bottom-right:** Standard position, familiar to most users
* **Bottom-left:** Alternative if right side has other widgets
* **Top-right:** Unusual but visible above the fold
* **Top-left:** Rare, use if layout demands it
Test different positions on mobile devices. Bottom positions are generally
more accessible on mobile screens.
### primaryColor
Custom brand color for buttons, accents, and highlights.
**Format:** Hex color code (e.g., `"#0073CF"`)
**Default:** Apten blue
The primary color is used for:
* Chat bubble background
* Send button
* Active states
* Links and accents
* User message bubbles
**Color Tips:**
* Use your brand's primary color for consistency
* Ensure sufficient contrast with background
* Test readability on both light and dark themes
* Hover and active states are automatically calculated
**Example Values:**
* `"#0073CF"` - Professional blue
* `"#10B981"` - Friendly green
* `"#8B5CF6"` - Modern purple
* `"#EF4444"` - Bold red
## Customer Profile Settings
These settings are configured in your customer profile but directly affect webchat behavior. Edit them in **Settings > Customer Profiles**.
### Tone and Messaging Style
Your customer profile's tone settings determine how the webchat agent communicates:
* **Conversation style** - Formal, casual, friendly, professional
* **Message length** - Concise chat messages vs. detailed explanations
* **Emoji usage** - Whether agent uses emojis in responses
* **Personality traits** - Helpful, enthusiastic, serious, etc.
For webchat, shorter messages with frequent back-and-forth work better than
long-form responses. Consider creating a dedicated webchat profile with
chat-optimized messaging.
### Email Requirement
Whether email address is required for contact collection.
**Location:** Customer Profile > Contact Settings
**Default:** Optional
**When to Require Email:**
* Email is your primary follow-up channel
* You send automated email sequences
* You need email for your CRM
**When to Make Optional:**
* Phone is your primary contact method
* Reduce friction in contact collection
* Some visitors are reluctant to share email
### Transfer Call Number
Phone number to call when agent transfers a visitor to human sales team.
**Location:** Customer Profile > Transfer Settings
**Format:** E.164 format (e.g., +1234567890)
**Required for:**
* Human transfer capability
* "Talk to sales" requests
* Escalations from agent to human
**Not required if:**
* You don't offer human transfers from webchat
* You only want automated lead capture
### Guardrails
Configure content restrictions and conversation boundaries in your customer profile:
* **Topic restrictions** - Subjects the agent should avoid
* **Content policies** - Language and behavior rules
* **Disclosure requirements** - Required disclaimers or notices
* **Compliance rules** - Industry-specific regulations
These guardrails ensure your webchat agent maintains appropriate, brand-aligned conversations.
## Next Steps
Learn about webchat features and use cases
Install the webchat widget on your website
Understand what your webchat agent can do
Configure your agent's behavior and conversation flow
# Setup and Integration
Source: https://docs.apten.ai/webchat/setup
Add the Apten webchat widget to your website in minutes
## Prerequisites
Before setting up webchat, ensure you have:
* An active Apten account
* A website where you can add JavaScript code (access to edit HTML)
* At least one [customer profile](/tutorials/customer_profiles) configured for webchat conversations
## Step 1: Create an API Key
API keys authenticate your website, hold your webchat configuration, and protect against unauthorized use. In **Settings > Webchat > API Keys**, click **Create API Key** and configure:
**Allowed Domains** (required) — Domains authorized to use this key.
* Specific domain: `example.com`
* All subdomains: `*.example.com`
* Add multiple domains to one key
**Webchat Customer Profile** (required) — The customer profile that handles conversations on this key. Defines the agent's tone and conversational flow.
**Lead Conversion Profile** — Customer profile used when converting webchat leads to phone outreach. Defaults to the webchat customer profile.
**Greeting Message** — First message shown when a visitor opens the chat. Default: "How can I help?"
**Opt-In Message** — Consent message displayed above the contact form submit button. Commonly used for TCPA compliance.
**Enable Auto-Conversion** — Automatically convert sessions with contact info to leads after a period of inactivity.
**Inactivity Timeout** — Minutes of inactivity before auto-conversion (default: 60, range: 15–1440). Only applies when auto-conversion is enabled.
**Send SMS on Duplicate Conversion** — When a session converts and the contact already exists as a lead, send that existing lead an SMS.
Click **Save** and copy your generated API key.
Not sure which profile to use? Learn more about [customer
profiles](/tutorials/customer_profiles) and how to configure them for webchat.
**Keep your API key secure!** Never commit API keys to public repositories or
expose them in client-side code that could be copied. The widget code on your
website is safe because domain whitelisting prevents misuse.
See the [configuration reference](/webchat/settings) for full details on each field.
## Step 2: Add Widget to Your Website
Copy the integration code below and paste it before the closing ` ` tag on every page where you want the webchat widget to appear.
### Basic Integration
```html theme={null}