# Cloudflare Workers AI
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/cloudflare

Prepare a Cloudflare Workers AI Chat Completions candidate and test it through the supported custom-model connection probe.

Cloudflare Workers AI exposes a public Chat Completions API. Use this page to prepare a candidate endpoint for Threetone's dashboard connection probe. Provider API availability does not establish a supported Threetone runtime integration.

<Note>
  Custom-model publication is currently rejected with `custom_llm_execution_unavailable`. A successful connection test does not publish an agent or start a conversation.
</Note>

## Prepare the candidate

| Threetone field | Candidate value |
| - | - |
| Server URL | `https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/v1`, with your account ID substituted. |
| Model ID | The exact Workers AI identifier for a chat-capable model available to your account. |
| API Key | A workspace secret or Secret environment reference holding the authorized Cloudflare API token. |

Cloudflare documents the account-specific base URL and bearer-token authentication in its [API compatibility reference](https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/). Use a text-generation model, not an embedding model. Do not paste the full `/chat/completions` endpoint into Server URL; Threetone appends that path.

## Run a controlled probe

<Steps>
  <Step title="Confirm account access">
    Check the account ID, model access, and token permissions with the account owner. Keep the token in approved secret storage. Do not place it in an agent prompt or a public example.
  </Step>

  <Step title="Enter the custom configuration">
    Open the agent's LLM selection, choose **Custom LLM**, and fill the fields above. Follow the [custom-model workflow](/agents-platform/advanced/custom-models/overview). Secret environment references resolve against production during the probe, so verify that value before testing.
  </Step>

  <Step title="Test and inspect">
    **Test connection** makes a real provider request and can consume provider usage. The probe requests a streaming text response with `stream_options.include_usage: true`. Verify that the selected endpoint accepts this request and produces assistant text; ordinary JSON or a tool-only stream does not pass.
  </Step>
</Steps>

For failures, distinguish an incorrect account path, insufficient token access, unavailable model, and incompatible streaming response. Keep safe error details without the token. Review [endpoint compatibility](/agents-platform/advanced/custom-models/compatible-endpoints) before changing the endpoint shape.

Preserve a reviewed candidate as a complete server draft and read it back. Use [the managed model catalog](/overview/models) when selecting currently documented managed options.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use a Workers binding as Server URL?">No. The probe calls a public HTTPS API base URL. A Workers binding is a different execution interface.</Accordion>
  <Accordion title="Does Cloudflare Responses API support make it usable by this probe?">No. The current Threetone probe accepts Chat Completions only. Provider support for another API does not change that boundary.</Accordion>
</AccordionGroup>


# Endpoint compatibility
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/compatible-endpoints

Review the supported custom-model probe format, URL shape, credential references, and provider compatibility.

Check the endpoint's actual protocol rather than assuming compatibility from a provider or model name. The current Threetone probe supports Chat Completions only.

| Setting | Current probe requirement |
| - | - |
| API type | `chat_completions`; Responses and WebSocket types are rejected by probe policy. |
| Response | Streaming Chat Completions with `stream_options.include_usage: true` and a nonempty assistant text delta. |
| URL | Public HTTPS API base URL, without credentials or a private-network destination. |
| Model ID | A nonempty string without surrounding whitespace, at most 256 characters. |
| API key | None when the endpoint needs no key, or a supported workspace secret or Secret environment reference. |
| Request headers | Permitted literal or credential-reference headers; reserved and dynamic headers are rejected. |
| API version and auth connection | Not supported by the current probe. |

The streamed response must use SSE data with a nonempty assistant text delta. An ordinary JSON response or a stream containing only tool calls does not satisfy the current probe.

For example, `https://models.example.com/v1` illustrates a base URL. It is not an operational Threetone endpoint. Review the provider's current Chat Completions documentation for the model identifier and response shape.

The probe resolves environment references using the workspace's production environment. Review that value before testing; the probe does not select an environment from a future deployment.

<Frame>
  <img alt="Recording pending for Inspect a custom-model connection probe. No playable video is available yet." />
</Frame>

## Provider review

Cloudflare Workers AI, Groq, Together AI, SambaNova, or a self-hosted endpoint may expose different authentication, routing, model, and parameter conventions. Select a provider only after checking the required base URL, available protocol, credential scope, rate limits, and data-processing terms. Provider compatibility must be demonstrated; it is not guaranteed by this list.

Keep a controlled probe result with the endpoint configuration and model identity. Retest after changing the endpoint, credential reference, model ID, or headers. A previous success belongs to that earlier configuration.

<Frame>
  <img alt="Screenshot pending for custom model endpoint. This illustration is not a product screenshot." />
</Frame>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a schema alternative mean the probe supports it?">No. The broader authoring schema includes alternatives that current executable probe policy rejects. Use the requirements above for that probe.</Accordion>
  <Accordion title="Does the endpoint probe validate every tool and speech feature?">No. It tests a bounded model request. Agent publication, tool behavior, voice processing, and live execution require separate support.</Accordion>
</AccordionGroup>


# Groq
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/groq

Prepare a Groq chat model, protected API-key reference, and streaming connection probe without assuming runtime compatibility.

Groq offers a Chat Completions API at a documented compatibility endpoint. Prepare the candidate below and use Threetone's dashboard probe to check the specific model and credentials.

<Note>
  Connection testing is available, but custom-model publication and execution are unavailable. A successful probe is not a provider compatibility guarantee or a production release.
</Note>

## Candidate settings

| Threetone field | Candidate value |
| - | - |
| Server URL | `https://api.groq.com/openai/v1` |
| Model ID | The exact chat model ID currently enabled for your Groq account. |
| API Key | A workspace secret or Secret environment reference containing the Groq API key. |

Use the base URL from [Groq's compatibility documentation](https://console.groq.com/docs/openai). Keep `/chat/completions` out of Server URL. Groq documents differences in supported parameters; compatibility with a client library does not mean every request or model feature is interchangeable.

## Check the connection

<Steps>
  <Step title="Choose one chat model">
    Verify its current availability and limits in your provider account. Keep the exact model ID with your test record so a later model replacement is reviewed deliberately.
  </Step>

  <Step title="Configure the secret reference">
    In the agent's **Custom LLM** settings, enter the server URL and model ID, then select the API-key reference. Environment references use their production value during the probe. See [custom models](/agents-platform/advanced/custom-models/overview) for the complete field workflow.
  </Step>

  <Step title="Inspect the streaming result">
    Select **Test connection** only with approval to make a real provider request. The probe uses streaming Chat Completions with usage reporting requested and requires a nonempty assistant text delta. A model that only returns another response shape will fail this check.
  </Step>
</Steps>

Separate authentication errors, model-access errors, rate limits, and unsupported parameters when diagnosing failures. Do not add speculative headers or switch API types to bypass a failed probe; review [the accepted endpoint contract](/agents-platform/advanced/custom-models/compatible-endpoints).

Local edits are not a published version. If you need a durable candidate for review, save a complete server draft and read it back. Compare it with [managed model options](/overview/models) before planning a release.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I need to install a Groq SDK in Threetone?">No SDK installation is part of this dashboard probe. You supply the endpoint, model identifier, and protected credential reference.</Accordion>
  <Accordion title="Does a successful text probe verify tool use or voice latency?">No. It checks the probe's request and text stream. Tool behavior, conversation execution, speech, and end-to-end latency require separate supported runtime tests.</Accordion>
</AccordionGroup>


# Custom models
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/overview

Prepare a custom language-model endpoint, run the supported dashboard connection probe, and preserve a candidate configuration as a draft.

A custom model configuration identifies an external model endpoint and its credential references. It differs from selecting a managed model in the workspace catalog.

<Note>
  The dashboard has an implemented connection probe for an unsaved custom configuration. Current custom-model publication is rejected with `custom_llm_execution_unavailable`. A successful probe does not publish the configuration or start an agent conversation.
</Note>

## Configure the candidate

<Steps>
  <Step title="Choose the model mode">Open an editable agent's LLM selection and choose **Custom LLM**. Keep the intended agent and workspace selected.</Step>
  <Step title="Set the endpoint">Enter **Server URL** and **Model ID**. The current probe accepts a public HTTPS Chat Completions base URL. Review [endpoint compatibility](/agents-platform/advanced/custom-models/compatible-endpoints).</Step>
  <Step title="Prepare credentials">Select a workspace secret or Secret environment variable for **API Key**, or **None** when the endpoint needs no key. Environment references resolve against production for the probe. Review request headers. Current probe policy rejects auth connections, API-version parameters, and dynamic headers.</Step>
  <Step title="Test the connection">Use **Test connection** with an approved provider account. This makes a real model request. Inspect the returned result and any error before changing other fields.</Step>
  <Step title="Preserve the candidate">Field edits update the editor's local working copy; closing the sheet only dismisses it. For durable review, create a complete [server draft](/agents-platform/deploy/versioning) and read it back. Do not treat a rejected Publish action as a saved version.</Step>
</Steps>

## Configuration relationship

Under `conversation_config.agent.prompt`, custom selection requires `llm: "custom-llm"`, a `custom_llm` definition, and `backup_llm_config.preference: "disabled"`. Managed model selection requires `custom_llm` to be null. Preserve the rest of the selected snapshot when authoring a draft.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a successful test be used as an agent runtime release?">No. Endpoint probing, draft storage, publication, and conversation execution are different operations.</Accordion>
  <Accordion title="Can I invoke the dashboard probe with my personal API key?">The probe is dashboard-only. Its implementation is not a public API-key workflow or a reason to copy dashboard credentials into application code.</Accordion>
</AccordionGroup>


# SambaNova
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/sambanova

Prepare a SambaNova cloud Chat Completions candidate and review endpoint, model, and streaming behavior before saving a draft.

Use SambaNova's cloud Chat Completions endpoint as a candidate for the Threetone connection probe. Confirm the model and endpoint in the provider account before testing, especially when using a dedicated deployment.

<Note>
  The current custom-model workflow supports connection testing and candidate drafts. It does not support publication or agent execution with a custom model.
</Note>

## Candidate settings

| Threetone field | Candidate value |
| - | - |
| Server URL | `https://api.sambanova.ai/v1` for the documented shared cloud endpoint. |
| Model ID | Copy the exact chat model identifier available in your provider account. |
| API Key | A workspace secret or Secret environment reference holding the provider API key. |

SambaNova's [endpoint configuration guide](https://docs.sambanova.ai/docs/en/integrations/vscode) documents the full cloud Chat Completions URL and notes that dedicated deployments may use a different URL. Threetone expects its base URL, with the trailing `/chat/completions` path removed. Do not assume a separate enterprise endpoint uses the shared cloud path or authentication method.

## Validate the candidate

<Steps>
  <Step title="Confirm the provider deployment">
    Check the account, model identifier, endpoint, and credential scope together. Use the provider's current endpoint details rather than copying an example model that may no longer be available.
  </Step>

  <Step title="Enter the custom-model fields">
    Choose **Custom LLM** in the agent editor and add the candidate settings. Environment references resolve against production for the probe. Review the [custom-model guide](/agents-platform/advanced/custom-models/overview) before selecting a credential.
  </Step>

  <Step title="Run the connection test">
    The dashboard's **Test connection** action sends a real request. The endpoint must accept streaming Chat Completions with usage reporting requested and emit assistant text. Provider access or a successful nonstreaming example alone does not establish this behavior.
  </Step>
</Steps>

If the probe fails, inspect the endpoint path, credential access, exact model name, and stream shape. A dedicated endpoint that requires unsupported authentication or API parameters needs a separate integration review; do not bypass [probe policy](/agents-platform/advanced/custom-models/compatible-endpoints).

Save a complete server draft only when you want to preserve the candidate. A dismissed editor sheet or failed Publish action does not create a released version. See [managed models](/overview/models) for the separate managed selection path.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I paste the full Chat Completions URL from a provider example?">No. Server URL must be the base URL. The Threetone probe adds the Chat Completions path itself.</Accordion>
  <Accordion title="Are all SambaNova deployment types supported?">No such guarantee is established. Each endpoint, authentication method, model, and response stream must satisfy the current probe contract, and runtime execution remains unavailable.</Accordion>
</AccordionGroup>


# Together AI
Source: https://docs.threetone.in/agents-platform/advanced/custom-models/together-ai

Prepare a Together AI chat-model candidate and verify the endpoint, model identifier, and streaming connection probe.

Together AI documents a Chat Completions API that can be evaluated with Threetone's custom-model connection probe. Choose a model available to your provider account and preserve the exact identifier with the candidate configuration.

<Note>
  The probe makes a real model request. A successful result does not enable custom-model publication or conversation execution, which remain unavailable.
</Note>

## Candidate settings

| Threetone field | Candidate value |
| - | - |
| Server URL | `https://api.together.ai/v1` |
| Model ID | The exact Together AI chat-model identifier available to your account. |
| API Key | A workspace secret or Secret environment reference containing the provider API key. |

Use Together AI's current [compatibility reference](https://docs.together.ai/docs/inference/openai-compatibility) for the base URL and model naming. Model IDs use provider-specific names, commonly including a namespace. Do not substitute a display label or assume that similarly named models have the same capabilities.

## Test one configuration

<Steps>
  <Step title="Review model access">
    Confirm that the intended chat model is available, that the key can access it, and that a test request is authorized. The provider's image, embedding, or speech endpoints are separate from this text probe.
  </Step>

  <Step title="Configure the candidate">
    In **Custom LLM**, enter the base URL without `/chat/completions`, the model ID, and the secret reference. Environment references use production during the probe. Follow [the field workflow](/agents-platform/advanced/custom-models/overview).
  </Step>

  <Step title="Inspect the response">
    Use **Test connection** and record a safe result. Threetone requests streaming Chat Completions with `stream_options.include_usage: true` and requires assistant text in the stream. Model-specific parameter or response differences can still cause the probe to fail.
  </Step>
</Steps>

Check authentication, exact model access, provider capacity, and stream compatibility separately. Keep credential values out of error reports. Do not treat a successful provider playground request as a substitute for this probe's [endpoint contract](/agents-platform/advanced/custom-models/compatible-endpoints).

For durable review, create a complete server draft and read it back. Publication remains rejected for custom selection; [managed models](/overview/models) use a separate configuration path.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does provider support for tools verify agent tool execution?">No. This connection probe verifies a text response. Tool schemas, tool authorization, and runtime execution require their own supported tests.</Accordion>
  <Accordion title="Can I omit the namespace from Model ID?">Use the exact identifier supplied by Together AI for the model. A shorter display label may not resolve to a callable model.</Accordion>
</AccordionGroup>


# Client events
Source: https://docs.threetone.in/agents-platform/advanced/events/client-events

Prepare client event selections and UI handling without assuming a released conversation transport.

Client events help an interface distinguish user input, agent output, interruptions, and tool activity. The configuration can store event selections, but a verified Threetone client subscription API is not established by the documented runtime.

## Review the event selection

The schema includes names such as `user_transcript`, `agent_response`, `interruption`, `client_tool_call`, `agent_tool_response`, and `context_usage`. Use [Update agent](/api-reference/agents-platform/update-agent) to inspect the exact accepted selection under `conversation_config.conversation.client_events`.

Keep the selection focused on the interface's needs. Transcript and tool data can include private information. Define which events are displayed, retained, or excluded from logs before the channel is enabled.

## Prepare handlers

| Scenario | Expected integration behavior |
| - | - |
| A user or agent transcript arrives | Associate it with the intended conversation and distinguish partial from final data when the released contract supports that distinction. |
| An interruption occurs | Update the interface using the released event identity and ordering rules. |
| A tool action is requested | Check the owning service's permission and confirmation requirements. |
| The client reconnects | Reconcile available server state instead of assuming every event was received. |

Do not invent a socket URL, payload envelope, or `onEvent` SDK method. Add runnable handlers when those contracts are released and tested.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will every selected event be emitted today?">A saved selection does not prove emission. Conversation initiation and execution remain separately gated.</Accordion>
  <Accordion title="Should I log all events during testing?">Use controlled data and retain only what the test needs. Keep credentials and unnecessary transcript content out of application logs.</Accordion>
</AccordionGroup>


# Client-to-server context
Source: https://docs.threetone.in/agents-platform/advanced/events/client-to-server

Plan typed conversation context and action boundaries for a future supported client transport.

A conversation client may need to submit text, contextual values, or a client-tool result. The integration must define which data the client can influence and which decisions remain owned by the server.

## Prepare contextual values

Use [dynamic variables](/agents-platform/configure/personalization/dynamic-variables) to identify named values and expected types. Keep identity, workspace access, resource authorization, and spending policy server-owned. A value submitted by a browser is not proof of any of those permissions.

The public initiation schemas describe conversation configuration overrides and contextual data. Their presence does not establish a working session or a released real-time event envelope.

## Design the request boundary

1. List the fields a client is allowed to submit and their type and length constraints.
2. Resolve the authenticated user and workspace independently of submitted identifiers.
3. Validate tool results against the outstanding request and the owning service's policy.
4. Define duplicate, expired, interrupted, and disconnected-request handling.
5. Verify a complete client request and saved result when the runtime is released.

Use [authentication](/agents-platform/configure/authentication/overview) and [environment values](/agents-platform/deploy/environment-variables) for the supported preparation workflows. Do not embed a workspace API key in the client.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a client override any agent setting?">No. Use the exact released override policy and preserve server-owned authorization. Schema fields do not imply unrestricted client control.</Accordion>
  <Accordion title="Can I send these values through an undocumented WebSocket?">No supported Threetone transport contract is established here. Keep runnable transport examples tied to a verified release.</Accordion>
</AccordionGroup>


# Events
Source: https://docs.threetone.in/agents-platform/advanced/events/overview

Distinguish client events, monitoring selections, and post-call notifications before designing an integration.

An event describes something an integration may need to observe or submit. The event category determines its timing, recipient, and data requirements.

| Category | Configuration | Purpose |
| - | - | - |
| Client events | `conversation_config.conversation.client_events` | Select conversation events intended for a supported client. |
| Monitoring events | `conversation_config.conversation.monitoring_events` | Select events for a supported monitoring path. |
| Post-call notifications | Workspace `webhooks.events` and permitted agent overrides. | Request notifications associated with completed or failed calls. |

The public schemas describe these selections. They do not establish a released socket protocol, SDK subscription method, delivery order, or replay mechanism.

## Choose an event design

Use [client events](/agents-platform/advanced/events/client-events) to plan what the interface needs to display. Use [client-to-server context](/agents-platform/advanced/events/client-to-server) to define what a supported client may submit. Use [post-call webhooks](/agents-platform/advanced/post-call-webhooks) for server-side notification preparation.

Document the event's owner, required fields, privacy classification, conversation identifier, and failure behavior. Treat external event data as untrusted input. Separate displaying an event from authorizing an action based on it.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Are event names proof of delivery?">No. Verify the released transport, emitted payload, authorization, and failure behavior before implementing a subscription.</Accordion>
  <Accordion title="Can a client event replace a post-call notification?">They serve different recipients and lifecycle points. Choose the supported path for the job rather than assuming identical timing or persistence.</Accordion>
</AccordionGroup>


# LLM cascading
Source: https://docs.threetone.in/agents-platform/advanced/llm-cascading

Configure managed model fallback policy, backup order, and timeout, then inspect the saved configuration.

Cascading configuration defines the requested backup models when a primary model cannot provide an acceptable response in time. Saving that policy is separate from demonstrating failover in a live conversation.

## Select the policy

The dashboard's **Backup LLM configuration** provides Default, Custom, and Disabled choices. These map to `conversation_config.agent.prompt.backup_llm_config`:

| Preference | Configuration intent |
| - | - |
| `default` | Resolve the platform-managed backup order from the workspace-selectable catalog. |
| `override` | Supply an explicit ordered list of supported catalog model IDs. |
| `disabled` | Request no backup model. |

`cascade_timeout_seconds` defaults to 4 seconds and accepts 2–15 seconds. Review model compatibility, latency requirements, and provider costs before changing the order or timeout.

## Review and save

Use [platform-managed backup discovery](/api-reference/agents-platform/get-the-platform-managed-llm-backup-order) and the [LLM catalog](/api-reference/agents-platform/list-available-llms). Preserve the selected primary model and unrelated prompt settings. For supported managed text-only publication, the primary and backups must resolve against the same catalog release.

Read the saved branch or draft back. Empty or incompatible custom backup selections, or an unavailable default policy, can prevent publication. Custom LLM selection requires disabled backups and cannot currently be published.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does the timeout guarantee a response within that duration?">No. It records fallback intent. End-to-end latency and actual failover require a released runtime and measured tests.</Accordion>
  <Accordion title="Can I use custom endpoints as managed backups?">The reviewed custom-LLM selection requires disabled backups. Do not substitute custom endpoint definitions for supported catalog IDs.</Accordion>
</AccordionGroup>


# Advanced configuration
Source: https://docs.threetone.in/agents-platform/advanced/overview

Review event selections, custom model endpoints, model fallback, and post-call notification configuration.

Use these guides when an integration needs configuration beyond the basic prompt, model, and resource references. Review a complete agent version and the external service together.

<CardGroup>
  <Card title="Events" icon="bolt" href="/agents-platform/advanced/events/overview">Separate client and monitoring selections from post-call notifications.</Card>
  <Card title="Custom models" icon="microchip" href="/agents-platform/advanced/custom-models/overview">Prepare a compatible endpoint and inspect the supported connection probe.</Card>
  <Card title="LLM cascading" icon="layer-group" href="/agents-platform/advanced/llm-cascading">Review managed model fallback policy, order, and timeout.</Card>
  <Card title="Post-call webhooks" icon="webhook" href="/agents-platform/advanced/post-call-webhooks">Prepare notification settings and a receiver for a future delivery release.</Card>
</CardGroup>

## Review boundaries

Stored configuration, a successful endpoint probe, configuration publication, and live execution are different results. Current publication supports compatible managed text-only configurations; voice and custom-model publication remain gated in the reviewed implementation.

Use [server drafts](/agents-platform/deploy/versioning) to preserve a complete candidate configuration where publication is unavailable. Keep credential values in supported private storage. Read the draft or version back instead of treating an editor preview as a saved result.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does an advanced setting enable the related runtime feature?">No. Each guide identifies its authoring, inspection, or probe capability and the separate execution requirements.</Accordion>
  <Accordion title="Should I edit every advanced setting for a new agent?">Start with the settings needed for one task. Review their effect on model compatibility, credentials, privacy, latency, and failure handling before adding more.</Accordion>
</AccordionGroup>


# Post-call webhooks
Source: https://docs.threetone.in/agents-platform/advanced/post-call-webhooks

Review persisted notification preferences and prepare a receiver without assuming webhook resource storage or delivery is released.

A post-call webhook is a server notification associated with a completed or failed call. It can support downstream review or business processing once its event and delivery contract is released.

<Note>
  Workspace notification preferences persist, but the current webhook-resource CRUD is placeholder behavior. Creating a resource returns an identifier without verified persistence. There is no verified delivery, signature, retry, or callback-log implementation. Do not use the current create response as evidence of a working receiver.
</Note>

## Configuration shape

Workspace settings expose `webhooks.post_call_webhook_id`, `webhooks.events`, and `webhooks.transcript_format`. Agent-specific intent belongs under `platform_settings.workspace_overrides.webhooks`. Transcript format accepts `json` or `opentelemetry`.

Use [Get Agents Platform settings](/api-reference/agents-platform/get-agents-platform-settings) and [Update Agents Platform settings](/api-reference/agents-platform/update-agents-platform-settings) to inspect the committed contract. The dashboard currently reads the selected post-call default; it is not a verified end-to-end setup wizard.

## Prepare a receiver

| Requirement | Design to review before delivery is enabled |
| - | - |
| Authentication | Verify the exact released signature or authentication contract against raw request bytes. |
| Event ownership | Bind the event to the intended workspace, conversation, and agent version. |
| Repeated delivery | Deduplicate using a released stable event identifier and persist processing state. |
| Processing | Acknowledge according to the released delivery contract and run expensive work in a durable worker. |
| Failures | Record failed or uncertain processing without silently repeating business mutations. |
| Data | Minimize transcript/audio retention and restrict access to private content. |

No signature-header name, payload envelope, or retry schedule is promised here. Add executable receiver examples when those contracts are released and verified.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a saved webhook ID prove the receiver is registered?">No. Preference storage and webhook resource persistence are separate. Current resource CRUD does not establish a working registration.</Accordion>
  <Accordion title="Will selecting OpenTelemetry send traces to my collector?">No verified collector delivery is established. Review [OpenTelemetry](/agents-platform/monitor/opentelemetry) for the supported stored-data distinction.</Accordion>
</AccordionGroup>


# Channel behavior
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/channel-behavior

Prepare response length, formatting, and interaction-budget settings for different text conversation sources.

A short chat reply and a longer support exchange may need different response styles. Channel behavior settings describe those differences without changing the agent's core purpose or permissions.

<Note>
  This guide covers configuration authoring. A channel name in the schema does not establish an available SDK, connector, messaging channel, or live session path.
</Note>

## Define the response style

Per-channel settings live in `conversation_config.agent.text_behavior_overrides`. The map uses supported conversation-initiation source identifiers as keys. Each value can contain:

| Field | Accepted values |
| - | - |
| `verbosity` | `auto`, `concise`, `thorough` |
| `output_format` | `plain_text`, `markdown` |
| `interaction_budget` | `realtime`, `5_minutes`, `10_minutes`, `1_hour` |

These are requested response settings. An interaction budget is not a billing plan, guaranteed response time, or conversation-retention period.

## Prepare a channel-specific draft

<Steps>
  <Step title="Identify the actual integration">
    Start with the supported source identifier in the [agent schema](/api-reference/agents-platform/get-agent). Do not invent keys such as your app's display name. Check [deployment guidance](/agents-platform/deploy/web/overview) separately for integration availability.
  </Step>

  <Step title="Choose the smallest useful difference">
    Prefer concise plain text for a narrow message surface. Use Markdown only when your application can render it appropriately. Keep instructions about required information and permitted actions in the base prompt.
  </Step>

  <Step title="Save and inspect the map">
    Preserve the current branch configuration, add only the intended overrides, and save a complete [server draft](/agents-platform/deploy/versioning). Read the draft back to check the exact source keys and enum values.
  </Step>

  <Step title="Prepare comparable examples">
    Write the same example request for each intended channel. Record the desired length, formatting, and clarification behavior so later runtime testing has a clear expected result.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does adding a WhatsApp source connect WhatsApp?">
    No. Behavior overrides do not provision or authenticate a channel. Review [WhatsApp availability](/agents-platform/deploy/whatsapp/overview) before planning that integration.
  </Accordion>

  <Accordion title="Do channel settings change access to tools?">
    No. Response style is separate from workspace permissions, tool attachments, and authorization in the service that owns an action.
  </Accordion>
</AccordionGroup>


# Conversation flow
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/conversation-flow

Configure first-message interruptions and soft timeouts, then review the saved turn settings on an agent version.

Conversation-flow settings describe when an agent should wait, respond, or allow an interruption. This guide updates the first-message and soft-timeout controls that the dashboard saves, then shows where the remaining turn settings belong in the API.

<Note>
  This guide ends with a reviewed configuration. Conversation execution is currently gated, so saving these values does not demonstrate timing or interruption behavior in a live session. See [current availability](/agents-platform/overview#current-availability).
</Note>

## Before you begin

Open an agent you can edit in the intended workspace and select its branch. Preserve voice or custom-model changes in a complete server draft; those publication paths are unavailable. Managed text-only publication has model, resource, and workflow validation. See [versions and drafts](/agents-platform/deploy/versioning) for the appropriate workflow.

## Configure the saved dashboard controls

<Steps>
  <Step title="Review the opening message">
    Open the agent's **Agent Configuration** page. Write a short **First message** that matches the task, or leave it empty to express that the user should speak first.

    Review **Interruptible** beside the first-message editor. When enabled, the stored `conversation_config.agent.disable_first_message_interruptions` value is `false`. Turning it off stores `true`. This control applies to the opening message, not every agent response. Use a wider desktop window if the control is hidden.
  </Step>

  <Step title="Open the soft-timeout settings">
    In the **LLM** section, open the selected model's settings, then select **Soft timeout**. Turn on **Enable soft timeout** to configure a filler message for a delayed model response.

    When no earlier duration is available, enabling the setting starts at 2 seconds. **Timeout duration** accepts 0.5–8 seconds. Turning the setting off stores `timeout_seconds: -1`.

    <Frame>
      <img alt="Screenshot pending for the Soft timeout settings. This is a placeholder, not a dashboard screenshot." />
    </Frame>
  </Step>

  <Step title="Choose filler copy">
    For static copy, edit **First message** inside the Soft timeout sheet and optionally add more messages. This is the first filler message, separate from the agent's opening message. **Randomize filler order** becomes available when you add another filler.

    Alternatively, enable **Use LLM-generated message**. Review **Maximum filler messages**, **Override soft timeout prompt**, and **Fallback message**. Enable **Wait for first user message** if the saved configuration should defer fillers until the user has spoken.

    Keep the copy brief and avoid implying that an external action has completed. These controls save the requested behavior; runtime delivery still requires a supported execution path.
  </Step>

  <Step title="Save and read back">
    Review the first-message interruption value and `conversation_config.turn.soft_timeout_config` in the complete snapshot, then save a server draft. For eligible managed text-only publication, inspect **Review Changes** and confirm the branch before submitting a **Commit message**.

    Inspect the saved draft or eligible published version and confirm the values. For an API check, use [Get agent](/api-reference/agents-platform/get-agent) with the selected branch and the appropriate read options. Retain the configuration identifiers for later runtime testing.
  </Step>
</Steps>

## Soft-timeout fields

The following paths are relative to `conversation_config.turn.soft_timeout_config`.

| Field | Default and accepted configuration |
| - | - |
| `timeout_seconds` | `-1` disables the setting. The dashboard accepts 0.5–8 seconds when enabled. |
| `message` | `"Hhmmmm...yeah."`; 1–200 characters. Used for static first-filler copy or the generated mode's fallback. |
| `additional_soft_timeout_messages` | Empty list; at most 7 additional static messages. |
| `use_llm_generated_message` | `false`; selects static or generated filler intent. |
| `randomize_fillers` | `false`; applies to static fillers. |
| `max_soft_timeouts_per_generation` | `1`; integer from 1 to 8. |
| `llm_generated_message_prompt_override` | `null`; an override must contain 1–1000 characters. |
| `disable_until_first_user_message` | `false`. |

The dashboard's duration range is an editor constraint. Use the generated [Update agent schema](/api-reference/agents-platform/update-agent) for the complete API contract.

## Other turn settings through the API

The main **Agent behavior** presets are labelled as previews and do not save changes. The **Advanced** tab on the Security page also displays disabled example settings. Use the API to author the following base-agent fields, and read the resulting values back.

These paths are relative to `conversation_config.turn`.

| Field | Default | Configuration purpose |
| - | - | - |
| `turn_timeout` | `7` | Requested wait, in seconds, before re-engaging a silent user. |
| `initial_wait_time` | `null` | Opening wait when the first message is empty; unset uses the regular turn timeout. |
| `silence_end_call_timeout` | `-1` | Requested silence limit before ending a call. |
| `turn_eagerness` | `normal` | Choose `patient`, `normal`, or `eager`. |
| `spelling_patience` | `auto` | Choose `auto` or `off`. |
| `speculative_turn` | `false` | Request earlier response generation while a turn is being detected. |
| `interruption_ignore_terms` | `[]` | Terms configured not to trigger interruptions. |
| `interruption_ignore_term_languages` | `[]` | Languages associated with configured ignore-term presets. |
| `merge_with_default_ignore_terms` | `false` | Request preset terms alongside custom terms. |
| `transcribe_on_disabled_interruptions` | `false` | Request transcription while interruptions are disabled. |

The schema also includes `mode` (`silence` or `turn`, default `turn`), `turn_model` (`turn_v2` or `turn_v3`, default `turn_v3`), and `retranscribe_on_turn_timeout` (default `false`). Their presence in a saved document does not establish runtime support.

The total-duration setting is separate: `conversation_config.conversation.max_duration_seconds` defaults to `600`. Its optional closing copy is `conversation_config.agent.max_conversation_duration_message`, which defaults to an empty string.

Use [Update agent](/api-reference/agents-platform/update-agent) with an explicit `branch_id` when changing conversation configuration. For a complete server draft, preserve the selected version's other fields and follow [versions and drafts](/agents-platform/deploy/versioning).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why did the Agent behavior preset disappear after reopening?">
    That picker is a local preview. Use the saved controls described above or the corresponding API fields, then inspect the published version. Preview selections are not evidence of a configuration change.
  </Accordion>

  <Accordion title="Does Interruptible control every response?">
    No. The switch beside First message updates only `disable_first_message_interruptions`. Review other turn fields separately; do not infer a conversation-wide interruption setting from that switch.
  </Accordion>

  <Accordion title="Does a soft timeout end the conversation?">
    The soft-timeout configuration describes filler feedback while waiting for a model response. Turn silence and total conversation duration use separate fields. Saving any of them does not verify live timing behavior.
  </Accordion>

  <Accordion title="How do I verify the change today?">
    Compare the published configuration with the intended values and record its version ID. Keep timing and interruption scenarios for a later execution test when the runtime path is available.
  </Accordion>
</AccordionGroup>


# Guardrails
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/guardrails

Define conversation boundaries and review guardrail configuration while dashboard enforcement controls remain in preview.

Guardrails describe topics or behaviors that need a defined response. Start by writing what the agent may help with, when it should ask for clarification, and when it should stop or direct the user elsewhere.

<Note>
  The dashboard's **Guardrails** page is a preview: changes there are not published. The API includes guardrail authoring fields, but saved settings do not establish live moderation, prompt-injection protection, or automated intervention.
</Note>

## Write the policy first

For each boundary, keep a realistic example, the expected response, and the service responsible for enforcing any access restriction. For example, a support agent can explain the account-recovery process while the account service verifies identity before changing a login method.

Do not rely on a prompt or guardrail setting to grant or deny access to private data. [Tool authorization](/agents-platform/configure/tools/overview) must be enforced by the service that owns the action.

## Review the authored settings

Guardrail configuration lives under `platform_settings.guardrails`. The current version discriminator is `version: "1"`.

| Setting | Configuration to review |
| - | - |
| `focus` | Whether the authored focus guardrail is enabled. |
| `prompt_injection` | Whether the authored prompt-injection guardrail is enabled. |
| `content` | Category configuration, execution mode, and trigger action. |
| `moderation` | Optional moderation configuration. |
| `custom` | Optional custom guardrail configuration. |

Content categories include sexual content, violence, harassment, self-harm, profanity, religion or politics, and medical or legal information. Category entries contain `is_enabled` and `threshold`. A stored threshold is a configuration value, not a measured accuracy or protection guarantee.

## Prepare a review

<Steps>
  <Step title="Choose relevant boundaries">
    Select categories that matter for the task. Include ordinary requests that must remain answerable, so the review covers both inappropriate responses and unnecessary refusals.
  </Step>

  <Step title="Save API-authored configuration separately">
    If preparing guardrail fields through the API, preserve the complete agent snapshot and use a [server draft](/agents-platform/deploy/versioning). Read the draft back. Do not treat changes in the preview dashboard as a saved policy.
  </Step>

  <Step title="Record the expected response">
    For each example, specify acceptable wording, any handoff, and whether an external action must be denied. Keep execution verification pending until the applicable runtime path is available.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does enabling a guardrail prove it is enforced?">
    No. Saving a field and verifying runtime enforcement are separate checks. Do not describe the agent as protected against a class of attacks based only on its configuration.
  </Accordion>

  <Accordion title="Why did my dashboard changes disappear?">
    The Guardrails page is labelled as an unpublished preview. Use the API draft workflow for configuration authoring, and inspect the returned document.
  </Accordion>
</AccordionGroup>


# Models
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/models

Choose a managed language model, review supported generation settings, and save a configuration with compatible backups.

Choose a language model for the work your agent needs to do: understand the request, follow the prompt, and produce an appropriate response. Start with the current model catalog so the identifier and available settings match Threetone.

<Note>
  Creation and draft saving are separate from publication. Later publication checks model availability and compatibility. Managed text-only configurations can pass those checks; voice and custom-model publication are currently unavailable. See [current availability](/agents-platform/overview#current-availability).
</Note>

## Choose and review a model

<Steps>
  <Step title="Check the catalog">
    Read [Models](/overview/models) and [List available LLMs](/api-reference/agents-platform/list-available-llms). Choose an available managed model and keep its exact identifier. A provider's model name is not necessarily its Threetone catalog identifier.
  </Step>

  <Step title="Set the primary model">
    In the agent editor, open **LLM** to review the model and its settings. The saved primary model is `conversation_config.agent.prompt.llm`.

    For API authoring, read the intended branch first and preserve the rest of its configuration. Use an explicit `branch_id` when updating conversation settings.
  </Step>

  <Step title="Review supported settings">
    Set only options supported by the chosen model. Use the table below to locate them, and review [LLM cascading](/agents-platform/advanced/llm-cascading) before selecting backups.
  </Step>

  <Step title="Save and read back">
    Save a complete [server draft](/agents-platform/deploy/versioning). If you publish an eligible managed text-only configuration, review the diff and record the new version ID. Read the saved document with [Get agent](/api-reference/agents-platform/get-agent) and check the primary model and backup policy together.
  </Step>
</Steps>

## Generation settings

These fields belong to `conversation_config.agent.prompt`.

| Field | What to review |
| - | - |
| `llm` | Exact managed model identifier from the current catalog. |
| `temperature` | Whether the selected model accepts the requested sampling setting. |
| `max_tokens` | The response budget, subject to the selected model's limits. |
| `reasoning_effort`, `thinking_budget` | Model-specific reasoning controls; support is not universal. |
| `enable_reasoning_summary` | Whether the model supports this requested output setting. |
| `backup_llm_config` | The selected backup policy and compatibility of every resolved backup. |
| `cascade_timeout_seconds` | The authored timeout setting associated with cascading. |

A successful save is evidence of configuration storage. It does not measure response quality, latency, or successful failover. Prepare a small set of representative prompts before comparing models when execution is available.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does publication reject a model that creation accepted?">
    Creation stores the initial authoring configuration. Later publication also checks available models and compiles an execution configuration. Check the primary model, backups, and whether the agent is text-only.
  </Accordion>

  <Accordion title="Can I connect my own model endpoint?">
    You can prepare a [custom model configuration](/agents-platform/advanced/custom-models/overview), but custom-model publication is unavailable. An endpoint probe does not remove that restriction.
  </Accordion>
</AccordionGroup>


# Multimodal input
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/multimodal-input

Prepare file-input limits and representative image or document examples while multimodal conversation support remains planned.

Multimodal input would let a conversation use an image or document as part of a request. Prepare the intended task and limits now, but do not depend on a released upload-to-model conversation workflow.

<Note>
  The agent contract includes file-input configuration. This does not establish working image or PDF uploads, model processing, file retention, or per-file charging. Live multimodal conversation support is not available through this guide.
</Note>

## Prepare the input contract

The fields below belong to `conversation_config.conversation.file_input` and can be reviewed as part of an [agent draft](/agents-platform/deploy/versioning).

| Field | Authoring constraint |
| - | - |
| `enabled` | Boolean; defaults to `true` in the schema. This is not a readiness signal. |
| `max_files_in_memory` | Integer from 1 to 30; default 10. |
| `max_files_per_conversation` | Default 10. Must be `-1` or at least `max_files_in_memory`. |

Prefer a small, explicit limit for your intended task. Do not interpret `-1` as an entitlement to unlimited storage or processing. These fields do not define a deletion schedule or establish how long files are retained.

## Prepare examples for later testing

<Steps>
  <Step title="Define what the file contributes">
    Write one concrete task, such as identifying the model number on a product label. Specify what the agent should do when the label is unreadable or missing.
  </Step>

  <Step title="Select a compatible model when available">
    Check the current [model catalog](/overview/models) for the exact input capability. Text generation support alone does not establish image or document understanding.
  </Step>

  <Step title="Create a small review set">
    Use synthetic files covering a clear example, a low-quality example, an irrelevant file, and conflicting text. Record the expected answer and when the agent should request clarification.
  </Step>

  <Step title="Keep file input separate from knowledge">
    A per-conversation attachment is different from a maintained workspace [knowledge document](/agents-platform/configure/knowledge-base/overview). Choose the latter for reviewed information intended to be reused across agents.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does enabled: true mean users can upload files now?">
    No. It is an authored setting. A supported client, upload path, model integration, and released conversation path are still required.
  </Accordion>

  <Accordion title="Does the memory limit define file deletion?">
    No. Do not use these fields as a retention policy. Confirm the released file-storage and deletion behavior before accepting real user files.
  </Accordion>
</AccordionGroup>


# Agent configuration
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/overview

Configure an agent's first message, prompt, language, models, and resource references, then review the complete saved version.

An agent configuration combines instructions, models, language settings, and references to workspace resources. Review these settings as one version so the prompt does not promise actions or information the configuration cannot provide.

<Frame>
  <img alt="Recording pending for Configure an agent. No playable video is available yet." />
</Frame>

<Note>
  The dashboard submits prompt, first-message, LLM, soft-timeout, and dynamic-variable edits through the configuration publication flow. Publication currently requires an eligible managed text-only configuration; voice and custom-model publication are blocked. Its **Voices**, **Language**, **ASR**, and **Agent behavior** pickers are previews whose changes are not saved; the Security page also displays disabled example settings. Use a complete server draft to preserve those settings without publication. See [voice and language](/agents-platform/configure/voice-and-language/overview) and [conversation flow](/agents-platform/configure/agent-behavior/conversation-flow).
</Note>

## Configuration structure

| Section | Purpose | Guide |
| - | - | - |
| `conversation_config.agent` | First message, base language, response-language policy, and prompt. | [Prompting](/agents-platform/configure/agent-behavior/prompting) |
| `conversation_config.asr` | Recognition model and language mode for voice input. | [Models and voices](/overview/models) |
| `conversation_config.tts` | Speech model and saved workspace voice. | [Models and voices](/overview/models) |
| `conversation_config.agent.prompt` | LLM selection, tool and MCP identifiers, and knowledge attachments. | [Tools](/agents-platform/configure/tools/overview) and [knowledge](/agents-platform/configure/knowledge-base/overview) |
| `platform_settings` | Platform-level configuration separate from the conversational instructions. | [Update agent schema](/api-reference/agents-platform/update-agent) |
| `workflow` | The workflow included in the configuration snapshot. | [Versions and drafts](/agents-platform/deploy/versioning) |

## Configure and review

<Steps>
  <Step title="Set the purpose and opening">
    Define the task in `agent.prompt.prompt` and write a matching `agent.first_message`. Keep the first message short enough to establish the purpose without asking several questions at once.
  </Step>

  <Step title="Choose language and models">
    Set `agent.language` and review `agent.response_language_policy`. Select an available LLM with `agent.prompt.llm`.

    For voice configurations, include ASR and TTS settings with compatible models and a saved voice. Check the catalog rather than assuming a provider supports every language and recognition mode.
  </Step>

  <Step title="Attach workspace resources">
    Review each tool, MCP server, and knowledge attachment. Use the intended identifiers and check access in the active workspace.

    Keep secrets in supported credential storage. Resource identifiers and prompt instructions do not replace authorization.
  </Step>

  <Step title="Review the entire version">
    Inspect the configuration diff, including `platform_settings` and `workflow`. Preserve unrelated fields when preparing a full draft snapshot.

    Save a complete server draft on the intended branch and read it back. Only publish when the configuration is eligible; managed text-only publication has model, resource, and workflow checks. See [versions and drafts](/agents-platform/deploy/versioning).
  </Step>
</Steps>

Paths in the steps above are relative to `conversation_config`. The generated [Create agent](/api-reference/agents-platform/create-agent), [Get agent](/api-reference/agents-platform/get-agent), and [Update agent](/api-reference/agents-platform/update-agent) pages define the request and response shapes.

## Configuration and execution

<Note>
  The documented implementation currently gates signed-token session initiation, outbound calling, traffic deployment, and automated response-test invocation. A valid configuration can be saved and reviewed without proving that those execution paths work. See [current availability](/agents-platform/overview#current-availability).
</Note>

Privacy, retention, evaluation, and related settings must be assessed separately from their enforcement. A saved field is not evidence of automatic deletion, a completed evaluation, or a compliance guarantee.

## Troubleshooting

| Problem | What to inspect |
| - | - |
| Configuration is rejected | The reported schema field, model compatibility, and workflow validation errors. |
| A referenced resource is missing | The active workspace, resource ID, and access granted to the editor or API key. |
| An edited field was lost | Whether a full snapshot omitted fields from the selected version. |
| A saved agent does not start a session | The separate execution path and its current availability. |

Start with [Create your first agent](/agents-platform/get-started/first-agent) for the dashboard workflow or [API quickstart](/agents-platform/get-started/api-quickstart) for a server-side request example.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do resource IDs grant access to the resource?">
    No. Each referenced voice, tool, MCP server, or knowledge source must be available to the intended workspace and caller. Inspect access separately from the configuration reference.
  </Accordion>

  <Accordion title="How do I confirm which settings were saved?">
    Read the intended branch or version, compare its complete configuration with the reviewed diff, and retain the version ID. A saved setting does not prove that its runtime behavior is available or enforced.
  </Accordion>
</AccordionGroup>


# Procedures
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/procedures

Create branch-scoped procedure drafts, review their triggers and content, and compile a workflow preview.

Procedures organize a repeatable task into named content with a trigger. Use a procedure to keep a focused process, such as gathering the information for a support request, separate from the agent's general instructions.

<Note>
  Procedure management and compilation produce authoring resources. Compilation returns a workflow preview; it does not save that workflow, publish an agent, or run the procedure.
</Note>

## Create and review a procedure

You need an existing agent, its intended `branch_id`, and permission to edit it. Procedure endpoints are scoped to both agent and branch.

<Steps>
  <Step title="Choose the procedure type">
    Use `free_form` for written instructions, `deterministic` for structured JSON content, or `folder` to organize procedures. The structured type name does not guarantee deterministic runtime behavior.
  </Step>

  <Step title="Create the resource">
    Use [Create procedure](/api-reference/agents-platform/create-procedure). Supply a useful `name`, the `content`, and a `trigger` that describes when the procedure is relevant. Use `folder_parent_id` when placing it in a folder.
  </Step>

  <Step title="Edit the branch draft">
    Read [Get procedure draft](/api-reference/agents-platform/get-procedure-draft), then use [Update procedure draft](/api-reference/agents-platform/update-procedure-draft) with the required `name`, `content`, and `type`. Preserve the existing type; changing it through a draft update is rejected.

    Keep the procedure's completion condition and error response explicit. Avoid putting credentials or real customer records in the content.
  </Step>

  <Step title="Compile and inspect">
    Call [Compile procedures](/api-reference/agents-platform/compile-procedures) for the intended branch. Inspect the returned `workflow`, including prompts, trigger conditions, and referenced tools. Fix validation errors by their procedure ID and field path.

    If you want that graph in the agent, review and save it separately through the [workflow and draft process](/agents-platform/configure/agent-behavior/workflows).
  </Step>
</Steps>

## Free-form content

Use `free_form` when the procedure is best expressed as written instructions. For example:

```text theme={null}
Ask which product the request concerns.
Ask the user to describe the problem without sharing passwords.
Summarize the information collected and identify anything still missing.
```

Keep the trigger outside the content, such as “The user wants help preparing a support request.” Compilation places the written content in a workflow node's additional prompt. It does not convert each sentence into a separately enforced step.

## Structured content

For a `deterministic` procedure, `content` is a JSON string containing an object with a `steps` array. The compiler recognizes these step types:

| Step type | Required field |
| - | - |
| `ask`, `tell` | `instruction` |
| `say` | `message` |
| `tool_call` | `tool_id` |
| `sub_procedure` | `procedure_id` |
| `system_tool` | `system_tool_name` |
| `branch` | `branches` array |

The preview represents procedure instructions in workflow nodes. Review that output directly; a successful compile does not prove a step-by-step execution engine or successful external actions.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is a procedure draft a published agent version?">
    No. Procedure drafts, compiled workflow previews, and agent versions are separate resources. Record which branch and draft you reviewed before changing an agent snapshot.
  </Accordion>

  <Accordion title="Why does structured content fail to compile?">
    Check that the content parses as a JSON object, contains a steps array, and supplies the required field for each recognized step type. Use the returned error paths to locate the failing step.
  </Accordion>
</AccordionGroup>


# Free-form procedures
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/procedures/free-form

Write a focused procedure, save it on an agent branch, and inspect how its instructions appear in a compiled workflow preview.

A free-form procedure stores written instructions for a repeatable task. Use it when the task needs judgment or clarification, such as collecting the information for a support request.

<Note>
  Procedure creation, draft updates, and compilation are authoring operations. Compilation places the content in a workflow preview; it does not enforce each sentence as an execution step, publish the agent, or run a conversation.
</Note>

## Write the procedure

Keep the entry condition, requested information, completion condition, and unavailable-action response explicit. For example:

```text theme={null}
Ask which product the request concerns.
Ask the user to describe the problem without sharing passwords.
If the description is unclear, ask one focused follow-up question.
Summarize the information collected and identify anything still missing.
Do not say a support ticket exists unless a separate action confirms it.
```

Use `trigger` for the condition that makes the procedure relevant. Use `content` for the instructions after entry. A procedure name is a label, so avoid relying on it to explain the task.

## Save and inspect

You need an existing agent, an editable `branch_id`, and permission to change the agent.

<Steps>
  <Step title="Create the branch resource">
    Use [Create procedure](/api-reference/agents-platform/create-procedure) with `type: "free_form"`, a useful `name`, your written `content`, and an explicit `trigger`. The name accepts up to 200 characters. Set `folder_parent_id` only when placing it in an existing procedure folder.
  </Step>

  <Step title="Read the draft back">
    Keep the returned `procedure_id` and read [Get procedure draft](/api-reference/agents-platform/get-procedure-draft) on the same agent and branch. Compare the stored name, content, type, and trigger with the intended task.
  </Step>

  <Step title="Make a complete draft update">
    [Update procedure draft](/api-reference/agents-platform/update-procedure-draft) requires `name`, `content`, and `type`. Draft content accepts up to 50,000 characters. Keep `type: "free_form"`; this operation cannot change a procedure's type.
  </Step>

  <Step title="Compile for review">
    Use [Compile procedures](/api-reference/agents-platform/compile-procedures). Inspect the returned node's additional prompt and trigger condition. Save a reviewed workflow separately through [versions and drafts](/agents-platform/deploy/versioning) if you intend to use it in an agent snapshot.
  </Step>
</Steps>

An explicitly empty trigger produces no automatic trigger edge in the preview. Do not use an empty trigger for a procedure you expect the preview's router to select directly.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I convert this procedure to structured content?">
    The draft update rejects type changes. Create a separate [structured procedure](/agents-platform/configure/agent-behavior/procedures/structured), review its content, and update any references deliberately.
  </Accordion>

  <Accordion title="Does a tool name in the text execute that tool?">
    No. Text alone does not establish a tool attachment, authorization, or execution. Review the referenced resource and its availability separately.
  </Accordion>
</AccordionGroup>


# Structured procedures
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/procedures/structured

Prepare typed procedure steps, resolve resource references, and review compiler validation without assuming deterministic execution.

A structured procedure stores a JSON description of steps. In the API, its procedure `type` is `deterministic`. That name identifies the authoring format; it is not a guarantee of deterministic conversation execution.

<Note>
  Compilation validates the structured content and returns a workflow preview containing the procedure instructions. It does not turn each step into a separately enforced workflow node, execute tools, or save the returned graph.
</Note>

## Define the steps

The procedure's `content` field is a **string containing JSON**, not a nested request object. The JSON inside that string must be an object with a `steps` array. For example, the inner content can be:

```json theme={null}
{
  "steps": [
    { "type": "ask", "instruction": "Ask which product needs support." },
    { "type": "tell", "instruction": "Explain what information is needed." },
    { "type": "say", "message": "Please do not share passwords." }
  ]
}
```

Serialize this object into the request's `content` string. The compiler checks these step types and required fields:

| Step type | Required field |
| - | - |
| `ask`, `tell` | `instruction` |
| `say` | `message` |
| `tool_call` | `tool_id` |
| `sub_procedure` | `procedure_id` |
| `system_tool` | `system_tool_name` |
| `branch` | `branches`, which must be an array |

The presence of a required field is not proof that its referenced resource is usable or that a branch condition is complete. Do not invent an execution format for nested branch entries from this table alone.

## Save and review

<Steps>
  <Step title="Choose real resources">
    Prepare an existing agent and editable branch. Resolve any tool or procedure identifiers against resources you can access. Start with steps that collect or explain information before adding external actions.
  </Step>

  <Step title="Create the procedure">
    Use [Create procedure](/api-reference/agents-platform/create-procedure) with `type: "deterministic"`, `name`, a clear `trigger`, and the serialized `content`. Read its branch draft back before further edits.
  </Step>

  <Step title="Compile and correct errors">
    Call [Compile procedures](/api-reference/agents-platform/compile-procedures). Errors identify the procedure and a content path, such as `steps.0.instruction`. Check JSON syntax, recognized step types, and required fields first.
  </Step>

  <Step title="Inspect the preview">
    Review the generated additional prompt, trigger edges, and tool references. The compiler collects `tool_id` values into additional tool references. Saving the graph to an [agent draft](/agents-platform/deploy/versioning) is a separate action.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does content fail JSON validation?">
    Parse the inner content separately. It must be a JSON object with a steps array, then serialized as a string in the procedure request. An array alone is not accepted as the content object.
  </Accordion>

  <Accordion title="Does successful compilation prove every step can run?">
    No. It proves the compiler accepted the authored structure. Resource access, runtime behavior, and successful external actions require separate verification.
  </Accordion>
</AccordionGroup>


# Write an agent prompt
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/prompting

Define an agent's task, boundaries, first message, and response rules, then review prompt changes before publication.

A prompt defines the agent's instructions. Keep factual source material in the [knowledge base](/agents-platform/configure/knowledge-base/overview) and external actions in [tools](/agents-platform/configure/tools/overview). A prompt alone does not grant access to either.

<Frame>
  <img alt="Recording pending for Write and review an agent prompt. No playable video is available yet." />
</Frame>

## Define the task

Write the desired outcome in one sentence before editing the prompt. For example: help customers understand a support process using approved information, and direct account-specific requests to support.

<Steps>
  <Step title="Set the role and scope">
    State which requests the agent handles and which require a person or another system. Avoid a broad instruction to handle every customer request.
  </Step>

  <Step title="Specify how to use information">
    Tell the agent to use approved sources and acknowledge missing information. Do not invent prices, policies, account state, or actions that it cannot verify.
  </Step>

  <Step title="Define action boundaries">
    Explain when an action requires confirmation. An instruction to check an order or contact a team is useful only when the corresponding integration exists and the caller has access.
  </Step>

  <Step title="Set the response style">
    Describe the preferred length, tone, and follow-up behavior. Set the response language through the configuration's language policy rather than conflicting instructions scattered through the prompt.
  </Step>

  <Step title="Review the complete configuration">
    Read the prompt with the first message, knowledge attachments, tools, and language settings. Review the version diff before publishing the changes.
  </Step>
</Steps>

## Example instructions

This is an example of prompt structure, not a promise of deployed behavior. Adapt it to your approved support process.

```text theme={null}
Role
You help customers understand our published support process.

Task
Answer process questions using approved information. Ask a brief
clarifying question when the request is ambiguous.

Boundaries
Do not invent policies, prices, account details, or completed actions.
If information is missing, say what is unknown and explain the next step.
Do not request passwords, API keys, or payment-card details.

Responses
Use short, clear sentences. Give the next useful step before extra detail.
For account-specific changes, direct the customer to the approved support path.
```

## Prompt and first message

The prompt lives at `conversation_config.agent.prompt.prompt`; the first message lives at `conversation_config.agent.first_message`. The first message opens the interaction. It should match the task and avoid implying access to private account information.

For the example above, a suitable first message is: “Hello. I can help explain our support process. What do you need help with?”

## Review scenarios

Before publication, write expected outcomes for a normal question, an ambiguous request, missing information, an out-of-scope task, and a request involving sensitive data. Use these cases to review the prompt and attachments now, and retain them for runtime testing when execution is available.

<Note>
  Automated response-test invocation is currently gated in the documented implementation. A stored test definition or a published prompt does not prove that a test ran successfully. Check [current availability](/agents-platform/overview#current-availability).
</Note>

## Continue

Read [agent configuration](/agents-platform/configure/agent-behavior/overview) for the field structure and [versions and drafts](/agents-platform/deploy/versioning) for reviewing changes. The [Update agent reference](/api-reference/agents-platform/update-agent) defines the API request shape.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I put all source documents in the prompt?">Keep instructions focused. Use reviewed knowledge attachments for factual material and inspect their stored content before relying on them.</Accordion>
  <Accordion title="Does an instruction to take an action enable it?">No. The appropriate tool, resource access, and execution path must exist. The prompt should explain the action boundary without claiming a completed action.</Accordion>
</AccordionGroup>


# Workflows
Source: https://docs.threetone.in/agents-platform/configure/agent-behavior/workflows

Author a graph of agent instructions, tools, and transitions, then review its structure in a saved draft.

A workflow describes how an agent should move between tasks. Use it when different stages need different instructions or resources, such as collecting a request before preparing a handoff.

<Note>
  Workflow authoring and structural validation are available. A saved graph does not prove that its transitions, tool calls, or handoffs execute in a live conversation. Review [current availability](/agents-platform/overview#current-availability).
</Note>

## Build a reviewable graph

<Frame>
  <img alt="Recording pending for workflow draft authoring. No playable video is available yet." />
</Frame>

Start with an existing agent, an editable branch, and a written description of the task's entry and exit conditions.

<Steps>
  <Step title="Define the stages">
    Open the agent's **Workflows** page. Describe what each stage needs to know, what it may change, and what ends that stage. Keep ordinary wording and tone in the base prompt rather than repeating it at every node.
  </Step>

  <Step title="Choose nodes and resources">
    The workflow contract includes `start`, `override_agent`, `tool`, `standalone_agent`, `phone_number`, and `end` nodes. Their presence in the contract does not establish live transfer or telephony support.

    An `override_agent` node can hold `additional_prompt`, `additional_knowledge_base`, and `additional_tool_ids`. Review those resources with the same care as the base agent's attachments.
  </Step>

  <Step title="Check transitions">
    Each edge names a `source` and `target`. Each node's `edge_order` must include every outgoing edge exactly once. Write clear conditions so a reviewer can explain which transition is intended for each example request.
  </Step>

  <Step title="Save the complete snapshot">
    Preserve the graph under the top-level `workflow` field of the agent draft, alongside `name`, `conversation_config`, and `platform_settings`. Follow [versions and drafts](/agents-platform/deploy/versioning), then read the draft back and compare its node and edge identifiers.
  </Step>
</Steps>

## Structural checks

A nonempty workflow must have exactly one Start node. Edges must reference existing nodes, cannot return to Start, and must follow the permitted outgoing transitions for each node type. A node cannot have multiple unconditional outgoing edges. Tool-result conditions require a tool node.

Validation can identify malformed structure. It cannot establish that a natural-language condition is unambiguous or that a downstream service will succeed. Prepare examples for the normal path, missing information, tool failure, and a request outside the workflow's purpose.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I need a workflow for a simple agent?">
    No. Start with a clear prompt and add a workflow when separate stages make the task easier to review. An empty workflow is valid authoring configuration.
  </Accordion>

  <Accordion title="Does a valid phone-number node enable a transfer?">
    No. The node describes a requested handoff. Telephony provisioning and a working conversation path are separate requirements; see [telephony](/agents-platform/deploy/telephony/overview).
  </Accordion>
</AccordionGroup>


# Auth connections
Source: https://docs.threetone.in/agents-platform/configure/authentication/auth-connections

Create reusable workspace authentication configuration, reference it from supported fields, and review safe credential changes.

An auth connection stores the authentication configuration used by supported external-service requests. It is separate from your dashboard sign-in and from the personal API key used to access Threetone.

## Supported manual methods

| Method | Required preparation |
| - | - |
| Basic Authentication | The provider's username and password requirements. |
| Bearer Token | A provider-issued token with the intended access. |
| OAuth2 Client Credentials | A client ID, client secret, token URL, and provider-required token parameters. |
| OAuth2 JWT | The provider's signing algorithm, key, claims, and expected token placement. |

These are manually configured service credentials. Selecting an OAuth method here does not create an interactive user consent flow or enable a native connector that is absent from the catalog.

<Frame>
  <img alt="Recording pending for workspace auth connection configuration. No playable video is available yet." />
</Frame>

## Create a connection

<Steps>
  <Step title="Choose the intended workspace">
    Open [Agent Settings](https://threetone.in/app/agents/settings) and find **Auth connections**. Use a workspace account permitted to manage these credentials.
  </Step>

  <Step title="Choose the method">
    Select **Add auth** and the method required by the provider. Enter a useful **Name**, review the **Provider** field, and supply the required configuration. Use the provider's current documentation for scopes, claims, and token parameters.
  </Step>

  <Step title="Save and read back">
    Select **Create auth connection**, then reopen the saved entry and inspect the non-secret metadata. Retain the connection ID for supported references. Do not expect the raw credential to appear in the list or edit form.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for workspace auth connections. This illustration is not a product screenshot." />
</Frame>

## Reference and update

Select the saved connection in a supported MCP or tool field, or use its identifier in a supported [environment value](/agents-platform/deploy/environment-variables). Creating a connection does not attach it to every agent or grant resource access to every member.

For a manually managed connection, use its actions menu and **Edit connection** when permitted. Confirm the metadata and changed fields before **Save changes**. Empty secret fields keep the existing values in the supported edit workflow. Do not treat an empty field as a request to clear a credential.

Provider-managed native connections must be managed through their integration workflow. Review dependencies before deletion or rotation. If the edit is rejected because the resource changed, refresh and reconcile with the current version instead of repeatedly overwriting it.

## Verify the external boundary

Credential storage is separate from successful authentication to a provider and successful tool execution. When the intended request path is available, test a harmless operation against the approved provider endpoint, inspect its outcome, and verify that an incorrect or revoked credential fails. Do not use a production mutation as a connection test.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can this replace my Threetone API key?">No. Auth connections authenticate supported requests to external services. Use [Access and credentials](/agents-platform/configure/authentication/overview) for Threetone's API and session boundaries.</Accordion>
  <Accordion title="Why are saved password and token fields empty when editing?">The form does not retrieve raw stored secrets. Leaving a secret field empty preserves its current value in the supported edit workflow. Enter a new value when intentionally replacing it.</Accordion>
  <Accordion title="Why can I not edit a native provider connection here?">Its management type and permissions determine the available actions. Use the native integration workflow for provider-managed connections.</Accordion>
</AccordionGroup>


# Access and credentials
Source: https://docs.threetone.in/agents-platform/configure/authentication/overview

Separate API keys, dashboard sessions, provider credentials, and conversation access when preparing an agent integration.

Choose the credential for the operation you are performing. A personal API key, dashboard session, provider secret, and conversation token have different purposes and should not be exchanged as substitutes.

## Credential boundaries

| Credential | Purpose | Where it belongs |
| - | - | - |
| Personal API key | Permitted programmatic API operations. | Server-side integration secret storage. |
| Dashboard session | Signed-in account workflows and dashboard-only management. | The authenticated dashboard. |
| Provider credential | Access to a connected external service. | The supported workspace credential or connection workflow. |
| Conversation token | Access to a particular runtime session where supported. | The supported session workflow, not a replacement for a workspace API key. |

## Server-side API access

Create a scoped key in [workspace API keys](/overview/administration/workspaces/api-keys) and send it in `x-api-key`. Follow the [authentication reference](/api-reference/authentication) for header examples and error handling. Do not send both `x-api-key` and `Authorization` in one request.

Keep the key out of client-side JavaScript, URLs, prompts, screenshots, and logs. Give separate services their own keys so you can revoke one without disrupting unrelated integrations.

## Workspace and resource access

A valid credential does not guarantee access to every workspace resource or operation. Check the workspace, key permissions, and resource access. Tool management and billing administration currently have different credential requirements from ordinary public API reads.

Use [environment variables](/agents-platform/deploy/environment-variables) for supported strings and credential references. A reference identifies a workspace resource; it does not grant a new user or agent permission to use it.

For provider credentials, follow [auth connections](/agents-platform/configure/authentication/auth-connections) or [workspace secrets](/agents-platform/configure/authentication/secrets). A [native integration](/agents-platform/configure/integrations/overview) manages its provider connection through a separate workflow.

## Conversation access

<Note>
  Public conversation token and signed-URL initiation are currently gated in the documented implementation. Agent authentication settings can be represented in configuration, but their presence does not establish a working protected session.
</Note>

The dashboard's preview Security controls are not a verified persisted setup workflow. Do not rely on a preview toggle as proof of authentication enforcement. When a supported runtime path is released, assess token scope, expiry, workspace ownership, and unauthorized access against that release.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I put my workspace API key in a web widget?">No. Keep the key server-side. A browser integration needs its own supported session-access design and must not expose a workspace credential.</Accordion>
  <Accordion title="Why can a valid key receive 403?">The key can authenticate while lacking permission, resource access, an allowed source IP, or support for that credential type on the operation.</Accordion>
  <Accordion title="Does a Security toggle mean access is enforced?">No. A local preview control or stored setting must be distinguished from released runtime enforcement.</Accordion>
</AccordionGroup>


# Workspace secrets
Source: https://docs.threetone.in/agents-platform/configure/authentication/secrets

Store a private workspace value, use its identifier in supported configuration, and review dependencies before replacement or removal.

Workspace secrets hold private values that supported configuration fields can reference by identifier. A secret is not a prompt variable, an API key for Threetone, or a complete provider connection.

<Frame>
  <img alt="Recording pending for workspace secret configuration. No playable video is available yet." />
</Frame>

## Add a secret

<Steps>
  <Step title="Open workspace credential settings">
    Select the intended workspace and open [Agent Settings](https://threetone.in/app/agents/settings). Find **Workspace secrets** and select **Add secret**.
  </Step>

  <Step title="Enter a useful name and private value">
    Enter **Name** and **Value**, then submit the form. Use a name that identifies the purpose without including the credential itself. Do not include customer data in the name.
  </Step>

  <Step title="Confirm the stored reference">
    Reopen the list, confirm the saved name and identifier, and inspect any recorded dependencies. The raw value is not retrievable through this settings workflow. Keep the original credential in your approved private credential storage.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for the workspace secret list. This illustration is not a product screenshot." />
</Frame>

## Use a supported reference

Use the saved identifier where a field explicitly accepts a secret reference. For example, a secret-typed [environment value](/agents-platform/deploy/environment-variables) uses a `secret_id` reference. Plain strings and prompt placeholders do not become private simply because you put a secret value inside them.

Use [auth connections](/agents-platform/configure/authentication/auth-connections) when the provider needs a structured authentication method. Use a native integration's own workflow for its managed credentials. These resources have different ownership and update behavior.

## Replace or remove safely

Review dependent resources before changing a credential. For replacement, prepare the new secret, update the intended references through their supported workflow, and verify the resulting configuration before retiring the old provider credential. Revoking a provider credential and deleting a Threetone secret are different actions.

If deletion reports dependencies, inspect those resources instead of assuming the reference is unused. Do not promise immediate provider revocation, historic-data erasure, or automatic cleanup of all agent versions from a secret-deletion response.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I retrieve the stored secret value from Settings?">No. Verify its name, identifier, and dependencies through the supported workflow. Store the original credential privately when the provider issues it.</Accordion>
  <Accordion title="Can I put the value in a dynamic variable instead?">Do not use prompt placeholders for private credentials. A supported secret reference identifies private storage; a string in a prompt does not.</Accordion>
  <Accordion title="Does deleting the secret revoke the provider key?">Provider revocation is a separate action. Follow that provider's credential-management workflow and verify dependent resources before removal.</Accordion>
</AccordionGroup>


# Cal.com
Source: https://docs.threetone.in/agents-platform/configure/integrations/calcom

Prepare a Cal.com API-key connection, create selected integration tools, and review their saved agent attachment.

Use the native Cal.com connection to prepare scheduling tools for a workspace. The reviewed implementation enables provider connection and tool creation. This guide ends with saved resources and a reviewed agent configuration.

<Note>
  Cal.com is a preview integration. Availability depends on the deployed catalog and provider configuration. Live agent session initiation remains gated in the documented implementation; saving these resources does not demonstrate a completed booking.
</Note>

<Frame>
  <img alt="Recording pending for Cal.com connection and tool configuration. No playable video is available yet." />
</Frame>

## Before you begin

Use a signed-in workspace account with permission to manage connections and tools. Prepare a dedicated Cal.com account or credential with the access required for your scheduling task. Review the provider's [API v2 authentication guidance](https://cal.com/docs/api-reference/v2/introduction#authentication) when creating a key.

The current Threetone native workflow uses an API key rather than an interactive OAuth consent flow. Enter the raw key in its dedicated field; the integration prepares the provider authentication header. Keep the key out of prompts, example arguments, recordings, and browser embed code.

## Create the connection

<Steps>
  <Step title="Select the provider">
    Open [Integrations](https://threetone.in/app/agents/integrations), select **Add integration**, and find **Cal.com**. Review the provider details, then open its connection form. If the deployed catalog says connection is unavailable, stop and check that release before continuing.
  </Step>

  <Step title="Provide the credential">
    Review the **API Key** credential method, enter a useful connection name and the key, then select **Connect**. Keep the selected provider account separate from unrelated team or customer accounts.
  </Step>

  <Step title="Read the connection back">
    Reopen the saved connection in the list and confirm its identifier, provider, name, and ownership. Check errors or reconnection requirements before creating tools. A displayed Connected badge does not replace inspection of the stored connection state.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for the Cal.com connection form. This illustration is not a product screenshot." />
</Frame>

## Create only the tools you need

Use the integration-tool creation flow in [Tools](https://threetone.in/app/agents/tools). In **Select Integration Tool**, choose the eligible connection and select the intended operations. Confirm **Create Tools**, then inspect the created definitions and identifiers.

The reviewed Cal.com operation contracts include availability and booking operations. Review the current operation list and its inputs instead of copying names or parameter shapes from a different release. Start with the smallest useful set. Creating a cancellation or booking tool grants a different capability from creating a read-only availability tool.

This flow currently supports eligible personal connections. Shared-connection tool creation is unavailable. An inactive connection or a provider without enabled tool creation is not a valid substitute.

Attach the created tool IDs through the agent's **Tools** page. Review the prompt, attachment list, and selected branch together, then save a complete server draft. Publication requires an eligible managed text-only configuration; voice and custom-model publication are unavailable. Reopen the draft or eligible published version to confirm the saved references.

## Prepare a scheduling task

Document the event type, attendee fields, and IANA time zone that the task requires. Distinguish the caller's requested time from the provider's returned availability. Define when the user must confirm a booking, cancellation, or rescheduling request. Confirm an external action only after its supported execution path returns a verifiable result.

When execution becomes available, test reads first in a controlled provider account. Then test writes, retries, unavailable slots, provider rejection, and an uncertain result before using customer data. Do not infer a booking from successful credential storage.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I include Bearer in the API Key field?">Enter the raw key in the native connection form. The catalog's credential binding adds the authentication header. A separately authored webhook may use a different explicit header configuration.</Accordion>
  <Accordion title="Why is my connection missing from the tool selector?">Check that it is active, visible to your workspace account, and supports tool creation. Shared connections are not supported by the reviewed tool-creation path.</Accordion>
  <Accordion title="Does Connect validate a complete booking workflow?">No. Connection storage, provider credential testing, tool creation, and agent execution are separate checks. This guide does not claim a successful live booking.</Accordion>
</AccordionGroup>


# Calendly
Source: https://docs.threetone.in/agents-platform/configure/integrations/calendly

Review the planned Calendly connection method and the prerequisites for a future scheduling integration.

Calendly appears in the reviewed integration catalog, but its self-serve connection and tool-creation flows are disabled. The dashboard preview describes the intended provider and operations. It does not establish a usable connection.

<Note>
  Do not enter a token into an unrelated provider form to work around the disabled flow. Wait for a release that explicitly enables the Calendly connection and the intended operation contracts.
</Note>

## Prepare for the connection release

The catalog defines a Personal Access Token credential method. Use [Calendly's token documentation](https://developer.calendly.com/docs/authentication/how-to-authenticate-with-personal-access-tokens) to understand account permissions and scopes. There is no need to create or paste a credential merely to inspect the current Threetone preview.

Plan which account owns the event types, what calendar data the task needs, and which changes require confirmation. Provider account access and subscription restrictions are separate from Threetone workspace access.

## What the release must establish

| Check | Required result |
| - | - |
| Credential setup | The deployed form supports the intended token method and stores it privately. |
| Connection state | The connection can be read back, reconnected, and removed through the supported workflow. |
| Tool definitions | Released operation contracts define the actual inputs, outputs, and allowed actions. |
| Agent execution | A supported runtime can call those operations with the intended workspace and account. |
| Result verification | Controlled tests confirm provider outcomes and failure handling. |

Use [integration overview](/agents-platform/configure/integrations/overview) to choose an available connection method today. A custom integration needs its own supported credentials and execution design; it is not automatically equivalent to the planned native connector.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why can I see Calendly but not connect it?">The catalog can display a preview definition while its connection feature remains disabled. Check the provider's current release status and enabled actions.</Accordion>
  <Accordion title="Are the listed operations ready to execute?">No executable Calendly operation manifest is established by the reviewed source. Catalog descriptions are planning information rather than proof of tool execution.</Accordion>
</AccordionGroup>


# Cursor
Source: https://docs.threetone.in/agents-platform/configure/integrations/cursor

Plan a reviewed IDE workflow for inspecting Threetone configuration without assuming a hosted management server.

Use this preparation guide to define a Cursor workflow that inspects an agent's saved configuration and proposes a change for review.

<Note>
  Threetone has no verified native Cursor connector or first-party hosted agent-management MCP service. This page describes integration preparation. It does not provide an install command or a working agent runtime.
</Note>

## Prepare the IDE workflow

You need an approved development workspace, permission to read the target agent, and an owner for any adapter you build.

<Steps>
  <Step title="Choose a read-only starting task">
    Start with reading an agent and comparing its saved configuration with a proposed prompt change. Record the workspace, agent, branch, and version identifiers. Use the committed [API reference](/api-reference/introduction) to determine which reads accept your credential.
  </Step>

  <Step title="Review the adapter and credential boundary">
    Cursor is an MCP client with local and remote server options. Review its [MCP documentation](https://cursor.com/docs/mcp) before trusting an adapter. Keep Threetone credentials outside repository files and prompts. A server you operate must restrict its exposed operations and permitted workspaces.
  </Step>

  <Step title="Separate proposals from writes">
    Have the adapter return a readable diff before any future write. Require an explicit decision on the target branch and re-read its version to detect stale proposals. If a request times out, inspect saved state before retrying.
  </Step>
</Steps>

The result is an adapter specification and a review procedure. Threetone's [MCP server configuration](/agents-platform/configure/integrations/mcp-servers) makes Threetone a consumer of external tools; it does not expose Threetone as a server for Cursor.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is there a Threetone MCP URL to paste into Cursor?">No verified first-party endpoint is available. See [Hosted MCP](/agents-platform/monitor/hosted-mcp) for that release boundary.</Accordion>
  <Accordion title="Can an IDE adapter manage every tool with my API key?">No. Current tool-management operations reject API-key credentials. Follow the supported [tool configuration workflow](/agents-platform/configure/tools/overview); do not give an adapter dashboard session credentials.</Accordion>
</AccordionGroup>


# Custom channel
Source: https://docs.threetone.in/agents-platform/configure/integrations/custom-channel

Define identity, routing, delivery, and failure requirements for an application-owned conversation channel.

A custom channel would connect messages from your application to an agent and return replies to the correct recipient. Prepare that boundary before choosing a transport.

<Note>
  There is no verified released custom-channel adapter or custom WebSocket SDK. Agent execution remains gated. Saving a tool or agent configuration does not create an inbound messaging endpoint.
</Note>

## Design the message flow

You need a channel owner, its authentication contract, sample messages without personal data, and a documented routing policy.

<Steps>
  <Step title="Identify the sender and destination">
    Define how your server authenticates the channel's requests and maps a channel user to permitted application data. Bind the target workspace and agent on your server. A channel user ID does not grant workspace membership or authorize an arbitrary agent ID.
  </Step>

  <Step title="Define delivery records">
    Preserve the provider message ID, destination, and processing outcome. Deduplicate repeated inbound deliveries. Specify size and attachment limits, unsupported-message responses, and how an operator handles a message that cannot be routed.
  </Step>

  <Step title="Review outbound actions">
    Show the intended recipient and message before a consequential send. Track acceptance separately from delivery and conversation completion. An uncertain response requires reconciliation before retrying, so one request does not produce duplicate messages.
  </Step>
</Steps>

Use [secrets](/agents-platform/configure/authentication/secrets) and [auth connections](/agents-platform/configure/authentication/auth-connections) only in supported configuration fields. [Tool authoring](/agents-platform/configure/tools/overview) can describe a future outbound action. It does not implement your bridge or release the [agent runtime](/agents-platform/overview#current-availability).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a client tool receive incoming channel messages?">A saved client tool definition does not provide an inbound transport. Your channel design needs a separately implemented and authorized receiver.</Accordion>
  <Accordion title="What should be ready before a live channel test?">A released execution path, reviewed identity mapping, retry handling, recipient confirmation, and a tested route for delivery failures. Configuration read-back alone proves none of these.</Accordion>
</AccordionGroup>


# Exa
Source: https://docs.threetone.in/agents-platform/configure/integrations/exa

Prepare a bounded public-web research action with source URLs, limited queries, and explicit failure results.

Plan an Exa action that finds public sources for a specific research question, such as a company's published product documentation. Return evidence the reader can inspect.

<Note>
  Exa is absent from the current native integration catalog. These steps prepare an external tool design. Saved credentials and tool definitions do not enable live agent execution.
</Note>

## Prepare a source lookup

Have an approved Exa account, a credential owner, and a short list of information the action may send outside your application.

<Steps>
  <Step title="Limit the search">
    Define the question, allowed domains where appropriate, result limit, and maximum returned text. Send only the search terms needed for the task. Do not forward a full customer conversation to obtain public product information.
  </Step>

  <Step title="Choose the request boundary">
    Exa documents API-key authentication with the `x-api-key` header in its [Search reference](https://exa.ai/docs/reference/search). Keep the key in your server's secret store, or a supported [workspace secret](/agents-platform/configure/authentication/secrets) reference when authoring an applicable tool field. Never place it in the prompt or query.
  </Step>

  <Step title="Return evidence and errors separately">
    Preserve each source URL and the relevant excerpt. Treat retrieved text as source material, not instructions to execute tools. Define distinct outcomes for no useful results, authentication failure, quota exhaustion, and timeout. None should produce a fabricated citation.
  </Step>
</Steps>

Review the proposed input and result contract through [tool configuration](/agents-platform/configure/tools/overview). Confirm the exact schema and bounded response in your own service before any future runtime test.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should a search result trigger an external action?">No. Research results can inform a proposal. Sending messages or changing records requires a separate authorized action and confirmation where appropriate.</Accordion>
  <Accordion title="Does saving an Exa key test the connection?">No. Secret storage proves that a value was saved. Provider authentication, the tool's request contract, and agent execution need separate verification.</Accordion>
</AccordionGroup>


# Freshdesk
Source: https://docs.threetone.in/agents-platform/configure/integrations/freshdesk

Prepare ticket lookup and reviewed support-note actions with account permissions and clear reply visibility.

Start a Freshdesk integration design with ticket lookup and a drafted internal note. Keep customer-facing replies as a separate action with explicit review.

<Note>
  There is no current native Freshdesk connector. You can prepare a credential and tool contract, but this guide does not enable a live support workflow.
</Note>

## Prepare the ticket workflow

You need a Freshdesk account owner, an approved test ticket, and an agreed list of fields that may enter agent context.

<Steps>
  <Step title="Choose restricted account access">
    Freshdesk's [API documentation](https://developers.freshdesk.com/api/) describes Basic authentication using the API key as the username and a dummy password. The underlying account's permissions still apply. Choose an account whose ticket access matches the task and keep its key in the supported [auth-connection workflow](/agents-platform/configure/authentication/auth-connections).
  </Step>

  <Step title="Define a small ticket result">
    Resolve the exact ticket ID and account before returning its subject, status, and permitted conversation excerpts. Exclude attachments and unrelated requester details unless needed. Separate lookup permission from permission to add a note or reply.
  </Step>

  <Step title="Review the proposed note">
    Show the ticket, text, and visibility before submission. Distinguish an internal note from a public reply. If the eventual request times out, inspect the ticket's recent activity before retrying; do not create duplicate notes from an uncertain result.
  </Step>
</Steps>

Use [tool authoring](/agents-platform/configure/tools/overview) to document the intended action and error response. Saving the definition does not authenticate to Freshdesk or prove runtime availability.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can one broad API key be limited by a prompt?">No. Enforce ticket and action restrictions in the provider account and your service. Prompt instructions cannot reduce the credential's actual access.</Accordion>
  <Accordion title="What should happen when a ticket is unavailable?">Report that the lookup could not be completed. Do not infer that the ticket was deleted or create a replacement ticket without a separate decision.</Accordion>
</AccordionGroup>


# Genesys
Source: https://docs.threetone.in/agents-platform/configure/integrations/genesys

Prepare contact-center context and handoff requirements without assuming a live media or transfer integration.

Plan a Genesys Cloud workflow that identifies an approved queue and prepares a concise handoff summary. Treat routing context, call control, and media transport as separate requirements.

<Note>
  Threetone has no native Genesys connector or verified live Genesys transfer workflow. Agent runtime remains gated. A saved credential does not establish a contact-center bridge.
</Note>

## Prepare a handoff design

Have your Genesys administrator identify the organization, region, permitted queues, and a test environment.

<Steps>
  <Step title="Choose the authentication context">
    Genesys [OAuth client guidance](https://help.genesys.cloud/articles/create-an-oauth-client/) distinguishes client credentials from user authorization. Client credentials cannot call user-specific APIs. Review the exact operation before choosing a grant; give a service client only the required roles and divisions.
  </Step>

  <Step title="Limit the handoff payload">
    Define the queue identifier, routing reason, and permitted summary fields. Include only information the receiving team needs. Specify who may select or change the destination. Do not let free-form agent output choose an unrestricted queue or organization.
  </Step>

  <Step title="Define acceptance and fallback">
    A future action should confirm the destination before requesting a handoff and distinguish accepted routing from an answered call. Define the response to an unavailable queue, rejected permission, timeout, or disconnected caller. Preserve the request identifier for reconciliation.
  </Step>
</Steps>

Supported [manual auth connections](/agents-platform/configure/authentication/auth-connections) can store compatible configuration. [Tool authoring](/agents-platform/configure/tools/overview) records the proposed action. Interactive user authorization and live telephony require their own released implementation.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will a client-credentials connection act as a Genesys user?">No. Its authorization context differs from a user's. Confirm that every selected endpoint permits the chosen grant and assigned roles.</Accordion>
  <Accordion title="Can I test a live transfer after saving the tool?">No released Threetone transfer path is verified. Review [current availability](/agents-platform/overview#current-availability) before scheduling an end-to-end test.</Accordion>
</AccordionGroup>


# Google Calendar
Source: https://docs.threetone.in/agents-platform/configure/integrations/google-calendar

Prepare availability lookup and separately confirmed booking with narrow calendar access and timezone review.

Design availability lookup before event creation. A useful first task answers whether an approved calendar is busy during a specified time window without returning event descriptions.

<Note>
  Google Calendar is absent from the native catalog. Threetone does not provide a Google consent wizard for this workflow. This guide prepares an external integration and its tool contract.
</Note>

## Prepare availability and booking

You need an authorized calendar owner, a test calendar, and an application responsible for Google's OAuth consent and token lifecycle.

<Steps>
  <Step title="Request only the required access">
    Google's [Calendar authorization guide](https://developers.google.com/workspace/calendar/api/auth) separates free/busy, event-read, and event-write scopes. Choose the narrowest scope that covers the selected calendars. Do not request event-writing access for availability lookup alone.
  </Step>

  <Step title="Make the time window explicit">
    Record the calendar ID, start and end, timezone, and meeting duration. Return availability without exposing titles or attendees unless the task requires them. Treat a failed lookup as unknown availability, never as an empty calendar.
  </Step>

  <Step title="Review a booking separately">
    Before a future event write, confirm the calendar, local date and time, attendees, description, and notification behavior. Recheck availability because the calendar may have changed. After an uncertain response, reconcile with the calendar before retrying creation.
  </Step>
</Steps>

Use [tool configuration](/agents-platform/configure/tools/overview) to keep lookup and booking separate. An [auth connection](/agents-platform/configure/authentication/auth-connections) stores supported manual credentials; it does not implement delegated Google consent or release tool execution.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does free/busy access reveal event details?">Design the lookup to return occupied intervals only. If event details are needed, review the corresponding scope and data access separately.</Accordion>
  <Accordion title="Does an available slot reserve the time?">No. A lookup is a point-in-time result. A confirmed booking needs a separate authorized write and subsequent read-back.</Accordion>
</AccordionGroup>


# Google Drive
Source: https://docs.threetone.in/agents-platform/configure/integrations/google-drive

Prepare selected-document access and knowledge import with explicit permissions, provenance, and removal rules.

Plan a workflow that reads one approved Drive document for a knowledge source. Decide whether your application needs a temporary excerpt or a separately stored copy.

<Note>
  There is no native Google Drive connector, Google file picker, or continuous Drive synchronization in the reviewed Threetone implementation. Existing knowledge import is a separate workflow.
</Note>

## Prepare a document import

You need the document owner's approval, a known file ID, and an application that owns Google authorization and any export operation.

<Steps>
  <Step title="Choose file access deliberately">
    Google's [Drive scope guide](https://developers.google.com/workspace/drive/api/guides/api-specific-auth) recommends narrow per-file access where appropriate. The `drive.file` scope covers files opened or shared with the app and can permit changes; it is not universal read-only access. Review the scope, app behavior, and selected files together.
  </Step>

  <Step title="Record the source and permitted content">
    Preserve the file ID, source URL, title, and version or modification evidence available to your application. Review document text before export. Exclude comments, linked files, or attachments unless separately approved.
  </Step>

  <Step title="Review the copy's lifecycle">
    If you import an approved export through [knowledge document management](/agents-platform/configure/knowledge-base/manage-documents), read the document and ingestion status back. Assign an owner for refresh and removal. Revoking Drive access does not automatically remove a copy previously uploaded to Threetone.
  </Step>
</Steps>

Keep Google token handling in the authorized integration service. A [manual auth connection](/agents-platform/configure/authentication/auth-connections) does not supply a Google consent flow. For a future on-demand fetch, review the [tool contract](/agents-platform/configure/tools/overview) and report inaccessible or stale sources explicitly.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will changes to a Drive file update knowledge automatically?">No verified synchronization exists. Review and replace imported content through the knowledge workflow when its source changes.</Accordion>
  <Accordion title="Can I import an entire shared drive?">This guide covers selected documents. Bulk enumeration, permission propagation, and deletion synchronization need separate implementation and access review.</Accordion>
</AccordionGroup>


# HubSpot
Source: https://docs.threetone.in/agents-platform/configure/integrations/hubspot

Prepare CRM context lookup and reviewed property updates with account-specific authorization and record matching.

Begin a HubSpot design with contact or company lookup, then propose a small property update for human review. Keep the exact CRM record and account visible throughout the action.

<Note>
  HubSpot is not a current native Threetone connector. The workflow below prepares an external integration. Neither saved credentials nor an authored tool enable CRM execution.
</Note>

## Prepare CRM access

You need a HubSpot administrator, a test account or approved test records, and a list of allowed objects and properties.

<Steps>
  <Step title="Choose an authentication model">
    HubSpot's [authentication overview](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/overview) distinguishes OAuth from static authentication for a single authorized account. Choose the supported model for your distribution and request only required object access. Client-credentials tokens for app configuration do not substitute for user-account authorization.
  </Step>

  <Step title="Resolve the record before reading">
    Require a confirmed record ID or a reviewed match. A company name alone can be ambiguous. Return only allowed properties and relevant associations. Keep each account's credentials and identifiers separate.
  </Step>

  <Step title="Review the proposed change">
    Show the account, record, existing value, and replacement value. Confirm association changes separately from property updates. Re-read stale records and reconcile uncertain writes before retrying. Treat permission and rate-limit failures as incomplete actions.
  </Step>
</Steps>

Use [auth connections](/agents-platform/configure/authentication/auth-connections) only for compatible manually managed credentials. An external service must own any interactive OAuth lifecycle. [Tool configuration](/agents-platform/configure/tools/overview) can describe the reviewed lookup and update as separate actions.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a single-account token connect every customer's account?">No. Select the provider-supported authorization and distribution model for each intended account. Do not reuse one customer's credential for another.</Accordion>
  <Accordion title="Does a provider-hosted MCP service make this native?">No. An external MCP service still needs compatible authentication and transport. Threetone's [MCP discovery and execution limits](/agents-platform/configure/integrations/mcp-servers) remain applicable.</Accordion>
</AccordionGroup>


# Intercom
Source: https://docs.threetone.in/agents-platform/configure/integrations/intercom

Prepare conversation lookup and reviewed support replies with appropriate OAuth and audience controls.

Design an Intercom workflow that retrieves permitted conversation context and drafts a response. Keep reading context, adding an internal note, and replying to a customer as distinct actions.

<Note>
  No native Intercom connector or live reply workflow is available in the current Threetone catalog. This guide prepares the authorization and action design.
</Note>

## Prepare the support workflow

Have a workspace administrator, a test conversation, and an owner for your integration's OAuth lifecycle.

<Steps>
  <Step title="Use the right authorization flow">
    Intercom's [authentication guide](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication) requires OAuth for integrations accessing other people's workspaces. Do not ask customers to supply their private access tokens. Review only the permissions needed for the selected conversation and contact operations.
  </Step>

  <Step title="Limit retrieved context">
    Bind the workspace and conversation ID before reading. Return relevant message excerpts and status, with only the contact fields needed for support. Avoid copying an entire contact profile or unrelated conversation history into a prompt.
  </Step>

  <Step title="Confirm audience and sender">
    Before a future write, show the destination conversation, sender identity, text, and whether the action is an internal note or customer-visible reply. On timeout, inspect the conversation before retrying. An accepted request must not be described as a delivered reply without matching evidence.
  </Step>
</Steps>

Use [tool authoring](/agents-platform/configure/tools/overview) for separate lookup and reply contracts. Threetone's [auth connections](/agents-platform/configure/authentication/auth-connections) do not provide an interactive Intercom installation or consent wizard.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a stored bearer token implement OAuth consent?">No. Token storage and user authorization are different responsibilities. Your approved integration must manage consent, token lifecycle, and revocation.</Accordion>
  <Accordion title="Should a failed lookup create a new conversation?">No. Report the failed lookup and resolve its access or identifier problem. Creating a conversation is a separate action with a reviewed recipient.</Accordion>
</AccordionGroup>


# Jira
Source: https://docs.threetone.in/agents-platform/configure/integrations/jira

Prepare issue drafts and reviewed updates with project permissions, precise targets, and duplicate prevention.

Plan a Jira action that turns a reviewed support problem into an issue draft. The reviewer should see the project, issue type, summary, description, and selected fields before creation.

<Note>
  Jira is absent from the current native catalog. This page prepares an external integration; it does not provide an installation wizard or working issue-creation tool.
</Note>

## Prepare an issue workflow

You need a project owner, an approved test project, and a mapping between the proposed action and that project's required fields.

<Steps>
  <Step title="Review application authorization">
    Atlassian's [REST authentication guidance](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/) recommends OAuth 2.0 authorization-code grants for integrations. Do not build a distributed integration that collects customers' API tokens or asks each customer to create an individual OAuth app. Review the app's permissions and the user's project access together.
  </Step>

  <Step title="Prepare a concrete issue draft">
    Include only the problem details needed by the project. Remove secrets and unnecessary customer data from transcripts. Resolve project and issue identifiers explicitly; names alone may be ambiguous. Validate required fields against the target project's current configuration.
  </Step>

  <Step title="Confirm writes and reconcile failures">
    Review issue creation separately from comments, assignments, and workflow transitions. On an uncertain creation result, search for the intended issue before retrying. If the project rejects a field or transition, report that rejection without claiming the issue changed.
  </Step>
</Steps>

Document each action through [tool configuration](/agents-platform/configure/tools/overview). An [auth connection](/agents-platform/configure/authentication/auth-connections) cannot supply the missing interactive OAuth flow or release agent execution.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a valid token grant every project permission?">No. The underlying user and project permissions still matter. Verify access to the actual project and operation.</Accordion>
  <Accordion title="Can a prompt choose any issue transition?">No. The integration must validate transitions against the issue's current workflow and enforce authorization before requesting a change.</Accordion>
</AccordionGroup>


# MCP servers
Source: https://docs.threetone.in/agents-platform/configure/integrations/mcp-servers

Save a reviewed MCP endpoint and credential reference, configure approval intent, and attach the server to an agent version.

Model Context Protocol, or MCP, gives external servers a common way to describe tools. Threetone can store an MCP server configuration and its agent attachment. Review who operates the server and what it can access before saving it.

<Note>
  The current **Test Connection** button is disabled, and server tool discovery returns an unavailable result. Saving the server is a configuration operation. It does not verify transport connectivity, tool discovery, approvals at runtime, or execution.
</Note>

<Frame>
  <img alt="Recording pending for MCP server configuration. No playable video is available yet." />
</Frame>

## Before you begin

Have a documented endpoint, its supported transport, its operator, and its authentication requirements. Use an account allowed to manage workspace tools. Keep credentials in the supported [auth-connection](/agents-platform/configure/authentication/auth-connections) or [secret](/agents-platform/configure/authentication/secrets) workflow.

## Save the configuration

<Steps>
  <Step title="Open the server form">
    Open [Integrations](https://threetone.in/app/agents/integrations) and select **Add MCP server**. Enter a useful **Name** and an optional **Description**.
  </Step>

  <Step title="Set the endpoint and transport">
    Set **Transport Protocol** to the server's documented **Server-Sent Events (SSE)** or **Streamable HTTP** transport. Enter the **Server URL** and select an appropriate auth connection if required. Review any configured request headers and metadata.
  </Step>

  <Step title="Review approval intent">
    Review the tool approval mode and other settings against the actions this server exposes. A stored approval policy does not establish runtime enforcement. Avoid granting broad mutation access merely to simplify configuration.
  </Step>

  <Step title="Acknowledge the operator and save">
    Select **I trust this server** only after reviewing its operator and data access. Threetone does not verify custom servers through that checkbox. Select **Add Server**, then reopen the entry to inspect the saved endpoint, transport, credential reference, and identifier.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for MCP server configuration. This illustration is not a product screenshot." />
</Frame>

## Attach the server

The agent's **Tools > MCP** tab currently opens the workspace server list and its details. Selecting an entry there does not save an agent attachment.

Use [Update agent](/api-reference/agents-platform/update-agent) with an explicit `branch_id` to author `conversation_config.agent.prompt.mcp_server_ids`. Preserve the intended existing server references when replacing that list. Read the selected branch and resulting version back to confirm the saved identifier. Follow [versions and drafts](/agents-platform/deploy/versioning) when reviewing a complete server draft.

Shared server configuration changes and agent publication are separate actions. Review agents that reference a server before changing or removing it. Retain a server-side record of the resource IDs your integration needs.

## Plan execution verification

When discovery and execution are released, confirm the actual tools and schemas returned by the server. Test credential scope, read and write permissions, required confirmations, endpoint failures, and changed tool definitions. Instructions returned by an external server do not override your application's access policy.

The [Create MCP server](/api-reference/agents-platform/create-mcp-server) and [Update MCP server configuration](/api-reference/agents-platform/update-mcp-server-configuration) pages describe the committed public schemas. Check operation permissions before using a programmatic credential.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does Add Server test the endpoint?">No. The reviewed create path stores the configuration. The disabled Test Connection control and unavailable tool discovery must not be interpreted as successful tests.</Accordion>
  <Accordion title="Does I trust this server mean Threetone verified it?">No. You acknowledge the custom server's operator and intended access. Review the provider independently before sending data or credentials.</Accordion>
  <Accordion title="Is a saved approval policy sufficient?">No. Confirm enforcement and the actual tool contract when the execution path is released. Storing a policy alone does not demonstrate a confirmation step.</Accordion>
</AccordionGroup>


# Integrations
Source: https://docs.threetone.in/agents-platform/configure/integrations/overview

Choose a native provider connection, a custom MCP server, or a webhook tool, then review its credentials and agent attachment.

An integration connects a workspace resource to an external service. Choose the connection method before creating tools or attaching the resource to an agent.

## Choose a connection method

| Method | Use it for | Start here |
| - | - | - |
| Native integration | A provider offered by the deployment's integration catalog. | [Cal.com](/agents-platform/configure/integrations/calcom) or [Calendly preview](/agents-platform/configure/integrations/calendly). |
| Custom MCP server | A server you operate or have reviewed and trust. | [MCP server configuration](/agents-platform/configure/integrations/mcp-servers). |
| Webhook tool | A documented HTTP action that you configure and authorize separately. | [Agent tools](/agents-platform/configure/tools/overview). |

<Note>
  The reviewed native catalog contains Cal.com and Calendly. Cal.com enables connection and tool-creation workflows; Calendly is a preview with self-serve connection disabled. The deployed catalog can differ. A listed provider, saved connection, or attached tool does not prove live agent execution.
</Note>

## Review the dashboard catalog

Open [Integrations](https://threetone.in/app/agents/integrations) in the intended workspace. The list combines installed native connections and saved MCP servers. Select **Add integration** to inspect available providers, search by name, or filter by category. Select **Add MCP server** for a custom endpoint.

Before connecting, review the provider, credential method, ownership, and allowed actions. A credential with access to a provider account can grant more access than one task requires. Use a dedicated account or appropriately limited credential where the provider supports it.

## Connect, create tools, and attach

These are separate changes:

1. A provider connection stores the relationship and credential reference.
2. Creating integration tools selects the provider operations the workspace needs.
3. Saving an agent draft preserves the selected tool or server identifiers. Later publication is available only for an eligible configuration; voice and custom-model publication remain gated.

Read each result back. Review changing shared resources separately from the agent's configuration diff. Check [current execution availability](/agents-platform/overview#current-availability) before planning a live demonstration.

## Credentials and environments

Use [auth connections](/agents-platform/configure/authentication/auth-connections) for supported reusable authentication and [workspace secrets](/agents-platform/configure/authentication/secrets) for private stored values. Native provider connections have their own managed credential workflow. Editing an unrelated secret does not automatically rotate a native provider connection.

Use [environment variables](/agents-platform/deploy/environment-variables) when a supported field needs a string, secret reference, or auth-connection reference for an environment. Keep personal API keys server-side.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I connect a provider that is absent from the catalog?">There is no verified native connection workflow for an absent provider. Review a custom MCP or webhook design where appropriate. Its credential, transport, and execution requirements still need verification.</Accordion>
  <Accordion title="Does Connected mean every action works?">No. Verify the stored connection status, provider access, enabled operations, and the intended execution path separately. A label alone is insufficient.</Accordion>
  <Accordion title="Are integration tools added to an agent automatically?">Creating a connection or tool is separate from saving the agent's attachment list. Follow the provider guide, attach the reviewed identifiers, and preserve a server draft. Publish only an eligible configuration on the intended branch.</Accordion>
</AccordionGroup>


# Parallel
Source: https://docs.threetone.in/agents-platform/configure/integrations/parallel

Prepare a bounded web-research action with a clear objective, attributable evidence, and incomplete-result handling.

Use Parallel to plan a focused research action, such as finding a vendor's published integration requirements. Define what evidence would answer the question before selecting search terms.

<Note>
  Parallel is not in Threetone's current native catalog. This guide prepares a search tool design. It does not enable background research, scheduled monitors, or live agent execution.
</Note>

## Prepare a research request

Have an approved provider account, a credential owner, and a limit for request cost and response size.

<Steps>
  <Step title="State the research objective">
    Write a bounded objective and a small set of relevant search queries. Parallel's [Search quickstart](https://docs.parallel.ai/search/search-quickstart) documents these request concepts and `x-api-key` authentication. Avoid placing private customer details in a public-web query.
  </Step>

  <Step title="Keep credentials and results bounded">
    Store the key outside prompts and source-controlled files. Use [workspace secrets](/agents-platform/configure/authentication/secrets) only through supported references. Specify the maximum sources, returned excerpt size, and allowed domains when applicable to the selected provider operation.
  </Step>

  <Step title="Preserve evidence and incomplete outcomes">
    Return source URLs with the excerpts used to support the answer. Mark missing or conflicting evidence clearly. A timeout, rate limit, or exhausted budget should return an incomplete result, not a confident unsupported conclusion. Retrieved instructions must not authorize another tool action.
  </Step>
</Steps>

Use [tool authoring](/agents-platform/configure/tools/overview) to describe the proposed request and result. Review any future external MCP endpoint through the separate [MCP configuration guide](/agents-platform/configure/integrations/mcp-servers).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a search integration start a long-running research task?">No. Search, background tasks, and scheduled monitoring have different contracts. Do not infer those workflows from a saved search tool.</Accordion>
  <Accordion title="Should a partial result be retried indefinitely?">No. Define a retry and cost limit, preserve useful evidence, and explain what remains unanswered when that limit is reached.</Accordion>
</AccordionGroup>


# Perplexity
Source: https://docs.threetone.in/agents-platform/configure/integrations/perplexity

Prepare a source-search action while keeping search results separate from model configuration and runtime support.

Plan a Perplexity Search action that returns sources for a factual question. This design retrieves evidence; it does not change the model assigned to your agent.

<Note>
  There is no native Perplexity connector in the current catalog. Search tool preparation does not establish model-catalog support, custom-model execution, or a working agent runtime.
</Note>

## Prepare a search action

You need a provider account, an approved API credential, and a policy for which queries may leave your application.

<Steps>
  <Step title="Choose search rather than an assumed model route">
    Review the [Search API quickstart](https://docs.perplexity.ai/docs/search/quickstart) for its query, result-count, and Bearer-token requirements. Define a small result limit and the exact question to investigate. Do not assume that a search credential is an agent model configuration.
  </Step>

  <Step title="Review the data sent and returned">
    Remove unnecessary personal or internal details from the query. Return relevant source titles, URLs, and available date information. Keep provider text separate from the agent's instructions and retain the evidence behind any resulting answer.
  </Step>

  <Step title="Define a bounded failure result">
    Distinguish no relevant sources from an unavailable provider, expired credential, or quota error. Limit retries and cost. Require separate authorization before any downstream action suggested by the research, such as contacting a person or modifying a record.
  </Step>
</Steps>

Review compatible credential storage in [auth connections](/agents-platform/configure/authentication/auth-connections) and the proposed action in [tool configuration](/agents-platform/configure/tools/overview). Saving either resource establishes configuration only.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will adding this search tool select a Perplexity model?">No. Tool references and model selection are separate configuration. Consult [models](/overview/models) for the current authoring and execution limits.</Accordion>
  <Accordion title="Can I omit sources from a researched answer?">Keep the sources that support the answer available to the reviewer. If the result lacks usable evidence, report that limitation rather than inventing a citation.</Accordion>
</AccordionGroup>


# Salesforce
Source: https://docs.threetone.in/agents-platform/configure/integrations/salesforce

Prepare CRM reads and reviewed updates with organization, object, and field boundaries.

Start a Salesforce integration design with a case or account lookup and a proposed update to a small set of approved fields. Use a sandbox or approved test records for later verification.

<Note>
  Salesforce is not a current native connector. Threetone does not provide its installation or consent flow. The steps below prepare an external service and tool contract.
</Note>

## Prepare the CRM workflow

You need an organization administrator, the intended application authorization model, and an explicit object-and-field allowlist.

<Steps>
  <Step title="Review OAuth and user access">
    Salesforce's [OAuth scope reference](https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-scope-parameter-values.html) distinguishes `api` access from the broader `full` scope. Request the access needed for the operation and review the connected user's permissions. Avoid selecting broad scopes merely to bypass a permissions error.
  </Step>

  <Step title="Bind the organization and record">
    Resolve the organization and record ID before reading. Return only allowed fields and relationships. Require review when an email address or name matches multiple records. Keep production and sandbox credentials and identifiers separate.
  </Step>

  <Step title="Review a field-level change">
    Show the record, current values, and proposed replacements. Confirm ownership changes and customer-visible effects separately. Re-read stale state before writing. If the response is uncertain, inspect the record before retrying rather than assuming the update failed.
  </Step>
</Steps>

Use [tool authoring](/agents-platform/configure/tools/overview) to separate lookup from mutation. [Manual auth configuration](/agents-platform/configure/authentication/auth-connections) can store compatible credentials, but it does not supply an interactive Salesforce OAuth lifecycle or enable execution.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does the api scope grant access to every Salesforce field?">Do not treat a scope as a substitute for organization, object, and field permissions. Review the actual account and operation before returning data.</Accordion>
  <Accordion title="Should a missing record be created automatically?">No. A missing or inaccessible lookup result is not authorization to create a new record. Review duplicates and required fields in a separate creation workflow.</Accordion>
</AccordionGroup>


# ServiceNow
Source: https://docs.threetone.in/agents-platform/configure/integrations/servicenow

Prepare incident lookup and reviewed work notes with instance-specific authentication and access controls.

Plan a ServiceNow workflow that reads an approved incident and drafts a work note. Keep assignment changes, state transitions, and customer-visible comments as separate decisions.

<Note>
  There is no native ServiceNow connector in the current catalog. This guide covers preparation for an external integration, not a released incident runner.
</Note>

## Prepare incident access

You need an instance administrator, a test incident, and an agreed list of tables and fields the integration may access.

<Steps>
  <Step title="Review the instance's access controls">
    ServiceNow's [REST API documentation](https://www.servicenow.com/docs/r/api-reference/rest-api-explorer/c_RESTAPI.html) describes Basic or OAuth authentication and endpoint, table, and field access controls. Select an approved method and the minimum required roles. Do not use an administrator account as a shortcut around a rejected request.
  </Step>

  <Step title="Define a precise incident lookup">
    Resolve the instance, table, and record's `sys_id`. Return only required incident fields. Have your service constrain filters and identifiers instead of accepting unrestricted generated queries. A field omitted by access control should remain unavailable.
  </Step>

  <Step title="Review the destination field">
    Confirm the target incident, text, and intended audience before a future write. Review work notes separately from comments and verify visibility in your instance. On timeout or conflict, read the current record before retrying. Do not report a state transition as complete without its saved result.
  </Step>
</Steps>

Use [auth connections](/agents-platform/configure/authentication/auth-connections) for supported manual configuration and [tool authoring](/agents-platform/configure/tools/overview) for the action contract. Your integration still owns instance-specific authorization and execution.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why can authentication succeed while a record read fails?">Authentication identifies the caller. Endpoint, table, and field controls determine what that caller can access. Review those controls with the instance administrator.</Accordion>
  <Accordion title="Can a saved tool bypass the incident workflow?">No. The provider's workflow rules and authorization still apply. Validate permitted changes against the current record.</Accordion>
</AccordionGroup>


# Slack
Source: https://docs.threetone.in/agents-platform/configure/integrations/slack

Prepare a reviewed escalation message with narrow posting permissions and an exact channel or thread destination.

Plan a Slack action that sends an approved escalation summary to a known channel. Keep message posting separate from reading channel history or subscribing to events.

<Note>
  Slack is absent from Threetone's native catalog. No Slack installation, event receiver, or live message tool is provided by this guide.
</Note>

## Prepare a message action

You need an approved Slack app, a workspace administrator, and a designated test channel.

<Steps>
  <Step title="Limit app permissions">
    Slack's [chat.postMessage reference](https://docs.slack.dev/reference/methods/chat.postMessage/) documents the `chat:write` scope. Posting access does not grant channel-history access. Review the app's channel access and request additional permissions only for a separately justified task. Keep tokens server-side.
  </Step>

  <Step title="Bind the destination and content">
    Use an approved channel ID and, for a reply, the intended parent message identifier. Show the channel, thread, and final text before sending. Remove private conversation details the destination audience should not receive. Review mentions because they can notify people.
  </Step>

  <Step title="Define send and retry outcomes">
    Preserve the returned channel and message identifier when a future request succeeds. A timeout needs reconciliation before another send. Report missing channel access, revoked authorization, and rate limits clearly. Do not change the destination automatically to make a rejected post succeed.
  </Step>
</Steps>

Use [auth connections](/agents-platform/configure/authentication/auth-connections) for compatible stored credentials and [tool configuration](/agents-platform/configure/tools/overview) for the proposed action. Your service must enforce recipient review; a prompt alone cannot enforce approval.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can the agent read history with posting permission?">No. Reading history is a separate operation with its own permission and data-access review.</Accordion>
  <Accordion title="Does a saved tool receive Slack events?">No. An inbound event integration needs a separately implemented receiver, request verification, routing, and duplicate-event handling.</Accordion>
</AccordionGroup>


# Tavily
Source: https://docs.threetone.in/agents-platform/configure/integrations/tavily

Prepare focused public-web search with source evidence, bounded content, and explicit quota handling.

Plan a Tavily lookup that finds public documentation for a product question. Define the permitted query and the evidence needed to answer it before making search part of an agent workflow.

<Note>
  Tavily is not a current native Threetone integration. Credential storage and tool authoring are available preparation steps; live search execution is not established by saving them.
</Note>

## Prepare a bounded search

Have a provider account, an approved API key, and an owner for search cost and data-sharing decisions.

<Steps>
  <Step title="Specify the useful result">
    Set a focused query, result limit, and relevant domain restrictions where supported. Review Tavily's [Search API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search) for the current request options and Bearer authentication. Do not use a customer transcript as an unreviewed search query.
  </Step>

  <Step title="Protect the credential and returned context">
    Store the key through a compatible [auth connection](/agents-platform/configure/authentication/auth-connections) or in your integration service. Limit returned content to useful excerpts and URLs. Treat retrieved text as untrusted source content that cannot change your access policy.
  </Step>

  <Step title="Keep uncertainty visible">
    Preserve source links and distinguish an empty result from provider failure. A relevance score does not establish that a statement is true. Set timeout, retry, and quota limits; report an incomplete search when those limits are reached.
  </Step>
</Steps>

Document the planned action through [tool configuration](/agents-platform/configure/tools/overview). Any resulting proposal to send a message or change a record requires a separate authorized action.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I allow arbitrary search options from agent output?">Have your service validate allowed options and enforce result, cost, and content limits. A generated request should not override those limits.</Accordion>
  <Accordion title="Does an empty search prove the information does not exist?">No. It only means this request returned no usable evidence. Explain that limitation and let the reader refine the question.</Accordion>
</AccordionGroup>


# Telegram
Source: https://docs.threetone.in/agents-platform/configure/integrations/telegram

Prepare a bot channel with authenticated updates, explicit chat routing, and duplicate-message handling.

Design a Telegram bot bridge that receives an approved message type and replies to the same authorized chat. Keep bot identity, channel-user identity, and Threetone workspace access separate.

<Note>
  There is no native Telegram connector or released Telegram-to-agent runtime. Your application would own the bot receiver and outbound delivery. This guide defines that preparation.
</Note>

## Prepare the bot boundary

You need a bot owner, a private test chat, and a server that can protect the bot token.

<Steps>
  <Step title="Choose one update transport">
    Telegram's [Bot API](https://core.telegram.org/bots/api) supports polling with `getUpdates` or webhook delivery. Polling does not work while a webhook is configured. For webhook delivery, review `secret_token` and validate the `X-Telegram-Bot-Api-Secret-Token` header on your receiver.
  </Step>

  <Step title="Map and validate incoming updates">
    Bind permitted chat and user identifiers to your application's policy. Deduplicate updates using their identifiers, constrain accepted message types, and define how to reject unsupported attachments. A Telegram user ID does not authorize access to a Threetone workspace or its private documents.
  </Step>

  <Step title="Review outbound delivery">
    Confirm the destination and content before a consequential send. Keep the bot token out of browsers, prompts, and logs. Preserve message identifiers and reconcile uncertain responses before retrying, so a repeated update cannot send duplicate replies.
  </Step>
</Steps>

Review [custom-channel preparation](/agents-platform/configure/integrations/custom-channel) and [tool authoring](/agents-platform/configure/tools/overview). Supported [secret storage](/agents-platform/configure/authentication/secrets) does not provision your receiver or remove the [runtime gate](/agents-platform/overview#current-availability).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is webhook receipt proof that an agent replied?">No. Receiving an update, processing it, and delivering an outbound reply are separate outcomes.</Accordion>
  <Accordion title="Can the bot token identify the person sending a message?">The token identifies the bot. Your service must separately validate incoming updates and apply its policy to the sender and chat.</Accordion>
</AccordionGroup>


# Twilio
Source: https://docs.threetone.in/agents-platform/configure/integrations/twilio

Review existing Twilio phone configuration and prepare messaging or call workflows with clear runtime and webhook boundaries.

Threetone already exposes Twilio-specific phone-number configuration. Use it to inspect provider ownership and agent assignment while preparing the separate delivery and execution requirements.

<Note>
  Availability is mixed. Phone configuration can be saved and read back. Twilio is absent from the general native integration catalog, and outbound calls remain blocked by the agent runtime gate. General messaging and live call demonstrations are not established by an imported number.
</Note>

## Review configuration and prepare delivery

You need the provider account owner, an approved number, permission to manage workspace phone resources, and the intended agent identifier.

<Steps>
  <Step title="Read the number configuration">
    Follow [phone integration](/agents-platform/deploy/telephony/overview) and its provider-specific import reference. Inspect the existing record's provider, number, workspace, and assigned agent. Read any saved change back. Keep credentials out of prompts and configuration screenshots.

    For import preparation, current validation requires `enable_sms: false` and rejects a non-null `account_auth_token`. The presence of those fields in the public schema does not establish SMS routing or secure webhook-signature credential handoff.
  </Step>

  <Step title="Review the receiver separately">
    An application-owned receiver must follow [Twilio request validation](https://www.twilio.com/docs/usage/security). Validation uses the request signature and actual request URL and data; account for reverse-proxy URL handling. A workspace webhook configuration does not establish callback delivery or a receiver implementation.
  </Step>

  <Step title="Define the future execution test">
    Confirm the sender, recipient, call or message purpose, and applicable consent before an authorized test. Keep request and provider identifiers for duplicate detection. Distinguish accepted requests from connected calls or delivered messages, and reconcile uncertain outcomes before retrying.
  </Step>
</Steps>

The immediate result is a reviewed phone record and test plan. Check [current availability](/agents-platform/overview#current-availability) before attempting runtime verification. A saved voice configuration also does not establish voice publication eligibility.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does importing a Twilio number enable outbound calls?">No. Import and assignment are configuration operations. The outbound route still encounters the runtime gate.</Accordion>
  <Accordion title="Does acknowledging a webhook mean delivery succeeded?">No. Acknowledgement confirms receipt by your receiver. Track the provider's actual call or message outcome separately.</Accordion>
</AccordionGroup>


# Zendesk
Source: https://docs.threetone.in/agents-platform/configure/integrations/zendesk

Prepare ticket lookup and reviewed internal notes using the current OAuth model and explicit comment visibility.

Plan a Zendesk workflow that retrieves an authorized ticket and drafts an internal note. Give public replies, status changes, and reassignment their own review requirements.

<Note>
  Zendesk is not a native Threetone connector. This guide prepares an external integration and action contract; it does not enable a working support automation.
</Note>

## Prepare the ticket action

You need a Zendesk administrator, an approved test ticket, and an application owner responsible for OAuth and revocation.

<Steps>
  <Step title="Use the current authentication guidance">
    Zendesk's [security and authentication reference](https://developer.zendesk.com/api-reference/introduction/security-and-auth/) recommends OAuth and marks API tokens deprecated. Integrations distributed to multiple customers require global OAuth. Do not ask customers to hand over private account credentials. Review the token's scope and the acting user's access.
  </Step>

  <Step title="Limit the ticket context">
    Bind the Zendesk instance and exact ticket ID. Return only the subject, state, and permitted excerpts needed for the task. Exclude unrelated requester details and attachments. A ticket ID supplied in a message is not proof that its sender can read that ticket.
  </Step>

  <Step title="Confirm visibility before a write">
    Show the target ticket, final text, and whether the comment is internal or public. Review notification and status effects. If the request times out, inspect the ticket before retrying so the same comment is not added twice. Report rejected or incomplete updates honestly.
  </Step>
</Steps>

Use [tool authoring](/agents-platform/configure/tools/overview) for separate read and write contracts. A supported [auth connection](/agents-platform/configure/authentication/auth-connections) stores manual configuration; it does not perform a customer's OAuth installation.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should a new integration start with an API token?">Use Zendesk's current OAuth guidance. The provider marks API tokens deprecated, and distributing an integration has additional global OAuth requirements.</Accordion>
  <Accordion title="Can the agent decide whether a comment is public?">Make visibility an explicit reviewed decision and enforce it in your service. Do not infer it from generated prose or a generic send action.</Accordion>
</AccordionGroup>


# Manage documents
Source: https://docs.threetone.in/agents-platform/configure/knowledge-base/manage-documents

Inspect, update, organize, and remove knowledge documents while checking current agent dependencies and stored content.

Treat each knowledge document as maintained source material. Give it a clear name, keep a record of who owns its content, and review affected agents before replacing or deleting it.

## Before you begin

You need access to the document's workspace and permission to manage knowledge. Keep the document ID and the original source. For initial creation, follow [Knowledge base](/agents-platform/configure/knowledge-base/overview).

<Steps>
  <Step title="Inspect the document">
    Read [document metadata](/api-reference/agents-platform/get-knowledge-base-document) and [stored content](/api-reference/agents-platform/get-knowledge-base-document-content). Check the type, intended source, and whether the stored representation includes the facts the agent needs.

    A folder organizes documents; it does not have document content of its own.
  </Step>

  <Step title="Review dependencies">
    Use [List agents using a document](/api-reference/agents-platform/list-agents-using-knowledge-base-document). Follow `next_cursor` while `has_more` is true. Keep the same filters when requesting another page.

    The list covers active agent references and related nonarchived branches. It is not a complete historical-version inventory. Review relevant saved versions separately before a destructive change.
  </Step>

  <Step title="Choose the matching change">
    Use the operation below for the source type. Review the proposed replacement before sending it; editing a shared document is different from changing an agent's attachment list.
  </Step>

  <Step title="Read the result back">
    Check the returned status, metadata, and stored content. Review indexes and any affected agent references separately. A successful update does not prove that a live conversation is using the new information.
  </Step>
</Steps>

## Choose an operation

| Task | Operation and review |
| - | - |
| Rename a document or update text content | [Update document](/api-reference/agents-platform/update-document); review the `name` and, for editable text content, `content` fields. |
| Replace a file source | [Replace file](/api-reference/agents-platform/replace-knowledge-base-file); inspect the replacement's stored content and processing state. |
| Refresh a URL source | [Refresh URL](/api-reference/agents-platform/refresh-knowledge-base-url); read the resulting content instead of assuming automatic synchronization. |
| Reorganize a source | [Move an item](/api-reference/conversational-ai/move-knowledge-base-item); confirm the destination folder and workspace. |
| Remove a source or folder | [Delete document or folder](/api-reference/agents-platform/delete-knowledge-base-document-or-folder); inspect dependencies and the intended scope first. |

Do not use a force-delete option merely to dismiss a dependency conflict. Decide how the referencing agents should change first. Bulk operations can report a different result for each item; inspect every result before treating the batch as complete.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does replacing a file prove retrieval is ready?">
    No. Inspect stored content and the relevant index state, then review [RAG](/agents-platform/configure/knowledge-base/rag). Source storage and live retrieval are separate checks.
  </Accordion>

  <Accordion title="Does a URL document stay synchronized automatically?">
    Do not assume that it does. Use the explicit refresh operation where supported and read back the content you intend to use.
  </Accordion>

  <Accordion title="Why is the dependency list empty for an old version?">
    The dependency list is not a complete historical inventory. Inspect the version's saved knowledge locators directly before deleting a source it references.
  </Accordion>
</AccordionGroup>


# Knowledge base
Source: https://docs.threetone.in/agents-platform/configure/knowledge-base/overview

Create and organize knowledge documents, inspect their stored content, and review agent attachments and dependencies.

The knowledge base holds URL, text, and file documents in your workspace. Prepare accurate source material, inspect what was stored, and review the agents that reference it before changing or deleting a document.

<Frame>
  <img alt="Recording pending for Add and review knowledge documents. No playable video is available yet." />
</Frame>

## Choose a source

You need access to the workspace, permission to manage knowledge documents, and an existing target agent if you intend to attach the source. This procedure uses the API operations linked below; the dashboard can also be used to inspect workspace resources.

| Source | Use it for | API reference |
| - | - | - |
| Text | A small, reviewed passage you want to maintain directly. | [Create from text](/api-reference/agents-platform/create-knowledge-base-document-from-text) |
| File | A document you own and can replace when its content changes. | [Create from file](/api-reference/agents-platform/create-knowledge-base-document-from-file) |
| URL | A source page whose content you can inspect and keep current. | [Create from URL](/api-reference/agents-platform/create-knowledge-base-document-from-url) |
| Folder | An organizational container for related documents. | [Create a folder](/api-reference/conversational-ai/create-knowledge-base-folder) |

Keep credentials, private customer records, and information outside the agent's approved scope out of general-purpose knowledge documents. Give each source a clear name and an owner responsible for keeping it accurate.

## Add and inspect

<Steps>
  <Step title="Prepare reviewed content">
    Remove outdated instructions, repeated navigation, and irrelevant sections. Use descriptive headings and explicit facts that a reader can understand without the surrounding website layout.
  </Step>

  <Step title="Create the document">
    Add the source through the dashboard or the corresponding API operation. Keep the returned document identifier and organize related sources in folders.
  </Step>

  <Step title="Read metadata and content back">
    Inspect [document metadata](/api-reference/agents-platform/get-knowledge-base-document) and [document content](/api-reference/agents-platform/get-knowledge-base-document-content). Check that the stored representation contains the intended information.

    A successful create response alone does not prove that parsing, indexing, or retrieval has completed. Inspect the relevant status and content before attaching the source.
  </Step>

  <Step title="Review the agent attachment">
    Select the intended document in the agent configuration. Knowledge locators use `type`, `name`, `id`, and `usage_mode`; the usage mode is `auto` or `prompt`.

    Review the attachment with the agent's instructions and save a complete server draft on the intended branch. Check the stored references. Voice and custom-model publication are unavailable; only an eligible managed text-only configuration can use the current publication workflow.

    Attach knowledge to an existing agent after creation. The current create-agent path rejects a nonempty knowledge attachment list in the initial request.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for A synthetic knowledge document with its stored content and processing status. This illustration is not a product screenshot." />
</Frame>

## Storage and retrieval

Stored source content, processed document chunks, and retrieval during a live conversation are different stages. The API reference includes index and retrieval operations, but this guide does not claim that every ingestion or runtime retrieval path has been validated end to end.

<Note>
  Document creation or a saved attachment does not establish that a live agent answered from that source. Check [current availability](/agents-platform/overview#current-availability) and verify the ingestion and execution paths before relying on retrieval in an integration.
</Note>

## Update or remove a source

Check [agents using the document](/api-reference/agents-platform/list-agents-using-knowledge-base-document) before replacing or deleting it. The response is paginated: follow `next_cursor` while `has_more` is true, rather than relying only on the first page.

This dependency list covers active agent references and includes related nonarchived branches. It is not a complete inventory of references in historical versions. Review relevant branches and versions separately, since a change can affect more than the configuration currently open in the editor.

Use [Replace file](/api-reference/agents-platform/replace-knowledge-base-file) for a file source, [Move an item](/api-reference/conversational-ai/move-knowledge-base-item) to reorganize it, or [Delete document or folder](/api-reference/agents-platform/delete-knowledge-base-document-or-folder) when it is no longer needed. Read the affected content and references back after the operation. Do not assume URL documents automatically synchronize with later website changes.

## Troubleshooting

If content is empty or incomplete, inspect the source and stored representation before attaching it. If a document is unavailable to an agent, check its workspace, identifier, and resource access. If a delete or replacement affects existing agents, review dependencies and the intended configuration versions first.

Continue with [agent configuration](/agents-platform/configure/agent-behavior/overview) and [versions and drafts](/agents-platform/deploy/versioning).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a created document prove retrieval is ready?">No. Inspect stored content and processing status. A saved attachment is separate from ingestion completion and retrieval during a live conversation.</Accordion>
  <Accordion title="Can I attach knowledge in the initial agent creation request?">The documented create-agent path rejects a nonempty knowledge list. Attach the source to an existing agent and read its saved configuration back.</Accordion>
  <Accordion title="Is the first dependency page enough before deletion?">No. Follow the returned cursor while has\_more is true. Review relevant branches and historical versions separately because the dependency list is not a complete historical inventory.</Accordion>
</AccordionGroup>


# Retrieval-augmented generation
Source: https://docs.threetone.in/agents-platform/configure/knowledge-base/rag

Prepare retrieval settings, inspect document indexes and chunks, and separate those checks from live knowledge-grounded answers.

Retrieval-augmented generation, or RAG, is intended to bring relevant source material into an agent's response. Prepare clear documents and a small set of questions with known answers before adjusting retrieval settings.

<Note>
  The API exposes index, chunk, and query operations. An index marked successful or a configured embedding-model identifier does not establish semantic vector retrieval or a live knowledge-grounded answer. Conversation execution remains [gated](/agents-platform/overview#current-availability).
</Note>

## Prepare and inspect the source

<Steps>
  <Step title="Read the stored document">
    Follow [document management](/agents-platform/configure/knowledge-base/manage-documents). Check headings, current facts, and source ownership before creating an index. Empty or incomplete source content cannot provide useful answers.
  </Step>

  <Step title="Review index state and chunks">
    Use [Get document RAG indexes](/api-reference/agents-platform/get-document-rag-indexes) to inspect the index state. [Create document RAG index](/api-reference/agents-platform/create-document-rag-index) requires a model selection and write access.

    Inspect [document chunks](/api-reference/agents-platform/list-rag-chunks-for-document). Check that important instructions and their qualifications remain understandable. Do not interpret the index status as proof that an embedding provider ran.
  </Step>

  <Step title="Review the agent attachment">
    Attach the source to an existing agent through `conversation_config.agent.prompt.knowledge_base`. Each locator uses `type`, `name`, `id`, and `usage_mode`, whose values are `auto` or `prompt`. Initial agent creation rejects nonempty knowledge attachments.
  </Step>

  <Step title="Prepare a query review">
    The [Query agent knowledge base](/api-reference/agents-platform/query-agent-knowledge-base) reference describes a separate query operation. Review any returned material against the known answer and source text. A useful result from this operation does not demonstrate retrieval inside a live conversation.
  </Step>
</Steps>

## Retrieval configuration

These fields belong to `conversation_config.agent.prompt.rag`. Save them in a complete [server draft](/agents-platform/deploy/versioning) and inspect the read-back.

| Field | Authoring constraint |
| - | - |
| `enabled` | Boolean; defaults to `false`. |
| `embedding_model` | A supported embedding-model identifier. |
| `max_vector_distance` | Greater than 0 and less than 1; default 0.6. |
| `max_documents_length` | Greater than 0 and less than 10,000,000; default 50,000. |
| `max_retrieved_rag_chunks_count` | Integer from 1 to 20; default 20. |
| `num_candidates` | Optional integer from 1 to 10,000. |
| `query_rewrite_prompt_override` | Optional text from 1 to 1,000 characters. |

These are authoring limits. A specific query operation may impose narrower limits, and a schema field does not establish that every retrieval stage uses it. Avoid tuning values until you can inspect the actual returned material.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does enabling RAG ensure an answer cites the source?">
    No. A configuration flag does not prove retrieval, answer grounding, or citation behavior. Keep those as separate checks in the eventual conversation review.
  </Accordion>

  <Accordion title="What should the review questions cover?">
    Include an exact factual question, a paraphrase, a question spanning two sections, and a question the source cannot answer. Record which passage supports each expected answer.
  </Accordion>
</AccordionGroup>


# Configure an agent
Source: https://docs.threetone.in/agents-platform/configure/overview

Configure behavior, speech, knowledge, tools, personalization, authentication, and integrations, then review the saved agent version.

Start with the task the agent should handle. Work through the settings that support that task, then review the complete version rather than publishing isolated field changes without their context.

## Choose a guide

| Task | Guide | Review outcome |
| - | - | - |
| Understand the configuration | [Agent behavior](/agents-platform/configure/agent-behavior/overview) | Identify instructions, models, platform settings, and workflow. |
| Write clear instructions | [Prompting](/agents-platform/configure/agent-behavior/prompting) | Match the prompt, first message, and task boundaries. |
| Adjust conversation behavior | [Conversation flow](/agents-platform/configure/agent-behavior/conversation-flow) | Review interruption and timeout settings. |
| Prepare per-conversation values | [Personalization](/agents-platform/configure/personalization/dynamic-variables) | Separate variable placeholders, defaults, and private values. |
| Configure speech and language | [Voice and language](/agents-platform/configure/voice-and-language/overview) | Choose compatible recognition, generation, and language policy. |
| Attach source material | [Knowledge base](/agents-platform/configure/knowledge-base/overview) | Read stored content and inspect dependencies. |
| Attach actions | [Tools](/agents-platform/configure/tools/overview) | Review definitions, resource access, and identifiers. |
| Prepare credentials | [Authentication](/agents-platform/configure/authentication/overview) | Separate platform access, provider credentials, and session access. |
| Connect an external service | [Integrations](/agents-platform/configure/integrations/overview) | Choose native connections, custom MCP, or separately configured webhook tools. |

## Review a saved configuration

Use the [API quickstart](/agents-platform/get-started/api-quickstart) for a complete creation example. Use [versions and drafts](/agents-platform/deploy/versioning) to select a branch, inspect the diff, and read the published configuration back.

Dashboard controls marked as previews do not establish saved configuration. Use the supported persisted controls or the corresponding API fields, and confirm the saved values after a change.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where should I start?">Define one task, then configure the prompt and first message. Add models and permitted resource references after the task is clear.</Accordion>
  <Accordion title="Does saving a configuration deploy the agent?">No. Configuration publication and runtime execution are separate. Review [deployment preparation](/agents-platform/deploy/overview) and [current availability](/agents-platform/overview#current-availability).</Accordion>
  <Accordion title="Why check the full diff?">A prompt can rely on a voice, language policy, knowledge attachment, or tool. Reviewing these together catches mismatches that a single-field check misses.</Accordion>
</AccordionGroup>


# Dynamic variables
Source: https://docs.threetone.in/agents-platform/configure/personalization/dynamic-variables

Add named variables to an agent prompt, preserve typed placeholder values in a draft, and review eligible publication.

Dynamic variables let you write reusable text such as `Hello {{customer_name}}.` and store example values alongside the agent configuration. Use fictitious values while preparing a prompt so you can review which information it expects.

<Note>
  This guide covers template and placeholder authoring. Conversation execution is currently gated; a saved placeholder does not demonstrate live substitution or a working client integration. Review [current availability](/agents-platform/overview#current-availability).
</Note>

## Before you begin

Open an editable agent and select the intended branch. Use a desktop window to access **Vars** in the editor header. Edits remain in the local working copy until saved through an eligible workflow. Voice and custom-model publication are unavailable; preserve their values in a complete server draft.

Decide which values the text needs. For a support-process example, `customer_name` can use `Sample customer` and `support_topic` can use `Delivery questions`. Keep account credentials and real customer records out of example values.

## Add and review placeholders

<Steps>
  <Step title="Add a named reference">
    In **Agent Configuration**, edit the prompt or **First message** and insert a reference using double braces. For example:

    ```text theme={null}
    Hello {{customer_name}}. I can explain our support process for {{support_topic}}.
    ```

    Use the same spelling wherever you mean the same value. A variable reference identifies expected data; it does not fetch an account record or grant access to a tool.
  </Step>

  <Step title="Set typed placeholder values">
    Open **Vars** in the editor header. The **Dynamic variables** panel lists custom variables found in the configuration and marks missing placeholder values.

    Choose a type for each placeholder: **String**, **Number**, **Boolean**, **List**, or **Null**. For the example above, choose String and enter `Sample customer` and `Delivery questions`.

    <Frame>
      <img alt="Screenshot pending for the saved dynamic-variable placeholder editor. This is a placeholder, not a dashboard screenshot." />
    </Frame>
  </Step>

  <Step title="Review the text and values together">
    Check that each reference uses the intended name and each placeholder has the intended type. The text should remain appropriate for the data it requests; a name or topic value should not be treated as permission to access an account.

    Review the prompt and first message together. A variable may also be referenced by other supported configuration fields, so check existing references before renaming it.
  </Step>

  <Step title="Publish and inspect the saved document">
    Review both the template text and placeholder map, then save a complete server draft on the selected branch. For an eligible managed text-only configuration, select **Publish**, inspect **Review Changes**, and confirm the branch and **Commit message**. Inspect the resulting draft or published version according to the workflow you used.

    Reopen the saved version or use [Get agent](/api-reference/agents-platform/get-agent). Confirm the values under `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders` and record the version ID. This completes the configuration check.
  </Step>
</Steps>

## Names and value types

Names must begin with a letter or underscore. After that, use letters, numbers, underscores, or hyphens. The accepted pattern is `[A-Za-z_][A-Za-z0-9_-]*`. For example, `customer_name` is valid; `customer.name` is not a variable name.

| Value type | Example | Authoring note |
| - | - | - |
| String | `"Sample customer"` | Use for short example text. |
| Number | `3` | Preserve a numeric value when the configuration expects one. |
| Boolean | `false` | Store a boolean rather than the string `"false"`. |
| List | `["Delivery", "Returns"]` | Lists can contain supported values, including nested lists. |
| Null | `null` | An explicit value, distinct from a missing map entry. |

The public placeholder input does not accept objects or maps as values. The placeholder map itself pairs variable names with the supported value types above.

## API configuration

The following fragment shows the stored relationship between first-message text and placeholders. It is a conversation-configuration fragment, not a complete agent or server-draft request.

```json theme={null}
{
  "agent": {
    "first_message": "Hello {{customer_name}}. I can explain our support process for {{support_topic}}.",
    "dynamic_variables": {
      "dynamic_variable_placeholders": {
        "customer_name": "Sample customer",
        "support_topic": "Delivery questions"
      }
    }
  }
}
```

Place this structure under `conversation_config` when preparing the corresponding agent change. [Update agent](/api-reference/agents-platform/update-agent) requires an explicit `branch_id` for conversation-configuration updates. If you create a complete server draft, preserve its other fields and follow [versions and drafts](/agents-platform/deploy/versioning).

## Reserved and private values

Names beginning with `system__` are reserved for platform-provided values. You cannot define them as custom placeholders. Their appearance in a schema or editor list does not establish availability in every runtime context.

Names beginning with `secret__` may be referenced only in supported request-header variable slots. They cannot be read from prompts, first messages, or general tool parameters. A prefix is not a substitute for credential storage or access control; use the supported credential configuration for a tool and keep real secrets out of examples.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why can I not see or edit Vars?">
    The header control is shown on desktop layouts. Widen the window and check that you are editing an agent rather than viewing a historical version. Version previews and restore operations make placeholder values read-only.
  </Accordion>

  <Accordion title="Does a placeholder become every caller's real value?">
    A placeholder is saved example data in the agent configuration. Supplying authenticated per-conversation values needs a supported session path and its own verification. This guide does not establish a working runtime integration.
  </Accordion>

  <Accordion title="Why is a variable marked as missing?">
    Check that the placeholder map contains the exact referenced name. An explicit `null`, `false`, or `0` is a value; an absent map entry is missing. Also check the name format and reserved prefixes.
  </Accordion>

  <Accordion title="Can I use variables to look up customer data?">
    A reference does not perform a lookup. Data access requires a separately configured, authorized integration. Review [tools](/agents-platform/configure/tools/overview) before designing a prompt that depends on private records.
  </Accordion>
</AccordionGroup>


# Overrides
Source: https://docs.threetone.in/agents-platform/configure/personalization/overrides

Prepare a narrow policy for caller-supplied conversation settings and distinguish permission flags from override values.

Overrides describe which settings a caller may supply when starting a conversation. Keep this policy narrow: a personalized first message usually needs less freedom than replacing the prompt or attached resources.

<Note>
  This guide covers policy authoring and read-back. The documented conversation-start paths are currently gated, so a saved override policy does not establish working session customization.
</Note>

## Policy flags and caller values

The agent's permission flags live under `platform_settings.overrides.conversation_config_override`. These are booleans that describe whether a setting may be overridden. They are different from the values a future session request would supply.

| Policy group | Fields that can be allowed |
| - | - |
| `agent` | `first_message`, `language`, `max_conversation_duration_message` |
| `agent.prompt` | `prompt`, `llm`, `tool_ids`, `native_mcp_server_ids`, `knowledge_base` |
| `conversation` | `text_only`, `max_duration_seconds` |
| `tts` | Supported speech override flags, including `voice_id` and `pronunciation_dictionary_locators` |
| `turn` | Supported turn-configuration override flags |

The individual permission flags default to `false`. Review the exact nested schema in [Get agent](/api-reference/agents-platform/get-agent) before adding a field.

## Prepare a least-access policy

<Steps>
  <Step title="Choose the necessary customization">
    Prefer [dynamic variables](/agents-platform/configure/personalization/dynamic-variables) for named text values. Only allow broader configuration replacement when the application has a clear need and can validate the caller's request.
  </Step>

  <Step title="Keep resource selection controlled">
    Treat prompt, model, tool, and knowledge overrides as significant changes. An allowed override does not grant access to another workspace's resources or replace authorization in the service handling an action.
  </Step>

  <Step title="Save the policy in a draft">
    Preserve the agent's other platform settings and save a complete [server draft](/agents-platform/deploy/versioning). Read back the permission flags and confirm that only the intended fields are allowed.
  </Step>

  <Step title="Prepare accepted and rejected examples">
    Record a valid caller request and a request that should be denied for each enabled field. Keep runtime verification pending until a supported conversation-start path is available.
  </Step>
</Steps>

Other flags under `platform_settings.overrides` include `enable_starting_workflow_node_id_from_client`, `enable_procedure_ids_from_client`, `custom_llm_extra_body`, and `enable_conversation_initiation_client_data_from_webhook`. They default to `false`. Enabling one does not release workflow execution, custom-model publication, or webhook delivery.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does allowing an override change the saved base value?">
    The policy records permission to supply a conversation-specific value. Editing the base agent configuration is a separate operation; inspect both the policy and base settings in the draft.
  </Accordion>

  <Accordion title="Can an override bypass a publication restriction?">
    No. Do not use an override flag as a workaround for unavailable voice, custom-model, or conversation execution paths.
  </Accordion>
</AccordionGroup>


# Twilio personalization
Source: https://docs.threetone.in/agents-platform/configure/personalization/twilio

Plan caller-specific context for a Twilio channel while keeping identity checks, private data, and conversation permissions separate.

Caller context can help an agent greet a customer or understand a support topic. Treat a phone number as a lookup input, not proof that the caller owns an account.

<Note>
  Twilio phone configuration and personalization authoring are separate from execution. A released inbound session path and secure provider credential handling are prerequisites for live caller personalization.
</Note>

## Before you begin

Review [Twilio preparation](/agents-platform/configure/integrations/twilio), [dynamic variables](/agents-platform/configure/personalization/dynamic-variables), and [override permissions](/agents-platform/configure/personalization/overrides). Decide which small set of values the greeting needs. Use fictitious customer data while drafting.

## Prepare the data boundary

<Steps>
  <Step title="Define the useful values">
    Keep the context narrow, such as `customer_name` and `support_topic`. Specify a neutral greeting when a value is missing. Avoid including an entire account record, payment information, or authentication credentials.
  </Step>

  <Step title="Verify provider requests on the server">
    A future inbound handler must verify the provider request before looking up a customer. Follow [Twilio's webhook security guidance](https://www.twilio.com/docs/usage/webhooks/webhooks-security) and account for the exact URL and parameters used to calculate the signature. An unverified caller-supplied number must not choose a private workspace or account.
  </Step>

  <Step title="Apply your own account authorization">
    Ask for additional verification before disclosing sensitive information or taking account actions. Match the authenticated customer's permissions to each requested operation; a personalized greeting does not authorize a tool call.
  </Step>

  <Step title="Review the draft and failure behavior">
    Store example values in the agent draft and read them back. Prepare cases for unknown numbers, failed verification, slow lookups, and missing values. Use a neutral response when private context cannot be safely retrieved.
  </Step>
</Steps>

The stored `platform_settings.overrides.enable_conversation_initiation_client_data_from_webhook` flag defaults to `false`. Authoring that policy does not create an inbound handler or prove that the platform fetches values from your service. Do not enable it as a workaround for a gated runtime.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can the caller's number identify the customer by itself?">
    No. Phone numbers may be shared, recycled, or presented without proof of ownership. Apply the verification appropriate to the requested information or action.
  </Accordion>

  <Accordion title="Should missing context prevent a generic greeting?">
    Plan a neutral greeting that does not reveal whether a private account exists. Sensitive account access still requires verification, even when a lookup succeeds.
  </Accordion>
</AccordionGroup>


# Client tools
Source: https://docs.threetone.in/agents-platform/configure/tools/client-tools

Create a client-tool definition in the dashboard, review its parameters and response policy, and attach it to an agent draft.

A client tool describes an action intended for the application hosting the conversation, such as opening a help panel. The stored definition describes the action; your application's handler would perform it through a supported runtime integration.

<Note>
  Dashboard tool management is available. Personal API keys are rejected for tool-management operations. Saving a client tool does not install a handler or establish live client-tool execution.
</Note>

## Create and inspect the definition

Use a signed-in dashboard session with permission to manage workspace tools and edit the intended agent.

<Steps>
  <Step title="Open the client-tool form">
    Open [Tools](https://threetone.in/app/agents/tools) and select **Add client tool**. Choose a name that describes one action, such as `open_help_panel`.
  </Step>

  <Step title="Describe inputs and results">
    Explain when the tool is appropriate and what each parameter means. Use the parameter schema to describe required values. Keep credentials and privileged server operations out of a client-side action.
  </Step>

  <Step title="Review the response policy">
    Review `expects_response`, `response_timeout_secs`, and the [execution settings](/agents-platform/configure/tools/tool-execution). Decide whether your planned handler needs to return information or only update the interface.
  </Step>

  <Step title="Save and attach separately">
    Select **Add tool**, then reopen the resource and inspect its stored definition. Follow [tool attachment](/agents-platform/configure/tools/overview) to add its ID to the agent. Save an agent draft and read the attachment back; tool creation and agent publication are different actions.
  </Step>
</Steps>

## Definition fields

| Field | Configuration |
| - | - |
| `type` | `client` |
| `name`, `description` | Action identifier and instructions about when to use it. |
| `parameters` | Optional object schema for the planned handler's input. |
| `expects_response` | Requested response behavior; defaults to `false`. |
| `response_timeout_secs` | Integer from 1 to 120; default 20. |

Before runtime integration, prepare examples for an unknown action, invalid arguments, a handler failure, and a repeated request. Use [client events](/agents-platform/advanced/events/client-events) as contract guidance, not proof of an available first-party SDK.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does adding a client tool execute JavaScript?">
    No. It stores a definition. This form does not upload application code or create a hosted execution environment.
  </Accordion>

  <Accordion title="Can I put a private API key in the parameters?">
    No. Client arguments are not credential storage. Keep privileged credentials on your server and enforce access there.
  </Accordion>
</AccordionGroup>


# Code tools
Source: https://docs.threetone.in/agents-platform/configure/tools/code-tools

Prepare functions for future tool integration while hosted code execution remains planned.

A code tool would run a function as part of an agent action. Threetone does not currently document a released hosted-code tool type, function-upload workflow, or execution sandbox.

<Note>
  Do not add an invented `type: "code"` tool definition or assume a language runtime, package installer, filesystem, or network environment is available. Existing client and webhook tool definitions are different interfaces.
</Note>

## Prepare a function contract

You can make future integration easier by writing a small function with explicit inputs and a reviewable result. For example, a delivery-window formatter might accept a date range and a time zone and return a display string.

| Decision | What to record |
| - | - |
| Inputs | Required fields, accepted types, and validation rules. |
| Output | A small result object and the meaning of each field. |
| Failure | Invalid input, unavailable dependencies, and timeouts. |
| Side effects | Whether the function reads data, changes data, or only computes a result. |
| Ownership | The application or service responsible for authorization and execution. |

## Choose an existing configuration path

<Steps>
  <Step title="Use a client definition for interface actions">
    Prepare a [client tool](/agents-platform/configure/tools/client-tools) when the intended action belongs in your application's interface. The definition does not provide the handler or release its runtime integration.
  </Step>

  <Step title="Use an HTTP contract for server actions">
    If you already operate an authorized service, prepare a [webhook tool](/agents-platform/configure/tools/webhook-tools) describing its endpoint. Keep code, dependencies, credentials, and access checks in that service.
  </Step>

  <Step title="Test your function independently">
    Use synthetic inputs to check the function in your own environment. Record those results separately from Threetone integration testing; local success does not prove agent-tool execution.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I paste Python or JavaScript into a tool?">
    There is no verified hosted-code submission workflow in this guide. Pasting code into a description stores text; it does not run that code.
  </Accordion>

  <Accordion title="Does a webhook tool host my function?">
    No. It describes an HTTP request. You operate the receiving service and its code separately, and live tool execution still needs verification.
  </Accordion>
</AccordionGroup>


# MCP security
Source: https://docs.threetone.in/agents-platform/configure/tools/mcp-security

Review MCP operators, credential scope, and stored approval policies while discovery and runtime enforcement remain unavailable.

Before connecting an MCP server, identify its operator, the data it receives, and the actions its credentials allow. A server configuration and an agent attachment are separate resources to review.

<Note>
  Threetone can store server configuration and tool approval records. Tool discovery is unavailable, and **Test Connection** is disabled. Stored approval settings do not establish live confirmation, tool-change detection, or execution enforcement.
</Note>

## Review the connection

<Steps>
  <Step title="Verify the operator and endpoint">
    Follow [MCP server setup](/agents-platform/configure/integrations/mcp-servers). Confirm the intended HTTPS endpoint and transport with the operator. Selecting **I trust this server** records your acknowledgement; it is not a Threetone verification of the server.
  </Step>

  <Step title="Limit credentials and transmitted data">
    Use the supported [secret](/agents-platform/configure/authentication/secrets) or [auth-connection](/agents-platform/configure/authentication/auth-connections) workflow. Review `secret_token`, `request_headers`, `request_meta`, and `auth_connection` as applicable. Keep the credential's actual permissions limited to the required actions.

    A secret reference avoids placing a credential in authored prose. It does not reduce the permissions held by the receiving server.
  </Step>

  <Step title="Record approval intent">
    Review `approval_policy` and any per-tool records. Keep an operator-supplied copy of the tool names, descriptions, and input schemas while live discovery is unavailable. Do not describe that copy as a successful connection test.
  </Step>

  <Step title="Read back the saved resources">
    Use [Get MCP server](/api-reference/agents-platform/get-mcp-server) to inspect configuration and stored approval records. Separately inspect the intended server ID in the agent draft's `mcp_server_ids` list.
  </Step>
</Steps>

## Approval fields

| Scope | Values and records |
| - | - |
| Server `approval_policy` | `require_approval_all` by default, `require_approval_per_tool`, or `auto_approve_all`. |
| Per-tool `approval_policy` | `requires_approval` by default or `auto_approved`. |
| Per-tool approval request | `tool_name`, `tool_description`, `input_schema`, and the policy. |
| Stored approval record | `tool_name`, `tool_hash`, and the policy. |

[Create MCP server tool approval](/api-reference/agents-platform/create-mcp-server-tool-approval) stores a hash derived from the supplied name, description, and input schema. That record does not demonstrate that a future changed tool is blocked. Review changed definitions and remove obsolete approvals through the corresponding [delete operation](/api-reference/agents-platform/delete-mcp-server-tool-approval).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does require_approval_all guarantee a confirmation dialog?">
    No. It stores an approval policy. The actual runtime confirmation and enforcement path must be verified when execution is available.
  </Accordion>

  <Accordion title="Can a server's tool instructions authorize access?">
    No. Your application and the service owning the data must enforce authorization. Tool descriptions and returned content do not grant permission to read or change resources.
  </Accordion>
</AccordionGroup>


# MCP tools
Source: https://docs.threetone.in/agents-platform/configure/tools/mcp-tools

Review MCP server and tool references, prepare input and approval policies, and track the separate discovery and execution requirements.

An MCP server describes tools exposed by an external service. Review the server and each intended action separately: knowing an endpoint does not tell you which data its tools can access or change.

<Note>
  Server configuration can be saved, but **Test Connection** is disabled and server tool discovery returns an unavailable result. This guide does not establish live discovery, runtime approval enforcement, or MCP tool execution.
</Note>

## Prepare the server and tools

<Steps>
  <Step title="Review and save the server">
    Follow [MCP servers](/agents-platform/configure/integrations/mcp-servers) to review its operator, endpoint, transport, and credential reference. Record the resulting server ID.
  </Step>

  <Step title="Document the intended actions">
    Obtain the tool names, descriptions, and input schemas from the server operator. Identify read and write actions separately. Keep discovery verification pending; do not present a manually copied schema as a successful connection test.
  </Step>

  <Step title="Review approval intent">
    The tool contract includes `approval_policy` values `require_approval_all`, `require_approval_per_tool`, and `auto_approve_all`. Decide which actions should require confirmation, but verify enforcement separately when execution is released.
  </Step>

  <Step title="Inspect agent references">
    Custom server references belong in `conversation_config.agent.prompt.mcp_server_ids`. Preserve the intended list in a complete [agent draft](/agents-platform/deploy/versioning) and read it back. Selecting a server in the dashboard's **Tools > MCP** list currently opens its details; it does not save an attachment.
  </Step>
</Steps>

## Tool-level contract

The MCP tool shape includes `type: "mcp"`, `integration_type`, `mcp_server_id`, `mcp_server_name`, `mcp_tool_name`, and `mcp_tool_description`. It can also describe `parameters`, `mcp_input_schema`, and `input_overrides`.

These fields describe a tool configuration. They do not make tool-management endpoints available to personal API keys, and they do not create a functioning server connection. Use the [tool overview](/agents-platform/configure/tools/overview) for the current management restriction.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does saving an approval policy display a confirmation?">
    Not by itself. A stored policy is authoring intent. Runtime confirmation and enforcement need separate verification when the execution path is available.
  </Accordion>

  <Accordion title="Are native MCP references the same as custom server IDs?">
    The agent schema separates `mcp_server_ids` from `native_mcp_server_ids`. Use the identifier required by the relevant [integration workflow](/agents-platform/configure/integrations/overview), rather than moving IDs between these lists.
  </Accordion>
</AccordionGroup>


# Configure agent tools
Source: https://docs.threetone.in/agents-platform/configure/tools/overview

Review workspace tool configuration, attach permitted tool identifiers to an agent, and keep credentials and action boundaries separate.

Tools describe actions or integrations an agent may use. Review a tool's purpose, inputs, credentials, and access before attaching it. Saving a tool definition does not prove that its external service or agent execution is available.

Use [Integrations](/agents-platform/configure/integrations/overview) for native provider connections and [MCP servers](/agents-platform/configure/integrations/mcp-servers) for custom server configuration. Use [auth connections](/agents-platform/configure/authentication/auth-connections) and [workspace secrets](/agents-platform/configure/authentication/secrets) for supported credential storage.

<Frame>
  <img alt="Recording pending for Review and attach a tool. No playable video is available yet." />
</Frame>

## Before you begin

Use a signed-in dashboard session with permission to manage the workspace's tools and edit the target agent. Have a documented action, its input schema, and any approved external integration ready.

<Note>
  Tool management currently rejects API-key credentials in the documented implementation. Use the authenticated dashboard workflow for tool management. An endpoint in the API reference does not mean a personal API key can call it.
</Note>

## Review and attach

<Steps>
  <Step title="Open the workspace tool">
    Open [Tools](https://threetone.in/app/agents/tools). Select an existing webhook or client tool to inspect its configuration. This procedure assumes the workspace already has an approved tool to attach.

    The tool detail view shows its configuration. Keep the tool identifier and confirm that it belongs to the intended workspace.
  </Step>

  <Step title="Define the action">
    Give the tool a clear name and description. Identify which inputs are required, what a successful result contains, and how errors should be handled. Keep one tool focused on one understandable action.
  </Step>

  <Step title="Review access and credentials">
    Confirm that the workspace can access the resource and that its credentials are stored through the supported integration workflow. Do not put secrets into the prompt, a tool description, or an example input.

    Decide which actions require user confirmation and enforce access in the service that owns the data or mutation. Prompt instructions are not an authorization boundary.

    If you edit a webhook or client tool, select **Save**, then reopen the tool to check its persisted definition. Saving that shared resource is separate from publishing an agent's attachment list.
  </Step>

  <Step title="Attach the intended identifiers">
    Open the intended agent, select its **Tools** page, then choose **Add tool**. Search for the reviewed tool and select it. Confirm that it appears in the attached tools list. Published references use `conversation_config.agent.prompt.tool_ids`.

    MCP references use `mcp_server_ids` or `native_mcp_server_ids`. These fields identify resources; they do not establish that a server is connected, trusted, or ready to execute.
  </Step>

  <Step title="Review the agent version">
    Review the attachment list and prompt together. Save a complete server draft for durable review. For an eligible managed text-only configuration, select **Publish** and confirm the branch and diff in **Review Changes**, then read the saved version back. Voice and custom-model publication remain unavailable.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for An approved sample tool attached to the agent configuration. This illustration is not a product screenshot." />
</Frame>

## Keep instructions and enforcement separate

The prompt should explain when the tool is relevant and how to respond when it fails. The external service should validate inputs, check access, and enforce confirmations where required. Do not let an agent's generated arguments decide which workspace or user is authorized.

For a tool that changes data, define how to handle a repeated request or an uncertain result before runtime testing. A retry must not silently create a second action.

## Review checklist

| Check | Evidence to keep |
| - | - |
| Purpose and inputs | A clear description and validated input schema. |
| Workspace access | The intended resource and the account permitted to use it. |
| Credentials | A supported secret-storage reference, with no secret in authored content. |
| Failure behavior | Expected timeout, unavailable-service, and invalid-input responses. |
| Agent attachment | The saved tool or MCP identifiers in the reviewed version. |

## Troubleshooting

If a tool is unavailable in the dashboard, confirm the active workspace and resource access. If a tool-management API request returns `403`, check whether it used an API key: that credential type is currently rejected for these operations. Do not bypass the restriction by putting dashboard credentials into application code.

Check [current availability](/agents-platform/overview#current-availability) before planning live tool execution. The [API reference](/api-reference/introduction) exposes the current schemas; [versions and drafts](/agents-platform/deploy/versioning) explains how attachments become part of a saved configuration.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I manage tools with a personal API key?">The documented tool-management path rejects API-key credentials. Use the supported authenticated dashboard workflow.</Accordion>
  <Accordion title="Does saving a tool publish its agent attachment?">No. Saving the shared tool definition and publishing an agent attachment list are different actions. Read both resources back.</Accordion>
  <Accordion title="Can the prompt grant permission to use a tool?">No. The owning service must enforce access and validate inputs. Instructions are not an authorization boundary.</Accordion>
</AccordionGroup>


# System tools
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools

Review built-in conversation-control tool contracts and prepare their conditions without assuming live transfer or telephony support.

System tools describe conversation-control actions, such as ending a conversation or requesting a handoff. Configure a clear condition for each action and an appropriate response when the action is unavailable.

<Note>
  System-tool definitions are authoring contracts. Their presence does not establish working call transfers, keypad tones, language detection, voicemail detection, or procedure execution in a live conversation.
</Note>

## Available contract categories

A system-tool definition uses `type: "system"` and a `params` object whose `system_tool_type` selects the action contract.

| Category | Contract values |
| - | - |
| Conversation control | `end_call`, `skip_turn` |
| Language | `language_detection` |
| Handoff | `transfer_to_agent`, `transfer_to_number` |
| Telephony input and detection | `play_keypad_touch_tone`, `voicemail_detection` |
| Knowledge | `knowledge_base_rag`, `knowledge_base` |
| Procedures | `start_procedure`, `end_procedure` |

The agent prompt's `built_in_tools` field describes built-in tool configuration. Follow the current [agent schema](/api-reference/agents-platform/get-agent) for its exact shape. Do not treat a system-tool name as an ordinary workspace tool ID.

## Prepare the behavior

<Steps>
  <Step title="Write the action condition">
    State when the action is appropriate. For a handoff, describe the request that requires another handler and what information should be retained in a summary.
  </Step>

  <Step title="Review required resources">
    Transfer tools require their own destination configuration. Procedure tools reference procedures. Review those resources independently; a destination field does not provision a phone number or grant access to another agent.
  </Step>

  <Step title="Save a configuration draft">
    Preserve the complete snapshot through [versions and drafts](/agents-platform/deploy/versioning). Read the saved built-in configuration back and compare it with your intended conditions.
  </Step>

  <Step title="Prepare an unavailable-action response">
    Write a response the agent should use if a transfer or other action cannot complete. Do not tell a user that an action succeeded without a verified result.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does end_call prove that outbound calls are available?">
    No. Conversation controls and channel readiness are separate. Review [telephony availability](/agents-platform/deploy/telephony/overview) before planning phone workflows.
  </Accordion>

  <Accordion title="Does a knowledge tool make retrieval ready?">
    No. Inspect the document, attachment, index, and retrieval behavior separately. Start with [RAG](/agents-platform/configure/knowledge-base/rag).
  </Accordion>
</AccordionGroup>


# Agent transfer
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/agent-transfer

Prepare transfer rules with reviewed agent or workflow-node destinations and inspect their saved configuration.

An agent-transfer rule describes when another agent or workflow node should take over a task. Define the receiving destination and the reason for the handoff together.

<Note>
  Transfer-rule authoring is available. A stored destination does not prove a live handoff, context transfer, or authorization to use the receiving agent. Conversation execution remains gated.
</Note>

## Add a transfer rule

You need an editable source agent and a destination you can identify and review.

<Steps>
  <Step title="Open Transfer to Agent">
    On the source agent's **Tools > System tools** panel, enable **Transfer to Agent**. Its configuration opens before activation. Select **Add Rule** in **Agent transfer rules**.
  </Step>

  <Step title="Choose the destination and condition">
    Choose the **Agent** and write a specific **Condition**. For example, distinguish an order-status request from a technical-support request. The editor requires at least one rule, with a nonblank condition and destination for every rule.
  </Step>

  <Step title="Review the handoff wording">
    Review **Transfer message**, **Delay before transfer (ms)**, and whether the receiving agent's first message is requested. Avoid wording that announces success before a transfer result exists.
  </Step>

  <Step title="Save and read back">
    Select **Save** to update the working copy. For API persistence, place the reviewed definition in a complete [server draft](/agents-platform/deploy/versioning), then inspect each destination and condition in the returned draft.
  </Step>
</Steps>

## Transfer fields

Use `conversation_config.agent.prompt.built_in_tools.transfer_to_agent`, with `params.system_tool_type: "transfer_to_agent"` and `params.transfers` as the rule list.

| Rule field | Configuration |
| - | - |
| `agent_id` | Destination agent identifier for an agent transfer. |
| `node_id` | Destination node identifier for a workflow-node transfer. |
| `is_workflow_node_transfer` | Defaults to `false`; distinguishes the node destination. |
| `condition` | Required description of when to transfer. |
| `delay_ms` | Requested delay; defaults to 0. |
| `transfer_message` | Optional handoff wording. |
| `enable_transferred_agent_first_message` | Defaults to `false`. |
| `preserve_client_tts_overrides` | Defaults to `false`; requested treatment of voice overrides. |

For API-authored node transfers, use the node identifier from the intended [workflow](/agents-platform/configure/agent-behavior/workflows). A node ID and an agent ID identify different resources.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why can I not save an empty rule?">
    The dashboard requires a condition and the appropriate destination before it activates the tool. An empty list is not a completed editor configuration.
  </Accordion>

  <Accordion title="Does the receiving agent inherit every setting?">
    Do not assume that it does. Review the receiving configuration separately. The voice-override preference does not establish complete prompt, tool, knowledge, or runtime-state inheritance.
  </Accordion>
</AccordionGroup>


# End call
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/end-call

Author when an agent should end a conversation and inspect the stored end-call definition without assuming a live hangup path.

The end-call definition describes when an agent should finish a conversation. Make the completion condition specific so an ordinary pause or an unanswered question is not mistaken for the end of the task.

<Note>
  The system-tool configuration can be edited and saved in an agent draft. This does not establish a working hangup action or an available phone channel. Voice publication and documented conversation-start paths remain gated.
</Note>

## Configure the definition

<Steps>
  <Step title="Define the ending condition">
    Write a condition such as: the request has been addressed, the user has no remaining questions, and a brief closing has been given. Define what should happen when the task cannot be completed instead of treating every failure as a reason to end immediately.
  </Step>

  <Step title="Enable End Call">
    Open the agent's **Tools** page and find **System tools**. Enable **End Call**, then open its settings. Use **Description (optional)** to describe when the action is appropriate.
  </Step>

  <Step title="Review and save">
    Review **Advanced > Interruptions** if needed, then select **Save**. This updates the agent working copy. For API persistence, include the reviewed definition in a complete [server draft](/agents-platform/deploy/versioning) and read it back.
  </Step>
</Steps>

## Stored shape

The tool belongs at `conversation_config.agent.prompt.built_in_tools.end_call`. Its tool-specific `params` object contains only the discriminator:

```json theme={null}
{
  "type": "system",
  "name": "end_call",
  "description": "Use after the request is addressed and the user confirms they are finished.",
  "params": {
    "system_tool_type": "end_call"
  }
}
```

This is a tool-definition fragment, not a complete agent-draft request. Do not add an invented delay or termination callback inside `params`. Shared tool settings belong at the outer level of the definition.

Prepare examples for a clear goodbye, a mid-task pause, an unresolved action, and a user asking another question during the closing. A read-back verifies the configuration, not those runtime outcomes.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does End Call configure a maximum conversation duration?">
    No. The tool-specific parameters do not contain a duration limit. Review conversation duration settings separately rather than treating this definition as a timer.
  </Accordion>

  <Accordion title="Does enabling it provision a phone connection?">
    No. Review [telephony availability](/agents-platform/deploy/telephony/overview) independently. The definition does not create a number, trunk, or live call.
  </Accordion>
</AccordionGroup>


# Flag an issue
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/flag-issue

Prepare an issue-review process and use existing conversation tags or feedback without assuming an automatic issue-flagging tool.

An issue flag should identify a specific conversation that needs review and explain why. Keep the observation, expected behavior, and next reviewer separate from an automated decision about severity.

<Note>
  `flag_issue` is not an accepted built-in tool type in the current API. This guide does not establish automatic issue detection, ticket creation, notifications, or callbacks during a conversation.
</Note>

## Review an existing conversation

<Steps>
  <Step title="Inspect the record">
    Use [conversation inspection](/agents-platform/monitor/conversations) and [Get conversation details](/api-reference/agents-platform/get-conversation-details). Confirm the conversation and agent identifiers before recording a concern.
  </Step>

  <Step title="Describe the evidence">
    Record the relevant turn or event, what you expected, and what the stored record shows. Distinguish an unavailable tool from an incorrect answer. Keep unnecessary private information out of review notes.
  </Step>

  <Step title="Use a tag for categorization">
    If your workspace uses review tags, [Add tag to conversation](/api-reference/agents-platform/add-tag-to-conversation) accepts a `tag_ids` list. Use existing tag identifiers from the same workspace. Repeated assignments are ignored; a tag is a category, not a notification or an assigned ticket.
  </Step>

  <Step title="Record feedback separately">
    [Send conversation feedback](/api-reference/agents-platform/send-conversation-feedback) accepts `feedback` with `like`, `dislike`, or `null`. It does not accept an arbitrary issue title, severity, or reviewer assignment. Do not confuse a negative rating with a complete incident record.
  </Step>
</Steps>

## Prepare a future issue process

| Decision | What to define |
| - | - |
| Trigger | The observable condition that warrants review. |
| Evidence | Conversation ID, relevant turn, and expected outcome. |
| Owner | The person or service responsible for reviewing the concern. |
| Follow-up | How that owner records resolution and verifies a correction. |

Keep this process in your existing review system until a supported integration is available. Do not tell a user that a ticket was created or someone was notified unless the responsible service confirms it.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does adding a tag alert my team?">
    No notification behavior is established by the tag operation. It categorizes the stored conversation. Configure and verify any separate review or notification process independently.
  </Accordion>

  <Accordion title="Can I add flag_issue through Edit as JSON?">
    No. It is not an accepted system-tool type. Use the existing conversation-management operations for manual review instead of inventing a tool definition.
  </Accordion>
</AccordionGroup>


# Keypad tones
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/keypad-tones

Prepare DTMF tool preferences and distinguish generated keypad tones from caller input and transfer extension settings.

Keypad tones, also called DTMF tones, are used by telephone menus. The system-tool contract describes how an agent would send them; it does not provide an available IVR navigation or live calling workflow.

<Note>
  You can author the DTMF preferences below. Saving them does not prove tone delivery, compatibility with a carrier or IVR, or a working phone connection. Voice publication remains unavailable.
</Note>

## Configure the preferences

<Steps>
  <Step title="Document the intended menu interaction">
    Record the approved destination, the expected menu prompt, and the intended option. Include a response for an unexpected menu rather than assuming every prompt matches the preparation material.
  </Step>

  <Step title="Open Play DTMF Tones">
    On the agent's **Tools > System tools** panel, enable **Play DTMF Tones** and open its settings. Review **Use out-of-band DTMF** and **Suppress turn after DTMF**.
  </Step>

  <Step title="Save the tool definition">
    **Save** updates the working copy. For API authoring, use `conversation_config.agent.prompt.built_in_tools.play_keypad_touch_tone` and preserve the reviewed definition in a complete [server draft](/agents-platform/deploy/versioning).
  </Step>

  <Step title="Read back the flags">
    Confirm the discriminator and both flags in the stored draft. Keep tone delivery and menu-result verification pending until the applicable telephony path is available.
  </Step>
</Steps>

## Tool-specific parameters

| Field | Authored meaning |
| - | - |
| `system_tool_type` | Must be `play_keypad_touch_tone`. |
| `use_out_of_band_dtmf` | Defaults to `true`; requests tones separate from the call audio. The contract limits this option to SIP-trunk imported numbers. |
| `suppress_turn_after_dtmf` | Defaults to `false`; requests no further agent speech after the tones. |

These are configuration flags. The parameters do not define a saved sequence of digits or a general-purpose menu script. Do not add an invented `digits` field to this object.

Caller keypad collection is separate: its settings live under `conversation_config.conversation.dtmf_input_settings`. Transfer extension settings are also separate and use `post_dial_digits` in a transfer rule. None of these fields establish a live telephony feature by themselves.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this collect digits entered by the caller?">
    No. The tool describes generated keypad tones. Caller-input settings are a separate configuration, and their runtime behavior needs its own verification.
  </Accordion>

  <Accordion title="Does out-of-band mode work on every channel?">
    No universal support is established. The authored option is scoped to SIP-trunk imported numbers; review [telephony availability](/agents-platform/deploy/telephony/overview) and the actual carrier path separately.
  </Accordion>
</AccordionGroup>


# Language detection
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/language-detection

Prepare the language-detection tool and its early-conversation policy while keeping ASR, response language, and live switching separate.

Language detection describes a requested decision to change the conversation language. Prepare the supported languages and corresponding messages before adding a switching policy.

<Note>
  This is system-tool authoring guidance. It does not establish live language detection or switching. The dashboard's separate Language and ASR selectors are unsaved previews, and voice publication remains unavailable.
</Note>

## Review the policy

The tool is stored at `conversation_config.agent.prompt.built_in_tools.language_detection`. Its `params` contains:

| Field | Authored meaning |
| - | - |
| `system_tool_type` | Must be `language_detection`. |
| `only_at_conversation_start` | Boolean; defaults to `false`. |

When `only_at_conversation_start` is enabled, the requested policy is: if no language switch occurs during the first two user turns, keep the current language afterward. If a switch occurs during those turns, later switching remains permitted. This describes intended behavior, not a verified runtime result.

## Prepare the configuration

<Steps>
  <Step title="Choose the language set">
    Follow [Language](/agents-platform/configure/voice-and-language/language) to prepare the base response language, recognition settings, and any language presets. A detection tool does not add language support to a model or voice.
  </Step>

  <Step title="Open the tool settings">
    On the agent's **Tools > System tools** panel, enable **Language Detection** and open its settings. Review the **Only at conversation start** switch and the description of when detection is appropriate.
  </Step>

  <Step title="Save and inspect">
    Select **Save** to update the working copy. Preserve the reviewed tool in a complete [server draft](/agents-platform/deploy/versioning) for API read-back. Check its policy separately from `conversation_config.agent.language` and `response_language_policy`.
  </Step>

  <Step title="Prepare ambiguous examples">
    Include a greeting in one language followed by a full request in another, a quoted foreign phrase, and a user explicitly requesting a language change. Record the intended response for later testing.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is this the same as ASR recognition mode?">
    No. Input recognition belongs to ASR configuration. This tool describes a requested conversation-language action; the base response policy and language presets are also separate settings.
  </Accordion>

  <Accordion title="Does enabling it translate my prompt?">
    No automatic prompt translation is established by the tool. Review the authored wording and language-specific messages yourself.
  </Accordion>
</AccordionGroup>


# Skip turn
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/skip-turn

Prepare when an agent should avoid an unnecessary reply and distinguish that instruction from silence timers and call termination.

The skip-turn definition describes situations where the agent should avoid responding immediately. Use a narrow condition, such as the user explicitly asking for a moment to find information.

<Note>
  This guide covers authoring the built-in definition. It does not establish working turn suppression, microphone handling, or live waiting behavior. A stored setting cannot confirm that a conversation will remain silent.
</Note>

## Configure the condition

<Steps>
  <Step title="Choose when waiting is appropriate">
    Write examples of a deliberate request to wait and an ordinary unanswered question. Specify that the agent should continue helping when the user resumes, without inventing a timer or callback.
  </Step>

  <Step title="Enable Skip Turn">
    On the agent's **Tools > System tools** panel, enable **Skip Turn** and open its settings. Use **Description (optional)** to describe the intended condition.
  </Step>

  <Step title="Save and inspect">
    Select **Save** to update the agent working copy. To persist through the API, include the tool at `conversation_config.agent.prompt.built_in_tools.skip_turn` in a complete [server draft](/agents-platform/deploy/versioning).
  </Step>
</Steps>

## Tool definition

```json theme={null}
{
  "type": "system",
  "name": "skip_turn",
  "description": "Use when the user explicitly asks for a moment to find information.",
  "params": {
    "system_tool_type": "skip_turn"
  }
}
```

This is a tool-definition fragment. The tool-specific `params` accepts only the discriminator; it does not contain `wait_seconds`, a resume event, or a silence-detection threshold. General turn settings and the [end-call tool](/agents-platform/configure/tools/system-tools/end-call) serve different purposes.

Prepare examples for “give me a moment,” a short background remark, silence after a question, and a new question during the wait. Record expected behavior for later execution testing instead of assuming these cases are handled by enabling the tool.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does Skip Turn end the conversation?">
    The authored action is distinct from end\_call. Do not use it as a termination policy or infer a runtime hangup result from it.
  </Accordion>

  <Accordion title="Can I set an exact waiting period here?">
    No waiting-period field exists in this tool's parameters. Do not add an invented duration or resume callback.
  </Accordion>
</AccordionGroup>


# Transfer to number
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/transfer-to-number

Prepare phone or SIP transfer destinations, conditions, and optional handoff settings without assuming telephony execution.

A transfer-to-number rule describes a handoff to a telephone or SIP destination. Confirm who operates that destination, when it is appropriate, and what the agent should say if the handoff cannot complete.

<Note>
  This guide covers configuration authoring. It does not provision a phone number, import a trunk, verify carrier support, or establish working transfers. Review [telephony availability](/agents-platform/deploy/telephony/overview) separately.
</Note>

## Prepare a rule

<Steps>
  <Step title="Review the destination">
    Obtain the intended phone number or SIP URI from its operator. Use approved test destinations in preparation materials; do not treat a syntactically valid value as proof it is reachable.
  </Step>

  <Step title="Open the tool editor">
    On the agent's **Tools > System tools** panel, enable **Transfer to Number**. Complete a transfer rule with a destination and a clear condition. The editor requires at least one complete rule before saving.
  </Step>

  <Step title="Review the transfer type">
    The contract accepts `blind`, `conference`, and `sip_refer`, with `conference` as the default. These describe requested transfer modes. Confirm the actual channel and destination support before planning execution.
  </Step>

  <Step title="Save the authored definition">
    **Save** updates the agent working copy. Preserve the reviewed definition in a complete [server draft](/agents-platform/deploy/versioning) and read back the rules. Keep connection and transfer testing pending.
  </Step>
</Steps>

## Destination and optional fields

The definition belongs at `conversation_config.agent.prompt.built_in_tools.transfer_to_number`. Set `params.system_tool_type` to `transfer_to_number`. Its `transfers` list contains `condition`, `transfer_destination`, and optional transfer settings.

| Destination `type` | Destination field |
| - | - |
| `phone` | `phone_number` |
| `sip_uri` | `sip_uri` |
| `phone_dynamic_variable` | `phone_number`, using the intended variable reference contract. |
| `sip_uri_dynamic_variable` | `sip_uri`, using the intended variable reference contract. |

The outer `params.enable_client_message` defaults to `true`. Each rule can also contain `custom_sip_headers`, `sip_refer_play_dialtone`, `uui`, and `post_dial_digits`. Review the exact [agent schema](/api-reference/agents-platform/get-agent) before supplying these fields. Do not assume they work on every carrier or transfer type.

Dynamic destinations require the same destination review as static ones. A caller-supplied value must not decide which destinations your service authorizes.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a saved number become a Threetone phone number?">
    No. It is a destination in an authored rule. Number ownership, provisioning, carrier configuration, and a supported call path are separate requirements.
  </Accordion>

  <Accordion title="Can I rely on a transfer message as success confirmation?">
    No. Prepared wording is not a transfer result. Only a verified execution outcome can establish that a handoff completed.
  </Accordion>
</AccordionGroup>


# Update state
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/update-state

Plan how conversation values should change and use existing placeholder or assignment configuration without inventing a built-in state tool.

A state update would change values used during a conversation, such as a selected product or a completed verification step. Define who owns each value and which action is allowed to change it before designing that behavior.

<Note>
  `update_state` is not an accepted built-in tool type in the current API. Do not add that type to an agent or assume a state-update callback exists. This page covers preparation and adjacent authoring features.
</Note>

## Separate the kinds of state

| Need | Existing configuration or ownership |
| - | - |
| Example values in an authored prompt | Agent [dynamic-variable placeholders](/agents-platform/configure/personalization/dynamic-variables). |
| Requested extraction from a tool result | A tool definition's `assignments` list. |
| A customer record or transaction | The application service that owns and authorizes that record. |
| Changes to the agent itself | The [agent draft and version workflow](/agents-platform/deploy/versioning). |

Changing a placeholder edits example configuration. It is not a live customer-data update. Changing an agent draft is also separate from changing values inside an active conversation.

## Prepare a tool-result assignment

The current assignment contract includes:

| Field | Authoring meaning |
| - | - |
| `source` | Only `response` is accepted. |
| `dynamic_variable` | Name of the variable intended to receive a value. |
| `value_path` | Dot-notation path such as `record.status` or `items.0.id`. |
| `sanitize` | Requested removal of the assigned value from model and transcript output; defaults to `false`. |
| `preserve_native_type` | Requested preservation of the extracted type; defaults to `false`. |

These fields describe assignment intent. They do not establish that live assignment or sanitization is implemented. Do not treat `sanitize: true` as verified protection for a sensitive value.

<Steps>
  <Step title="Define the value and source">
    Choose a non-secret variable name and an actual response field from a reviewed tool contract. Record the expected type and what should happen when the field is missing.
  </Step>

  <Step title="Review the definition">
    Use the supported [tool configuration workflow](/agents-platform/configure/tools/overview) to inspect or author assignments. Keep reserved platform names and credentials out of general-purpose variable slots.
  </Step>

  <Step title="Inspect stored configuration">
    Reopen the tool and check the assignment path and destination name. Keep live assignment testing pending until the relevant execution path is available.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I mark a customer as verified with a placeholder?">
    A placeholder cannot perform identity verification or grant access. The service responsible for that decision must establish and enforce it.
  </Accordion>

  <Accordion title="Do assignments update my database?">
    No database write is established by this configuration. Durable business changes belong to a separately authorized service action.
  </Accordion>
</AccordionGroup>


# Voicemail
Source: https://docs.threetone.in/agents-platform/configure/tools/system-tools/voicemail

Prepare a voicemail-detection definition and optional message without assuming outbound calls, detection, or message delivery.

The voicemail definition describes what the agent should do if voicemail is detected. Prepare wording that remains appropriate when someone other than the intended recipient hears it.

<Note>
  This is configuration authoring. It does not establish working voicemail detection, outbound calling, or delivery of a recorded message. An optional message in the draft is not evidence that a call was placed.
</Note>

## Prepare the definition

<Steps>
  <Step title="Decide whether a message is appropriate">
    Keep any message brief and avoid private account details. Do not promise a callback, completed action, or follow-up that your process cannot provide.
  </Step>

  <Step title="Open Voicemail Detection">
    On the agent's **Tools > System tools** panel, enable **Voicemail Detection** and open its settings. Review the **Voicemail message (optional)** field.
  </Step>

  <Step title="Set the intended response">
    Leave the field blank to store `null`, expressing the intent to end without a message when voicemail is detected. Enter text to request a message before ending. These are intended behaviors, not verified live outcomes.
  </Step>

  <Step title="Save and inspect">
    **Save** updates the working copy. Preserve the definition at `conversation_config.agent.prompt.built_in_tools.voicemail_detection` in a complete [server draft](/agents-platform/deploy/versioning), then read it back.
  </Step>
</Steps>

## Parameters and message review

`params.system_tool_type` must be `voicemail_detection`. The only additional tool-specific field is `voicemail_message`, an optional string whose default is `null`.

A preparation example is: “This is the delivery support assistant. Please use the support contact listed in your order confirmation.” Adapt the wording to your actual organization and support process before use.

The editor accepts text containing [dynamic-variable references](/agents-platform/configure/personalization/dynamic-variables). Review them using fictitious placeholder values. A reference does not prove that the variable will be available or substituted during a call.

Prepare examples for a human greeting, a recorded greeting, silence, and an ambiguous automated message. The configuration does not include a verified detection-accuracy guarantee or a threshold you can tune here.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does saving the message schedule an outbound call?">
    No. It stores text in an agent configuration. Calling and scheduling are separate capabilities with their own availability limits.
  </Accordion>

  <Accordion title="Is an empty message a request to leave silence?">
    The dashboard converts an empty field to null. The authored intent is to end without playing a message when voicemail is detected; runtime behavior still requires verification.
  </Accordion>
</AccordionGroup>


# Tool execution
Source: https://docs.threetone.in/agents-platform/configure/tools/tool-execution

Review authored timing, interruption, and error settings while keeping configuration checks separate from live execution evidence.

Execution settings describe when a tool should run and how the conversation should handle its result. Review them alongside the action's input schema and the service that performs the work.

<Note>
  The settings below are configuration contracts. They do not prove working scheduling, background execution, speech timing, retries, or live tool calls. See [current availability](/agents-platform/overview#current-availability) before building a conversation integration.
</Note>

## Timing and response settings

| Field | Authored choices |
| - | - |
| `execution_mode` | `immediate`, `post_tool_speech`, or `async` on tool types that expose it. |
| `response_timeout_secs` | Requested response timeout; allowed ranges differ by tool type. |
| `interruption_mode` | `allow`, `disable_during_tool`, or `disable_during_tool_and_turn`. |
| `pre_tool_speech` | `auto`, `force`, or `off`. |
| `tool_call_sound` | Optional supported sound identifier. |
| `tool_call_sound_behavior` | `auto` or `always`. |
| `tool_error_handling_mode` | `auto`, `summarized`, `passthrough`, or `hide`. |

For client tools, also review `expects_response`. MCP tools have their own approval policy. Use the exact tool schema instead of copying settings across tool types.

## Prepare a result contract

<Steps>
  <Step title="Define success">
    Specify which result proves that the action completed. For a write operation, include a stable record identifier or another way your service can check the final state.
  </Step>

  <Step title="Define uncertainty">
    Decide what happens when a timeout occurs after the service may have accepted a request. A timeout is not proof of failure. Design duplicate-request handling in the service that owns the action.
  </Step>

  <Step title="Review error exposure">
    Avoid returning credentials, private records, or internal diagnostics in an error intended for the conversation. Do not depend on a saved error-handling mode as proof that sensitive output will be removed.
  </Step>

  <Step title="Separate the checks">
    First reopen the dashboard tool to confirm its saved settings. Next inspect the agent's attachment in a draft. Keep actual invocation and result verification pending until the relevant execution path is available.
  </Step>
</Steps>

Tool management, including execution-history reads, currently rejects personal API keys. Use the supported dashboard workflow. An empty execution list is not proof that a configured tool was tested successfully.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does async create a background job?">
    The enum records the requested mode. This guide does not establish a released background-execution mechanism, retry policy, or delivery guarantee.
  </Accordion>

  <Accordion title="Can I retry every failed call automatically?">
    A write may have completed even if its response was lost. Your service needs a way to recognize repeated requests and inspect uncertain outcomes before retrying.
  </Accordion>
</AccordionGroup>


# Tool interruptions
Source: https://docs.threetone.in/agents-platform/configure/tools/tool-interruptions

Review the authored interruption window for a tool and distinguish it from cancellation, execution timing, and first-message behavior.

An interruption policy describes when a caller should be able to interrupt around a tool call. Choose the narrowest restriction needed for the task and prepare a clear response when the user changes their request.

<Note>
  The dashboard and API can store interruption settings. They do not prove working audio interruption handling or cancellation of an external action. Live tool and conversation execution require separate verification.
</Note>

## Choose the requested window

The tool's `interruption_mode` has three values:

| Value | Intended interruption policy |
| - | - |
| `allow` | Allow interruptions; this is the default. |
| `disable_during_tool` | Suppress interruptions while the tool runs. |
| `disable_during_tool_and_turn` | Extend suppression through the agent response following the tool. |

The setting does not define a cancellation endpoint. Even when a caller changes their mind, a remote write may already have completed. The service handling that action needs its own way to inspect or cancel work where appropriate.

## Save and review a preference

<Steps>
  <Step title="Locate the correct resource">
    For a system tool, open the agent's **Tools > System tools** panel, enable the intended tool, and open its settings. For a shared client or webhook tool, use the workspace tool editor.
  </Step>

  <Step title="Review the interruption choice">
    In the system-tool editor, expand **Advanced > Interruptions**. **Allow**, **Disable during tool**, and **Disable through turn** correspond to the values above.
  </Step>

  <Step title="Save at the right level">
    A system-tool sheet's **Save** changes the agent working copy. Preserve the reviewed definition in a complete [server draft](/agents-platform/deploy/versioning) for API read-back. A shared tool's **Save** changes that shared resource instead.
  </Step>

  <Step title="Prepare an interruption review">
    Record what should happen if the caller interrupts before dispatch, during a slow response, or after completion. Keep expected conversation behavior separate from the external action's final state.
  </Step>
</Steps>

`execution_mode` controls a different requested behavior: when the tool runs. `conversation_config.agent.disable_first_message_interruptions` is also separate and applies to the first message. Do not use either as a substitute for the tool's interruption policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does allow cancel a running tool when I speak?">
    No cancellation guarantee is established by this flag. Interrupting conversation output and cancelling work in another service are different operations.
  </Accordion>

  <Accordion title="Can I infer the policy from a timeout?">
    No. Response timeout, interruption mode, and execution timing are separate settings. Review all three for the intended tool type.
  </Accordion>
</AccordionGroup>


# Tool sounds
Source: https://docs.threetone.in/agents-platform/configure/tools/tool-sounds

Prepare stored sound and timing preferences for tool calls while sound previews and live playback remain planned.

A tool sound is intended to indicate a wait while an action is in progress. Choose whether it would help the listener understand the pause before selecting a sound.

<Note>
  Tool sound preferences can be saved, but the current webhook editor has no supplied sound-preview assets. A disabled preview control is not playable audio. Live conversation playback and timing remain unverified and unavailable through this guide.
</Note>

## Review the stored preferences

| Field | Authoring values |
| - | - |
| `tool_call_sound` | `null`, `typing`, `elevator1`, `elevator2`, `elevator3`, or `elevator4`. |
| `tool_call_sound_behavior` | `auto` or `always`; default `auto`. |
| `pre_tool_speech` | `auto`, `force`, or `off`; default `auto`. |

The intended behavior of `auto` is to associate the sound with pre-tool speech; `always` requests it for every invocation. These are requested settings, not evidence that playback occurred.

## Prepare a sound preference

<Steps>
  <Step title="Open an existing webhook tool">
    Use the signed-in [Tools dashboard](https://threetone.in/app/agents/tools). Open **Advanced**, then review **Tool call sound**. Personal API keys cannot manage these tool resources.
  </Step>

  <Step title="Choose whether a sound is appropriate">
    Select **None** for `null`, or one of the listed presets. Consider whether an extra sound would compete with spoken instructions or accessibility needs. Do not upload a custom track through an invented sound field.
  </Step>

  <Step title="Review timing and save">
    When a sound is selected, review **Sound behavior**: **With pre-speech** maps to `auto`, and **Always play** maps to `always`. Save the tool, reopen it, and check the persisted values. Keep actual listening and timing verification pending.
  </Step>
</Steps>

MCP per-tool overrides have a distinct convention: `tool_call_sound: "off"` requests silence, while `null` means inherit the server setting. Do not put `"off"` in an ordinary webhook or client tool's sound field.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a sound indicate that the action succeeded?">
    No. A progress cue is separate from the tool's result. Confirm completion from the action's actual response when a supported execution path is available.
  </Accordion>

  <Accordion title="Is this the conversation's background audio?">
    No. [Audio environment](/agents-platform/configure/voice-and-language/audio-environment) describes separate background-sound settings. Neither configuration proves live playback.
  </Accordion>
</AccordionGroup>


# Webhook tools
Source: https://docs.threetone.in/agents-platform/configure/tools/webhook-tools

Define a reviewed HTTP action, configure its request schema and credential references, and inspect the saved dashboard tool.

A webhook tool describes an HTTP request to a service you control or have permission to use. Start with one clearly defined action and the service's actual request and response contract.

<Note>
  Use the authenticated dashboard to manage tools; personal API keys are currently rejected for these operations. Saving a webhook tool does not demonstrate request delivery, retries, or successful execution during a conversation.
</Note>

## Define the request

<Frame>
  <img alt="Recording pending for webhook tool authoring and read-back. No playable video is available yet." />
</Frame>

<Steps>
  <Step title="Open the webhook form">
    Open [Tools](https://threetone.in/app/agents/tools) and choose **Add webhook tool**. Give the action a precise name and description. Prefer a read-only lookup for initial integration planning.
  </Step>

  <Step title="Match the service contract">
    Review the URL, method, path parameters, query parameters, and request body. A path placeholder such as `{record_id}` needs a matching entry in `path_params_schema`.
  </Step>

  <Step title="Review authentication and returned data">
    Use supported [auth connections](/agents-platform/configure/authentication/auth-connections) or [secret references](/agents-platform/configure/authentication/secrets). Keep credentials out of the tool description and model-supplied arguments.

    Define the smallest response the task needs. The service must validate arguments and authorize access independently of the prompt.
  </Step>

  <Step title="Save and inspect">
    Select **Add tool**, reopen the resource, and check the persisted request definition. Attach the reviewed tool through the agent's [Tools page](/agents-platform/configure/tools/overview), then inspect its ID in the agent draft.
  </Step>
</Steps>

## Request fields

These fields are under the webhook tool's `api_schema`.

| Field | Configuration |
| - | - |
| `url` | The intended service URL. |
| `method` | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. |
| `path_params_schema`, `query_params_schema` | Input definitions matched to the service contract. |
| `request_body_schema`, `response_body_schema` | Optional body and response definitions. |
| `request_headers`, `auth_connection` | Supported header and credential configuration. |
| `content_type` | `application/json` or `application/x-www-form-urlencoded`. |
| `response_filter` | Requested filtering of returned content; verify actual behavior before relying on it. |

The outer tool configuration also includes `follow_redirects` and `follow_redirects_allowed_domains`. Enabling redirects requires a nonempty allowed-domain list. Review it with the endpoint operator and the current schema. A saved setting is not proof of network-policy enforcement.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is this the same as an event webhook?">
    No. A webhook tool describes an agent-requested HTTP action. Notifications about product events are a separate feature; this guide does not establish event delivery or signature verification.
  </Accordion>

  <Accordion title="How should I prepare a write operation?">
    Define authorization, required confirmation, duplicate-request handling, and a way to inspect an uncertain result in your service. Do not infer those protections from a tool description.
  </Accordion>
</AccordionGroup>


# Audio environment
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/audio-environment

Prepare background-sound settings and distinguish ambient audio from tool-call sounds and speech recognition.

An audio environment describes background sound intended to accompany a conversation. Keep it subtle enough that spoken information remains easy to understand.

<Note>
  The dashboard's **Audio environment** control belongs to the unsaved voice preview. The API accepts background-sound authoring settings, but voice publication and live background playback are not available through this guide.
</Note>

## Background-sound fields

These fields belong to `conversation_config.conversation.background_sound`.

| Field | Accepted configuration |
| - | - |
| `source_type` | `preset` or `null`. |
| `source_id` | A supported preset identifier or `null`. |
| `volume` | Number from 0.01 to 1; default 0.15. |
| `crossfade_loop` | Boolean; defaults to `true`. |

Preset identifiers include `office1`, `office2`, `restaurant`, `city`, `typing`, and `elevator1` through `elevator4`. The source type does not provide a custom audio-file upload option.

## Prepare an environment

<Steps>
  <Step title="Decide whether background sound is needed">
    Consider the listener's task and likely surroundings. A quiet environment may be easier to understand for instructions containing dates, addresses, or codes.
  </Step>

  <Step title="Choose one preset">
    Record the intended preset and a conservative volume. Keep a version without background sound in your review plan so later listening tests can compare intelligibility.
  </Step>

  <Step title="Save and inspect a draft">
    Preserve the full agent snapshot and use the [server-draft workflow](/agents-platform/deploy/versioning). Read the background-sound object back. Do not treat the unsaved dashboard preview as confirmation of stored settings.
  </Step>
</Steps>

Background sound is separate from `tool_call_sound` on a tool definition. It also does not configure noise suppression, microphone processing, or ASR recognition. Use [voice and language](/agents-platform/configure/voice-and-language/overview) for input-recognition settings.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I upload a custom background track?">
    The current background-sound contract supports presets. This guide does not provide a custom-track upload workflow.
  </Accordion>

  <Accordion title="Does volume change the agent's speaking volume?">
    This field belongs to background sound. Speech-volume controls, when offered, are model-specific TTS options and should be reviewed separately.
  </Accordion>
</AccordionGroup>


# Expressive mode
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/expressive-mode

Prepare expressive speech deliberately and check model-specific emotion or audio-tag capabilities before authoring settings.

Expressive speech can convey a calm explanation or a welcoming greeting. Start with the words and intended tone, then check whether the selected speech model exposes a compatible control.

<Note>
  There is no universal expressive-mode switch in the agent TTS contract. Model options and expressive-audio-tag capabilities are separate. Voice publication and live expressive conversation behavior remain unavailable.
</Note>

## Choose an approach

| Approach | What to prepare |
| - | - |
| Wording | Clear sentences and a tone instruction appropriate to the agent's task. |
| Model-specific options | An option such as `emotion` only when the selected model's parameter schema includes it. |
| Expressive audio tags | Tagged text only when the model reports `supports_expressive_audio_tags`. |

An emotion option does not imply support for arbitrary tags. Pronunciation dictionaries and phoneme tags are also separate capabilities; review [pronunciation](/agents-platform/configure/voice-and-language/pronunciation) when the issue is how a word sounds.

## Prepare a controlled comparison

<Steps>
  <Step title="Write the intended delivery">
    Describe a concrete result, such as a calm pace while explaining a failed payment. Avoid instructions that pressure the listener or claim emotions the agent cannot know.
  </Step>

  <Step title="Check the selected model">
    Use [Get available AI model](/api-reference/agents-platform/get-available-ai-model) to inspect its parameter schema and expressive-tag capability. Do not borrow tag syntax or option names from another model.
  </Step>

  <Step title="Save only supported settings">
    If using a model option, place it under `conversation_config.tts.options` with the matching `schema_id`. Preserve the rest of the configuration in a [server draft](/agents-platform/deploy/versioning).
  </Step>

  <Step title="Keep the listening result separate">
    Read back the requested settings, then record the listening comparison as pending until a supported speech path is available. A saved option cannot establish that the delivery sounds natural.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I add arbitrary stage directions to the prompt?">
    Treat tone instructions as text. Do not assume bracketed directions become audio controls; an unsupported model may ignore or speak them.
  </Accordion>

  <Accordion title="Does expressive support imply phoneme support?">
    No. Check each capability independently for the selected TTS model.
  </Accordion>
</AccordionGroup>


# Language
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/language

Separate response language from speech recognition, prepare language-specific text, and inspect the saved draft.

Choose the language of the agent's replies independently from the languages it should recognize. Review the prompt, first message, and any language-specific wording together so they describe the same task.

<Note>
  The dashboard's **Language** and **ASR** controls are unsaved previews. Use API drafts for configuration authoring. Voice publication is currently unavailable, even when the language and speech settings are compatible.
</Note>

## Language settings

| Field | Purpose |
| - | - |
| `conversation_config.agent.language` | Base response language; defaults to `en`. |
| `conversation_config.agent.response_language_policy` | `base_language` or `recognized_language`; defaults to `base_language`. |
| `conversation_config.asr.recognition` | Model-specific input recognition mode and language settings. |
| `conversation_config.language_presets` | Map of language tags to supported text, turn, and voice overrides. |

Use valid language tags and the selected model's actual coverage. Choosing `recognized_language` requests responses based on recognized input; it does not establish working automatic language switching.

## Prepare a language draft

<Steps>
  <Step title="Choose the base response language">
    Set the base language and write the first message in that language. Ask a fluent reviewer to check names, dates, numbers, and task-specific terms.
  </Step>

  <Step title="Review recognition separately">
    For a voice draft, select a compatible ASR model and its supported recognition mode. Follow [voice configuration](/agents-platform/configure/voice-and-language/overview); a response-language tag does not configure microphone input recognition.
  </Step>

  <Step title="Prepare additional-language text">
    A language preset requires an `overrides` object. It can include `agent.first_message`, `agent.max_conversation_duration_message`, `turn.soft_timeout_config`, and `tts.voice_id` within that object.

    Translation records use `source_hash` and `text`. Do not assume the preview translation controls have saved or translated the agent's complete prompt.
  </Step>

  <Step title="Save and inspect">
    Save the complete [server draft](/agents-platform/deploy/versioning), preserving unrelated fields. Read it back and compare the base language, response policy, preset keys, and reviewed text. Keep voice publication pending.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does the base language choose the ASR language?">
    No. Base response language and input recognition are separate settings. Check both against the current model catalog.
  </Accordion>

  <Accordion title="Can a language preset change the model or tools?">
    The language-preset contract has a limited override set. It does not accept a replacement LLM, tool list, or arbitrary conversation configuration.
  </Accordion>
</AccordionGroup>


# Multiple voices
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/multiple-voices

Prepare a default saved voice and compatible language-specific voice overrides without assuming live multi-speaker support.

You can prepare a default voice and language-specific voice references in an agent draft. This is useful when different languages need different saved voices while retaining the same agent instructions.

<Note>
  The dashboard's voice controls are unsaved previews, and voice publication is unavailable. Language-specific voice references do not establish multi-speaker output or voice switching during a live conversation.
</Note>

## Prepare voice references

You need a target branch and saved voices that your workspace can access. Start with [List my voices](/api-reference/voices/list-my-voices) and the current [model catalog](/overview/models).

<Steps>
  <Step title="Choose the default pair">
    Set `conversation_config.tts.model_id` and `conversation_config.tts.voice_id`. Record the selected model, voice, and intended base language together.
  </Step>

  <Step title="Choose a voice for each additional language">
    In `conversation_config.language_presets`, use the language tag as the map key. A preset can set `overrides.tts.voice_id` to an accessible saved voice.

    The preset does not contain a replacement TTS model. Review each voice against the base TTS model and that language's requirements.
  </Step>

  <Step title="Keep the wording consistent">
    Review each language's first message and pronunciation requirements. A voice reference does not translate the prompt or establish that a voice supports every language.
  </Step>

  <Step title="Inspect the saved draft">
    Follow [versions and drafts](/agents-platform/deploy/versioning). Read the draft back to confirm the default voice and each language-specific reference. Do not use publication as a voice test while voice publication is gated.
  </Step>
</Steps>

## Choose voices deliberately

Keep the selection small enough to review. For each voice, record the intended language, character of delivery, and a short sample script with names and numbers. These are preparation materials for later listening tests, not evidence that conversation switching is working.

If a voice is inaccessible, check the active workspace and saved identifier before changing the rest of the configuration.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can two voices speak in the same response?">
    This guide does not provide a released multi-speaker conversation feature. The documented settings are a default voice and language-specific voice references.
  </Accordion>

  <Accordion title="Can each language use a different TTS model?">
    The language preset supports a voice ID override, not a model ID override. Choose voices compatible with the base model.
  </Accordion>
</AccordionGroup>


# Voice and language
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/overview

Prepare compatible speech-recognition, voice, and response-language settings in a server draft while voice publication remains unavailable.

A voice configuration connects an input-language policy, a speech-recognition model, a response language, and a speech-generation model with a saved voice. Choose these together so the configuration supports the languages you intend to use.

<Note>
  The dashboard's **Voices**, **Language**, and **ASR** sections are labelled previews whose changes are not saved. Additional-language first messages and translation are also previews. Use the API workflow below for draft authoring. Voice publication and live conversation execution remain [gated](/agents-platform/overview#current-availability).
</Note>

## Before you begin

You need an agent you can update, the intended `branch_id`, a server-side [API key](/overview/administration/workspaces/api-keys) with the required access, and a saved voice in the same workspace. To create a complete voice configuration from the start, follow the [API quickstart](/agents-platform/get-started/api-quickstart).

## Choose and save compatible settings

<Steps>
  <Step title="Read the branch and model catalog">
    Read the selected branch with [Get agent](/api-reference/agents-platform/get-agent). Keep the current document so you can preserve fields you are not changing.

    Use [List available AI models](/api-reference/agents-platform/list-available-ai-models) and [Get available AI model](/api-reference/agents-platform/get-available-ai-model) to inspect available ASR and TTS models. Check language coverage, recognition modes, and supported options instead of copying an identifier from a screenshot.
  </Step>

  <Step title="Configure input recognition">
    Set `conversation_config.asr.model_id` to the selected catalog model. Supply its required `recognition` configuration using a mode that model supports.

    Choose the caller's input language independently from the response language. If you add `keyterms`, use distinct, nonblank terms within the model's limits. Only supply `options` that match the selected model's parameter schema.
  </Step>

  <Step title="Configure speech generation and response language">
    Use [List my voices](/api-reference/voices/list-my-voices) to choose an accessible saved `voice_id`. Set `conversation_config.tts.model_id` and `conversation_config.tts.voice_id`, then check compatibility with the intended languages.

    Set `conversation_config.agent.language` for the base response language. Review `conversation_config.agent.response_language_policy`: `base_language` is the default; `recognized_language` requests responses in a language identified by compatible ASR.
  </Step>

  <Step title="Save and inspect a server draft">
    Use [Create agent draft](/api-reference/agents-platform/create-agent-draft) with an explicit `branch_id` and the complete snapshot. Follow [versions and drafts](/agents-platform/deploy/versioning) and preserve unrelated fields.

    Read the selected branch's draft back and confirm ASR mode, model IDs, voice ID, base language, and response policy. Do not use Update agent to publish this voice configuration: the runtime projection is unavailable, even with compatible speech settings.
  </Step>
</Steps>

## Input-language modes

All fields below are inside `conversation_config.asr.recognition`.

| `mode` | Required fields | What to check |
| - | - | - |
| `fixed` | `language` | The model supports the selected input language. |
| `automatic_provider_languages` | No language list | The model supports automatic recognition across its available languages. |
| `automatic_selected_languages` | Nonempty `languages` list | The model supports candidate selection and any required `primary_language`. |

Selected languages must be distinct. When a `primary_language` is supplied, it must appear in `languages`. Some model contracts require that field; others do not accept it. The presence of a mode in the request schema does not mean every model offers it.

The ASR `task` currently accepts only `transcribe`. A response-language policy does not turn speech recognition into a translation task.

## Response language and localized copy

`conversation_config.agent.language` defaults to `en`. ASR input-language selection does not replace this field.

| Response policy | Configuration requirement |
| - | - |
| `base_language` | Use the configured base response language. This is the default. |
| `recognized_language` | Requires speech input and an ASR model and options that provide compatible recognized-language information. It is rejected for text-only configurations or absent ASR. |

`conversation_config.language_presets` can store localized first-message and duration-limit copy, localized soft-timeout settings, and compatible voice overrides. Presets do not switch the ASR model, TTS model, language model, or tool set. Their saved copy does not prove automatic translation or runtime language switching.

## Speech fields to review

These paths are relative to `conversation_config`.

| Field | Authoring requirement or default |
| - | - |
| `asr` | May be `null` while authoring. When supplied, `model_id` and `recognition` are required. |
| `asr.task` | `transcribe`. |
| `asr.keyterms` | Empty list; support and limits vary by model. |
| `asr.options` | `null` or the selected model's matching options. |
| `tts` | May be `null` while authoring. When supplied, `model_id` and a nonempty `voice_id` are required. |
| `tts.options` | `null` or the selected model's matching options. |
| `tts.pronunciation_dictionary_locators` | Empty list; use only when supported by the model. |
| `tts.enable_phoneme_tags` | `false`; use only when supported by the model. |

ASR and TTS compatibility is necessary for a future voice publication path, but does not make that path available today. A configuration with `conversation.text_only: true` does not require speech settings, but it cannot use `recognized_language` as its response policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why did my dashboard language or voice selection not save?">
    The visible speech and language pickers currently hold preview values. Use the API to save a server draft, then inspect that draft. The dashboard's LLM editor is a separate control; persisting its change still requires an eligible publication.
  </Accordion>

  <Accordion title="Can I use a provider's public voice ID?">
    Use an accessible saved workspace voice returned by List my voices. A public provider identifier is not automatically a saved workspace voice, and model compatibility still needs to be checked.
  </Accordion>

  <Accordion title="Why is an automatic recognition mode rejected?">
    Recognition modes and primary-language requirements vary by model. Inspect the selected model's catalog entry and the returned validation error. Do not assume that every alternative in the public schema is supported by that model.
  </Accordion>

  <Accordion title="Does publishing confirm that the voice sounds correct?">
    Voice publication is currently unavailable. A future publication would still require a separate supported runtime test to establish audio quality, language detection, and conversation behavior. Keep the assessed version ID with that evidence.
  </Accordion>
</AccordionGroup>


# Pronunciation
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/pronunciation

Prepare difficult terms and review pronunciation dictionary and phoneme settings against the selected speech model.

Names, acronyms, and product codes often need a pronunciation review. Keep a short list of terms and their intended spoken forms before changing speech settings.

<Note>
  Threetone exposes pronunciation-related authoring fields, but this guide does not provide a verified dictionary-creation workflow or live pronunciation execution. Voice publication remains unavailable.
</Note>

## Review the supported fields

The following fields belong to `conversation_config.tts`.

| Field | Authoring meaning |
| - | - |
| `pronunciation_dictionary_locators` | List of dictionary references. Each reference requires `pronunciation_dictionary_id` and may include `version_id`. |
| `enable_phoneme_tags` | Requests phoneme-tag support for a compatible model; defaults to `false`. |
| `model_id` | Determines which pronunciation capabilities and options are accepted. |

Check the selected model's `supports_pronunciation_dictionaries` and `supports_phoneme_tags` capabilities in [Get available AI model](/api-reference/agents-platform/get-available-ai-model). Support for one does not imply support for the other.

## Prepare a pronunciation review

<Steps>
  <Step title="Collect ambiguous terms">
    Include organization names, abbreviated titles, alphanumeric identifiers, and words with different regional pronunciations. Record their intended meaning as well as how they should sound.
  </Step>

  <Step title="Use complete example sentences">
    Put each term in a sentence the agent is likely to say. Include a plain-language fallback, such as spelling a short code when a listener asks for clarification.
  </Step>

  <Step title="Reference only known resources">
    If you have an accessible dictionary identifier, review its intended version before adding a locator to a [server draft](/agents-platform/deploy/versioning). Do not invent dictionary IDs or assume a public creation endpoint exists.
  </Step>

  <Step title="Keep listening verification pending">
    Read the saved draft back to confirm the references and model. Verify the actual pronunciation through a supported speech path when it becomes available; configuration alone cannot confirm the sound.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use phoneme tags with every voice?">
    No. Check the selected TTS model's capabilities. A compatible saved voice is also required; a tag in text does not add model support.
  </Accordion>

  <Accordion title="Does a dictionary locator upload a dictionary?">
    No. A locator references a resource. This guide does not claim an available dictionary-upload or creation workflow.
  </Accordion>
</AccordionGroup>


# Speed
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/speed

Prepare speech-rate options using the selected model's schema and a consistent listening script.

Speech rate should make the response easy to follow, especially when it contains dates, names, or instructions. Prepare a moderate setting and a repeatable listening script before experimenting with faster delivery.

<Note>
  Speed is model-specific configuration under `conversation_config.tts.options`. There is no universal top-level TTS speed field. Voice publication remains unavailable, and the dashboard voice preview does not save these settings.
</Note>

## Use the model's options

Read the selected model through [Get available AI model](/api-reference/agents-platform/get-available-ai-model). Match `options.schema_id` and the option names to that model's parameter schema.

Examples of current authoring contracts:

| Model | Options schema | Rate setting |
| - | - | - |
| `cartesia/sonic-3.6` | `cartesia_sonic_tts_options_v1` | `speed`: `slow`, `normal`, `fast`, or a number from 0.6 to 1.5. |
| `sarvam/bulbul:v3` | `sarvam_bulbul_v3_tts_options_v1` | `pace`: a number from 0.5 to 2.0. |

These identifiers describe accepted authoring shapes, not guaranteed catalog availability or working speech execution. Check the current catalog before using them. Do not transfer an option object from one model to another.

## Prepare a rate comparison

<Steps>
  <Step title="Choose one short script">
    Include an ordinary explanation, a number, and a name. Use the same text and voice for each comparison so the rate is the only planned difference.
  </Step>

  <Step title="Change one option">
    Preserve the model and voice IDs, then set the supported rate option in a [server draft](/agents-platform/deploy/versioning). Keep unrelated options unchanged.
  </Step>

  <Step title="Read the draft back">
    Check the schema ID, option name, and value. Record the desired outcome, such as clearer numbers or shorter pauses, for a later listening review when the speech path is available.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a faster rate reduce model response latency?">
    Speech rate describes the intended delivery of generated speech. It does not promise a faster model response or lower end-to-end latency.
  </Accordion>

  <Accordion title="Why is my speed value rejected?">
    Check that the option name, schema ID, and numeric range belong to the selected model. Some models use pace, others speed, and not every model exposes the same control.
  </Accordion>
</AccordionGroup>


# Voice design
Source: https://docs.threetone.in/agents-platform/configure/voice-and-language/voice-design

Prepare a voice brief and review saved voices while a first-party voice-generation workflow remains planned.

A voice brief describes the sound appropriate to your agent: language, delivery, pace, and the kinds of words it needs to pronounce clearly. You can prepare that brief now and use it to evaluate accessible saved voices.

<Note>
  This page does not provide a released text-to-voice design or cloning workflow. A saved voice reference is not evidence that Threetone can generate or clone a new voice. Voice-agent publication is also currently unavailable.
</Note>

## Write a useful voice brief

| Decision | Example requirement |
| - | - |
| Language | Clear delivery in the languages your task requires. |
| Tone | Calm explanations, with a neutral response when an action fails. |
| Pace | Slow enough to distinguish dates, addresses, and short codes. |
| Pronunciation | A reviewed list of organization names and domain terms. |
| Consistency | Similar clarity across greetings, questions, and longer explanations. |

Describe the desired qualities without asking to imitate an identifiable person. Use sample text you are permitted to use and avoid real customer information.

## Review existing options

<Steps>
  <Step title="Prepare a short script">
    Include a greeting, one explanation, a clarification question, and a response to an unavailable service. Keep the script unchanged across voice comparisons.
  </Step>

  <Step title="Inspect accessible saved voices">
    Use [List my voices](/api-reference/voices/list-my-voices) and the [model catalog](/overview/models). Record actual voice IDs and compatible model requirements instead of treating a brief as a generated resource.
  </Step>

  <Step title="Prepare the draft reference">
    If a suitable saved voice is available, follow [voice configuration](/agents-platform/configure/voice-and-language/overview) to prepare its model and voice IDs in a server draft. Keep listening and live-conversation verification separate.
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where do I submit a voice-design prompt?">
    There is no verified first-party voice-design submission workflow documented here. Keep the brief as preparation and select from accessible saved voices where suitable.
  </Accordion>

  <Accordion title="Can a voice brief replace a voice ID?">
    No. Agent TTS configuration requires an actual saved voice identifier and a compatible model identifier.
  </Accordion>
</AccordionGroup>


# Batch calls
Source: https://docs.threetone.in/agents-platform/deploy/batch-calls

Prepare a controlled batch-calling plan and inspect the release requirements before submitting work.

A batch-calling workflow needs a reviewed agent version, permitted recipients, scheduling and time-zone rules, provider capacity, and reliable per-call outcomes. Treat the batch as a set of independently traceable operations.

<Note>
  Batch creation, export, and retry are unavailable in the reviewed implementation. Existing schema or job-read operations do not establish a working batch runner.
</Note>

## Prepare the batch

Define the recipient source and authority to contact each recipient. Record the intended agent, branch, version, caller number, recipient time zone, and relevant context. Keep credential values and unrelated personal data out of batch input.

Plan maximum concurrency, cancellation, retry rules, and how an uncertain provider outcome is reconciled. A repeat must not silently place a second call. Review [call consent](/agents-platform/legal/call-consent) and [capacity planning](/agents-platform/guides/call-queueing).

## Verify the released runner

Begin with a small controlled recipient set. Confirm admission, scheduling, per-call identity, result persistence, cancellation behavior, and safe export. Measure actual provider outcomes rather than treating a job identifier as a completed batch.

Add an executable submission example only when the runtime and provider path are released. Preserve [current availability](/agents-platform/overview#current-availability) as the boundary for integration planning.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I rely on a submit-job schema today?">No. The current creation path is unavailable. Schema parity is separate from provider and runner execution.</Accordion>
</AccordionGroup>


# Environment variables
Source: https://docs.threetone.in/agents-platform/deploy/environment-variables

Manage workspace values and credential references, understand production fallback, and verify environment-specific configuration.

Workspace environment variables hold a value or resource reference for each named environment. Use them to keep integration configuration together. They do not create infrastructure or replace workspace permissions.

<Frame>
  <img alt="Recording pending for Configure environment values. No playable video is available yet." />
</Frame>

## Value types

| Type | Stored value | Use it for |
| - | - | - |
| String | A nonempty string. | Configuration such as a service URL. |
| Secret | A `{secret_id}` reference. | A secret stored through the supported workspace credential workflow. |
| Auth Connection | An `{auth_connection_id}` reference. | A workspace authentication connection. |

Secret and connection references must belong to the same workspace. Do not put a raw credential into a String value, a prompt, or a recorded example.

## Create a variable

You need permission to manage environment variables in the active workspace.

<Steps>
  <Step title="Open environment variables">Go to [Developers > Environment variables](https://threetone.in/app/developers/environment-variables), then select **Add variable**.</Step>
  <Step title="Name and type the variable">In **New variable**, set **Name** and **Type**. Names use 1 to 64 letters, numbers, or underscores. Choose the value type before creating the variable.</Step>
  <Step title="Set the production value">Enter the required **production** value or select the corresponding workspace reference. The variable must have a production value even when you also use another environment.</Step>
  <Step title="Save and inspect">Select **Save**, then reopen the variable and confirm its type, label, and production value or reference.</Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for workspace environment variable values. This illustration shows no actual secret or connection details." />
</Frame>

## Add an environment value

Use **Create environment** and **New environment** to add values to existing variables. An environment name starts with a lowercase letter and contains lowercase letters, digits, underscores, or hyphens, up to 64 characters.

An environment is a set of value keys. It does not provision a deployment, database, server, or separate workspace. When a variable lacks a value for the requested environment, the resolver falls back to its production value. Confirm that this fallback is appropriate before testing an integration.

Creating an environment updates variables separately. If part of the operation fails, refresh the page and inspect which values were saved before retrying.

## Update or remove an override

Open the variable or environment detail and use **Edit value** to update it. Use **Remove value** to remove a nonproduction override. Production cannot be removed. Removing an override restores production fallback for that variable and environment.

The current public contract provides create, list, get, and update operations. It does not provide a variable deletion, rename, or type-change endpoint.

## API operations

| Task | Reference |
| - | - |
| Create a variable | [Create environment variable](/api-reference/agents-platform/create-environment-variable) |
| List values | [List environment variables](/api-reference/agents-platform/list-environment-variables) |
| Inspect one variable | [Get environment variable](/api-reference/agents-platform/get-environment-variable) |
| Change supplied environment keys | [Update environment variable](/api-reference/agents-platform/update-environment-variable) |

An update merges the supplied environment keys. A `null` value removes a nonproduction key. The list endpoint supports cursor pagination and filters; an environment filter returns explicitly stored matches, not the resolved production fallbacks.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why is production required for a staging-only test?">Every variable must have a production entry because it is the fallback. Use safe test values and review what the integration will actually resolve before making a request.</Accordion>
  <Accordion title="Does an environment create a separate deployment?">No. It only adds configuration values. Create and secure infrastructure separately when your application requires it.</Accordion>
  <Accordion title="Can I paste an API key into a String variable?">Use the Secret reference type and supported credential storage for secrets. Do not store raw credentials as ordinary text.</Accordion>
  <Accordion title="What should I do after a partial save?">Refresh and inspect each variable. Retry only the missing or incorrect values so you do not assume every update succeeded.</Accordion>
</AccordionGroup>


# Kotlin SDK for Android
Source: https://docs.threetone.in/agents-platform/deploy/mobile/kotlin

Prepare Android session ownership, microphone permission, lifecycle behavior, and device checks before a supported Kotlin SDK release.

This guide prepares an Android application for a future Threetone integration. No verified public Kotlin SDK, Gradle dependency, or supported native session contract is established here.

## Prepare the application boundary

Keep workspace API keys on your server. The Android application should receive only the access allowed by the released session contract after your server has authorized the signed-in user and intended agent.

Use the [server resource guides](/agents-platform/deploy/server/overview) for current API operations. A phone application can be inspected by its users, so embedding a workspace key in a resource file or build configuration does not protect it.

## Design the native lifecycle

<Steps>
  <Step title="Choose who owns the session">
    Decide whether a session belongs to a screen or a longer-lived application component. Define what rotation, navigation, and process recreation should do. A recreated screen must not silently create a second conversation.
  </Step>

  <Step title="Plan permission and audio states">
    For a voice feature, review Android's [runtime permission workflow](https://developer.android.com/training/permissions/requesting) and provide clear granted, denied, and settings-recovery states for microphone access. Request access for an intentional voice action. Do not request audio permission for a text-only interaction that does not use it.
  </Step>

  <Step title="Follow the lifecycle contract">
    Use lifecycle-aware components to observe when the interface becomes active or leaves the foreground. Android distinguishes paused, stopped, and destroyed states; they are not interchangeable. Follow the released transport's cleanup rules and [Android's lifecycle guidance](https://developer.android.com/guide/components/activities/activity-lifecycle).
  </Step>
</Steps>

## Device release checks

Test denied and revoked permissions, rotation, app switching, screen lock, process recreation, incoming phone calls, headset changes, and network loss. Verify that the interface never claims a dead connection is active and that end releases owned resources.

A future SDK release must specify supported Android versions, dependency versions, audio-session behavior, background restrictions, and reconnect semantics. Do not assume that an Activity callback or a foreground service alone makes background conversation execution supported.

Continue with [mobile deployment](/agents-platform/deploy/mobile/overview) and [current availability](/agents-platform/overview#current-availability).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Which Gradle dependency should I add?">No verified Threetone Kotlin dependency is documented yet. Wait for the official package coordinates and supported-version guidance.</Accordion>
  <Accordion title="Can I treat onPause as proof that the app is gone?">No. An Activity can be paused while still visible, including in multi-window situations. Match resource handling to the actual lifecycle and the released transport contract.</Accordion>
</AccordionGroup>


# Mobile deployment
Source: https://docs.threetone.in/agents-platform/deploy/mobile/overview

Prepare mobile session access, audio permissions, app lifecycle, and recovery behavior for a future client release.

A mobile integration must handle application lifecycle and permissions as well as conversation configuration. No verified Threetone mobile SDK release or supported native session contract is established here.

## Define the application behavior

Document foreground/background transitions, permission denial, audio-route changes, interruption by another call, network loss, and explicit session termination. Decide which state the server owns and which state is only an interface preview.

Keep long-lived API keys out of the application binary. Review a server-owned session-access design through [authentication](/agents-platform/configure/authentication/overview). Use [events](/agents-platform/advanced/events/overview) to prepare typed inputs and output handling without inventing SDK methods.

## Validate the released client

Test a controlled account on supported platform versions and physical devices. Confirm microphone prompts, audio output, reconnect behavior, cleanup, and authorized access. A simulator or visual preview is not sufficient evidence of device audio or server execution.

Use [SDK resources](/agents-platform/resources/sdks/overview) for current package readiness. Add React Native, Swift, or Kotlin installation steps only with a verified first-party package and compatible runtime release.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I ship a server API key in a mobile app?">No. Use a supported server-owned access flow rather than exposing a workspace credential in a distributed application.</Accordion>
</AccordionGroup>


# React Native
Source: https://docs.threetone.in/agents-platform/deploy/mobile/react-native

Prepare a React Native agent interface with a server-owned access boundary, permission handling, and device release checks.

Use this guide to prepare a React Native integration while the Threetone mobile session contract is pending. There is no verified Threetone React Native package or supported native session recipe to install from this guide.

## Prepare the application

<Steps>
  <Step title="Keep workspace access on the server">
    Identify which signed-in user may use which agent. Keep workspace API keys out of the application bundle, device logs, and client configuration. The application will need the released scoped session-access mechanism before it can connect.
  </Step>

  <Step title="Design permission states">
    For an Android voice interface, review the manifest and runtime handling for `RECORD_AUDIO`. React Native's [PermissionsAndroid](https://reactnative.dev/docs/permissionsandroid) distinguishes granted, denied, and never-ask-again results. Provide a useful recovery message for each denied state.

    On iOS, supply a clear [microphone usage description](https://developer.apple.com/documentation/bundleresources/information-property-list/nsmicrophoneusagedescription). Request access as part of an intentional voice action. Text-only interfaces should not request microphone access without a voice feature that needs it.
  </Step>

  <Step title="Define lifecycle ownership">
    Choose the screen or service that owns the session. Use [AppState](https://reactnative.dev/docs/appstate) to observe foreground and background changes, then follow the released transport's pause, end, or reconnect rules. Remove subscriptions when their owner unmounts.
  </Step>
</Steps>

## Device acceptance checks

Run these checks on physical iOS and Android devices once a supported transport is available.

| Scenario | Expected application behavior |
| - | - |
| Permission denied | Explain the limitation without repeatedly prompting or opening an unusable session. |
| Phone call or audio interruption | Show the interruption and follow the documented resume or end behavior. |
| Headset or speaker change | Keep the selected audio route understandable to the user. |
| Background, lock, or navigation | Release or retain resources only as the released mobile contract allows. |
| Network loss or expired access | Stop presenting the session as connected; offer a safe retry without replaying actions. |

Record the framework version, OS versions, native dependencies, and session contract used for the test. A browser demo inside a WebView does not establish native package support or background audio behavior.

Continue with [mobile deployment](/agents-platform/deploy/mobile/overview) and [current availability](/agents-platform/overview#current-availability).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Which package should I install?">Wait for an official package and versioned installation guide. No package name or installation command is established here.</Accordion>
  <Accordion title="Does AppState keep a conversation alive in the background?">No. It reports application state. Background execution and audio require their own platform support and a verified transport lifecycle.</Accordion>
</AccordionGroup>


# Swift SDK for iOS
Source: https://docs.threetone.in/agents-platform/deploy/mobile/swift

Prepare an iOS agent interface with protected server access, microphone disclosure, scene lifecycle, and device acceptance checks.

Prepare your iOS application while the Threetone native client release is pending. There is no verified public Swift package URL, package version, or supported iOS session recipe in this guide.

## Prepare access and permissions

Keep workspace API keys on a trusted server. Authorize the application user for the intended agent before issuing access through the eventual supported session flow. A key included in an app bundle is not a server-held secret.

For a voice interface, provide a meaningful `NSMicrophoneUsageDescription` explaining why the app needs audio input. Review [Apple's microphone usage-description reference](https://developer.apple.com/documentation/bundleresources/information-property-list/nsmicrophoneusagedescription). Design a useful path for permission denial and an explicit user action to start voice capture.

## Define session ownership

<Steps>
  <Step title="Choose the owning model or controller">
    Keep connection ownership separate from a view's repeated rendering. Decide what happens when the user leaves the conversation screen, opens another scene, or signs out. One displayed interaction should not accidentally create multiple sessions.
  </Step>

  <Step title="Observe application state">
    For SwiftUI, review [ScenePhase](https://developer.apple.com/documentation/swiftui/scenephase) when planning active, inactive, and background behavior. State observation does not grant background audio execution; follow the eventual SDK and platform requirements.
  </Step>

  <Step title="Make ending explicit">
    Provide a visible end action and define how it cancels pending work, removes subscriptions, and releases owned audio resources. Handle interruptions and network loss without showing stale connected state.
  </Step>
</Steps>

## Verify on physical devices

After a supported client and runtime are available, test permission denial, lock and unlock, background transitions, incoming calls, Bluetooth changes, network transitions, access expiry, and repeated entry to the screen. Record the iOS version, package version, and session contract used.

Before a public release, verify the package's authoritative source, minimum deployment target, audio configuration, supported concurrency model, and reconnect behavior. Do not infer those requirements from a browser widget or private dashboard component.

See [mobile deployment](/agents-platform/deploy/mobile/overview) and [server resource access](/agents-platform/deploy/server/overview) for the current separation of responsibilities.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I add a guessed Swift Package Manager URL?">No. Use only a verified first-party package and its published installation instructions once available.</Accordion>
  <Accordion title="Does a microphone usage description authorize recording automatically?">No. It explains the permission request. The application must still handle the user's permission decision and the supported audio lifecycle.</Accordion>
</AccordionGroup>


# Prepare an integration
Source: https://docs.threetone.in/agents-platform/deploy/overview

Prepare credentials, environment values, configuration versions, and phone resources before a supported runtime integration is released.

An integration needs the right configuration, resource access, and environment values. Prepare those independently from the runtime path that will eventually serve a conversation.

## Integration checklist

<Steps>
  <Step title="Identify the configuration">Keep the agent, branch, and version IDs for the reviewed configuration. Read the settings back before using them in an integration.</Step>
  <Step title="Prepare credentials">Use a scoped server-side API key and the workspace credential workflow for provider access. Keep secrets out of browser bundles and prompt text.</Step>
  <Step title="Review environment values">Define required strings and credential references for the intended environment. Understand production fallback before using another environment name.</Step>
  <Step title="Check execution availability">Confirm that the intended channel and runtime path are supported by the released implementation. A saved number, version, or environment variable is not evidence that a live session can execute.</Step>
  <Step title="Verify the complete integration">When the runtime path is released, test authentication, resource access, connection, failure handling, and stored results together using controlled data.</Step>
</Steps>

## Guides

<CardGroup>
  <Card title="Versions and drafts" icon="code-branch" href="/agents-platform/deploy/versioning">Review the configuration you intend to connect.</Card>
  <Card title="Environment variables" icon="sliders" href="/agents-platform/deploy/environment-variables">Manage workspace values and credential references.</Card>
  <Card title="Access and credentials" icon="key" href="/agents-platform/configure/authentication/overview">Separate server keys, dashboard sessions, and conversation access.</Card>
  <Card title="Phone configuration" icon="phone" href="/agents-platform/deploy/telephony/overview">Review provider records and calling prerequisites.</Card>
  <Card title="WhatsApp" icon="comments" href="/agents-platform/deploy/whatsapp/overview">Prepare a business account connection and review planned messaging and calling.</Card>
</CardGroup>

<Note>
  The documented signed-token initiation, traffic deployment, outbound calling, and automated response-test paths remain unavailable. This section prepares configuration and access; it does not provide a verified live deployment walkthrough.
</Note>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a published version receive live traffic?">A published version identifies saved configuration. Traffic allocation and execution require a separate released runtime path.</Accordion>
  <Accordion title="Do environment names create infrastructure?">No. Workspace environment values are configuration data. They do not create separate servers, deployments, databases, or workspaces.</Accordion>
</AccordionGroup>


# Server integrations
Source: https://docs.threetone.in/agents-platform/deploy/server/overview

Prepare server-side API access, resource identity, request handling, and deployment verification.

A server integration can use permitted public API operations to manage configuration and inspect stored resources. Runtime sessions and provider execution have their own release requirements.

## Set up the boundary

<Steps>
  <Step title="Scope credentials">Create a key for the intended service and workspace. Follow [API keys](/overview/administration/workspaces/api-keys) and the [authentication reference](/api-reference/authentication).</Step>
  <Step title="Identify resources">Retain agent, branch, version, document, and connection identifiers. Resolve access independently of user-submitted display names.</Step>
  <Step title="Handle responses">Set timeouts, check status, and retain safe request-ID context. Distinguish rejected requests from uncertain mutation outcomes before retrying.</Step>
  <Step title="Read results back">Inspect the stored resource and exact version after changes. Do not infer success from a return URL or local editor state.</Step>
</Steps>

Use [Python](/agents-platform/resources/sdks/python) and [TypeScript](/agents-platform/resources/sdks/typescript) resource pages for checked read examples. The private dashboard session is not an alternative public SDK credential.

## Operational review

Separate development, staging, and production credentials and resource identifiers. Define request limits, access logging, dependency failure behavior, and revocation. Keep secrets and unnecessary customer content out of logs.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does API access include every dashboard operation?">No. Use the public contract and the operation's allowed credential type. Internal-web workflows are a separate boundary.</Accordion>
</AccordionGroup>


# WebSockets
Source: https://docs.threetone.in/agents-platform/deploy/server/websockets

Define the authorization, event contract, reconnect behavior, and operational checks required for a future WebSocket integration.

A WebSocket integration needs a published endpoint and message protocol. The current public resource API does not establish a general Threetone WebSocket conversation endpoint, event stream, or supported client package.

<Note>
  Do not derive a socket URL by replacing `https` with `wss` on an API route. A signed-URL or token operation in the reference does not establish a WebSocket protocol, and conversation execution remains gated by [current availability](/agents-platform/overview#current-availability).
</Note>

## Specify the integration before connecting

| Contract | Questions the release must answer |
| - | - |
| Access | How is session access issued, scoped, refreshed, and revoked? |
| Handshake | Which endpoint, protocol version, and authentication mechanism are supported? |
| Messages | Which event types, schemas, ordering rules, and payload limits apply? |
| Delivery | Are acknowledgments, retries, duplicate detection, or resumable cursors supported? |
| Lifecycle | What do close codes, heartbeat failures, idle timeouts, and session expiry mean? |
| Audio | Which encoding, sample rate, frame size, and interruption behavior are accepted? |

Keep workspace credentials in your server's secret storage. Give the application only the access permitted by the released session contract. Avoid putting long-lived credentials in URLs, which can be retained in logs.

## Plan failure handling

<Steps>
  <Step title="Use an explicit connection state">
    Distinguish connecting, open, closing, and closed. Send only when the connection is ready, and stop accepting new work after the owning session ends.
  </Step>

  <Step title="Bound outgoing work">
    Set a queue limit and an application response to overload. The standard [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) has no automatic backpressure; a growing buffer needs deliberate handling.
  </Step>

  <Step title="Treat reconnect as a protocol decision">
    Retry transient failures with a bounded delay only when the released protocol permits it. Do not replay tool actions, user messages, or audio unless the protocol defines safe replay or deduplication.
  </Step>
</Steps>

Before release, test malformed messages, expired access, duplicate events, slow consumers, abrupt disconnects, and cleanup. Record identifiers and error codes without logging access tokens or full customer payloads.

Use [server deployment](/agents-platform/deploy/server/overview) for supported resource requests and [client events](/agents-platform/advanced/events/overview) for the separate event-contract boundaries.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can the live conversation count endpoint stream messages?">No. It returns a workspace count. It is not a transcript subscription or socket endpoint.</Accordion>
  <Accordion title="Does an event name in agent configuration make it subscribable?">No. Saved event preferences require a released producer, transport, and authorization contract before a client can subscribe.</Accordion>
</AccordionGroup>


# Amazon Connect
Source: https://docs.threetone.in/agents-platform/deploy/telephony/contact-center/amazon-connect

Prepare an Amazon Connect external-transfer design, destination ownership, and fallback behavior for a future agent integration.

An Amazon Connect integration needs an explicit call-routing design. Threetone does not provide a released Amazon Connect connector or a destination that can be assumed to receive transferred calls.

## Choose the transfer boundary

Amazon Connect supports agent, queue, and phone-number quick connects. A phone-number quick connect targets an external number; it is not a queue or flow selection. See [Amazon Connect transfer types](https://docs.aws.amazon.com/connect/latest/adminguide/transfer.html).

Before preparing a route, identify the Connect instance, flow owner, existing queue, intended transfer destination, and the team responsible for restoring the original route.

## Prepare the flow

<Steps>
  <Step title="Select the trigger">Decide whether an agent will use a quick connect or the flow will use a Transfer to external number block. Record which callers may reach that branch and how caller identity is presented.</Step>
  <Step title="Verify destination ownership">Use a destination controlled by the intended deployment and confirm the account's outbound destination permissions. An imported Threetone phone record is not evidence that the number can receive agent traffic.</Step>
  <Step title="Design the return path">Specify what happens on timeout, rejection, and external disconnect. Preserve a staffed queue or reviewed fallback. Decide whether the Connect flow should resume after the external participant disconnects.</Step>
  <Step title="Prepare acceptance cases">Wait for a released receiving runtime. Then test transfer initiation, caller ID, two-way audio, external hangup, caller hangup, and the fallback without moving the entire queue.</Step>
</Steps>

Use the official [external transfer block](https://docs.aws.amazon.com/connect/latest/adminguide/transfer-to-phone-number.html) and [resume-after-disconnect guidance](https://docs.aws.amazon.com/connect/latest/adminguide/contact-flow-resume.html) for the selected flow behavior.

## Failure handling

Capture the Connect contact identifier and the destination provider's call identifier separately. Distinguish flow-branch errors, outbound restrictions, unreachable destinations, and media failures. Do not repeatedly transfer a caller back into the same failing branch.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this configure direct media streaming into Threetone?">No. External transfer and media streaming are different designs. This page prepares a transfer review.</Accordion>
  <Accordion title="Can I remove the existing fallback queue?">Keep a reviewed fallback while the receiving runtime is unavailable and until the full transfer lifecycle has passed acceptance testing.</Accordion>
</AccordionGroup>


# Five9
Source: https://docs.threetone.in/agents-platform/deploy/telephony/contact-center/five9

Prepare Five9 VoiceStream destinations and event correlation while separating audio observation from an active agent call integration.

Five9 VoiceStream can deliver call audio and events to an external system. That receiving path is different from transferring a caller to an interactive agent. Threetone does not provide a released Five9 receiver or active call adapter.

## Before you begin

Identify the Five9 domain and region, administrator, intended use of the audio, and the system responsible for receiving it. Review access and retention requirements before preparing a stream subscription.

Five9's [VoiceStream developer guide](https://documentation-be.five9.com/bundle/voicestream-dev-guide/raw/resource/enus/voicestream-dev-guide.pdf) describes SIP and gRPC audio delivery, with call events and stream-status events handled separately. Do not assume it uses the same contract as a generic WebSocket audio service.

## Prepare the receiving design

<Steps>
  <Step title="Choose observation or interaction">For observation, define what the receiving system may analyze or retain. For an interactive agent, identify a separate supported call-control and return-audio design; receiving a stream alone does not establish one.</Step>
  <Step title="Choose the protocol">Review SIP or gRPC receiver requirements, authentication, certificates, and network access with the infrastructure owner. Use the current provider requirements rather than adapting a WebSocket URL by name.</Step>
  <Step title="Separate the destinations">Document the audio destination, CTI Call Event Destination, and StreamStatus Event Destination. Correlate their identifiers so a stream failure is not confused with the call ending.</Step>
  <Step title="Prepare release checks">Require a supported receiver before activating a subscription. Include missing events, duplicate events, audio disconnect, receiver restart, and subscription pause in the acceptance plan.</Step>
</Steps>

Use Five9's [subscription administration guide](https://documentation-be.five9.com/bundle/voicestream-administrators-guide/raw/resource/enus/voicestream-administrators-guide.pdf) to review provider-side subscription and destination settings with the account owner.

## Failure handling

If events arrive without audio, inspect the media destination and protocol independently. If audio arrives without call metadata, inspect event delivery and correlation. Preserve the contact center's existing call path while investigating an observation failure.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does VoiceStream let a Threetone agent speak into a call?">This guide does not establish a return-audio or call-control integration. Those capabilities need an explicitly supported design.</Accordion>
  <Accordion title="Can I activate a subscription using a Threetone API URL?">No released Five9 receiver is documented. Do not configure a guessed API or WebSocket destination.</Accordion>
</AccordionGroup>


# Genesys Cloud
Source: https://docs.threetone.in/agents-platform/deploy/telephony/contact-center/genesys

Review Genesys Cloud transfer and BYOC Cloud boundaries before preparing a future Threetone telephony integration.

Decide whether your integration needs an external call transfer or a carrier trunk. Threetone does not have a released Genesys Cloud connector, and an existing carrier connection does not create an agent media adapter.

## Before you begin

Identify the Genesys organization, flow and queue owners, telephony site, carrier, and the intended destination. For a trunk-based design, review [Genesys BYOC Cloud](https://help.genesys.cloud/articles/about-byoc-cloud/), which connects the Genesys media tier to an external carrier through SIP trunks.

## Review the integration boundary

<Steps>
  <Step title="Choose the call path">Draw the current queue-to-destination route. Mark whether the proposed change is a transfer within a flow or a change to external trunk routing. Keep the existing staffed queue and its error behavior visible.</Step>
  <Step title="Inventory the telephony objects">For BYOC Cloud, review the external trunk, site, number plan, and outbound route with the Genesys administrator. Obtain the actual carrier signaling and media requirements rather than reusing a dashboard URL.</Step>
  <Step title="Map the receiving side">Compare a proposed SIP destination with the [SIP reference](/agents-platform/deploy/telephony/sip-reference). Require a released runtime ingress, agreed authentication, and an executable agent version before considering the route ready.</Step>
  <Step title="Specify acceptance and rollback">Plan transfer rejection, no answer, two-way audio, caller identity, disconnect, and fallback checks. Record which provider configuration returns traffic to its previous destination.</Step>
</Steps>

## Failure handling

If a call takes the wrong route, inspect the selected number plan, outbound route, and trunk before changing agent behavior. If the destination answers but audio fails, inspect the media path separately from signaling. Keep the Genesys conversation identifier and the destination's call identifier in the same redacted incident record.

A BYOC trunk can support an existing carrier design without making that design compatible with Threetone. Treat compatibility as a deployment result to establish, not an inference from the presence of SIP.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does enabling BYOC Cloud connect an agent automatically?">No. It configures a Genesys carrier boundary. The receiving agent runtime and its integration require separate implementation and verification.</Accordion>
  <Accordion title="Should I import provider: genesys?">No. The phone API has no Genesys-specific import variant. Review any SIP candidate against the generic contract and current runtime limits.</Accordion>
</AccordionGroup>


# Customize calls
Source: https://docs.threetone.in/agents-platform/deploy/telephony/customize-calls

Set the agent, branch, and environment associated with a phone number and verify the saved routing configuration.

Phone-number assignment selects the agent and configuration context intended for calls to that number. Use the update operation carefully: omitted fields and explicit null values can have different effects.

## Change the assignment

<Steps>
  <Step title="Inspect the current record">
    Read [Get phone number](/api-reference/agents-platform/get-phone-number). Record its agent assignment, branch, environment, and trunk settings before preparing a change.
  </Step>

  <Step title="Choose the intended configuration">
    Select an agent in the same workspace. If you choose a branch, confirm it belongs to that agent and review its published version through [versioning](/agents-platform/deploy/versioning). Review the [environment variables](/agents-platform/deploy/environment-variables) needed by the deployment.
  </Step>

  <Step title="Apply a focused update">
    Use [Update phone number](/api-reference/agents-platform/update-phone-number) with only the fields you intend to change. Read the returned record and then retrieve it again to confirm the assignment you saved.
  </Step>
</Steps>

## Assignment rules

| Request | Current behavior |
| - | - |
| Supply `branch_id` without `agent_id` | Validates the branch against the number's existing assigned agent. |
| Supply a branch without any assigned agent | Rejects the update. |
| Supply a branch belonging to another agent | Rejects the update. |
| Supply `branch_id: null` | Removes the explicit branch selection. |
| Supply `agent_id` without `branch_id` | Clears the previous branch selection; supply the intended branch together with the agent when needed. |
| Supply `agent_id: null` | Clears the agent assignment. |

The update also accepts a label, environment, trunk configuration, and SIP-message storage preference. Treat nested trunk objects as complete candidate configurations and read them back; do not assume every omitted nested value is preserved by a partial update.

## Review the call experience

Configure instructions, first message, tools, and speech settings on the selected agent. Keep the greeting appropriate for the number's purpose and review [call consent](/agents-platform/legal/call-consent) and [AI disclosure](/agents-platform/legal/ai-disclosure) before deployment.

A saved assignment does not start a call or establish that the selected version can execute. After the runtime is released and configured, verify routing to the intended version, resolved environment values, greeting, two-way audio, and end behavior with an authorized test call.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will a branch from another agent be accepted?">No. The update validates branch ownership against the assigned agent.</Accordion>
  <Accordion title="Does removing an assignment cancel the number?">No. Clearing the assignment and canceling a number are separate operations. Review the cancellation workflow and provider state before relying on service termination.</Accordion>
</AccordionGroup>


# Azure Communication Services
Source: https://docs.threetone.in/agents-platform/deploy/telephony/microsoft-teams/azure-communication-services

Choose an identity model and prepare a custom Teams interoperability application before adding an agent media integration.

Azure Communication Services can support custom applications that interact with Teams. It does not provide an automatic bridge from a Teams meeting to a Threetone agent. No Threetone adapter for this path is currently released.

## Choose the identity model

Microsoft distinguishes external users authenticated by your application from Teams users authenticated through Microsoft Entra ID. The models differ in licensing, supported call scenarios, and policy behavior. Start with the current [Teams interoperability guide](https://learn.microsoft.com/en-us/azure/communication-services/concepts/teams-interop), including its service-lifecycle notice.

## Prepare the application

Before implementation, identify the Azure resource owner, Teams tenant owner, supported target clients, and intended interaction: joining a meeting or calling as a Teams user.

<Steps>
  <Step title="Specify the supported scenario">Document the chosen identity model and confirm that Microsoft supports the desired meeting or calling behavior for it. Do not assume an external identity has the capabilities of a licensed Teams user.</Step>
  <Step title="Design token issuance">Your backend must authorize the application user before issuing or exchanging Communication Services tokens. Keep resource credentials out of client code and define renewal and sign-out behavior.</Step>
  <Step title="Review meeting behavior">Plan admission, lobby handling, participant identity, disconnects, and recording or transcription indicators. Confirm applicable tenant policies with the administrator.</Step>
  <Step title="Define the agent boundary">Require a supported Threetone session transport and an explicit audio or text adapter. Establish how interruption, media loss, and agent failure will appear to the user before connecting the systems.</Step>
</Steps>

## Failure handling

Separate token rejection, meeting admission failure, unsupported calling scenarios, and media problems. Keep Microsoft call identifiers and application session identifiers distinct. Do not repeatedly mint new identities to work around a tenant policy or admission failure.

Before release, verify the exact Microsoft SDK and scenario against current lifecycle guidance. Review provider usage costs with the account owner before provisioning resources or testing calls.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is this the same as putting a widget in Teams?">No. A [Teams tab](/agents-platform/deploy/telephony/microsoft-teams/widget-tab) hosts web content. Communication Services supplies a separate communications application model.</Accordion>
  <Accordion title="Will a working Teams meeting automatically start an agent?">No. The Threetone session, media adapter, and execution requirements must be implemented and verified separately.</Accordion>
</AccordionGroup>


# Graph media bot
Source: https://docs.threetone.in/agents-platform/deploy/telephony/microsoft-teams/graph-media-bot

Prepare Microsoft Graph application-hosted media requirements, instance lifecycle, and agent boundaries for a future Teams bot.

An application-hosted media bot processes call or meeting media in its own service. Threetone does not ship a Teams media bot or an adapter for this interface.

## Platform prerequisites

Microsoft's current [application-hosted media guidance](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/calls-and-meetings/requirements-considerations-application-hosted-media-bots) requires C#/.NET with `Microsoft.Graph.Communications.Calls.Media` and Windows Server hosting in Azure for production. It does not support this media path as a Node.js API or an Azure web app. The documented platform remains subject to preview requirements.

Identify the tenant and application registration owners, hosting team, selected calling scenario, and permissions it needs. A chat bot registration alone does not establish real-time media support.

## Prepare the implementation review

<Steps>
  <Step title="Review permissions and terms">Map the intended call or meeting operations to the necessary Microsoft permissions and administrator consent. Review the [cloud communications guidance](https://learn.microsoft.com/en-us/graph/cloud-communications-concept-overview) and applicable media-use terms before planning persistence of audio or derived content.</Step>
  <Step title="Design the media host">Use Microsoft's supported hosting and networking requirements. Plan per-instance media reachability and capacity. Keep the media library within its supported update window.</Step>
  <Step title="Handle instance lifecycle">Media calls remain attached to the instance that accepted or created them. Plan admission limits, deployment draining, and caller-visible failure behavior; stopping that instance can terminate active calls.</Step>
  <Step title="Define the Threetone adapter">Specify the released agent session contract, audio conversion, interruption behavior, and teardown. None of these is supplied merely by creating a Graph application registration.</Step>
</Steps>

## Failure handling

Distinguish permission rejection, call-control errors, inaccessible media ports, and overloaded instances. Correlate Graph call identifiers with the media host and future agent session. Keep the existing human call path available during evaluation.

Before rollout, demonstrate invitation or joining behavior, two-way media, hangup, capacity limits, and host replacement with authorized test participants. Do not assume a generic messaging-bot emulator proves media behavior.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I host this in my existing JavaScript web app?">Not as the application-hosted media service described here. Follow Microsoft's C#/.NET and Windows Server requirements for that component.</Accordion>
  <Accordion title="Does Graph registration enable Threetone meeting access?">No. Tenant authorization, the media service, and a supported Threetone adapter are separate release requirements.</Accordion>
</AccordionGroup>


# Microsoft Teams
Source: https://docs.threetone.in/agents-platform/deploy/telephony/microsoft-teams/overview

Choose between a Teams tab, Azure Communication Services, and a Graph media bot when preparing a future integration.

Choose a Teams integration by the interaction you need. Displaying an assistant page, joining a meeting through a custom application, and processing live call media require different platform capabilities.

<Note>
  Threetone does not provide a released Teams app package, Teams media bot, or Azure Communication Services adapter. Use these guides to prepare the implementation and tenant review.
</Note>

## Choose a path

| Need | Preparation guide | Boundary |
| - | - | - |
| Show a web experience inside Teams | [Widget tab](/agents-platform/deploy/telephony/microsoft-teams/widget-tab) | Embedded web content does not receive meeting audio automatically. |
| Build a custom application that interoperates with Teams | [Azure Communication Services](/agents-platform/deploy/telephony/microsoft-teams/azure-communication-services) | Identity model, supported scenarios, and tenant policies determine behavior. |
| Process call or meeting media in an application | [Graph media bot](/agents-platform/deploy/telephony/microsoft-teams/graph-media-bot) | Requires a dedicated application-hosted media service. |

Microsoft documents these separately as [tabs](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/what-are-tabs), [Communication Services interoperability](https://learn.microsoft.com/en-us/azure/communication-services/concepts/teams-interop), and [application-hosted media bots](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/calls-and-meetings/requirements-considerations-application-hosted-media-bots).

## Prepare the review

<Steps>
  <Step title="Name the user action">Specify whether a user opens a page, joins a meeting, starts a call, or invites a bot. Avoid treating these as one generic connection flow.</Step>
  <Step title="Identify administrative ownership">Record the tenant, application registration owner, required installation or consent decisions, and the application backend owner. Request only permissions justified by the selected design.</Step>
  <Step title="Define release evidence">Require a supported Threetone session interface, a verified Microsoft-side design, identity checks, and clear disconnect behavior. Include a way for the user to recover if the integration is unavailable.</Step>
</Steps>

If a test fails, identify whether the failure is app loading, identity, meeting admission, call control, or media. Each belongs to a different part of the integration.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will a Teams tab hear the current meeting?">No. Embedding a webpage does not grant access to meeting audio.</Accordion>
  <Accordion title="Can I install a ready-made Threetone Teams app?">No released app package is documented. Use the relevant preparation guide to define the required implementation.</Accordion>
</AccordionGroup>


# Teams widget tab
Source: https://docs.threetone.in/agents-platform/deploy/telephony/microsoft-teams/widget-tab

Prepare an authenticated web experience for a Teams tab without assuming a public widget embed or access to meeting audio.

A Teams tab embeds a web page in the Teams client. It can provide an assistant interface when that interface is supported, but it does not turn the page into a meeting participant or media bot.

<Note>
  Threetone has saved widget configuration, but no released public embed script or Teams app package is documented. Review [widget readiness](/agents-platform/deploy/web/widget) before designing the tab's conversation flow.
</Note>

## Prepare the tab application

Identify a web application you control, its HTTPS origin, the intended Teams scope, and the backend that will authorize each user. A Teams user or channel identifier is context, not proof of access to a Threetone workspace.

<Steps>
  <Step title="Choose the scope">Decide whether the interface belongs in a personal app, chat, or channel. Prepare the content URL and allowed domains in the Teams app manifest.</Step>
  <Step title="Review embedding requirements">Use HTTPS, configure the page's framing policy for the intended Microsoft hosts, and initialize TeamsJS after load. Check the current host list, including Microsoft's cloud.microsoft migration.</Step>
  <Step title="Design authentication">Use an appropriate Teams authentication flow and verify authorization in your backend. Sign-in pages may not render inside the iframe; do not rely on an embedded redirect loop or expose a workspace API key in the page.</Step>
  <Step title="Prepare client acceptance tests">Test sign-in, theme, keyboard navigation, resizing, session expiry, and client-specific device permissions. Treat microphone access and a supported Threetone session transport as separate requirements.</Step>
</Steps>

Follow Microsoft's [tab requirements](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/tab-requirements) and [tab overview](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/what-are-tabs) for the host contract.

## Failure handling

For a blank tab, inspect HTTPS, framing policy, allowed domains, and TeamsJS initialization. For a sign-in loop, inspect the authentication flow independently. Provide a recoverable unavailable state when the assistant session cannot start.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I paste the dashboard into a tab?">Do not assume the dashboard is a supported embed. A tab needs an intentionally supported page, authentication flow, and framing configuration.</Accordion>
  <Accordion title="Does microphone permission expose meeting audio?">No. Device permission and access to a Teams call or meeting's media are different capabilities.</Accordion>
</AccordionGroup>


# Phone integration
Source: https://docs.threetone.in/agents-platform/deploy/telephony/overview

Review provider-backed phone number configuration, agent assignments, and the current limits of outbound and channel execution.

Phone configuration records connect workspace resources to provider-backed numbers. Review the provider, number, credentials, and assigned agent separately from whether a call can execute.

<Frame>
  <img alt="Recording pending for Review phone number configuration. No playable video is available yet." />
</Frame>

## Before you begin

This review assumes an existing imported phone-number record in your workspace. You need access to its provider account, permission to manage workspace phone resources, and the identifier of the intended agent. Keep provider credentials in the supported credential workflow and out of documentation, logs, and browser bundles.

Use [List phone numbers](/api-reference/agents-platform/list-phone-numbers) to find an existing record. If you have not imported one, review [Import phone number](/api-reference/agents-platform/import-phone-number) and its provider-specific fields first.

The public reference contains phone-number configuration for Twilio, Exotel, and SIP trunks. These are distinct provider request shapes. A number imported for one provider does not establish that every call direction or outbound route supports it.

## Configuration review

<Steps>
  <Step title="Identify the provider and number">
    Confirm which account owns the number and which provider configuration you intend to use. Review the provider-specific fields in [Import phone number](/api-reference/agents-platform/import-phone-number).
  </Step>

  <Step title="Inspect the workspace record">
    Use [Get phone number](/api-reference/agents-platform/get-phone-number) to read its metadata and identifier. Confirm that it belongs to the intended workspace and provider before changing its assignment.
  </Step>

  <Step title="Review the assigned agent">
    Check the agent identifier and saved voice configuration. Keep the relevant branch and version IDs with your configuration review.
  </Step>

  <Step title="Read changes back">
    After using [Update phone number](/api-reference/agents-platform/update-phone-number), inspect the number record and agent assignment again.
  </Step>
</Steps>

The [Delete phone number operation](/api-reference/agents-platform/delete-phone-number) follows the number cancellation workflow rather than simply removing a record. Check its result and the provider's cancellation or release process before assuming the number was released or provider billing ended.

## Current execution limits

<Warning>
  Outbound-call routes are currently blocked by the documented agent runtime gate. The general outbound implementation additionally requires a managed PSTN configuration and currently selects Twilio fulfillment. An imported Exotel or SIP number does not make that route available.
</Warning>

WhatsApp outbound call and message routes currently return HTTP `501`. Batch creation, export, and retry are also unavailable. Workspace webhook management does not currently establish persisted subscriptions or callback delivery.

This guide covers phone configuration. It does not establish inbound SIP availability or a successful call, batch job, WhatsApp message, or delivered callback.

## Plan the later call test

Once the relevant released execution path is available, validate the provider credentials, destination format, agent configuration, and call direction with a controlled test. Use E.164 destination numbers where the request requires them. Confirm the applicable consent, disclosure, and recording requirements before placing that test call.

Keep provider logs and Threetone request identifiers with the test result, with credentials and personal information removed. A saved phone number or agent assignment is configuration evidence, not proof of a connected call.

Continue with [agent configuration](/agents-platform/configure/agent-behavior/overview), [models and voices](/overview/models), and [conversation inspection](/agents-platform/monitor/conversations).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does importing a number enable calling?">No. Import and assignment are configuration operations. Provider support and runtime execution must be verified separately.</Accordion>
  <Accordion title="Does deleting a number just remove a record?">The public operation follows cancellation. Confirm the result and provider release or billing effects separately.</Accordion>
  <Accordion title="Are WhatsApp outbound calls and messages available?">The documented outbound routes currently return HTTP 501. Do not build an execution workflow around them yet.</Accordion>
</AccordionGroup>


# Provider integrations
Source: https://docs.threetone.in/agents-platform/deploy/telephony/provider-integrations

Prepare Twilio, Exotel, or SIP import fields and understand the provider checks that remain outside a saved phone record.

Choose the import variant that matches the number or trunk you control. The current API accepts Twilio, Exotel, and SIP configuration, but import does not authenticate the provider account, provision a number, or verify live calling.

## Choose an import variant

| Provider | Required preparation |
| - | - |
| Twilio | Number, label, `sid`, its paired `token`, and `enable_sms: false`. |
| Exotel | Number, label, account SID, API key, API token, account API subdomain, and app ID. |
| SIP trunk | Routing identifier, label, and the inbound or outbound settings needed by your deployment. |

Use the full [Import phone number schema](/api-reference/agents-platform/import-phone-number) for optional fields and exact request types. An optional `agent_id` must identify an agent available in the workspace.

### Twilio preparation

The `sid` field accepts an Account SID or API Key SID. Pair it with the corresponding Account Auth Token or API Key Secret. The current validator requires `enable_sms: false`; its default value of true is rejected. It also rejects `account_auth_token` until a secure webhook-signature credential handoff is available.

These restrictions mean you must not describe an import as enabling SMS or completing an API-key-based inbound webhook setup. For carrier-side trunk requirements, use [Twilio's official SIP documentation](https://www.twilio.com/docs/sip-trunking).

### Exotel preparation

Collect the account SID and API credentials from the account's API settings. Confirm the region-specific API host and the intended app ID. Exotel's [getting-started guide](https://developer.exotel.com/docs/call-support/basics/getting-started) explains where these account details originate. An Exotel record in Threetone does not prove that an applet, callback, or outbound runtime has been configured.

### SIP preparation

Use the [SIP trunk guide](/agents-platform/deploy/telephony/sip-trunk) to review routing direction, address restrictions, transport, media policy, and credentials with the trunk operator.

## Verify the result

<Steps>
  <Step title="Import only the intended configuration">Submit the appropriate variant from a trusted server or authorized dashboard workflow. Keep credentials out of screenshots and issue reports.</Step>
  <Step title="Inspect the saved record">Read the returned phone-number ID. Confirm the provider, routing identity, assignment, and configuration. Import stores redacted credential metadata, so it is not proof of a usable runtime secret.</Step>
  <Step title="Review runtime readiness">Verify credential handoff, the provider-specific route, and the selected executable agent version separately. The general outbound route requires managed PSTN with Twilio fulfillment; an Exotel or SIP import does not satisfy that requirement.</Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does a basic Twilio import fail validation?">Check that enable\_sms is explicitly false and account\_auth\_token is omitted. The current implementation rejects both SMS enablement and the separate webhook credential field.</Accordion>
  <Accordion title="Does deleting the Threetone record stop provider charges?">Do not assume that it does. Deletion follows a cancellation workflow with provider-specific requirements. Verify the final provider state separately.</Accordion>
</AccordionGroup>


# Bandwidth
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/bandwidth

Identify the Bandwidth platform and SIP routing objects before preparing a future Threetone carrier integration.

Start by identifying which Bandwidth platform your account uses. Configuration differs between Build SIP Trunking and Universal Platform. Threetone has no Bandwidth-specific import variant or verified carrier adapter.

## Prepare the correct platform configuration

| Platform | Review with the account owner |
| - | - |
| Build SIP Trunking | Realm, SIP credentials, inbound routes, and number-level SIP selection. |
| Universal Platform | Voice Configuration Package, associated numbers, and the intended routing configuration. |

Bandwidth's [Build SIP guide](https://dev.bandwidth.com/docs/voice/sip-trunking/sip-getting-started/) describes realms and prioritized inbound routes. For Universal Platform, use its [Voice Configuration Package guide](https://dev.bandwidth.com/docs/universal-platform/create-a-vcp/). Do not combine their configuration instructions.

## Review the candidate route

<Steps>
  <Step title="Inventory the existing number route">Record the platform, number assignment, current destination, and fallback. In Build, selecting SIP Trunking for a number changes its handling away from Voice API traffic, so review existing applications before making that change.</Step>
  <Step title="Collect the SIP boundary">For Build, collect the realm and its SIP credentials, then review the route endpoints and their priorities. For Universal Platform, obtain the routing details associated with the intended Voice Configuration Package.</Step>
  <Step title="Map the Threetone candidate">Compare the resulting destination, source restrictions, authentication, transport, and media requirements with the [SIP reference](/agents-platform/deploy/telephony/sip-reference). Do not put management API credentials in SIP fields.</Step>
  <Step title="Prepare release evidence">Require a supported runtime destination and credential handoff. Define separate inbound, outbound, and fallback tests before moving an existing number.</Step>
</Steps>

## Failure handling

If calls disappear after a routing change, inspect the number's selected service and associated route before editing the agent. For failover problems, check endpoint priority and the provider's result for the primary destination. Preserve the prior configuration for rollback.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I follow either platform's instructions?">No. Use the documentation that matches your Bandwidth account and product.</Accordion>
  <Accordion title="Does a saved generic SIP record switch my Bandwidth number?">No. Threetone import does not change number routing or provision provider resources.</Accordion>
</AccordionGroup>


# Exotel
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/exotel

Prepare Exotel account, region, and applet fields for phone import while identifying the current outbound execution limit.

The phone API accepts an Exotel import record. It does not validate the provider credentials, configure an applet, or release Exotel calling. The current shared outbound service requires Twilio fulfillment, so the existence of an Exotel outbound operation is not proof of working execution.

## Collect the import fields

Use the account's API settings to obtain credentials, following [Exotel's getting-started guide](https://developer.exotel.com/docs/call-support/basics/getting-started).

| Field | Preparation |
| - | - |
| `phone_number`, `label` | Intended number and a recognizable workspace label. |
| `account_sid` | Account owning the number and flow. |
| `api_key`, `api_token` | Matching account credentials. |
| `api_subdomain` | Account host: `api.in.exotel.com` or `api.exotel.com`. |
| `app_id` | Intended Exotel applet identifier. |
| `applet_url` | Optional explicit flow URL override; review before supplying. |

## Prepare and inspect the record

<Steps>
  <Step title="Confirm the flow">Exotel's number-to-flow operation calls a number and then connects it to an applet after answer. Confirm the correct flow in the provider account; do not confuse it with a two-number call.</Step>
  <Step title="Check account and region">Ensure the SID, credentials, API host, number, and app ID belong to the same intended configuration. Avoid constructing a flow URL from an unrelated account.</Step>
  <Step title="Import and read back">Use the Exotel variant of [Import phone number](/api-reference/agents-platform/import-phone-number). Inspect the saved identity and assignment. Credential metadata is redacted; readback is not provider authentication evidence.</Step>
  <Step title="Keep runtime release separate">Require provider-specific execution, credential delivery, callbacks, and an executable agent version before changing the existing call flow.</Step>
</Steps>

See [Exotel's number-to-flow reference](https://developer.exotel.com/docs/voice-v1/api-reference/connect-to-flow) for the relationship between the called number, caller ID, and applet URL.

## Failure handling

For import validation, inspect the API host enum and required fields. For an unsupported-fulfillment error during outbound initiation, stop retrying: changing account credentials cannot enable an unimplemented provider execution path.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I call immediately after Exotel import succeeds?">No. Import and provider execution are separate. The current shared outbound path does not support Exotel fulfillment.</Accordion>
  <Accordion title="Does import create my Exotel applet?">No. It records the supplied configuration. Review the applet with the provider account owner.</Accordion>
</AccordionGroup>


# Plivo
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/plivo

Prepare Plivo Zentrunk inbound and outbound configuration, authentication, and fallback destinations for a future SIP route.

Plivo Zentrunk is a candidate carrier path for a future SIP deployment. Threetone has no Plivo-specific import variant or verified Plivo runtime adapter. Use the generic SIP contract only as a configuration review boundary.

## Before you begin

Collect the trunk IDs, number assignment, SIP domain, and authentication details from the Plivo administrator. Zentrunk separates inbound and outbound trunks. Its [trunk API reference](https://www.plivo.com/docs/sip-trunking/api/trunks) identifies an inbound primary URI and optional fallback URI; outbound trunks use IP access controls, credentials, or both.

## Review both directions

<Steps>
  <Step title="Identify the inbound destination">Record the primary URI and any fallback URI attached to the inbound trunk. Keep their priority and expected behavior in the release plan. Do not replace them with an assumed Threetone address.</Step>
  <Step title="Identify outbound authentication">Record the outbound trunk domain and the associated credential or IP access-control configuration. The source address must match the future deployed runtime, not a developer laptop.</Step>
  <Step title="Map the accepted fields">Compare transport, media policy, credentials, and codecs with the [SIP reference](/agents-platform/deploy/telephony/sip-reference). Keep Plivo management credentials separate from SIP username and password.</Step>
  <Step title="Prepare acceptance and rollback">Wait for a released runtime destination and credential handoff. Then test each direction independently and verify the provider's configured fallback behavior before expanding traffic.</Step>
</Steps>

## Failure handling

An outbound authentication error and an unreachable inbound URI require different fixes. Capture the trunk direction, provider call identifier, timestamp, and SIP result. If fallback is unexpectedly used, investigate the primary destination before removing the fallback. See [Plivo's Zentrunk documentation](https://www.plivo.com/docs/sip-trunking) for provider-side configuration.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does an inbound trunk prove outbound calling works?">No. Zentrunk's inbound and outbound objects have different destinations and authentication requirements.</Accordion>
  <Accordion title="Will Threetone create the primary and fallback URIs?">No. Import does not provision provider resources. The deployment must supply and verify its actual supported runtime destinations.</Accordion>
</AccordionGroup>


# Sinch
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/sinch

Prepare Sinch Elastic SIP Trunking identity, number assignment, and outbound settings for a future supported calling route.

Use Sinch Elastic SIP Trunking as a provider configuration candidate. There is no Sinch-specific Threetone import variant or released Sinch adapter. A generic SIP record does not establish carrier connectivity.

## Before you begin

Identify the Sinch project, trunk, intended number, provider administrator, and current routing destination. Sinch's [Elastic SIP Trunking setup](https://developers.sinch.com/docs/est/getting-started) separates management access keys, the EST environment, trunk creation, outbound settings, and number preparation.

## Prepare the route

<Steps>
  <Step title="Record the provider identity">Collect the project and trunk identifiers and confirm which number is associated with the candidate. Keep management access keys separate from the SIP authentication details required by the trunk.</Step>
  <Step title="Review both call directions">Document where incoming calls go and the outbound settings that apply to the trunk. Confirm any destination restrictions and required account setup with the Sinch administrator.</Step>
  <Step title="Map signaling and media">Obtain the actual carrier destination, authentication method, network requirements, transport, encryption, and codecs. Compare them with the [SIP reference](/agents-platform/deploy/telephony/sip-reference); do not infer these values from an API access key.</Step>
  <Step title="Prepare a controlled release">Require a released runtime ingress, usable credential handoff, and an executable agent version before rerouting numbers. Plan inbound and outbound tests and restoration of the previous destination.</Step>
</Steps>

## Failure handling

If provider administration succeeds but calls fail, verify the number assignment and outbound configuration rather than repeatedly replacing the management access key. Capture direction, trunk identifier, timestamp, and the carrier result. Investigate signaling and media separately when the call connects without usable audio.

Provider account setup can include additional number and address requirements. Review those with the account owner. Emergency-calling capability needs a separate provider and deployment review.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can Threetone create my Sinch trunk?">No. Phone import stores workspace configuration and does not provision provider resources.</Accordion>
  <Accordion title="Is a Sinch management access key a SIP credential?">Do not assume that it is. Obtain the trunk's required authentication details and keep management credentials in their intended server-side context.</Accordion>
</AccordionGroup>


# Telnyx
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/telnyx

Map Telnyx SIP Connections, number assignments, and Outbound Voice Profiles into a future telephony deployment review.

Prepare Telnyx routing as a SIP integration candidate. There is no Telnyx-specific Threetone phone import or released Telnyx adapter. A saved generic SIP record does not connect these systems.

## Identify the provider objects

Telnyx uses a SIP Connection for authentication and incoming routing, assigns numbers to a connection, and uses an Outbound Voice Profile for outbound policy. Review [Telnyx's SIP getting-started guide](https://developers.telnyx.com/docs/voice/sip-trunking/get-started) with the carrier account owner.

| Object | Information to collect |
| - | - |
| SIP Connection | Identifier, authentication method, routing destination, and relevant network settings. |
| Phone number | Exact number and assigned connection. |
| Outbound Voice Profile | Linked connection, permitted destinations, and account-owner-approved spending controls. |

## Prepare the mapping

<Steps>
  <Step title="Trace inbound routing">Follow the number to its assigned connection and current destination. Document what will happen to callers during a failed or rolled-back deployment.</Step>
  <Step title="Trace outbound routing">Confirm that the intended connection is associated with the correct Outbound Voice Profile. A working inbound route does not establish outbound authorization.</Step>
  <Step title="Review the SIP candidate">Map the carrier destination, authentication, source restrictions, transport, and media requirements to the [SIP reference](/agents-platform/deploy/telephony/sip-reference). Keep the Telnyx API key separate from trunk credentials.</Step>
  <Step title="Require runtime readiness">Before changing number routing, verify a supported Threetone ingress, credential handoff, and executable agent version. Prepare independent inbound and outbound acceptance cases.</Step>
</Steps>

## Failure handling

If incoming calls take the wrong route, inspect the number-to-connection assignment first. If only outbound calls fail, review profile linkage, destination policy, and provider error details. If signaling succeeds but audio fails, examine negotiated media and network access before changing application prompts.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does importing a SIP record create a Telnyx Connection?">No. Threetone import stores configuration and does not create provider resources.</Accordion>
  <Accordion title="Can I use a Telnyx number through the current Twilio outbound path?">No. That service requires Twilio fulfillment. A generic SIP import does not satisfy the provider requirement.</Accordion>
</AccordionGroup>


# Vonage
Source: https://docs.threetone.in/agents-platform/deploy/telephony/providers/vonage

Prepare a Vonage SIP trunk, its regional domain, and authentication details for a future reviewed Threetone route.

Use this guide to prepare a Vonage SIP candidate. Threetone does not have a Vonage-specific phone import variant or a verified Vonage calling adapter. The generic SIP configuration must still pass a supported runtime review.

## Before you begin

Ask the Vonage administrator for the trunk's regional domain, number assignment, authentication method, and existing inbound destination. Keep the provider management credentials separate from SIP authentication.

Vonage's current [SIP technical details](https://developer.vonage.com/en/sip/technical-details) describe a dedicated regional trunk domain and authentication through SIP credentials or an access-control list. Account API credentials are not a substitute for those trunk credentials.

## Prepare the route

<Steps>
  <Step title="Confirm the trunk identity">Record the exact domain issued for your trunk and its region. Identify the caller and destination number formats expected by Vonage; its SIP guidance uses E.164 for these identities.</Step>
  <Step title="Map authentication by direction">For outbound requests, record the carrier destination and whether it expects digest credentials or an allowed source address. For inbound traffic, collect provider source ranges and the intended runtime ingress separately.</Step>
  <Step title="Compare transport and media">Review provider requirements against the [SIP reference](/agents-platform/deploy/telephony/sip-reference). Document transport, certificate domains, media encryption, and codecs instead of assuming the same settings apply in both directions.</Step>
  <Step title="Prepare the release test">Require a released ingress destination and credential handoff before changing the Vonage route. Plan answer, two-way audio, caller identity, hangup, and fallback checks with authorized test numbers.</Step>
</Steps>

## Failure handling

For authentication rejection, compare the trunk-specific credential or allowed source address with the actual deployment. For a call that answers without usable audio, inspect media negotiation and network reachability separately from SIP signaling. Preserve the existing provider route until the candidate passes review.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I send provider: vonage to the import API?">No. The API has no such variant. A reviewed SIP candidate uses the generic SIP schema; saving it does not validate Vonage compatibility.</Accordion>
  <Accordion title="Can I reuse my Vonage API key as the SIP password?">Do not substitute management credentials. Obtain the trunk's current authentication details from the Vonage administrator.</Accordion>
</AccordionGroup>


# SIP reference
Source: https://docs.threetone.in/agents-platform/deploy/telephony/sip-reference

Map inbound and outbound SIP fields to a carrier review, and distinguish saved configuration from negotiated call behavior.

Use this reference with the [SIP trunk procedure](/agents-platform/deploy/telephony/sip-trunk). The fields below describe configuration accepted by the phone-number API. They do not establish a runtime ingress address, provision a trunk, or verify media connectivity.

## Configuration fields

| Direction | Field | Review with the trunk operator |
| - | - | - |
| Inbound | `allowed_addresses` | Source IP addresses or CIDR ranges expected to send calls. |
| Inbound | `allowed_numbers` | Caller numbers allowed by the intended routing policy. |
| Inbound | `remote_domains` | Remote certificate domains for the TLS design. |
| Outbound | `address` | Hostname or IP receiving the SIP INVITE. |
| Outbound | `transport` | `auto`, `udp`, `tcp`, or `tls`. |
| Both | `media_encryption` | `disabled`, `allowed`, or `required`. |
| Both | `credentials` | Optional SIP digest username and password. |
| Outbound | `enabled_codecs` | `G722/8000`, `PCMU/8000`, or `PCMA/8000`. |

Outbound `headers` contains literal SIP header values. `attributes_to_headers` maps dynamic-variable names to header names. Review which information may leave your application before proposing either mapping. Keep credentials out of these headers.

## Review a candidate

<Steps>
  <Step title="Identify each direction">Write down who sends the INVITE, who receives it, and which endpoint supplies media. Carrier terms such as origination and termination must be interpreted from the carrier's perspective.</Step>
  <Step title="Validate the request">Compare the candidate with [Import phone number](/api-reference/agents-platform/import-phone-number). Keep transport, media policy, and codecs separate; selecting TLS does not by itself prove encrypted audio.</Step>
  <Step title="Read back stored configuration">Inspect the routing identity and assignment with [Get phone number](/api-reference/agents-platform/get-phone-number). Credential-presence and trunk flags describe stored state. Import redacts credential metadata; runtime credential delivery still needs verification.</Step>
  <Step title="Define acceptance evidence">Before a supported runtime is released, document the expected SIP response, negotiated codec, two-way audio, disconnect handling, and fallback route. Run those checks only after the deployment is ready.</Step>
</Steps>

For failed signaling or one-way audio, collect a timestamp, direction, redacted call identifier, and the carrier's result. Follow [telephony troubleshooting](/agents-platform/deploy/telephony/troubleshooting).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does an empty codec list mean no audio?">The schema describes an empty list as offering all supported codecs. Confirm the actual negotiated codec during a supported runtime test.</Accordion>
  <Accordion title="Can I treat has_auth_credentials as a successful login?">No. It is response metadata, not a carrier authentication result or proof that a runtime can retrieve the secret.</Accordion>
</AccordionGroup>


# SIP trunk
Source: https://docs.threetone.in/agents-platform/deploy/telephony/sip-trunk

Prepare SIP routing details, save a trunk configuration, and separate stored settings from a verified calling deployment.

The phone-number API accepts a `sip_trunk` import with inbound and outbound configuration. Importing saves a workspace record; it does not establish a connected trunk or prove that a call can reach an executable agent.

## Prepare the trunk

Ask the carrier or trunk operator for the routing identifier, inbound source addresses, outbound destination, authentication method, transport, media encryption, and codec requirements. Record which direction each value describes. For example, [Twilio's SIP documentation](https://www.twilio.com/docs/sip-trunking) distinguishes termination toward the phone network from origination toward your infrastructure.

| Configuration | Review |
| - | - |
| `phone_number` | Use the exact telephone number or SIP routing identifier expected by this route. |
| Inbound `allowed_addresses` and `allowed_numbers` | Limit accepted sources to the intended deployment. |
| Inbound `remote_domains` | Match the certificate domains required by your TLS design. |
| Outbound `address` and `transport` | Use the carrier-provided destination and supported transport. |
| `media_encryption` | Agree on the media policy at both ends; saving it does not prove negotiation. |
| `enabled_codecs` | Match the request schema and provider capability. |

The current schema accepts `auto`, `udp`, `tcp`, or `tls` transport and `disabled`, `allowed`, or `required` media encryption. Its codec values include `G722/8000`, `PCMU/8000`, and `PCMA/8000`. These are configuration choices, not a claim that every combination has passed a live call test.

## Save and verify the record

<Steps>
  <Step title="Import the configuration">
    Use [Import phone number](/api-reference/agents-platform/import-phone-number) with `provider: "sip_trunk"`. Review the nested inbound and outbound schemas before submitting. The import path redacts credential fields in stored provider metadata; it does not validate them against the carrier.
  </Step>

  <Step title="Read the result back">
    Keep the returned identifier and use [Get phone number](/api-reference/agents-platform/get-phone-number). Check the routing identity, label, assignment, and trunk details. A configured status is stored state, not a connectivity test.
  </Step>

  <Step title="Review the deployment separately">
    Confirm the runtime's ingress destination, credential handoff, network policy, and executable agent version before routing traffic. Use [customize calls](/agents-platform/deploy/telephony/customize-calls) for assignment and branch handling.
  </Step>
</Steps>

When a supported calling runtime is available, test inbound and outbound directions independently with authorized test numbers. Check answer, two-way audio, hangup, failure handling, and provider records. See [troubleshooting](/agents-platform/deploy/telephony/troubleshooting).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does importing a SIP number provision a carrier trunk?">No. It saves configuration in Threetone. Carrier provisioning and runtime connectivity require separate verification.</Accordion>
  <Accordion title="Can I use any listed outbound-call route after import?">No. Each route has its own provider and runtime requirements. A SIP import does not satisfy the managed PSTN and Twilio fulfillment requirements of the general outbound route.</Accordion>
</AccordionGroup>


# Telephony troubleshooting
Source: https://docs.threetone.in/agents-platform/deploy/telephony/troubleshooting

Isolate import, assignment, runtime, and provider failures without treating a saved phone number as a successful call.

Start with the operation that failed. Import validation, saved assignment, provider routing, and conversation execution are separate stages with different evidence.

## Diagnose the stage

| Symptom | Check next |
| - | - |
| Import rejects the request | Provider variant, required fields, routing identity, and workspace access. For Twilio, explicitly set `enable_sms: false` and omit `account_auth_token`. |
| Branch assignment fails | The number must have an assigned agent and the branch must belong to that agent. |
| Record exists but no call connects | Import does not provision or authenticate the provider. Confirm the released runtime and provider route before changing agent prompts. |
| General outbound route rejects the number | Check managed PSTN source and Twilio fulfillment requirements. Exotel and SIP records do not satisfy this route. |
| Runtime is unavailable | Check [current availability](/agents-platform/overview#current-availability), the selected version, and deployment readiness. Reimporting the number does not enable execution. |
| Cancellation fails | Inspect the cancellation result and required provider identifiers. Do not assume service or provider billing has stopped. |

## Inspect saved configuration first

<Steps>
  <Step title="Read the phone record">
    Use [Get phone number](/api-reference/agents-platform/get-phone-number). Compare the identifier, assignment, environment, and trunk details with your intended deployment. Record safe identifiers and the request error code.
  </Step>

  <Step title="Check recent changes">
    A supplied `agent_id` without `branch_id` clears the old branch selection. An explicit null branch also removes it. Review [assignment rules](/agents-platform/deploy/telephony/customize-calls) before applying another update.
  </Step>

  <Step title="Review provider evidence when a runtime is available">
    Compare the authorized test call's timestamp, direction, provider call ID, response status, and routing destination. If signaling succeeds but audio fails, inspect the negotiated media settings and network path rather than assuming successful signaling proves two-way audio.
  </Step>
</Steps>

For a carrier-side SIP issue, use the provider's current diagnostics, such as [Twilio's trunk troubleshooting](https://www.twilio.com/docs/sip-trunking/troubleshooting). Keep signaling credentials, access tokens, and customer transcripts out of public reports. Avoid repeated outbound retries until you know whether an earlier attempt created a call.

## Prepare a useful support report

Include the operation, redacted error, workspace and phone-number identifiers, agent and branch identifiers, timestamp with time zone, and expected routing behavior. State whether the failure occurred before provider contact, during signaling, or after answer. Include a provider call ID only when an actual provider attempt exists.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does configured SIP status mean the carrier accepted my credentials?">No. It reflects stored configuration. Import does not perform a live authentication or connectivity check.</Accordion>
  <Accordion title="Should I keep retrying an outbound request after a timeout?">First establish whether the previous request created a call. A blind retry can create duplicate attempts once calling is available.</Accordion>
</AccordionGroup>


# Twilio with a custom model
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/custom-model-integration

Review the separate model, speech, and telephony contracts required for a future Twilio deployment with a custom language model.

A custom language-model endpoint answers model requests. It does not receive telephone audio or supply a Twilio media bridge.

<Note>
  Threetone supports a dashboard connection probe for a custom model candidate. Custom-model publication is currently rejected, and Twilio calling has separate runtime requirements. A successful model probe does not release either path.
</Note>

## Prepare the integration design

Collect the model base URL and model ID, credential reference, desired phone route, and an owner for each service. Use [custom models](/agents-platform/advanced/custom-models/overview) for the supported probe and draft workflow.

<Steps>
  <Step title="Check the model contract">Review [endpoint compatibility](/agents-platform/advanced/custom-models/compatible-endpoints), including streaming responses and tool behavior. Record probe failures separately from any telephony findings.</Step>
  <Step title="Choose the media boundary">Decide whether the future runtime will receive SIP media or implement a provider-specific streaming bridge. Do not point a Twilio stream at a Chat Completions endpoint.</Step>
  <Step title="Specify the conversation lifecycle">Document how the bridge will handle audio conversion, transcription, synthesized speech, interruptions, silence, and caller hangup. Define the result when the model times out or the media connection closes.</Step>
  <Step title="Keep release checks independent">Require an executable custom-model version, supported credential delivery, a released media adapter, and the phone route's acceptance evidence before moving traffic.</Step>
</Steps>

Twilio distinguishes receive-only Media Streams from bidirectional streams. The latter uses `Connect` with `Stream` and blocks subsequent TwiML until the connection disconnects. Those provider capabilities do not establish a Threetone WebSocket endpoint. See [Twilio Media Streams](https://www.twilio.com/docs/voice/media-streams).

## Failure handling

Plan a bounded model timeout and a caller-facing fallback. Keep provider call IDs, model request IDs, and your application correlation ID separate so a model error is not misreported as a carrier failure. Do not retain audio or transcripts without a reviewed purpose and retention policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I publish after the connection probe succeeds?">No. Current publication rejects custom model execution. Preserve the reviewed candidate as a draft.</Accordion>
  <Accordion title="Can a receive-only stream speak back to the caller?">No. Twilio's unidirectional stream cannot play application audio back. A supported bidirectional integration would need a separate media implementation.</Accordion>
</AccordionGroup>


# Twilio native integration
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/native-integration

Prepare the supported Twilio phone import and identify the credential, routing, and execution checks required before calling.

Twilio phone records can be imported today. A complete calling integration still requires credential handoff, a configured runtime route, and an executable agent version. See [current availability](/agents-platform/overview#current-availability).

## Before you begin

Prepare a Twilio number you control, its workspace label, and credentials belonging to the intended account. Confirm whether your design uses Programmable Voice or Elastic SIP Trunking; they have different routing configuration. Start with [Twilio's SIP documentation](https://www.twilio.com/docs/sip-trunking) for trunk-based designs.

## Prepare and inspect the import

<Steps>
  <Step title="Pair the credential fields">Use an Account SID with its Account Auth Token, or an API Key SID with its API Key Secret, in the import's sid and token fields. Do not mix the two pairs.</Step>
  <Step title="Apply the current restrictions">Set enable\_sms explicitly to false. Omit account\_auth\_token: the current validator rejects that field until webhook-signature credentials have a secure runtime handoff. The default SMS value is not usable.</Step>
  <Step title="Save the intended record">Use [Import phone number](/api-reference/agents-platform/import-phone-number) with the Twilio variant. Read back the resulting record and check its number, label, and agent assignment. Import does not authenticate Twilio or provision carrier resources.</Step>
  <Step title="Review the calling requirements">The outbound service requires managed PSTN with Twilio fulfillment, a platform-managed SIP trunk, and an executable agent configuration. Stored status alone does not satisfy these requirements. Keep an existing working route until a supported deployment passes acceptance checks.</Step>
</Steps>

## Known request limits

The current Twilio outbound handler accepts but ignores `call_recording_enabled`; do not use it to establish recording behavior. Carrier answering-machine-detection configuration is rejected. Review [call consent](/agents-platform/legal/call-consent) separately from configuration.

If import fails, check the credential pair and rejected fields first. If a later operation reports a provider or runtime error, repeated imports will not provision the missing runtime.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does API-key import finish inbound webhook authentication?">No. The separate webhook credential field is currently rejected, and runtime handoff remains a release requirement.</Accordion>
  <Accordion title="Will the imported number receive SMS conversations?">No. SMS must remain disabled. Read [SMS conversations](/agents-platform/deploy/telephony/twilio/sms-conversations) for the preparation boundary.</Accordion>
</AccordionGroup>


# Twilio regional routing
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/regional-routing

Prepare region-specific Twilio credentials and edge choices while distinguishing accepted configuration from deployed routing.

Use regional configuration to record the intended Twilio region and edge for a deployment review. Saving these fields does not move a running service or establish where every system processes data.

Twilio Regions and Edge Locations serve different purposes. Region-specific credentials differ from the default region's credentials; an edge selects an entry or exit location. See [Twilio's regional usage documentation](https://www.twilio.com/docs/twilio-cli/general-usage/regional).

## Accepted configuration

The current Threetone `region_config` requires `region_id`, `token`, and `edge_location` when supplied.

| Field | Current request values |
| - | - |
| `region_id` | `us1`, `ie1`, `au1` |
| `edge_location` | `ashburn`, `dublin`, `frankfurt`, `sao-paulo`, `singapore`, `sydney`, `tokyo`, `umatilla`, `roaming` |
| `token` | Regional Auth Token for the intended account and region. |

These enums are an input contract. They do not certify every combination or automatically accept regions added by the provider.

## Review a regional route

<Steps>
  <Step title="Identify the region owner">Confirm the account, number, and intended regional resources with your Twilio administrator. Avoid combining a regional endpoint with credentials from another region.</Step>
  <Step title="Match the accepted fields">Compare the proposed values with [Import phone number](/api-reference/agents-platform/import-phone-number). Keep enable\_sms false and omit account\_auth\_token as required by the [Twilio import guide](/agents-platform/deploy/telephony/twilio/native-integration).</Step>
  <Step title="Review runtime delivery">Document how the future runtime will receive the regional credentials and choose its endpoints. Import redacts credential metadata; saving the regional token does not demonstrate usable secret delivery.</Step>
  <Step title="Plan regional acceptance checks">When the runtime is supported, verify the selected route in provider records and measure signaling and media separately. Keep a known fallback and document how it will be restored.</Step>
</Steps>

For an authentication failure, verify the account and regional credential pair before changing network routes. For latency, inspect the complete caller-to-runtime path rather than assuming the nearest edge resolves every delay.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use any region supported by Twilio?">Only the current schema's region values are accepted. Provider support can be broader than the Threetone request contract.</Accordion>
  <Accordion title="Does a saved region provide a data-residency guarantee?">No. Review the actual provider, application, model, logging, and storage paths and the applicable agreements separately.</Accordion>
</AccordionGroup>


# Register a Twilio call
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/register-call

Understand the current register-call response and prepare a future call handoff without configuring an unavailable webhook.

Call registration would connect an existing provider call to the intended agent session. It is different from importing a number or initiating a new outbound call.

<Warning>
  The current [Register Twilio call](/api-reference/agents-platform/register-twilio-call) handler returns HTTP 501. It does not generate usable TwiML or start media execution. Do not configure it as a live Twilio number's voice webhook.
</Warning>

## Prepare the handoff

Identify the number owner, call direction, target workspace and agent, and the existing route that should remain active. Keep a record of the provider-side call identifier without including credentials.

<Steps>
  <Step title="Review the future request boundary">The declared request includes agent, caller, destination, direction, and optional conversation initiation data. Validate these against the selected workspace and version rather than trusting caller-supplied values.</Step>
  <Step title="Separate the two HTTP contracts">Twilio's webhook contract and the Threetone registration request are not interchangeable merely because both concern a call. A released integration must document request authentication, field mapping, and the exact response.</Step>
  <Step title="Specify failure behavior">Decide what the caller hears if registration fails, how the existing route is preserved, and who owns termination. Avoid retrying a non-idempotent registration without checking whether a session was created.</Step>
  <Step title="Require release evidence">Before changing carrier configuration, require a supported handler, documented webhook credential handoff, usable call instructions, and a successful authorized test of answer, audio, and hangup.</Step>
</Steps>

Twilio uses [TwiML instructions](https://www.twilio.com/docs/voice/twiml) to control Programmable Voice calls. A declared HTML response type in an API schema is not evidence that a working instruction document will be returned.

## Failure handling

Treat the current 501 response as an implementation boundary. Rotating credentials or retrying it cannot enable the handler. Route support questions with the operation name and response status, keeping secrets and full caller details out of the report.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does number import enable registration?">No. Import saves a phone record. Registration remains unimplemented.</Accordion>
  <Accordion title="Can I use registration to place a new outbound call?">No. Outbound initiation is a separate operation with its own provider and runtime gates. See [Twilio native integration](/agents-platform/deploy/telephony/twilio/native-integration).</Accordion>
</AccordionGroup>


# Twilio SMS conversations
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/sms-conversations

Prepare message routing, identity, retries, and delivery handling for a future SMS channel without enabling unsupported workspace routing.

Workspace SMS conversations are not enabled by phone import. The current Twilio validator requires `enable_sms: false`. This guide describes the decisions needed for a future channel; it does not provide an active Threetone messaging webhook.

## Before you begin

Identify the sending number or Messaging Service, intended audience, application owner, and the policy for consent and opt-out requests. Confirm the provider requirements for your destinations with the account owner. A voice number and a verified phone number do not by themselves establish permission to send messages.

## Prepare the message flow

<Steps>
  <Step title="Define the incoming contract">Twilio sends form-encoded webhook data, including MessageSid, From, To, and Body. Plan provider signature validation using the provider's supported library and keep the external request separate from your internal conversation record.</Step>
  <Step title="Define conversation identity">Choose how workspace, receiving number, sender, and inactivity affect conversation boundaries. Use MessageSid to identify duplicate delivery rather than creating a second assistant reply.</Step>
  <Step title="Separate receipt from delivery">Specify the webhook response and the outbound sending workflow independently. Twilio expects TwiML for its incoming message webhook. A received webhook does not prove that a reply reached the handset.</Step>
  <Step title="Prepare release tests">Include duplicate messages, delayed status callbacks, unsupported attachments, opt-out requests, provider rejection, and an unavailable agent. Keep provider routing on its existing destination until a supported receiver is released.</Step>
</Steps>

See [Twilio's incoming message webhook reference](https://www.twilio.com/docs/messaging/guides/webhook-request) for the provider request and response contract.

## Failure handling

Record message identifiers and delivery states without putting message bodies or secrets in routine logs. Bound retries and check the original send result before attempting another reply. An unknown delivery result should not trigger an unlimited resend loop.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I enable SMS by changing the import flag?">No. Setting enable\_sms to true is rejected by the current API.</Accordion>
  <Accordion title="Does the demo verification flow provide an SMS agent?">No. [SMS verification](/agents-platform/deploy/telephony/twilio/sms-verification) checks a code for a specific demo flow; it is separate from conversational messaging.</Accordion>
</AccordionGroup>


# Twilio SMS verification
Source: https://docs.threetone.in/agents-platform/deploy/telephony/twilio/sms-verification

Distinguish the website demo's phone verification from workspace SMS, and prepare bounded code verification and failure handling.

Threetone's website demo has a dedicated Twilio Verify flow. It sends a code and checks approval before proceeding with a demo-call request. This is not a public workspace verification API, an SMS conversation channel, or proof that calling is available for your deployment.

## Prepare an application verification flow

For a separate application, identify the action being protected, the server responsible for verification, and the provider account owner. Use [Twilio Verify's Service, Verification, and Verification Check model](https://www.twilio.com/docs/verify/api). Do not copy demo-only routes into an application integration.

<Steps>
  <Step title="Bind the intended action">Associate the destination and verification attempt with the application request. A checked phone code should not grant access to unrelated workspaces or actions.</Step>
  <Step title="Bound code delivery">Validate the destination before sending. Define cooldowns and attempt limits on the server, and display retry timing in the interface. Keep provider credentials and verification requests server-side.</Step>
  <Step title="Check the result">Continue only after the provider approves the verification. Handle expired, incorrect, and exhausted codes explicitly. Do not treat a successful send response as a successful check.</Step>
  <Step title="Handle the protected action separately">A later call can fail even after verification succeeds. Keep code status, action authorization, and call status distinct so the user receives an accurate result.</Step>
</Steps>

## Existing demo behavior

The demo checks phone and IP eligibility, applies send limits, and can return retry timing. Its call flow requires the code check to succeed and has separate configuration and execution requirements. Keep OTP values out of logs, screenshots, and support tickets.

For a failed attempt, distinguish invalid destination, send cooldown, wrong or expired code, and downstream call failure. Do not resend automatically after every error.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does verification enable SMS on an imported number?">No. Workspace SMS routing remains disabled. Verification is a separate provider workflow.</Accordion>
  <Accordion title="Does an approved code establish consent for future calls?">Do not treat it as a substitute for reviewing the intended use, consent records, and applicable requirements. See [call consent](/agents-platform/legal/call-consent).</Accordion>
</AccordionGroup>


# Versions and drafts
Source: https://docs.threetone.in/agents-platform/deploy/versioning

Use explicit branches, review draft snapshots, and publish identifiable agent configuration versions without confusing them with deployment.

An agent has branches and published configuration versions. Use a draft to prepare a complete change, then review what will be published to the selected branch. Configuration publication and live traffic deployment are separate operations.

<Warning>
  Voice and custom-model configurations can be authored, but cannot be published in the current implementation. Managed text-only publication requires compatible model routing, referenced resources, and a valid workflow. Branch creation, merge, and rebase also validate publication eligibility. An initial version created with an agent does not establish the same runtime readiness as a later validated publication.
</Warning>

<Frame>
  <img alt="Recording pending for Review and publish a configuration version. No playable video is available yet." />
</Frame>

## Know the identifiers

| Identifier | What it identifies |
| - | - |
| `agent_id` | The agent resource. |
| `branch_id` | The branch you are reading, editing, or publishing. |
| `version_id` | A published configuration snapshot. |

[Create agent](/api-reference/agents-platform/create-agent) returns `agent_id`, `main_branch_id`, and `initial_version_id`. Keep these identifiers when creating subsequent requests.

## Dashboard working copy

The editor keeps a local working copy while you edit. Review its changes against the latest published version before selecting **Publish**. In **Review Changes**, confirm the branch, add a **Commit message**, and publish the reviewed diff.

A local working copy is not the same resource as a server draft created through the API. Do not assume an unsubmitted editor change is available to another teammate or integration.

## API workflow

<Steps>
  <Step title="Select the branch">
    Read the agent and identify the intended branch. To create a branch, provide `name`, `description`, and `parent_version_id` through [Create agent branch](/api-reference/agents-platform/create-agent-branch).
  </Step>

  <Step title="Prepare the complete draft">
    Use [Create agent draft](/api-reference/agents-platform/create-agent-draft) with an explicit `branch_id` query parameter. A draft is a configuration snapshot containing the agent name, `conversation_config`, `platform_settings`, and `workflow`.

    Start from the selected version and preserve fields you are not changing. Do not treat a complete draft snapshot as a small partial patch.
  </Step>

  <Step title="Review before publication">
    Compare the draft with the branch's current published configuration. Review models, knowledge, tool references, and workflow changes as well as the prompt.

    When combining branch changes, inspect [merge preview](/api-reference/agents-platform/preview-merged-configuration) or [rebase preview](/api-reference/agents-platform/preview-rebased-configuration) before applying them.
  </Step>

  <Step title="Publish and read back">
    Use [Update agent](/api-reference/agents-platform/update-agent) with an explicit `branch_id` query parameter and a useful `version_description`.

    To commit the saved server draft, send a body containing only `version_description`. A request containing other configuration fields publishes those submitted changes from the branch's published tip; it does not commit the saved draft. Review which workflow you intend before sending the request.

    Read the agent and [version metadata](/api-reference/agents-platform/get-agent-version-metadata) back. Confirm the branch, resulting version, and reviewed settings.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for Review Changes with a sample configuration diff and the selected branch. This illustration is not a product screenshot." />
</Frame>

<Note>
  Traffic deployment is currently gated in the documented implementation. Publishing a configuration version does not route live conversations to it. See [current availability](/agents-platform/overview#current-availability).
</Note>

## Discarding and reconciling changes

Use [Delete agent draft](/api-reference/agents-platform/delete-agent-draft) to remove the server draft for the selected branch. Dashboard **Discard changes** operates on the editor's working copy. Check which kind of draft you are changing before discarding it.

If the published version changes while you edit, review the newer version and reconcile your pending changes before publication. Keep a short version description that explains the intended behavior rather than listing only the fields changed.

## Review checklist

Confirm the workspace and branch, inspect the complete diff, check referenced resources, and read the published version back. Retain the agent, branch, and version IDs with any later runtime test evidence so you can identify exactly which configuration was assessed.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is the editor working copy a server draft?">No. The editor keeps local pending changes. An API server draft is a separate stored resource on a selected branch.</Accordion>
  <Accordion title="How do I commit the saved server draft?">Select branch\_id explicitly and send a PATCH body containing only version\_description. Other configuration fields publish submitted changes from the branch tip.</Accordion>
  <Accordion title="Does a published version allocate live traffic?">No. A version identifies saved configuration. Traffic allocation and runtime execution require a separate supported path.</Accordion>
</AccordionGroup>


# JavaScript SDK
Source: https://docs.threetone.in/agents-platform/deploy/web/javascript

Prepare a framework-independent browser integration with explicit initialization, event cleanup, and supported session access.

Use this page to plan an agent interface in a plain JavaScript application. There is no verified public Threetone browser SDK package, CDN script, or installation command in the current documentation.

## Prepare the browser boundary

Keep workspace API keys on a trusted server. The future client integration needs an authoritative package or script, a supported session-access flow, and a documented message contract. A browser `fetch` call to a resource endpoint is not a conversation transport.

<Steps>
  <Step title="Choose a single initialization point">
    Decide which page controller owns the interface. On applications that navigate without a full reload, define how entering and leaving a route mounts and disposes that controller. Prevent duplicate script loads and duplicate event listeners.
  </Step>

  <Step title="Design start and end controls">
    Use explicit visitor actions. Disable repeated starts while connecting, show a useful error on failure, and make ending the interaction available throughout an active session. Keep a fallback contact route outside the interface.
  </Step>

  <Step title="Plan resource cleanup">
    List each subscription, timer, network connection, and media resource the interface owns. Connect cleanup to the released client API and the page controller's disposal. Confirm that ending or leaving the page stops owned audio and event processing.
  </Step>
</Steps>

For voice, browser microphone access requires a secure context and permission. Handle a denied request and unavailable hardware as ordinary interface states. Review [browser microphone requirements](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) before testing an embedded voice interface.

## Before installing a release

Verify the exact distribution origin, versioning policy, export names, supported browsers, and session initialization contract. Test loading failures, slow connections, access expiry, repeated navigation, and cleanup. If an integration uses a socket, follow the released protocol rather than guessing a URL from REST endpoints; see [WebSocket preparation](/agents-platform/deploy/server/websockets).

Use the [TypeScript server example](/agents-platform/resources/sdks/typescript) for supported resource reads and [widget preparation](/agents-platform/deploy/web/widget) for an embedded interface.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is there a CDN script I can paste into any page?">No verified production script is supplied here. Use only the distribution URL documented by a released Threetone widget or client package.</Accordion>
  <Accordion title="Can I rename an internal event and use it in my application?">Only a released client event contract defines supported messages and behavior. Internal event names are not a stable integration contract.</Accordion>
</AccordionGroup>


# Web deployment
Source: https://docs.threetone.in/agents-platform/deploy/web/overview

Prepare browser session access, interface lifecycle, and hosting requirements before a supported widget release.

Web deployment places an agent interface in a website. The website needs a released widget or client contract and a working session path, not just a script bundle.

## Prepare the deployment

Keep workspace API keys on your server. Define the browser's session-access scope, expiry, allowed origin, and ownership rules against the released runtime. Review [authentication](/agents-platform/configure/authentication/overview) before exposing the interface.

The current dashboard widget preview references a legacy script origin or a separate local script server. Signed-token session initiation is also gated. These facts do not establish a production embed URL that customers should copy.

## Integration checks

| Check | Required result |
| - | - |
| Assets | Documented script/package origin, version, and loading policy. |
| Session | Supported creation, authorization, expiry, and conversation ownership. |
| Permissions | Appropriate microphone access and clear permission-denied states where voice is supported. |
| Lifecycle | No duplicate interface after navigation; cleanup releases owned resources. |
| Accessibility | Usable keyboard controls, focus, readable transcript, and error announcements. |

Use [website-builder preparation](/agents-platform/guides/no-code/overview) for Webflow and WordPress planning, and [UI resources](/agents-platform/resources/ui-components) for component-release requirements.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where is the production embed snippet?">A verified end-to-end production widget release is not established here. Add the snippet after the script origin, access design, and runtime have been validated.</Accordion>
</AccordionGroup>


# React SDK
Source: https://docs.threetone.in/agents-platform/deploy/web/react

Prepare a React integration with server-owned access, explicit session ownership, and cleanup while the public SDK release is pending.

A React integration needs a released client package and session contract. A verified public Threetone React SDK, package version, and installation recipe are not established here. You can prepare the application boundary and interface states now.

## Separate server and browser responsibilities

| Responsibility | Owner |
| - | - |
| Workspace API key and resource requests | Your trusted server. |
| User authorization for the intended agent | Your application server and the released session-access mechanism. |
| Start, end, permission prompts, and visible status | The browser interface. |
| Connection protocol and accepted events | The released client and runtime contract. |

For supported server resource reads, use the [TypeScript example](/agents-platform/resources/sdks/typescript). Keep that workspace credential out of client components, public environment variables, serialized props, and browser requests.

## Prepare the React lifecycle

<Steps>
  <Step title="Choose a session owner">
    Decide which component or application service owns an active session. Keep rerenders and route changes from accidentally creating a second connection. Begin an interaction through a deliberate user action with a clear pending state.
  </Step>

  <Step title="Pair subscriptions with cleanup">
    Once the client contract exists, attach its event subscriptions to the owning lifecycle and remove them during cleanup. React runs effect cleanup before a changed setup and on unmount; development Strict Mode also tests an extra setup-and-cleanup cycle. See [React's effect reference](https://react.dev/reference/react/useEffect).
  </Step>

  <Step title="Represent failures explicitly">
    Design idle, connecting, active, interrupted, and ended states. Prevent repeated start clicks from creating duplicate work. Show permission denial and expired access distinctly from a normal end.
  </Step>
</Steps>

## Release checks

When an official SDK is available, verify the package origin, supported React versions, event types, session access, and cleanup API. Test route transitions, development remounts, network loss, and session end against the real runtime. Do not suppress cleanup or disable development checks to hide duplicate connections.

Use [React components](/agents-platform/deploy/web/react-components) to prepare presentation and [the widget guide](/agents-platform/deploy/web/widget) if a managed embed is a better fit.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I install the dashboard's React components as an SDK?">Private application components do not establish a supported public package or transport. Wait for the documented release and installation contract.</Accordion>
  <Accordion title="Can I use the TypeScript resource example directly in a client component?">No. That example uses a workspace API key and belongs on a trusted server. Browser session access requires its own released mechanism.</Accordion>
</AccordionGroup>


# React components
Source: https://docs.threetone.in/agents-platform/deploy/web/react-components

Design accessible agent controls and transcript states while the public component package and client transport remain pending.

Prepare the presentation of an agent interface independently from its connection code. A verified public Threetone React component package and installation contract are not available in this documentation.

## Define the component responsibilities

| Interface element | Required behavior |
| - | - |
| Start control | Explain the action, show pending state, and prevent duplicate starts. |
| Connection status | Distinguish connecting, active, interrupted, and ended without relying on color alone. |
| Transcript | Keep speaker attribution and text readable; distinguish partial content from confirmed content when the released event contract supports that distinction. |
| Voice controls | Give mute and end actions accessible names and clear current states. |
| Error message | Explain the next useful action and preserve a fallback route. |

Do not invent a transcript event, mute method, or component prop while the public contract is pending. Record the data each element needs, then map it to the released types when they become available.

## Prepare the interface

<Steps>
  <Step title="Start with ordinary controls">
    Use semantic buttons, readable labels, visible focus, and a predictable tab order. Avoid clickable decorative artwork or controls that appear enabled before a supported action exists.
  </Step>

  <Step title="Separate display state from session ownership">
    Let one owner manage the connection and supply state to the presentation. Follow [React integration preparation](/agents-platform/deploy/web/react) for subscription and cleanup responsibilities. Keep keys and server-only configuration out of props sent to the browser.
  </Step>

  <Step title="Review failure and narrow-screen states">
    Check long transcripts, language direction, permission denial, expired access, and disconnected state. Important controls should remain usable when the interface expands or the on-screen keyboard appears.
  </Step>
</Steps>

Before release, test with keyboard navigation and assistive technology. Announce meaningful status changes without repeatedly reading every streamed token. Verify focus behavior when the interface opens, closes, or reports an error.

The eventual package must document styling boundaries, supported React versions, transport compatibility, and cleanup behavior. See [UI resources](/agents-platform/resources/ui-components) and [current availability](/agents-platform/overview#current-availability).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a working mock transcript prove the component is ready?">It verifies presentation for that sample. Real event delivery, authorization, input handling, and cleanup still need tests against a released runtime.</Accordion>
  <Accordion title="Should the component start a session whenever it renders?">No. Rendering can happen repeatedly. Use explicit session ownership and the released client's lifecycle contract.</Accordion>
</AccordionGroup>


# Widget
Source: https://docs.threetone.in/agents-platform/deploy/web/widget

Prepare widget appearance, access, and browser acceptance checks before installing a supported production embed.

A widget gives visitors an agent interface inside your website. You can review its saved configuration now; a production installation also needs a released embed asset and a working conversation runtime.

<Note>
  A supported production script URL and end-to-end widget session are not established by the current release. The dashboard preview is not an installation contract. Do not copy a development script or expose a workspace API key in page code.
</Note>

## Prepare the configuration

<Steps>
  <Step title="Choose the agent and audience">
    Record the workspace, agent, intended branch, and pages where the interface should appear. Review [authentication](/agents-platform/configure/authentication/overview), including public access and allowed origins, before planning an anonymous visitor experience.
  </Step>

  <Step title="Review the saved appearance">
    Inspect `platform_settings.widget` in the saved agent configuration. It includes placement, colors, avatar, labels, transcript visibility, and feedback options. Check text contrast and use labels that describe the action clearly.

    A saved option describes the desired interface. Verify that the released widget implements it before relying on it in your site.
  </Step>

  <Step title="Choose an installation location">
    Reserve space for the expanded interface and a fallback contact link. On sites with client-side navigation, plan one widget instance and cleanup when its owner unmounts. For builders, use the [no-code guides](/agents-platform/guides/no-code/overview).
  </Step>
</Steps>

The separate [Get agent widget configuration](/api-reference/agents-platform/get-agent-widget-configuration) route requires a valid, unexpired `conversation_signature`; a workspace API key alone does not authorize that read. Signature issuance remains tied to the gated session path, so this route is not a general configuration-read shortcut.

## Before a public launch

| Check | Evidence to collect |
| - | - |
| Release | Authoritative asset URL, version, installation instructions, and supported browsers. |
| Session access | Successful authorized start, expiry handling, and rejection of access outside the intended scope. |
| Visitor controls | Keyboard access, visible focus, readable errors, and a clear end action. |
| Audio | Permission denial, absent microphone, interruption, and resource cleanup on end. |
| Navigation | No duplicate widget, lingering audio, or stale session after changing pages. |

Browser microphone access requires a secure context and user permission. Embedded contexts also need the correct permission policy; a rendered iframe alone does not prove microphone access. See [the browser microphone reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does the widget endpoint return 401 with an API key?">The route requires a valid conversation\_signature. An API key does not replace that signature, and the read does not return a production embed script.</Accordion>
  <Accordion title="Can I enable text mode to bypass the runtime requirement?">No. A text interface still needs a supported session and message transport. A saved text-mode setting does not create that transport.</Accordion>
</AccordionGroup>


# Connect an account
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/connect-account

Use the enabled Meta authorization workflow to connect a WhatsApp Business account, inspect registration, and review saved settings.

Connect only the business account and phone intended for the selected Threetone workspace. This guide ends with an inspected account connection and saved preferences. It does not send a message or make a call.

## Before you begin

Open Threetone over HTTPS, select the intended workspace, and use an account permitted to manage the connection. Have access to the WhatsApp Business account you intend to authorize. The deployed dashboard must have Meta Embedded Signup enabled and configured. Allow its authorization popup to open.

<Note>
  If **Import account** is disabled, check the workspace, deployment configuration, and whether the authorization SDK has loaded. Do not paste a provider token into another settings field to bypass a disabled import workflow.
</Note>

<Frame>
  <img alt="Recording pending for WhatsApp account setup. No playable video is available yet." />
</Frame>

## Authorize and inspect

<Steps>
  <Step title="Start the account flow">
    Open [WhatsApp accounts](https://threetone.in/app/agents/whatsapp) and select **Import account**. Check the selected workspace before continuing.
  </Step>

  <Step title="Review the Meta authorization">
    Follow the provider popup, select the intended business account and phone, and review the requested access. Finish the supported authorization flow. Do not copy its authorization code or a provider token into a prompt, support message, or recording.
  </Step>

  <Step title="Read the account back">
    Return to the account list and open the connected phone's entry. Confirm the business account, phone number, and registration status. If the completion result was uncertain, refresh and inspect the list before starting another import.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for WhatsApp account details and registration status. This illustration is not a product screenshot." />
</Frame>

## Review registration and authorization

The status badge distinguishes **Phone registered**, **Registering phone**, **Registration unconfirmed**, **Registration needs attention**, and **Registration not checked**. **Authorization expired** takes precedence when the stored authorization has expired.

Use **Account actions > Refresh registration status** to inspect registration. **Retry phone registration** is offered for an unconfirmed or action-required state. Follow any returned error and inspect the refreshed account. A registration retry does not restore expired authorization or start agent execution.

The **WhatsApp Manager** action opens the provider's account management interface. Review provider-owned account details there rather than inferring them from a Threetone status badge.

## Save the intended account settings

Use **Agent** to select the intended saved agent or **No agent**. The selection saves the assignment immediately. Reopen the account to confirm it.

The **Messaging preferences** section currently saves these future preferences:

* **Enable messaging** records whether the assigned agent should respond when messaging becomes available.
* **Enable audio message response** records whether future audio-message replies should use audio.
* **Enable typing indicator** records the requested future read/typing feedback.

These switches store account settings. They do not enable a working channel today. See [Messaging and calls](/agents-platform/deploy/whatsapp/messaging-and-calls) before planning an execution test.

## Disconnect deliberately

Inspect dependencies and the phone's use by other providers before using **Account actions > Delete account**. Review the confirmation's described Cloud API disconnection and connection removal before proceeding. Threetone's account removal does not mean that the WhatsApp Business Account, phone number, or message history is deleted from Meta.

If removal returns an uncertain provider outcome, inspect the account and resolve that state before reimporting. Keep provider account management separate from local resource cleanup.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why is Import account unavailable?">The workflow needs a selected workspace, valid deployment signup configuration, a loaded authorization SDK, and HTTPS. Check those prerequisites and the current release before retrying.</Accordion>
  <Accordion title="Does assigning an agent start incoming responses?">No. The assignment is saved configuration. Incoming handling needs its own released and verified message or call runtime.</Accordion>
  <Accordion title="Can I repeat the import after an unclear result?">Refresh the account list and inspect the saved registration and authorization state first. Avoid treating an uncertain result as proof that nothing was created.</Accordion>
</AccordionGroup>


# Interactive messages
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/interactive-messages

Prepare reply choices and template buttons with stable identifiers and clear limits on the current WhatsApp schema.

Interactive choices can make a support flow clearer, such as asking a customer to select delivery, returns, or an existing order. Design the choice and its resulting action together.

<Note>
  Interactive sending and reply processing are not released in Threetone. The outbound template schema has button components, but the route returns HTTP `501`. It does not expose Meta's full interactive-message API.
</Note>

## Distinguish provider formats

Meta documents [interactive templates](https://www.postman.com/meta/whatsapp-business-platform/request/lwtlz1k/send-message-template-interactive) separately from [list messages](https://www.postman.com/meta/whatsapp-business-platform/request/jze7gxt/send-reply-to-list-message). A template button and a free-form interactive list are different request shapes.

Threetone's `template_params` supports `header`, `body`, and `button` components. A button component contains `parameters`, `index`, and `sub_type`. The open string `sub_type` is not proof that every provider subtype is implemented.

## Prepare a choice flow

Have an approved template or proposed message design, a supported language, and an owner for each action behind a choice.

<Steps>
  <Step title="Write distinct choices">
    Keep labels short and unambiguous. Record the meaning of each choice in your application separately from its translated label. Confirm which format and provider limits apply before preparing payloads.
  </Step>

  <Step title="Bind a reply to its original question">
    Plan to validate the sender, original message, and choice identifier together. Reject unknown choices and explain when a previous menu has expired. A display label alone should not select a customer record or authorize a tool.
  </Step>

  <Step title="Handle repeats and changes of mind">
    Define what happens when a user taps twice, replies with text, or selects an older menu. Deduplicate repeated deliveries. For purchases, cancellations, or external messages, show the resolved details and require the appropriate confirmation before mutation.
  </Step>
</Steps>

Keep these cases with your [outbound preparation](/agents-platform/deploy/whatsapp/outbound). The result is a reviewed interaction design; reply routing still needs a released channel implementation.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I send a Meta list payload through template_params?">Do not assume compatibility. The committed Threetone field accepts template components, not an arbitrary provider message object.</Accordion>
  <Accordion title="Does tapping a button authorize a sensitive action?">A choice is input. Your application must still verify identity, resource access, current state, and any required confirmation.</Accordion>
</AccordionGroup>


# Messaging and calls
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/messaging-and-calls

Prepare WhatsApp messaging and calling requirements without treating account setup or saved preferences as released execution.

Threetone plans to support WhatsApp conversations. Account authorization, phone registration, agent assignment, message processing, and calling must work together before the channel can be used with customers.

<Note>
  The documented outbound message and call endpoints currently return HTTP 501. This page describes preparation and release requirements. It is not a working send-message or call tutorial.
</Note>

## Messaging preparation

Before a messaging release, define the supported incoming and outgoing message types, template and language handling, delivery status, conversation continuity, and failure behavior. Confirm the provider's current consent and template requirements for the intended use. Do not assume that an approved account or a saved preference grants every messaging capability.

Keep tool credentials out of message content and prompts. Review [personalization](/agents-platform/configure/personalization/dynamic-variables) and [knowledge](/agents-platform/configure/knowledge-base/overview) against the data the channel is allowed to use. Stored example values do not demonstrate live variable substitution.

## Calling preparation

Before a calling release, verify the supported direction, provider permissions, phone registration, agent speech configuration, caller identity, connection failures, and stored call records. A phone usable for messaging is not automatic proof of calling access.

Record the exact agent version and provider account used in a controlled test. Confirm the result through the supported provider and conversation records before claiming that a call connected or an external action completed.

## Release checks

| Check | Evidence required before a working walkthrough |
| - | - |
| Account access | Intended workspace, provider account, phone, and valid authorization. |
| Registration | Confirmed phone registration or an explicit supported provider state. |
| Incoming handling | Verified event ingestion, duplicate handling, routing, and conversation ownership. |
| Outgoing messages | Verified provider submission, delivery outcomes, and safe handling of retries and uncertain results. |
| Calls | Verified permissions, session initiation, connection, termination, and saved records. |
| Settings | Demonstrated enforcement of enabled messaging and other released preferences. |

The existing public API reference includes [outbound messages](/api-reference/agents-platform/send-outbound-message-via-whatsapp) and [outbound calls](/api-reference/agents-platform/start-outbound-call-via-whatsapp). Schema presence does not establish working execution. Do not retry HTTP 501 as though it were a temporary delivery failure.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can enabling messaging make the current outbound endpoint work?">No. The preference stores future behavior. The current outbound implementation remains unavailable.</Accordion>
  <Accordion title="Is an account authorization enough for a call?">No. Provider calling permissions, phone state, agent configuration, and runtime execution must be verified separately for the released channel.</Accordion>
  <Accordion title="Where should I start today?">Review [account setup](/agents-platform/deploy/whatsapp/connect-account) if that workflow is enabled in the deployed dashboard, then prepare the configuration and controlled test cases for the future channel release.</Accordion>
</AccordionGroup>


# Outbound messages and calls
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/outbound

Prepare recipient, template, and call-permission data while distinguishing the public request contract from unavailable delivery.

Prepare one reviewed outbound request before designing bulk outreach. Keep the business phone, recipient, message purpose, and agent version together in the review.

<Note>
  Both outbound WhatsApp routes currently return HTTP `501`. Account registration and saved preferences can be reviewed, but they do not enable sending or calling. Do not retry `501` as a transient provider failure.
</Note>

## Review the request contract

You need an authorized [connected account](/agents-platform/deploy/whatsapp/connect-account), a controlled test recipient, and an approved reason to contact that person.

| Request | Fields to prepare |
| - | - |
| Message | `whatsapp_phone_number_id`, `whatsapp_user_id`, `agent_id`, `template_name`, `template_language_code`, `template_params` |
| Call | The same phone, recipient, and agent identifiers, plus `whatsapp_call_permission_request_template_name` and `whatsapp_call_permission_request_template_language_code` |
| Optional context | `conversation_initiation_client_data`; schema presence does not prove runtime substitution |

<Steps>
  <Step title="Verify the account and recipient">
    Read registration, authorization expiry, and agent assignment back. Confirm the exact recipient and the applicable provider permission requirements. A phone number copied from a record is not permission to contact its owner.
  </Step>

  <Step title="Review the template and language">
    Compare the intended text and parameter order with the provider's template. Meta's [template reference](https://www.postman.com/meta/whatsapp-business-platform/request/lwtlz1k/send-message-template-interactive) explains template components and button behavior. Review current template eligibility in the provider account. A message template does not establish permission to initiate a call.
  </Step>

  <Step title="Define submission and reconciliation">
    For a future released sender, record one application request identifier and retain the provider result. Separate queued, submitted, delivered, and failed outcomes. After an uncertain submission, reconcile before repeating it. Do not claim a Threetone idempotency header or delivery webhook that is not in the released contract.
  </Step>
</Steps>

Compare your review with the [message](/api-reference/agents-platform/send-outbound-message-via-whatsapp) and [call](/api-reference/agents-platform/start-outbound-call-via-whatsapp) reference pages. The current result is prepared request data, not a sent message or connected call.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a valid request body bypass the 501 response?">No. Validation and execution are separate. The provider execution path remains unimplemented.</Accordion>
  <Accordion title="Can I use this contract for bulk outreach?">Do not infer bulk execution from a single-request schema. Batch execution, recipient policy, per-recipient outcomes, and duplicate prevention require their own released workflow.</Accordion>
</AccordionGroup>


# WhatsApp
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/overview

Prepare a WhatsApp Business account connection, review phone registration and agent assignment, and understand planned messaging and calling.

WhatsApp is a planned conversation channel for Threetone agents. The current dashboard supports the account-connection and settings workflow when the deployment has Meta Embedded Signup configured. Account setup and conversation execution have separate availability requirements.

<Note>
  Outbound WhatsApp messages and calls currently return HTTP 501 in the documented implementation. Account registration and saved messaging preferences do not establish incoming message handling or working calls. This section covers account preparation and future channel requirements.
</Note>

## Choose a guide

<CardGroup>
  <Card title="Connect an account" icon="link" href="/agents-platform/deploy/whatsapp/connect-account">Authorize the intended business account, review phone registration, and save its agent assignment.</Card>
  <Card title="Messaging and calls" icon="comments" href="/agents-platform/deploy/whatsapp/messaging-and-calls">Review the planned channel and the checks required before sending messages or making calls.</Card>
</CardGroup>

## Account setup and runtime availability

| Area | Current documented behavior |
| - | - |
| Account authorization | A configured HTTPS dashboard can start Meta Embedded Signup and submit the authorized account to Threetone. |
| Phone registration | The account exposes a registration state, refresh action, and a retry action when available. |
| Agent assignment | Account settings can store the selected agent or No agent. |
| Messaging preferences | Settings store messaging, audio-response, and typing-indicator preferences for future support. |
| Outbound messages and calls | Provider execution is not implemented; the public routes return HTTP 501. |
| Incoming messages and calls | An account connection is not evidence of a verified incoming conversation workflow. |

Check both registration and authorization before preparing a channel test. A phone registration result confirms that particular registration step. It does not prove that an agent can receive, respond, or call.

## Prepare the agent

Review the intended agent's [configuration](/agents-platform/configure/overview), [language settings](/agents-platform/configure/voice-and-language/overview), and [tools](/agents-platform/configure/tools/overview). Keep its workspace and version identifiers with the account configuration. An assignment selects a saved resource; it does not release a runtime feature.

Use controlled account and customer data for future tests. Keep provider authorization codes, tokens, registration PINs, and credential values out of prompts, screenshots, and documentation.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I prepare an account before messaging is available?">Use the account setup workflow only when it is enabled in the deployed dashboard. You can review saved account settings separately from the unavailable conversation paths.</Accordion>
  <Accordion title="Does Phone registered mean the agent is live?">No. Registration, authorization, agent assignment, and runtime execution are separate checks.</Accordion>
  <Accordion title="Are message and call instructions available now?">The current outbound routes return HTTP 501. The [planned messaging and calls guide](/agents-platform/deploy/whatsapp/messaging-and-calls) records what must be verified before adding a working execution walkthrough.</Accordion>
</AccordionGroup>


# Tools in WhatsApp conversations
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/tools

Prepare narrowly scoped actions for a future WhatsApp channel without confusing sender identity, tool access, and confirmation.

Prepare one useful action, such as looking up an order's delivery status. Keep customer identity checks and business authorization in the service that owns the order.

<Note>
  Threetone can store tool definitions and agent references. A working WhatsApp conversation cannot execute them today. Account assignment, enabled messaging, and saved approval intent do not prove runtime enforcement.
</Note>

## Prepare an order-status action

You need a documented order service, a permitted test account, a workspace member allowed to manage tools, and an explicit rule for verifying the customer.

<Steps>
  <Step title="Define the minimum lookup">
    Return only the status and delivery information needed for the request. Do not return payment details or another customer's address. The service should resolve the authorized customer independently of the agent's generated arguments.
  </Step>

  <Step title="Keep channel identity separate from access">
    Plan how your application verifies the relationship between a WhatsApp sender and a customer account. Meta's [message-object reference](https://www.postman.com/meta/whatsapp-business-platform/folder/1dtuocp/messages-object) describes incoming message data; receiving a sender identifier does not grant permission to read private orders. Do not use an unverified phone-number match as the entire access check.
  </Step>

  <Step title="Save and review the tool contract">
    Follow [tool configuration](/agents-platform/configure/tools/overview) and use supported [credentials](/agents-platform/configure/authentication/auth-connections). Keep secrets out of chat messages and prompts. Review the saved tool and intended agent references through the eligible draft or version workflow.
  </Step>

  <Step title="Define failure and confirmation behavior">
    A failed lookup should report unavailable information without revealing whether another customer's order exists. Any later cancellation or address change needs a separate action that confirms the exact order and proposed change. Preserve action identifiers and reconcile uncertain results before retrying.
  </Step>
</Steps>

Your review should contain permitted inputs, a minimal result, denied-access behavior, and duplicate-request handling. It remains a configuration review until the [channel runtime](/agents-platform/deploy/whatsapp/messaging-and-calls) is released.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I put an order-service API key into a dynamic variable?">Do not put credentials into message text, prompts, or ordinary variable values. Use supported credential references in the applicable tool fields.</Accordion>
  <Accordion title="Can a saved approval policy replace a confirmation step?">No. The service performing the action must enforce authorization and the required confirmation. Stored policy alone does not demonstrate that behavior.</Accordion>
</AccordionGroup>


# WhatsApp troubleshooting
Source: https://docs.threetone.in/agents-platform/deploy/whatsapp/troubleshooting

Separate account setup, authorization, registration, saved preferences, and unavailable execution when diagnosing a WhatsApp issue.

Identify which operation failed before changing account settings. Setup problems and unavailable runtime paths need different responses.

<Note>
  Account setup has a current configuration workflow. Messaging and calling remain planned, and the outbound routes return HTTP `501`. Reconnecting an account does not implement those routes.
</Note>

## Start with the observed result

Have the workspace and phone identifiers, the attempted action, its time, and any error code. Exclude authorization codes, tokens, registration PINs, and customer message bodies from shared diagnostics.

| Symptom | Review next |
| - | - |
| Import account is disabled | Selected workspace, HTTPS, deployed Embedded Signup configuration, and authorization SDK readiness |
| Authorization expired | Account authorization state; a registration retry is not token renewal |
| Registration unconfirmed | Refresh registration status before repeating setup |
| Registration needs attention | Inspect the returned error and use the offered retry only after addressing its cause |
| Preferences save but no reply arrives | Preferences record future behavior; verify channel release availability |
| Outbound request returns `501` | Stop automatic retries; execution is not implemented |

<Steps>
  <Step title="Read the saved account">
    Follow [account setup](/agents-platform/deploy/whatsapp/connect-account). Confirm registration, `is_token_expired`, and `assigned_agent_id`. Check the selected workspace before concluding that a connection disappeared.
  </Step>

  <Step title="Resolve uncertain setup outcomes">
    Refresh the account list and inspect the record before importing again. Use **Refresh registration status** to check registration. Use **Retry phone registration** only when the current account offers it. Re-read the resulting state rather than relying on a success notification alone.
  </Step>

  <Step title="Escalate with bounded evidence">
    Record the operation, safe identifiers, response status, and whether the failure concerns setup or execution. For a future provider submission, preserve its message identifier and returned error. Do not report delivery from account registration or from local preference changes.
  </Step>
</Steps>

For later payload diagnosis, compare the selected operation with Meta's [official Cloud API reference collection](https://www.postman.com/meta/whatsapp-business-platform/collection/wlk6lh4/whatsapp-cloud-api) and Threetone's [outbound contract](/agents-platform/deploy/whatsapp/outbound). Their supported request shapes are not interchangeable.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I delete and reimport an account to fix a 501?">No. Deletion changes the account connection and may affect provider setup. It does not release outbound execution.</Accordion>
  <Accordion title="Does Phone registered prove delivery is healthy?">No. Registration, authorization, provider submission, delivery, and agent processing are separate states.</Accordion>
</AccordionGroup>


# API quickstart
Source: https://docs.threetone.in/agents-platform/get-started/api-quickstart

Authenticate, choose compatible models and a saved voice, and create an agent with the Threetone API.

This guide lists the voices saved in your workspace, creates an agent with a compatible voice ID, and reads the saved configuration back.

For the dashboard workflow, start with [Create your first agent](/agents-platform/get-started/first-agent). For key permissions, expiry, and rotation, read [API keys](/overview/administration/workspaces/api-keys).

<Note>
  This guide creates a configuration and its initial version. Creation validates authoring structure; it does not compile or prove a working runtime. Later voice and custom-model publication are unavailable even when creation succeeds. Review [current availability](/agents-platform/overview#current-availability) before planning an execution test.
</Note>

## 1. Create an API key

Open [API Keys](https://threetone.in/app/developers/api-keys) in the Threetone dashboard. Create a key with the permissions required for agents and voices, then store it in a server-side environment variable.

```bash theme={null}
export THREETONE_API_KEY="your_api_key"
```

## 2. Choose models and a saved voice

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/voices \
  --header "x-api-key: $THREETONE_API_KEY"
```

Choose a saved `voice_id` compatible with your selected TTS model. If your voice library is empty, add a voice in the dashboard first.

Use [List available AI models](/api-reference/agents-platform/list-available-ai-models) to check which ASR, TTS, and LLM models are available to your workspace. Model IDs use `provider/model` format. The request below uses `cartesia/ink-2`, `cartesia/sonic-3.6`, and `google/gemma-4-31b`; replace them with available, language-compatible model IDs when needed.

## 3. Create an agent

Replace `YOUR_VOICE_ID` with the selected voice ID.

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/convai/agents/create \
  --header "x-api-key: $THREETONE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Customer support agent",
    "conversation_config": {
      "asr": {
        "model_id": "cartesia/ink-2",
        "recognition": { "mode": "fixed", "language": "en" }
      },
      "tts": {
        "model_id": "cartesia/sonic-3.6",
        "voice_id": "YOUR_VOICE_ID"
      },
      "agent": {
        "first_message": "Hello, how can I help?",
        "language": "en",
        "prompt": {
          "prompt": "Help customers clearly and accurately.",
          "llm": "google/gemma-4-31b",
          "tool_ids": [],
          "mcp_server_ids": [],
          "native_mcp_server_ids": []
        }
      }
    }
  }'
```

A successful response returns the new agent, main branch, and initial version identifiers:

```json theme={null}
{
  "agent_id": "agent_3701kwyb5spce24t3h8gpqpsy6zh",
  "main_branch_id": "agtbrch_2201kwyb5tmbfb3a8a3jmtd5v28d",
  "initial_version_id": "agtvrsn_1401kwyb5tpwe868p2dtmj62q48t"
}
```

## 4. Read the configuration back

Replace `YOUR_AGENT_ID` with the returned `agent_id` and retrieve the saved agent:

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/convai/agents/YOUR_AGENT_ID \
  --header "x-api-key: $THREETONE_API_KEY"
```

Confirm the name, `conversation_config`, and the branch and version metadata. Keep the identifiers with your integration settings. This verifies the saved configuration, not a successful conversation or traffic deployment. See [Get agent](/api-reference/agents-platform/get-agent) for the complete response schema.

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Store keys safely and diagnose authentication failures.
  </Card>

  <Card title="Agents API" icon="robot" href="/api-reference/agents-platform/create-agent">
    Review the generated request and response schemas.
  </Card>

  <Card title="Knowledge base" icon="book" href="/agents-platform/configure/knowledge-base/overview">
    Prepare documents, inspect stored content, and review dependencies.
  </Card>

  <Card title="Channels and telephony" icon="phone" href="/agents-platform/deploy/telephony/overview">
    Review phone configuration and current execution limits.
  </Card>
</CardGroup>


# Create your first agent
Source: https://docs.threetone.in/agents-platform/get-started/first-agent

Create a blank agent in the dashboard, prepare its behavior, and understand how to preserve a configuration draft.

Start with a small, specific task, such as answering questions about a support process. This guide ends with a saved agent configuration you can inspect and revise.

<Frame>
  <img alt="Recording pending for Create your first agent. No playable video is available yet." />
</Frame>

## Before you begin

Sign in to the [Threetone dashboard](https://threetone.in/app/agents) and select the intended workspace. You need permission to create and edit agents. Blank-agent creation stores an initial configuration; it does not establish an execution-ready version.

<Note>
  This walkthrough covers configuration authoring. Voice and custom-model publication are currently unavailable, as are signed-token session initiation, outbound calling, traffic deployment, and automated response-test execution. See [current availability](/agents-platform/overview#current-availability) before planning a live demonstration.
</Note>

## Create and configure

<Steps>
  <Step title="Create a blank agent">
    Open **Agents**, select **Create Agent**, then choose **Blank Agent**. Enter an **Agent Name** that describes its purpose, such as `Support process guide`, and select **Create Agent**.

    The dashboard opens the new agent's workspace. Keep its identifier when connecting the configuration to an integration.
  </Step>

  <Step title="Write a focused prompt">
    Define the agent's task, the information it can use, and what it should do when an answer is missing. Write a short first message that tells the user what help the agent provides.

    Use the [prompting guide](/agents-platform/configure/agent-behavior/prompting) to separate instructions, knowledge, and actions. Start without tools or knowledge attachments so you can review the basic behavior clearly.
  </Step>

  <Step title="Choose the response model and prepare speech settings">
    Use the **LLM** section to select an available response model. The dashboard's **Voices**, **Language**, and **ASR** controls are previews whose changes are not saved.

    For voice configurations, prepare the base language, ASR and TTS models, and a compatible saved voice using the [voice and language authoring guide](/agents-platform/configure/voice-and-language/overview). These choices can be stored in a server draft, but compatible speech settings do not unblock voice publication.
  </Step>

  <Step title="Preserve and review the draft">
    Review the editor's pending changes and selected branch. The dashboard working copy is local; it is not automatically a saved server draft. Use [Create agent draft](/api-reference/agents-platform/create-agent-draft) with a complete snapshot and an explicit branch to preserve work through the API.

    The default blank agent is a voice configuration, so **Publish** cannot complete in the current implementation. For a managed text-only configuration, follow [Chat mode](/agents-platform/guides/chat-mode) and the [publication workflow](/agents-platform/deploy/versioning).
  </Step>

  <Step title="Read the saved version back">
    Read the selected branch and draft through [Get agent](/api-reference/agents-platform/get-agent), using the reference's supported read options. Distinguish the initial version, saved server draft, and unsaved editor values.

    Retain the agent, branch, and initial version IDs. Saving a draft does not create a newly published version or start a conversation.
  </Step>
</Steps>

## What you should have

You should have an agent in the intended workspace and a reviewed authoring plan. If you used the server-draft workflow, confirm that the draft was stored. Record resource IDs rather than relying on display names, and do not describe pending editor changes as published.

## Troubleshooting

| Problem | What to check |
| - | - |
| Agent creation is unavailable | Confirm the active workspace and your permission to create agents. |
| A speech or language choice did not save | Those dashboard controls are previews. Use the voice and language API workflow, then read the saved branch back. |
| Voice or custom-model Publish fails | These publication paths remain unavailable. Preserve a server draft; use a compatible managed text-only configuration for publication. |
| A newer version exists | Review the latest published configuration and reconcile the local working copy before publishing. |

## Continue

<CardGroup>
  <Card title="Add knowledge" icon="book" href="/agents-platform/configure/knowledge-base/overview">Prepare source documents and inspect their dependencies.</Card>
  <Card title="Review versions" icon="code-branch" href="/agents-platform/deploy/versioning">Understand branches, drafts, and configuration publication.</Card>
  <Card title="API quickstart" icon="code" href="/agents-platform/get-started/api-quickstart">Create an agent configuration from a server-side integration.</Card>
  <Card title="Configure an agent" icon="sliders" href="/agents-platform/configure/agent-behavior/overview">Understand the configuration fields and ownership boundaries.</Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does publishing the configuration start a conversation?">
    No. Publication saves a reviewed configuration version on the selected branch. Starting a session or deploying traffic uses a separate execution path. Check [current availability](/agents-platform/overview#current-availability) before planning a live test.
  </Accordion>

  <Accordion title="Why did my voice or language selection not save?">
    Those dashboard controls are previews. Use the [voice and language authoring workflow](/agents-platform/configure/voice-and-language/overview), then confirm the saved server draft. Voice publication remains unavailable.
  </Accordion>
</AccordionGroup>


# Burst pricing
Source: https://docs.threetone.in/agents-platform/guides/burst-pricing

Separate planned burst-capacity charges from subscription allowances and verify approved commercial terms before launch.

Burst capacity is a commercial and operational decision about handling demand above an included allowance. It should state what capacity can increase, which usage is billable, and what happens when a budget or service limit is reached.

## Plan the policy

Record the included capacity, maximum approved burst, measurement unit, rate, and billing period. Define whether the system rejects excess demand, places it in a queue, or permits an explicitly authorized overage. These are distinct behaviors; a price table alone does not implement any of them.

The [planned pricing](/overview/administration/billing/pricing) page contains draft commercial targets. They are not proof of active checkout products, enabled burst capacity, or metered billing. Confirm the approved catalog and agreement before estimating a customer's bill.

## Prepare for launch

Track usage by workspace and the version of the applicable commercial terms. Define warnings and hard-budget behavior, then test concurrency and failure handling separately from billing. Review [call queueing](/agents-platform/guides/call-queueing) and [pay as you go](/overview/administration/pay-as-you-go) as related plans.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is burst pricing enabled today?">No released burst-capacity pricing implementation is established by this documentation. Draft rates must not be treated as an active offer.</Accordion>
  <Accordion title="Does a higher plan guarantee extra concurrent calls?">Use the approved agreement and released capacity controls. A plan name or saved configuration does not establish additional capacity.</Accordion>
</AccordionGroup>


# Call queueing
Source: https://docs.threetone.in/agents-platform/guides/call-queueing

Define admission, waiting, expiry, and cancellation behavior for a future supported call queue.

A call queue separates accepted work from calls that are currently executing. No production Threetone queue scheduler or queue-management contract is verified for this release, so this guide defines the behavior to agree before integration.

## Define the queue policy

| Decision | Requirement to record |
| - | - |
| Admission | Workspace, channel, concurrency, and budget checks required before accepting a call. |
| Waiting | Maximum queue depth, waiting duration, and user-visible status. |
| Ordering | The supported ordering policy and any explicitly approved priority. |
| Expiry | What happens when a queued call is no longer useful. |
| Cancellation | Who may cancel, and how a cancellation racing with execution is resolved. |
| Retry | Which failures are safe to retry without placing duplicate calls. |

Do not use a live conversation count as a queue length. The [real-time count](/agents-platform/monitor/real-time-monitoring) describes active calls and has different availability and filtering behavior.

## Review operational outcomes

Keep a stable request identifier, the selected agent version, and the intended channel with each future queue item. Plan for unavailable providers and delayed execution. Review [batch calls](/agents-platform/deploy/batch-calls) and [call consent](/agents-platform/legal/call-consent) before accepting outbound work.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I create a queue through the API today?">A released queue contract is not verified. Do not infer one from batch-call request schemas or active conversation counts.</Accordion>
  <Accordion title="Does waiting guarantee a call will run?">No. Admission, expiry, cancellation, budget, and provider failures need explicit supported behavior before such a guarantee can be made.</Accordion>
</AccordionGroup>


# Chat mode
Source: https://docs.threetone.in/agents-platform/guides/chat-mode

Prepare a text-only agent configuration, choose a managed response model, and separate publication from live chat availability.

Chat mode configures an agent to accept text without requiring ASR or TTS. Set `conversation_config.conversation.text_only` to `true` when creating or authoring the configuration.

## Configure text behavior

Use a model returned by [List available LLMs](/api-reference/agents-platform/list-available-llms). Write a concise first message, define the task in the prompt, and select the base response language. A text-only configuration cannot use the `recognized_language` response policy because it has no recognized speech input.

```json theme={null}
{
  "conversation": { "text_only": true },
  "agent": {
    "language": "en",
    "first_message": "What would you like help with?"
  }
}
```

This fragment belongs inside `conversation_config`; preserve the rest of the selected snapshot when saving a complete server draft.

## Review publication separately

Managed text-only configurations can pass publication when model compatibility, referenced resources, and workflow validation succeed. With default backups, a compatible platform backup chain must be available; use [LLM cascading](/agents-platform/advanced/llm-cascading) to understand the alternatives.

<Warning>Custom-model publication remains unavailable. A published managed text-only version also does not establish a live chat transport or allocate traffic.</Warning>

Review [versions and drafts](/agents-platform/deploy/versioning), [client events](/agents-platform/advanced/events/overview), and [web deployment](/agents-platform/deploy/web/overview) before connecting a browser.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I leave speech settings unset?">Text-only configurations do not require ASR or TTS. Preserve any existing fields when reviewing a snapshot, and confirm the mode you intend to publish.</Accordion>
  <Accordion title="Does text-only mode remove access controls?">No. Workspace permissions, resource access, tool credentials, and publication validation still apply.</Accordion>
</AccordionGroup>


# Expo and React Native
Source: https://docs.threetone.in/agents-platform/guides/cookbooks/expo-react-native

Prepare a mobile client with explicit microphone permissions, server-owned credentials, and lifecycle-aware connection handling.

Prepare an Expo application that can explain its connection state, request microphone access deliberately, and stop capture when the user ends a session. Test these application behaviors before connecting a future agent transport.

<Note>
  There is no verified Threetone Expo package or working mobile conversation walkthrough. Public session initiation remains gated. This cookbook covers mobile preparation and supported server-side configuration reads.
</Note>

## Before you begin

Use an Expo project with recorded Expo and React Native versions, a physical test device, and an authenticated application backend. Decide which data the mobile user may access and whether the application needs microphone input at all.

<Steps>
  <Step title="Keep workspace credentials on the backend">
    Follow the [server-side quickstart](/agents-platform/guides/quickstarts/server-side) to read permitted agent configuration. Return only the application data the user is allowed to see. Expo's [environment guide](https://docs.expo.dev/guides/environment-variables/) explains that `EXPO_PUBLIC_` values are bundled into the application; they must not contain workspace API keys.
  </Step>

  <Step title="Prepare permission and capture states">
    Follow the version-matched [Expo Audio documentation](https://docs.expo.dev/versions/latest/sdk/audio/) for native configuration and recording permissions. Test denied permission, a later permission change, and explicit stop. Show when capture is active. A local recording test does not prove agent streaming support.
  </Step>

  <Step title="Handle app and network transitions">
    Use React Native's [AppState](https://reactnative.dev/docs/appstate) to observe foreground and background changes. Define whether capture stops or a future session ends when the app leaves the foreground. After a network interruption, recheck authentication and session state before reconnecting. Do not replay buffered audio or tool actions without a released replay contract.
  </Step>

  <Step title="Review logout and recovery">
    Release local audio resources, clear pending work, and remove application session material on logout. [SecureStore](https://docs.expo.dev/versions/latest/sdk/securestore/) can protect suitable local values, but it is not a reason to distribute a shared workspace key. Handle unavailable stored credentials by requiring sign-in again.
  </Step>
</Steps>

The result is a tested mobile lifecycle and a reviewed server boundary. Consult [React Native deployment](/agents-platform/deploy/mobile/react-native) before adding any future session transport.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a successful microphone test mean live voice works?">No. Device capture, network transport, session authorization, and agent execution are separate checks.</Accordion>
  <Accordion title="Should the app retry every connection error?">Use bounded retries only for recoverable failures. Stop on denied permission, expired access, user cancellation, or an unavailable runtime.</Accordion>
</AccordionGroup>


# Live avatar
Source: https://docs.threetone.in/agents-platform/guides/cookbooks/live-avatar

Prepare an avatar presentation layer with separate session ownership, media contracts, interruption, and cleanup requirements.

Design an avatar as a presentation layer around a conversation. Decide who produces speech, who renders video, and who owns each session before selecting a vendor mode.

<Note>
  Threetone has no verified native avatar adapter or working avatar conversation runtime. Vendor session APIs do not remove Threetone's execution gate. This cookbook produces an integration design and independent media test plan.
</Note>

## Before you begin

Have permission to use the selected avatar assets, an approved vendor account, a backend owner, and a clear policy for audio, video, and transcript handling. Use synthetic text or approved sample audio for preparation.

<Steps>
  <Step title="Assign media and conversation responsibilities">
    Record which service owns recognition, responses, speech generation, rendering, and playback. As one vendor example, [LiveAvatar's LITE lifecycle](https://docs.liveavatar.com/docs/lite-mode/lifecycle) expects an external speech pipeline and renders its audio as video. That mode's contract is not a Threetone integration.
  </Step>

  <Step title="Separate credentials and session identifiers">
    Review the vendor's [session-token contract](https://docs.liveavatar.com/api-reference/sessions/create-session-token). Keep the vendor API key on your backend. Authorize each user before issuing permitted session access, and map application and vendor session IDs explicitly. Never substitute a vendor token for a Threetone credential.
  </Step>

  <Step title="Review audio and interruption behavior">
    Verify the vendor's required encoding, sample rate, and chunk limits rather than forwarding arbitrary audio. Define how cancellation stops both speech generation and queued playback. Correlate utterances so late chunks from a previous response cannot make the avatar speak after interruption.
  </Step>

  <Step title="Plan disconnect and cleanup">
    Distinguish transport reconnection from creating another billable session. Inspect uncertain start outcomes before repeating them. On user exit or unrecoverable failure, stop the vendor session through its [documented lifecycle](https://docs.liveavatar.com/api-reference/sessions/stop-session), release media resources, and clear pending audio.
  </Step>
</Steps>

Keep a text alternative and visible disconnected state. Review [privacy boundaries](/agents-platform/monitor/privacy/overview) for every service receiving media. Threetone's stored retention settings do not guarantee deletion of vendor copies.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I paste an avatar endpoint into agent configuration?">There is no verified avatar configuration field or adapter. The integration needs a released transport and an implemented application boundary.</Accordion>
  <Accordion title="Does a vendor-only demo prove the Threetone integration works?">No. It verifies the tested vendor media path. Threetone session initiation and the complete conversation path require separate release and verification.</Accordion>
</AccordionGroup>


# Raspberry Pi
Source: https://docs.threetone.in/agents-platform/guides/cookbooks/raspberry-pi

Prepare a controlled device prototype with tested audio, restricted credentials, and explicit offline and restart behavior.

Prepare a Raspberry Pi prototype that can test its microphone and speaker locally, show whether it is recording, and recover predictably after a restart. Keep the device test separate from a future agent connection.

<Note>
  No Threetone Raspberry Pi runtime package or released live voice walkthrough is verified. Local audio and server-side API reads can be tested independently; they do not start a Threetone conversation.
</Note>

## Before you begin

Record the board model, Raspberry Pi OS release, power supply, network, and audio devices. Use a controlled location and test audio without bystanders' conversations. Decide how a user can stop capture physically or through the device interface.

<Steps>
  <Step title="Prepare the operating system and access">
    Follow Raspberry Pi's [operational security guidance](https://www.raspberrypi.com/documentation/security/operational-security.html) for maintained software, limited user permissions, and SSH access. Give the application only the device access it needs. Keep remote administration separate from the public user interface.
  </Step>

  <Step title="Verify the actual audio route">
    Record and play a short local sample with the selected input and output. Check clipping, speaker feedback, and device removal. Raspberry Pi's [audio documentation](https://www.raspberrypi.com/documentation/accessories/audio.html) explains the available audio frameworks; verify the stack installed on your OS image instead of assuming desktop and headless images match.
  </Step>

  <Step title="Define the server boundary">
    For a shared kiosk, keep workspace API keys on an application backend and give the device a narrowly scoped application identity. Use the [server-side quickstart](/agents-platform/guides/quickstarts/server-side) for authorized configuration reads. Do not place secrets in an image distributed to multiple devices.
  </Step>

  <Step title="Exercise offline and restart cases">
    Test unplugged audio, network loss, restart, and user cancellation. Show an offline state, bound any local queue, and start with capture stopped after reboot. Do not replay recorded speech or external actions after reconnect without a supported replay contract and current user intent.
  </Step>
</Steps>

Keep the resulting device inventory and recovery behavior with your [custom-channel design](/agents-platform/configure/integrations/custom-channel). A future release still needs session authorization, supported audio transport, and end-to-end execution verification.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I run a Threetone agent entirely on the device?">No local Threetone agent runtime is documented. This guide prepares device input, output, and an application boundary.</Accordion>
  <Accordion title="Should the device record while offline?">Choose an explicit product policy. The default preparation workflow stops capture and does not retain a backlog of speech for automatic upload.</Accordion>
</AccordionGroup>


# Redis context
Source: https://docs.threetone.in/agents-platform/guides/cookbooks/redis-context

Design an application-owned context cache with identity isolation, expiration, and predictable failure behavior.

Use this design to prepare a small cache of application context, such as a verified user's preferred language and the timestamp of a recent lookup. Keep the authoritative record in the service that owns that data.

<Note>
  Threetone does not expose a user-configurable Redis context connector or a released session path that consumes this cache. Existing dynamic variables are saved authoring values. This cookbook describes a cache your application would own.
</Note>

## Before you begin

Have an authenticated application backend, a managed Redis owner, and an approved list of cacheable fields. Decide the maximum age of each field and what happens when it is missing.

<Steps>
  <Step title="Scope keys on the server">
    Derive the workspace and user identifiers from authenticated server context. Include them in the cache namespace and never accept an unrestricted Redis key from a client. Store a source version and fetch timestamp with values that can become stale. A cache hit does not grant access to the source record.
  </Step>

  <Step title="Restrict the Redis connection">
    Follow [Redis security guidance](https://redis.io/docs/latest/operate/oss_and_stack/management/security/) for network isolation, ACLs, and TLS. Permit only the required commands and key patterns. Keep Redis credentials on the backend, outside prompts, browser bundles, mobile apps, and ordinary agent variables.
  </Step>

  <Step title="Set expiration with each write">
    Redis [`SET`](https://redis.io/docs/latest/commands/set/) supports an expiration on the same write, such as `EX` in seconds. Choose the duration from the data's freshness requirement. Review overwrite behavior so a refresh does not accidentally leave a key without expiry. Handle a cache miss by rechecking authorized source data or returning an explicit unavailable result.
  </Step>

  <Step title="Test stale and repeated work">
    Plan for Redis outage, revoked source access, concurrent refreshes, and delayed results. Never reuse one user's context for another as a fallback. A temporary `SET NX` marker can coordinate work, but expiration or eviction means it cannot prove an external action executed exactly once.
  </Step>
</Steps>

Use synthetic [dynamic-variable placeholders](/agents-platform/configure/personalization/dynamic-variables) to review the expected values today. A future runtime integration must authenticate and validate context before substitution. Redis expiry does not establish deletion of logs, backups, transcripts, or provider copies; review [retention limits](/agents-platform/monitor/privacy/retention) separately.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a cache TTL enforce Threetone retention?">No. It controls that Redis key's expiry. Other copies and Threetone retention enforcement have separate lifecycles and limitations.</Accordion>
  <Accordion title="Can a cache miss use the last available customer's data?">No. Keep identity boundaries intact. Fetch authorized data for the current user or report that context is unavailable.</Accordion>
</AccordionGroup>


# Documentation assistant
Source: https://docs.threetone.in/agents-platform/guides/documentation-assistant

Prepare an agent that answers from reviewed product documentation, identifies unsupported questions, and links users to the right source.

A documentation assistant should help readers find and apply published instructions. Start with a narrow product area and a reviewed source set, then evaluate whether answers are accurate, current, and traceable.

<Note>
  You can prepare sources, agent configuration, and test definitions now. A saved knowledge attachment does not establish working retrieval, and automated test execution and conversation runtime remain subject to [current availability](/agents-platform/overview#current-availability).
</Note>

## Prepare the source set

<Steps>
  <Step title="Choose a bounded scope">
    Select the product version, audience, and tasks the agent should cover. For example, answer setup and configuration questions for one public integration. Exclude internal plans, customer records, and outdated pages from a public assistant's general knowledge.
  </Step>

  <Step title="Create and inspect knowledge documents">
    Use the [knowledge-base workflow](/agents-platform/configure/knowledge-base/overview) for reviewed URL, text, or file sources. Read stored content back and check processing status. Include stable source titles and canonical URLs so reviewers can trace instructions to their origin.
  </Step>

  <Step title="Attach sources to the intended agent">
    Create the agent first, then attach knowledge to the existing agent. The initial create-agent request rejects nonempty knowledge attachments. Review the selected branch and saved references before publishing a supported configuration.
  </Step>

  <Step title="Define answer boundaries">
    In the [prompt](/agents-platform/configure/agent-behavior/prompting), specify the supported product scope, how to ask for missing context, and when to say that the sources do not answer a question. Request source links only when the source is actually available. Do not let the agent invent package names, commands, settings, or release dates.
  </Step>
</Steps>

## Build a review set

| Question type | Expected result |
| - | - |
| Documented setup task | Correct prerequisites and steps, with a relevant source. |
| Version-sensitive behavior | Identify the applicable version or ask for it. |
| Missing information | Explain the gap and offer the appropriate support route. |
| Request outside scope | Decline to invent an answer or expose private material. |
| Conflicting sources | Identify the conflict for review instead of silently combining instructions. |

Store representative cases through [testing](/agents-platform/monitor/testing). Review them manually while automated execution is unavailable. Once retrieval and runtime are released, compare answers with the exact source snapshot and agent version used for each run.

## Maintain the assistant

Assign an owner to each source. When documentation changes, inspect the stored content and agent dependencies; do not assume a URL source automatically synchronizes. Recheck affected questions before treating an updated source as ready for public answers. Use [model guidance](/overview/models) to review the model selected for the task.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this enable an assistant on my documentation site?">No. This prepares the agent and source workflow. Website placement still requires a supported widget and session release.</Accordion>
  <Accordion title="Can I promise citations on every answer?">Only after testing the released retrieval and answer path. A prompt requesting citations does not prove that a returned link supports the answer.</Accordion>
</AccordionGroup>


# Next.js preparation
Source: https://docs.threetone.in/agents-platform/guides/nextjs

Separate server-side workspace API access from browser interaction when preparing a Next.js agent experience.

A Next.js integration has two boundaries: your server reads or manages workspace resources, while a browser displays the experience. Giving the browser a workspace API key would collapse those boundaries.

<Note>Server-side resource reads can use the public API today. A live browser conversation needs a released session-initiation and client transport path; it is not established by this guide.</Note>

## Prepare the application

<Steps>
  <Step title="Keep credentials on the server">Store `THREETONE_API_KEY` in a server environment variable. Never give it a `NEXT_PUBLIC_` prefix or pass it through client component props. Keep the module that reads it server-only.</Step>
  <Step title="Authorize your own users">Before a server action or route reads private workspace data, verify the caller's identity and resource access. Hiding an agent ID in the interface is not authorization.</Step>
  <Step title="Read only the required data">Use [Get agent](/api-reference/agents-platform/get-agent) or [List agents](/api-reference/agents-platform/list-agents). Validate the response and return only fields needed by the interface. Avoid sharing private configuration through a public cache.</Step>
  <Step title="Prepare browser behavior">Provide loading, failure, and unavailable states. For a future voice experience, request microphone access only after a deliberate user action and include keyboard-accessible stop and mute controls.</Step>
</Steps>

Use the [TypeScript REST example](/agents-platform/resources/sdks/typescript) for authenticated resource reads. Review the [web deployment checklist](/agents-platform/deploy/web/overview) before adding a live experience.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does Threetone provide an installable Next.js SDK?">No first-party installable SDK is verified in this documentation release. The example uses server-side HTTP requests, not an invented package.</Accordion>
  <Accordion title="Should the browser call my server for every agent operation?">Route privileged workspace operations through an authorized server boundary. A future supported session transport may connect independently with appropriately scoped session access.</Accordion>
</AccordionGroup>


# Framer
Source: https://docs.threetone.in/agents-platform/guides/no-code/framer

Plan a Framer embed with a suitable layout, permitted hosting origin, and explicit checks before a Threetone widget release.

Use Framer's Embed component to plan where an agent interface would sit. A Threetone production embed and supported session path still need to be released before this becomes a working installation.

## Prepare the component

Framer's [embed guide](https://www.framer.com/help/articles/how-to-add-an-iframe-or-embed-script/) supports a URL or HTML containing an embed script. From **Insert**, search for **Embed** and place the component on the canvas. Set aside a suitable test page without adding an unverified Threetone URL.

<Steps>
  <Step title="Design the space">
    Give the interface enough width and height for its expanded state, errors, and controls. Review each breakpoint. Avoid placing it where it obscures navigation or the page's primary action.
  </Step>

  <Step title="Check the integration contract">
    When a widget is released, confirm whether it supports Framer's Embed context and whether it expects a URL or a script. Review allowed origins, frame restrictions, session access, and microphone permissions if voice is supported. A host that disallows framing cannot be made embeddable by changing a Framer layout setting.
  </Step>

  <Step title="Validate the published site">
    Add only the verified integration on the test page, then inspect the published domain. Test keyboard entry and exit, mobile sizing, navigation, permission denial, and ending a session. Preview rendering alone is not proof of a working conversation.
  </Step>
</Steps>

## Before wider placement

Confirm there is one interface per intended page, no credentials in public code, and no persistent audio after leaving the page. Keep a contact link outside the embed so visitors have an alternative if it cannot load. Retain the prior page version for rollback.

Review [widget preparation](/agents-platform/deploy/web/widget) for release evidence and [authentication](/agents-platform/configure/authentication/overview) for agent access.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does an HTTPS URL still show a blank frame?">The destination may forbid framing, or the integration may need a different installation mechanism. Verify the released widget contract and browser error before changing site policy.</Accordion>
  <Accordion title="Can I add a workspace API key to the HTML field?">No. Public embed code is visible to visitors. Use only the session-access mechanism documented for the released widget.</Accordion>
</AccordionGroup>


# Ghost
Source: https://docs.threetone.in/agents-platform/guides/no-code/ghost

Prepare a Ghost publication for a future Threetone widget, with a deliberate injection scope and published-site checks.

Ghost provides code injection for third-party scripts. Prepare the placement and review process now; install a Threetone widget only after its production asset, session access, and runtime are released.

<Note>
  There is no verified production Threetone embed snippet in this guide. A dashboard preview URL or local development script is not a supported installation asset.
</Note>

## Choose where it belongs

Ghost's **Settings > Code Injection** contains site header and footer fields that affect every page. The editor sidebar also provides code injection for an individual post. Ghost recommends the footer for JavaScript in its [code-injection tutorial](https://ghost.org/tutorials/use-code-injection-in-ghost/).

Begin with a single test page or post. Decide whether the assistant belongs on public articles, member content, or both. Page placement alone must not grant the agent access to private member information.

## Prepare the installation

<Steps>
  <Step title="Record the existing injection">
    Keep a copy of the current header and footer configuration before a future change. Identify existing chat, consent, analytics, and theme scripts that may compete for screen space or load the same dependency.
  </Step>

  <Step title="Review the released snippet">
    Verify its authoritative origin, version, required placement, and visitor access design. Keep workspace credentials out of Ghost's public HTML. Follow the widget's released placement requirements even if a general-purpose script would normally go in the footer.
  </Step>

  <Step title="Test the published page">
    Once installation is supported, test the actual published URL as a signed-out visitor and, where relevant, a member. Confirm that article navigation does not duplicate the interface and that the widget does not cover subscription or account controls.
  </Step>
</Steps>

Check narrow screens, keyboard focus, readable errors, permission denial for voice, and the ability to end a session. Keep a visible contact route available while the widget is unavailable. Record how to remove the injection and restore the previous configuration if the test fails.

For agent preparation, start with [the introduction](/overview/intro) and [widget requirements](/agents-platform/deploy/web/widget).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I paste the script into both header and footer?">No. Use the location required by the released widget instructions and load one instance. Duplicate injection can create duplicate interfaces or sessions.</Accordion>
  <Accordion title="Does member-only placement authorize private answers?">No. The agent's source access and session authorization need their own supported controls. Hiding a page is not an agent permission model.</Accordion>
</AccordionGroup>


# No-code websites
Source: https://docs.threetone.in/agents-platform/guides/no-code/overview

Prepare a website placement, content policy, and launch checklist for a future supported Threetone embed.

No-code site builders can provide a place for an agent experience without changing the site's application framework. The production Threetone embed and its live session path are not verified for this release, so the guides below describe preparation rather than a working copy-and-paste widget.

## Prepare the placement

Choose where the experience belongs: a help page, product page, or persistent launcher. Keep it clear of cookie controls, forms, and navigation. Define the questions it should answer, where its knowledge comes from, and when it should direct someone to support.

<CardGroup>
  <Card title="Webflow" icon="window" href="/agents-platform/guides/no-code/webflow">Plan an embed placement and staging checks in a Webflow site.</Card>
  <Card title="WordPress" icon="window" href="/agents-platform/guides/no-code/wordpress">Prepare a controlled page or theme placement without exposing credentials.</Card>
</CardGroup>

## Launch checklist

Before enabling a released embed, verify its authoritative script URL, session authentication, permitted origins, content security policy, keyboard behavior, and mobile layout. Test microphone permission refusal and disconnected sessions where voice is offered. Provide a visible alternative contact path.

Keep workspace keys and provider secrets out of HTML, CMS fields, tag managers, and third-party snippets. An agent identifier is not a substitute for a supported access policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where is the embed snippet?">A verified production snippet is not available in this release. These guides will add it after the browser session path is released and tested.</Accordion>
  <Accordion title="Can I publish a visual launcher now?">Use it only if it leads to a working destination and accurately describes availability. Do not present a decorative launcher as a live agent.</Accordion>
</AccordionGroup>


# Squarespace
Source: https://docs.threetone.in/agents-platform/guides/no-code/squarespace

Prepare Squarespace code-injection scope and published-page checks for a future supported Threetone widget.

Squarespace offers code injection in supported site configurations. First confirm that your current site supports the required mechanism; a plan change or purchase does not establish Threetone widget compatibility.

<Note>
  The production widget snippet and working session path are pending. Keep the site unchanged until a released Threetone installation contract specifies its asset and access requirements.
</Note>

## Choose the scope

Squarespace's [code-injection guide](https://support.squarespace.com/hc/en-us/articles/205815908-Customize-parts-of-your-site-with-code-injection) distinguishes global header and footer injection from page-specific header injection. Global fields affect every page; a page's settings under **Advanced** can restrict supported injection to that page.

Choose a test page before planning a site-wide rollout. Follow the released widget's placement instructions. Do not place visible interface HTML in a header field just because it accepts code.

## Prepare the change

<Steps>
  <Step title="Inventory existing code">
    Save a copy of the current injection and identify scripts already providing chat, consent, or analytics. Decide who will maintain the integration and restore the previous configuration if a test fails.
  </Step>

  <Step title="Review the released installation">
    Verify the script origin, version, loading behavior, allowed origins, and session authorization. Keep workspace API keys out of public page code. Use one installation location to avoid duplicate initialization.
  </Step>

  <Step title="Check the published page">
    Test outside the site editor after a supported installation is available. Visit the page directly, navigate to it from another page, and return using browser history. Check that the interface starts once and releases its resources when it ends.
  </Step>
</Steps>

Review mobile layout, cookie-banner overlap, keyboard focus, error messages, and voice permission denial. Keep a contact link visible even when the widget cannot load. If the integration affects editing, remove the test injection and investigate before expanding its scope.

Continue with [web deployment](/agents-platform/deploy/web/overview) and [widget requirements](/agents-platform/deploy/web/widget).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is a Squarespace code-injection option proof that the widget works?">No. It provides a place to insert code. Asset loading, session access, browser behavior, and conversation execution must still be verified.</Accordion>
  <Accordion title="Should I install it globally for the first test?">Start with the smallest supported scope and a clear rollback. Expand only after the published-page checks pass.</Accordion>
</AccordionGroup>


# Webflow
Source: https://docs.threetone.in/agents-platform/guides/no-code/webflow

Prepare a Webflow page for a future supported agent embed and define staging, accessibility, and security checks.

Prepare the site layout before connecting a live agent. Threetone's production embed URL and session transport are not verified in this release; do not use an illustrative URL as a working script.

## Prepare and review

<Steps>
  <Step title="Choose a page and placement">Work on a staging copy of the site. Decide whether the experience is an inline section or a launcher, and reserve room for its expanded state on narrow screens.</Step>
  <Step title="Define the content scope">Create the agent configuration and review its prompt, knowledge references, and support handoff instructions. Keep its workspace, agent, branch, and version IDs with your launch notes.</Step>
  <Step title="Plan the installation boundary">When a supported embed is released, use Webflow's documented embed or custom-code mechanism for your site plan. Install the official snippet once; avoid duplicating it in both page content and global code.</Step>
  <Step title="Test before publishing">Check keyboard navigation, focus restoration, microphone denial, loading failures, and mobile overlap. Confirm that your site's security policy permits only the verified resources required by the embed.</Step>
</Steps>

Keep keys out of Webflow CMS fields and client-side code. Use the [web deployment checklist](/agents-platform/deploy/web/overview) to assess the complete integration, and [call consent](/agents-platform/legal/call-consent) when planning recorded voice interactions.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a staging preview prove the agent is deployed?">Only test a live session after its supported transport and access path are available. A rendered launcher or saved configuration does not prove execution.</Accordion>
  <Accordion title="Should I put a workspace API key in custom code?">No. Browser-visible custom code cannot protect a workspace key.</Accordion>
</AccordionGroup>


# Wix
Source: https://docs.threetone.in/agents-platform/guides/no-code/wix

Prepare a Wix HTML or site embed and review frame, sizing, and access requirements before a supported widget release.

Wix Editor supports visible HTML and site embeds. Use this guide to prepare a test location; it does not supply a released Threetone widget snippet or prove Wix compatibility.

## Choose an embed type

In Wix Editor, open **Add Elements > Embed Code > Popular Embeds**. **Embed HTML** accepts a snippet, while **Embed a site** accepts an external URL. Both use an iframe. Wix requires HTTPS and cannot override a destination's policy that forbids embedding. See [Wix's embed guide](https://support.wix.com/en/article/wix-editor-embedding-a-site-or-a-widget).

A future widget release must explicitly support the selected embed context. Do not substitute a dashboard or API URL for a public widget URL.

## Prepare and test

<Steps>
  <Step title="Reserve a usable container">
    Place the test embed where it has room for controls, transcript, and errors. Check the desktop and mobile layouts separately. Container dimensions can crop an interface even if its content uses relative sizing.
  </Step>

  <Step title="Review the released asset">
    Confirm whether the widget supplies supported HTML or a hosted URL. Inspect the required origin, frame policy, permission policy, and session access. Public embed fields must not contain workspace API keys.
  </Step>

  <Step title="Inspect the published result">
    After a supported release, test the actual site URL. Give the embed a useful accessible description. Confirm keyboard access, readable error states, session end, navigation cleanup, and microphone permission behavior for a voice interface.
  </Step>
</Steps>

Keep a contact link outside the iframe. If the frame is blank, inspect loading and frame-policy errors before changing the page layout. If content is clipped, test the expanded interface at each target size. Remove the test embed if it interferes with navigation or essential site controls.

See [widget preparation](/agents-platform/deploy/web/widget) and [current availability](/agents-platform/overview#current-availability) before planning a public launch.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Will a widget automatically resize inside Wix?">Do not assume it will. Wix's embed container has its own dimensions. Test the supported widget at desktop and mobile sizes, including expanded and error states.</Accordion>
  <Accordion title="Can I fix a blocked destination by using another embed type?">A destination's security policy still applies. Use an installation method that the widget release supports rather than trying to bypass that policy.</Accordion>
</AccordionGroup>


# WordPress
Source: https://docs.threetone.in/agents-platform/guides/no-code/wordpress

Prepare a WordPress placement for a future Threetone embed while preserving credential safety and a reviewable release path.

Use a staging site to prepare an agent experience and its fallback contact path. A production Threetone embed is not verified for this release, so this guide does not provide a plugin name or script to install.

## Prepare the integration

Choose a page or theme placement owned by your team. Decide whether the experience should appear on every page or only alongside relevant support content. Document who can change the placement and how to disable it quickly.

Once an official embed is released, use a supported WordPress integration mechanism suitable for your hosting and security policy. Avoid editing a parent theme in a way that updates can overwrite. Keep installation in one place and review the exact script source before publishing.

## Verify the experience

Test the placement with your active theme, cache settings, consent manager, and mobile navigation. Confirm keyboard access, readable status messages, and focus restoration. A blocked script should leave the page usable and retain a working support link.

Never store workspace keys or provider secrets in page blocks, public shortcode output, or browser-visible settings. Privileged API operations belong on an authorized server boundary.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is there an official Threetone WordPress plugin?">No installable first-party plugin is verified in this documentation release. Do not install an unrelated package solely because its name appears similar.</Accordion>
  <Accordion title="Does caching make the integration public?">Review what is cached. Public placement HTML must not include credentials or private workspace responses. Session authentication requires its own supported path.</Accordion>
</AccordionGroup>


# Implementation guides
Source: https://docs.threetone.in/agents-platform/guides/overview

Choose a practical setup guide for API integrations, web experiences, conversation review, and planned channel workflows.

Start with a guide that matches the task you need to complete. Each guide states what can be configured or inspected today and which execution steps require a future release.

## Choose a starting point

<CardGroup>
  <Card title="Server-side quickstart" icon="server" href="/agents-platform/guides/quickstarts/server-side">Authenticate, list agents, and inspect a configuration without exposing a key.</Card>
  <Card title="Next.js preparation" icon="code" href="/agents-platform/guides/nextjs">Keep workspace API access on the server and plan a separate browser session boundary.</Card>
  <Card title="Chat mode" icon="comments" href="/agents-platform/guides/chat-mode">Prepare a text-only configuration and understand publication requirements.</Card>
  <Card title="No-code websites" icon="window" href="/agents-platform/guides/no-code/overview">Prepare a website placement and the checks needed before an embed is released.</Card>
  <Card title="User interviews" icon="users" href="/agents-platform/guides/scaling-user-interviews">Design a consistent interview, consent process, and evidence review.</Card>
  <Card title="Conversation simulations" icon="flask" href="/agents-platform/guides/simulate-conversations">Save test cases and define what a meaningful result should contain.</Card>
</CardGroup>

## Capacity and commercial planning

Use [call queueing](/agents-platform/guides/call-queueing) to define admission and waiting behavior for a future channel integration. Read [burst pricing](/agents-platform/guides/burst-pricing) before treating a capacity plan as a billing commitment. Neither guide establishes a released queue or an active rate.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I run every guide end to end today?">No. Read the availability note at the start of a guide. Configuration, publication, and live execution are separate operations.</Accordion>
  <Accordion title="Where are the complete request schemas?">Use the linked API reference for required fields and responses. Keep credentials server-side and preserve returned resource identifiers.</Accordion>
</AccordionGroup>


# JavaScript preparation
Source: https://docs.threetone.in/agents-platform/guides/quickstarts/javascript

Prepare a browser interface with an authorized server boundary, safe environment variables, and a clear integration lifecycle.

A JavaScript application can display agent information while its server reads workspace resources. Prepare that separation before adding a conversation transport. A workspace API key belongs on the server.

<Note>
  Authenticated resource reads are available. A browser conversation still requires a released session and transport path. This guide does not install a Threetone client package or start a live session.
</Note>

## Before you begin

Use the [TypeScript REST example](/agents-platform/resources/sdks/typescript) for the server request and review [web deployment](/agents-platform/deploy/web/overview). Choose an existing agent and authorize access to it in your application.

## Prepare the interface

<Steps>
  <Step title="Keep the API key on your server">
    Store `THREETONE_API_KEY` in the server environment. In a Vite application, do not put it in a variable prefixed with `VITE_`. Those values become part of the browser bundle. A public API base URL is configuration; a workspace key is a credential.
  </Step>

  <Step title="Return a small authorized response">
    Authenticate the caller before reading private agent configuration. Use [Get agent](/api-reference/agents-platform/get-agent) on the server and return only fields the interface needs. Do not expose an arbitrary resource proxy that accepts any agent ID without checking access.
  </Step>

  <Step title="Handle request failures">
    Show loading, unavailable, and retry states. Cancel obsolete requests when the user changes the selected agent. Avoid putting private responses in a shared public cache, and keep credentials and prompt contents out of browser error messages.
  </Step>

  <Step title="Prepare a future session lifecycle">
    Start microphone access only after an explicit user action. Include stop and mute controls with accessible labels. Plan for permission denial, disconnection, and cleanup when the page closes. Keep these controls unavailable until the supported session path is ready.
  </Step>
</Steps>

Follow [Vite's environment-variable guidance](https://vite.dev/guide/env-and-mode) when configuring a client build. Its development server proxy does not replace authentication or a production server boundary.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I hide a workspace key in a minified bundle?">
    No. Anyone who receives the bundle can inspect its values and requests. Keep privileged operations on an authorized server.
  </Accordion>

  <Accordion title="Is a resource read enough to enable chat or voice?">
    No. Reading an agent document and establishing a conversation are separate operations. Check [current availability](/agents-platform/overview#current-availability) before enabling a live control.
  </Accordion>
</AccordionGroup>


# Server-side quickstart
Source: https://docs.threetone.in/agents-platform/guides/quickstarts/server-side

Verify server-side authentication, list accessible agents, and inspect a selected configuration with the public API.

Use this read-only workflow to confirm that an integration can reach the intended workspace. It does not create a conversation or change an agent.

<Frame>
  <img alt="Recording pending for Read an agent through the API. No playable video is available yet." />
</Frame>

## Before you begin

Create a scoped [API key](/overview/administration/workspaces/api-keys). Store it as `THREETONE_API_KEY` in your server environment. You need permission to read agents in the selected workspace.

<Steps>
  <Step title="List accessible agents">
    Send a request to [List agents](/api-reference/agents-platform/list-agents). Follow the returned pagination cursor when more results are available.

    ```bash theme={null}
    curl --fail-with-body --request GET \
      --url https://api.threetone.in/v1/convai/agents \
      --header "x-api-key: $THREETONE_API_KEY"
    ```
  </Step>

  <Step title="Inspect one configuration">
    Use a returned agent ID with [Get agent](/api-reference/agents-platform/get-agent). Confirm its branch and version metadata, prompt, model, and resource references. Do not substitute a display name for its ID.
  </Step>

  <Step title="Handle failures explicitly">
    Set request timeouts in your application. Distinguish authentication failures, unavailable resources, validation errors, and service failures. Log status and a safe request identifier rather than keys, prompts, or transcripts.
  </Step>
</Steps>

Use the [Python](/agents-platform/resources/sdks/python) or [TypeScript](/agents-platform/resources/sdks/typescript) REST examples for application code. Continue with [API quickstart](/agents-platform/get-started/api-quickstart) when you need to create a configuration.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does an empty list mean authentication failed?">Not necessarily. Check the response status, workspace access, filters, and pagination. An empty successful response may contain no accessible agents.</Accordion>
  <Accordion title="Can this key be used in a browser?">Keep workspace API keys on a trusted server. Browser session access requires a separate supported authentication path.</Accordion>
</AccordionGroup>


# User interviews
Source: https://docs.threetone.in/agents-platform/guides/scaling-user-interviews

Plan a consistent research interview, consent process, data collection, and human review before scaling agent-assisted sessions.

Start with a research question and a small set of interviews. An agent can be configured around a repeatable question sequence, but reliable findings still need appropriate recruitment, consent, and human interpretation.

## Design the interview

Define the audience, purpose, expected duration, and topics you will avoid. Write open questions that do not imply a preferred answer. Include instructions for skipping a question, stopping the interview, and responding when the participant asks for a person.

Use [prompting](/agents-platform/configure/agent-behavior/prompting) to separate interview instructions from reference material. Use [data collection](/agents-platform/monitor/analysis/data-collection) to plan fields such as the participant's task and observed friction. An extracted value should remain traceable to the underlying conversation.

## Review before scaling

Create representative test cases, including short answers, unclear answers, and requests to withdraw. Review consent and [privacy settings](/agents-platform/monitor/privacy/overview) before collecting personal information. Saved settings do not establish retention enforcement.

Keep a sample of direct conversation reviews alongside summary metrics. Record which configuration version was used, and distinguish an observed issue from a researcher's interpretation.

<Note>Live session initiation, automated testing, and batch calling remain gated. This guide prepares the research workflow; it does not claim an available automated interview campaign.</Note>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can summaries replace reviewing the source?">No. Inspect representative transcripts and contradictory cases before drawing conclusions. Keep the evidence and configuration identifiers together.</Accordion>
  <Accordion title="Should interviews collect sensitive information?">Collect only information necessary for the approved research purpose. Explain the intended use and provide a clear way to stop.</Accordion>
</AccordionGroup>


# Simulate conversations
Source: https://docs.threetone.in/agents-platform/guides/simulate-conversations

Define representative conversation simulations, expected outcomes, and review criteria before automated execution is released.

A simulation describes an interaction you want to assess against an agent configuration. Save the definition separately from the result: accepting a test case does not mean a conversation ran or passed.

## Prepare a useful case

<Steps>
  <Step title="Choose one scenario">Name a concrete situation, such as a customer asking about an unsupported action. State the expected response and the boundary the agent must preserve.</Step>
  <Step title="Supply representative context">Prepare the chat history, dynamic variables, environment, and channel needed by the case. Use synthetic data and avoid copying private transcripts into fixtures.</Step>
  <Step title="Define the outcome">Specify response conditions, examples, or expected tool behavior supported by the test schema. Include a failure case as well as a normal interaction.</Step>
  <Step title="Save and read back">Use [Create test](/api-reference/tests/create-test), then retrieve the saved definition. Keep the case ID and agent version you intend to assess.</Step>
</Steps>

## Execution boundary

The current implementation stores test definitions and exposes invocation reads, but automated execution and resubmission remain gated. Do not report a success rate from saved definitions or empty invocation results.

When execution is released, require the exact configuration version, input scenario, result status, and review evidence for each run. See [Testing](/agents-platform/monitor/testing).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a simulation prove voice quality?">A text scenario cannot establish microphone behavior, speech recognition, audio quality, or channel reliability. Those need separate supported runtime tests.</Accordion>
  <Accordion title="Should a test assert an exact sentence?">Prefer meaningful behavior and constraints when wording can vary. Exact text is appropriate only when that text is itself a requirement.</Accordion>
</AccordionGroup>


# AI identity and disclosure
Source: https://docs.threetone.in/agents-platform/legal/ai-disclosure

Review how an agent identifies the business, explains its use of AI, describes its abilities, and responds when someone requests human help.

Make it clear who the agent represents and how it participates in the interaction. Review the full experience, including the displayed name, voice, greeting, generated responses, links, and actions.

The FTC's government and business impersonation rule addresses materially false identity and affiliation claims. An agent's name, voice, and wording should not create a misleading impression about the organization behind it. See the [FTC's explanation of the impersonation rule](https://www.ftc.gov/news-events/news/press-releases/2025/04/ftc-highlights-actions-protect-consumers-impersonation-scams).

<Note>
  The checks below are design recommendations for a deployment review. They do not provide a universal disclosure script or determine the legal requirements for every location or channel. Review applicable requirements with qualified advisers and check [runtime availability](/agents-platform/overview#current-availability).
</Note>

## Review the opening

<Steps>
  <Step title="Identify the responsible business">
    Use the approved business name and describe the purpose of the interaction. Check that the voice, display name, and contact information represent that business accurately.
  </Step>

  <Step title="Explain the use of AI">
    Prepare a short, understandable explanation that the person is interacting with an AI assistant. Review its placement, language, and audibility before the person is asked to act or provide information.
  </Step>

  <Step title="Describe the actual scope">
    State what the assistant can help with. Avoid claims of human identity, professional authority, guaranteed results, or completed actions that the integration cannot support.
  </Step>

  <Step title="Offer a real alternative">
    Identify the supported route for human assistance or another contact method. If live transfer is unavailable, provide the verified alternative without claiming that a transfer has started.
  </Step>
</Steps>

Review recording and transcription notices separately with the [call consent checklist](/agents-platform/legal/call-consent). An AI notice should not be used as a substitute for those decisions.

## Test the experience

Prepare an approved response for each scenario, then verify it in the released integration. Saving a first message or prompt only prepares the configuration.

| Scenario | Check |
| - | - |
| The person interrupts the greeting | The business identity and AI explanation remain understandable. |
| The person asks whether the agent is human | The answer acknowledges the use of AI directly. |
| The conversation changes language | The explanation remains accurate and comprehensible in the selected language. |
| The person asks for a person | The response describes the assistance route that actually exists. |
| A tool fails or has no result | The agent does not claim success, confirmation, or an action that did not occur. |
| The voice resembles a real person | The reviewer checks the authority to use it and whether the presentation could mislead the listener. |

Keep the reviewed wording with the agent version and the intended channel. Recheck it when the voice, first message, language policy, connected actions, or assistance route changes. See [prompting](/agents-platform/configure/agent-behavior/prompting) and [versioning](/agents-platform/deploy/versioning) for configuration review.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is a notice hidden in the privacy policy enough?">
    Do not assume a policy link resolves the interaction's disclosure requirements. Have the reviewer determine what must be communicated, where, and when. This guide recommends making the use of AI clear in the interaction itself.
  </Accordion>

  <Accordion title="Can an agent use a friendly name?">
    Review the name together with the voice and greeting. The presentation should not imply that a specific person is speaking or that the assistant has an affiliation or authority it does not have.
  </Accordion>

  <Accordion title="Does identifying the agent as AI approve the rest of the workflow?">
    No. Review calling permission, recording, data use, action authorization, and any sector-specific requirements separately. Clear identity is one part of the deployment review.
  </Accordion>
</AccordionGroup>


# Call consent and recording
Source: https://docs.threetone.in/agents-platform/legal/call-consent

Prepare a calling review that separates contact permission, artificial-voice requirements, recording decisions, and requests to stop contact.

Decide who may be contacted and for what purpose before preparing a calling workflow. Review permission to place a call separately from permission to record, transcribe, or reuse information from it.

<Note>
  This is a review procedure, not authorization to call. Outbound calling remains unavailable in the [documented execution paths](/agents-platform/overview#current-availability). Do not treat a saved phone configuration or consent field as a working enforcement control.
</Note>

## Identify the applicable requirements

For a proposed U.S. deployment, the FCC's AI voice ruling treats AI-generated human voices as artificial or prerecorded voices under the Telephone Consumer Protection Act. Its consent requirements and exceptions require a review of the actual call. Do not assume that interactive speech falls outside these rules. See [FCC Declaratory Ruling 24-17](https://docs.fcc.gov/public/attachments/FCC-24-17A1_Rcd.pdf).

Telemarketing may also require a separate review under the FTC's Telemarketing Sales Rule. The FTC has addressed AI-enabled calls and recordkeeping in its [telemarketing rule update](https://www.ftc.gov/news-events/news/press-releases/2024/03/ftc-implements-new-protections-businesses-against-telemarketing-fraud-affirms-protections-against-ai).

Have a qualified reviewer determine the rules that apply to the intended recipients, purpose, and locations. This guide does not classify a campaign, select an exemption, or determine the recording rules for a jurisdiction.

## Assemble the calling review

| Review item | Record before release |
| - | - |
| Purpose and parties | The business responsible for the call, the message, and whether the purpose changes during the interaction. |
| Recipients | The intended audience, relevant locations, and the source of the contact details. |
| Contact permission | The basis approved for this use, the scope of any consent, and where the evidence can be retrieved. |
| Identification and notices | The approved business identification, automation notice, and any required contact information. |
| Recording and transcription | Whether each is enabled, its purpose, the notice or consent approach, and what happens if a person declines. |
| Stopping contact | How a refusal or withdrawal reaches the system that determines eligibility for future calls. |
| Data handling | Who may access the evidence and conversation records, with the reviewed retention and deletion process. |

Do not assume a purchased contact list, an existing account, or permission for another channel covers the proposed call. Give the reviewer the actual collection wording and evidence rather than a generic consent label.

## Verify the intended controls

<Steps>
  <Step title="Review eligibility before calling">
    Design the calling integration to check the approved contact criteria before initiation. Prompt instructions are not a substitute for a check in the system that places the call.
  </Step>

  <Step title="Check notices and refusal paths">
    Review the opening, recording decision, request to stop, and request for another contact method. Use synthetic scenarios first. Verify the actual integration when its runtime path is released.
  </Step>

  <Step title="Trace a withdrawal through the workflow">
    Confirm which system records the request and prevents further contact within its reviewed scope. Include queued work and connected systems in the review; do not assume a conversation note updates them.
  </Step>

  <Step title="Keep retrievable evidence">
    Keep the approved wording and version, relevant permission evidence, control checks, and release decision under appropriate access controls. Have the reviewer set the retention requirements for this evidence.
  </Step>
</Steps>

Use the [AI disclosure guide](/agents-platform/legal/ai-disclosure) to review identity and automation notices. Use the [Privacy Policy](https://threetone.in/privacy-policy) for Threetone's current information-handling policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is permission to call the same as permission to record?">
    Review them separately. The intended use, applicable rules, and the person's choices may differ. Do not make one consent field stand in for every decision.
  </Accordion>

  <Accordion title="Does an AI notice make a call permissible?">
    A notice does not resolve whether the call may be placed. Review contact permission, applicable calling requirements, and the message itself before release.
  </Accordion>

  <Accordion title="Can the prompt manage requests to stop calling?">
    The prompt can describe the intended response. A reliable workflow also needs a verified mechanism to record the request and apply it to future contact. This guide does not claim that such a mechanism is currently supplied by Threetone.
  </Accordion>
</AccordionGroup>


# Healthcare deployment review
Source: https://docs.threetone.in/agents-platform/legal/healthcare

Assess a proposed healthcare workflow, its data flows, required agreements, safeguards, and service suitability before introducing patient information.

Start healthcare prototypes with wholly synthetic data. Before introducing patient information, have the responsible legal, privacy, security, and clinical reviewers assess the intended task and every service involved.

<Warning>
  This guide does not establish Threetone's suitability for HIPAA-regulated data or provide a business associate agreement. Confirm the supported service scope and required executed agreements with Threetone before sending protected health information. A plan name, configuration setting, or provider relationship does not establish that approval.
</Warning>

## Determine the parties and data

For a U.S. HIPAA review, determine whether the organization is a covered entity or business associate and whether the proposed workflow involves protected health information (PHI). HHS explains that business associate status depends on the function performed and the information handled, including services provided through AI systems. See [HHS business associate guidance](https://www.hhs.gov/hipaa/for-professionals/privacy/guidance/business-associates/index.html).

Map the actual information in audio, transcripts, prompts, knowledge documents, tool requests, logs, and exports. A workflow described as scheduling or administration still needs this assessment; its label does not establish the classification of its data.

## Confirm agreements and service scope

HHS explains that a cloud service handling electronic PHI on behalf of a covered entity or business associate can itself be a business associate, including when it cannot decrypt the information. Its guidance addresses the business associate agreement and responsibilities for the services involved. See [HHS guidance on HIPAA and cloud computing](https://www.hhs.gov/hipaa/for-professionals/special-topics/health-information-technology/cloud-computing/index.html).

For the proposed workflow, record which party contracts with each service and how any required downstream agreements are handled. Check the actual scope: environments, storage, model and speech processing, connected tools, support access, and permitted data use. Do not infer that an agreement for one service covers every connected service.

## Prepare the deployment review

<Steps>
  <Step title="Bound the task">
    Describe the intended administrative or clinical task, expected users, data categories, and excluded actions. For a clinical workflow, obtain a separate clinical safety review and define who handles situations outside the approved task.
  </Step>

  <Step title="Trace each data path">
    Identify where data enters, which services process it, where copies remain, and who can access them. Include troubleshooting logs and exports rather than reviewing only the conversation screen.
  </Step>

  <Step title="Evaluate safeguards">
    Review authentication, authorization, audit evidence, transmission and storage protection, recovery, and incident handling. Obtain evidence for the intended environment instead of treating a prompt or interface label as a safeguard.
  </Step>

  <Step title="Resolve retention and deletion">
    Identify the applicable recordkeeping requirements and the systems responsible for retaining or deleting each copy. Confirm what the actual controls do before describing a retention field as an enforced policy.
  </Step>

  <Step title="Record the release decision">
    Keep the agreements, assessment, control evidence, unresolved issues, and responsible reviewers together. Do not introduce PHI while required agreements or service suitability remain unresolved. Confirm runtime availability separately before an operational pilot.
  </Step>
</Steps>

For regulated entities, the HIPAA Security Rule addresses safeguards and risk analysis; a contract alone does not complete that work. Use the [HHS Security Rule summary](https://www.hhs.gov/hipaa/for-professionals/security/laws-regulations/index.html) with the responsible reviewers to determine the applicable requirements.

Review [access and credentials](/agents-platform/configure/authentication/overview), [stored conversation inspection](/agents-platform/monitor/conversations), and [current execution availability](/agents-platform/overview#current-availability) when collecting technical evidence. These product guides describe configuration and inspection, not healthcare approval.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does a paid plan include a BAA?">
    Do not assume one is included. Confirm whether the proposed service is supported and whether the required agreement has been executed with the correct parties and scope before using PHI.
  </Accordion>

  <Accordion title="Does encryption remove the need for the review?">
    No. HHS cloud guidance addresses business associate responsibilities even for encrypted data that the service cannot read. Review the agreements, data flows, and safeguards together.
  </Accordion>

  <Accordion title="Can I paste a patient conversation into a support request?">
    Use synthetic examples while the service scope is unresolved. For an approved workflow, follow its authorized support and data-handling process rather than sending patient information through an unreviewed channel.
  </Accordion>
</AccordionGroup>


# Legal review
Source: https://docs.threetone.in/agents-platform/legal/overview

Prepare a deployment review covering consent, AI disclosure, sensitive data, applicable agreements, and Threetone's current policies.

Review the intended workflow before connecting an agent to people or sensitive data. Identify who operates it, who it contacts, what information it handles, and which services receive that information.

<Note>
  These guides help prepare a review with your legal, privacy, and security advisers. They do not amend the published policies, establish compliance, or approve a deployment. Check [current execution availability](/agents-platform/overview#current-availability) separately.
</Note>

## Current policies

Use the canonical pages for the current policy text rather than a copied version in a prompt or deployment checklist.

| Document | Use it to review |
| - | - |
| [Terms of Service](https://threetone.in/terms-of-use) | The terms governing use of Threetone. |
| [Privacy Policy](https://threetone.in/privacy-policy) | How information is handled and how to raise a privacy request. |
| [Data deletion instructions](https://threetone.in/data-deletion) | How to identify an account, business, or set of records in a deletion request. |

For a deletion request, contact [legal@threetone.in](mailto:legal@threetone.in). Identify the associated account or business and the scope of the request. The process includes identity or authority checks and confirmation of the records involved. Do not send credentials or entire conversations. Follow the published instructions for the review process; this guide does not set a completion deadline.

## Choose a review

<CardGroup>
  <Card title="Call consent" icon="phone" href="/agents-platform/legal/call-consent">
    Review the intended recipients, calling purpose, consent evidence, and recording decisions.
  </Card>

  <Card title="AI disclosure" icon="message" href="/agents-platform/legal/ai-disclosure">
    Make the business identity, use of automation, and available assistance clear.
  </Card>

  <Card title="Healthcare" icon="shield" href="/agents-platform/legal/healthcare">
    Assess the data, parties, agreements, and safeguards before a healthcare use case.
  </Card>
</CardGroup>

## Prepare the review record

<Steps>
  <Step title="Describe one intended use">
    Record the business owner, task, channel, audience, locations, and agent version. Include the actions the agent may take and who handles exceptions.
  </Step>

  <Step title="Map information and access">
    List inputs, recordings, transcripts, knowledge sources, tool payloads, logs, and exports. Identify the recipient of each data flow and the people who can retrieve it.
  </Step>

  <Step title="Resolve notices and agreements">
    Have the appropriate reviewers determine the applicable requirements. Record the approved notices, consent approach, contractual scope, and unresolved restrictions for this use case.
  </Step>

  <Step title="Verify the controls before release">
    Use synthetic data to check access, disclosure, refusal handling, and data handling. When a runtime path is available, verify it separately. Keep unresolved items with an owner and a release decision.
  </Step>
</Steps>

Reopen the review when the audience, purpose, channel, data categories, connected services, or material agent behavior changes. Keep the review evidence in an access-controlled business system, not in this public documentation repository.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this section replace our legal review?">
    No. The relevant requirements depend on the parties, intended use, and applicable jurisdictions. Use these guides to prepare the facts and questions for qualified advisers.
  </Accordion>

  <Accordion title="Does an Enterprise plan include every required agreement?">
    A plan name does not establish the scope of an agreement or approval for a regulated use case. Confirm the executed documents and covered services with Threetone before relying on them.
  </Accordion>

  <Accordion title="Does disconnecting an integration delete its records?">
    Do not treat access revocation as deletion confirmation. Follow the published deletion instructions to identify the records and parties involved, including copies held by another business or service.
  </Accordion>
</AccordionGroup>


# Data collection
Source: https://docs.threetone.in/agents-platform/monitor/analysis/data-collection

Define primitive analysis fields and inspect values already stored with a conversation.

Data collection defines the facts you want a conversation review to extract. Use a narrow field such as a requested appointment date instead of asking for an unrestricted copy of the transcript.

<Note>
  Field definitions persist, and conversation reads expose stored collection results. Automatic extraction and rerunning analysis are unavailable in the current analysis execution path.
</Note>

You need agent edit access. Definitions live in `platform_settings.data_collection`, keyed by a stable field ID.

| Field | What to author |
| - | - |
| `type` | `boolean`, `string`, `integer`, or `number` |
| `description` | The fact to extract and how to recognize it |
| `name` | An optional readable label |
| `enum` | Optional allowed string values |
| `llm` | Optional per-field analysis model preference |

<Steps>
  <Step title="Define a small field set">
    Choose stable IDs and primitive types. Object and array results are not supported by this property contract. Include only information needed for the review.
  </Step>

  <Step title="Save and inspect the definition">
    Use Analysis settings or an [agent draft](/api-reference/agents-platform/create-agent-draft). `data_collection_scopes` can set each field to `conversation` or `agent`; missing entries default to conversation scope.
  </Step>

  <Step title="Inspect stored values">
    Read `analysis.data_collection_results` from [conversation details](/api-reference/agents-platform/get-conversation-details). Compare `value` and `rationale` with the transcript. Keep missing values distinct from false, zero, and an empty string.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Can one property return a nested customer object?">No. Use separate primitive fields with clearly defined purposes.</Accordion>
  <Accordion title="Does saving a field backfill old conversations?">No. The saved definition does not trigger extraction or update prior results.</Accordion>
</AccordionGroup>


# Conversation analysis
Source: https://docs.threetone.in/agents-platform/monitor/analysis/overview

Configure evaluation and data collection, then inspect analysis already stored with conversation records.

Conversation analysis has two distinct parts: the instructions you save for a review and the results stored with a conversation. Keep both tied to the configuration version used for that record.

<Note>
  Evaluation criteria and data-collection configuration can be saved. Conversation details can return existing analysis. The analysis and evaluation run routes currently read the conversation without computing new results.
</Note>

| Setting under `platform_settings` | Purpose |
| - | - |
| `evaluation.criteria` | Definitions of successful outcomes |
| `data_collection` | Named, typed extraction definitions |
| `analysis_llm` | Saved default analysis model preference |
| `summary_language` | Saved language preference for analysis output |

You need agent edit access to author settings, or conversation read access to inspect existing results.

<Frame>
  <img alt="Recording pending for Review conversation analysis settings. No playable video is available yet." />
</Frame>

<Steps>
  <Step title="Define the review">
    Write [success criteria](/agents-platform/monitor/analysis/success-evaluation) and [data fields](/agents-platform/monitor/analysis/data-collection) that answer a concrete question. Preserve existing `analysis_items` references when reviewing a migrated configuration.
  </Step>

  <Step title="Save a reviewable configuration">
    Use the agent's Analysis settings or the API draft workflow. Read the saved settings back through [versions and drafts](/agents-platform/deploy/versioning). Configuration acceptance does not run analysis.
  </Step>

  <Step title="Inspect existing evidence">
    Read [conversation details](/api-reference/agents-platform/get-conversation-details). Check `analysis`, its criteria results, collected values, and rationales against the transcript. Treat absent results as unmeasured.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for analysis field configuration. This illustration is not a product screenshot." />
</Frame>

<AccordionGroup>
  <Accordion title="Does Run analysis refresh an older record?">No. The current route returns an existing conversation rather than starting computation.</Accordion>
  <Accordion title="Do the general Analysis toggles all save?">Topic discovery, sentiment analysis, and source attribution are local preview controls. They do not establish saved or running analysis jobs.</Accordion>
</AccordionGroup>


# Find conversations for review
Source: https://docs.threetone.in/agents-platform/monitor/analysis/searching

Use supported conversation list filters while text and semantic message search remain unavailable.

Find review candidates with structured filters, then inspect the transcript for evidence. Keep the selection rule with your findings so another reviewer can locate the same population.

<Note>
  Text search and smart search currently return empty placeholder results. They do not search saved messages. An empty response from either route cannot establish that a phrase or behavior never occurred.
</Note>

You need workspace read access and a permitted credential for [List conversations](/api-reference/agents-platform/list-conversations).

| Filter | Use |
| - | - |
| `agent_id`, `branch_id`, `version_id` | Select the relevant configuration |
| `call_start_after_unix`, `call_start_before_unix` | Bound the review interval |
| `user_id` | Inspect an end user's stored history |
| `text_only` | Select the conversation mode |
| `page_size`, `cursor` | Read the result set in pages |

<Steps>
  <Step title="Start with a narrow population">
    Choose the agent and time interval first. Add a branch or version filter only when you know the stored identifier you need.
  </Step>

  <Step title="Follow pagination">
    Read `conversations`, `has_more`, and `next_cursor`. Use the returned cursor rather than constructing one or assuming the first page contains every record.
  </Step>

  <Step title="Read the evidence">
    Open [conversation details](/api-reference/agents-platform/get-conversation-details). Record the matching turns and identifiers. Describe any manual transcript search as your review method, not platform search output.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Can I use the users search box as message search?">No. The conversation-users API's `search` parameter matches a complete user identifier.</Accordion>
  <Accordion title="What should I check when no records appear?">Check workspace access, time boundaries, IDs, pagination, and whether relevant records exist.</Accordion>
</AccordionGroup>


# Sentiment analysis
Source: https://docs.threetone.in/agents-platform/monitor/analysis/sentiment

Interpret existing sentiment aggregates while distinguishing them from planned sentiment generation.

Sentiment can help prioritize a conversation for human review. It should not replace checking what happened or deciding whether the user's request was resolved.

<Note>
  Automatic sentiment generation is planned. The Analysis sentiment toggle is local preview state. Existing valid sentiment data can contribute to the conversation-users API, but enabling the toggle does not create new scores.
</Note>

With conversation read access, request [conversation users](/api-reference/agents-platform/list-conversation-users) for a defined agent and time window.

| Response field | Interpretation |
| - | - |
| `sentiment.scored_conversation_count` | Records contributing usable sentiment results |
| `positive_count`, `neutral_count`, `negative_count` | Counts within that scored population |
| `average_sentiment_score` | Average of stored sentiment scores, or null without scores |
| `average_frustration_score` | Average of stored frustration scores, or null without scores |
| `most_frustrated_conversations` | References ordered using existing frustration results |

Check coverage before comparing users. Ten conversations with one scored record do not support the same interpretation as ten scored conversations.

Open the referenced [conversation record](/agents-platform/monitor/conversations) and review the transcript. Record the concrete issue in [triage](/agents-platform/monitor/triage) when action is needed. Do not infer a diagnosis, verified personal trait, or future behavior from a sentiment label.

Future scoring needs a released producer, documented score meaning, and a way to review missing or disputed results.

<AccordionGroup>
  <Accordion title="Does null average sentiment mean neutral?">No. It means there are no usable scores contributing to that average.</Accordion>
  <Accordion title="Can Run analysis fill missing sentiment?">No. The current route only reads existing conversation data.</Accordion>
</AccordionGroup>


# Success evaluation
Source: https://docs.threetone.in/agents-platform/monitor/analysis/success-evaluation

Author precise outcome criteria and interpret saved evaluation results without treating configuration as execution.

A success criterion states what the transcript must demonstrate. For example, a booking assistant should confirm the requested date before requesting a reservation.

<Note>
  Criteria authoring and stored-result reads are available. [Run conversation evaluation](/api-reference/agents-workspace-analytics/run-conversation-evaluation) currently returns the existing record; it does not calculate a fresh score.
</Note>

With agent edit access, review `platform_settings.evaluation.criteria`. Each criterion has a stable `id`, a `name`, and a `conversation_goal_prompt` of up to 2,000 characters.

| Field | Saved meaning |
| - | - |
| `scoring_mode` | `binary` by default, or `numeric_uniform` |
| `scope` | `conversation`, or the defining `agent`'s portion |
| `max_score` | Numeric scale ceiling, default 100 |
| `score_instructions` | Optional numeric scoring rubric |
| `llm` | Optional per-criterion model preference |

<Steps>
  <Step title="Write an observable criterion">
    Describe the required evidence and how to handle missing information. Keep unrelated outcomes in separate criteria so one success cannot hide another failure.
  </Step>

  <Step title="Preserve the criteria list">
    Save through the Analysis editor or [agent draft](/api-reference/agents-platform/create-agent-draft). Review the complete criteria list and identifiers before saving a replacement.
  </Step>

  <Step title="Review stored results">
    Read `analysis.evaluation_criteria_results` in [conversation details](/api-reference/agents-platform/get-conversation-details). Inspect each result and rationale, plus `score` and `max_score` when present. Compare them with the relevant transcript turns.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Is an unknown result a failure?">Keep unknown separate from success and failure. It does not provide enough evidence to claim the criterion passed.</Accordion>
  <Accordion title="Does changing a criterion rescore history?">No. Saving a definition does not recalculate existing conversations.</Accordion>
</AccordionGroup>


# Analytics
Source: https://docs.threetone.in/agents-platform/monitor/analytics

Interpret dashboard analytics with consistent filters and distinguish them from unavailable public workspace reports.

Analytics can summarize recorded activity, but the meaning of an empty chart depends on where its data comes from.

<Note>
  The main Agents dashboard has real analytics reads backed by Tinybird. Availability depends on the deployment's analytics configuration and recorded data. The public workspace usage and API-request reports currently return empty placeholder results. The per-agent analytics page is also unfinished.
</Note>

Use an account with access to the workspace and an interval with known conversation records.

<Steps>
  <Step title="Set a comparable interval">
    Open the [Agents dashboard](https://threetone.in/app/agents). Keep the date range, time zone, and agent filter consistent when comparing periods. Note those choices with any exported findings.
  </Step>

  <Step title="Inspect counts and costs together">
    Dashboard reads include conversation counts, duration, cost, average cost, and LLM cost. Compare totals with the number of represented conversations before interpreting an average.
  </Step>

  <Step title="Check an unexpected empty result">
    Compare the interval with [saved conversations](/agents-platform/monitor/conversations). Missing analytics credentials or a request failure can produce empty results. An empty chart alone does not establish zero activity.
  </Step>
</Steps>

[Workspace usage](/api-reference/workspace/get-workspace-usage) and [API requests](/api-reference/workspace/list-api-requests) are public contracts, but their current empty responses cannot support an audit or cost calculation. Dashboard-only routes are not a public API integration contract.

<Frame>
  <img alt="Screenshot pending for workspace analytics. This illustration is not a product screenshot." />
</Frame>

<AccordionGroup>
  <Accordion title="Are analytics totals a billing statement?">Treat them as operational measurements. Reconcile charges through the billing workflow rather than assuming chart totals define the invoice.</Accordion>
  <Accordion title="Can I reproduce the dashboard through public reports?">Not currently. The public workspace reports do not implement the dashboard's data reads.</Accordion>
</AccordionGroup>


# Command-line workflows
Source: https://docs.threetone.in/agents-platform/monitor/cli

Use public API examples from a terminal while tracking the unreleased Threetone product CLI.

A dedicated Threetone product CLI is not released. There is no verified install package or set of Threetone login, deployment, or monitoring commands to use.

You can use a standard HTTP client with the public API. Start with a read operation so you can verify authentication and workspace scope without changing a resource.

<Steps>
  <Step title="Choose a public operation">
    Open [List conversations](/api-reference/agents-platform/list-conversations) or [List tests](/api-reference/tests/list-tests). Use the operation's generated cURL example and documented parameters.
  </Step>

  <Step title="Supply a permitted credential">
    Follow [API authentication](/api-reference/authentication). Keep your key in an appropriate local secret store or environment variable. Do not paste it into a shared script, recorded terminal, or issue report.
  </Step>

  <Step title="Handle the full response">
    Check the HTTP status, inspect the JSON body, and follow returned cursors for paginated reads. Preserve error details needed for diagnosis after removing private values.
  </Step>
</Steps>

A terminal client uses the same permissions and availability rules as other API clients. It cannot bypass the test, deployment, or conversation execution gates. Build automation around documented operations rather than guessed product commands.

<AccordionGroup>
  <Accordion title="Is the documentation CLI a Threetone client?">No. Documentation development tools build this site; they do not manage your Threetone agents.</Accordion>
  <Accordion title="Can a script safely retry every failed write?">Do not assume a write is idempotent. Check the operation contract and read back state before repeating an ambiguous mutation.</Accordion>
</AccordionGroup>


# Inspect conversations
Source: https://docs.threetone.in/agents-platform/monitor/conversations

List saved conversation records, inspect transcripts and summaries, and retrieve audio when a recording is available.

Use saved conversation records to inspect what was captured and identify the agent configuration associated with a record. This guide reads existing data; it does not initiate a new conversation or generate analysis.

<Frame>
  <img alt="Recording pending for Inspect a saved conversation. No playable video is available yet." />
</Frame>

## Before you begin

You need access to the workspace and an existing conversation record. Use a permitted API key for API reads. Sample records can help you understand the response shape, but they are not evidence of a real conversation.

## Choose a representation

| Operation | Use it when |
| - | - |
| [List conversations](/api-reference/agents-platform/list-conversations) | You need a filtered, paginated set of saved records. |
| [Conversation details](/api-reference/agents-platform/get-conversation-details) | You need the transcript, metadata, and any analysis already stored. |
| [Conversation summary](/api-reference/agents-platform/get-conversation-summary) | You need a smaller response and can account for omitted messages. |
| [Conversation audio](/api-reference/agents-platform/get-conversation-audio) | A recording exists and you are permitted to retrieve it. |

## Inspect a record

<Steps>
  <Step title="Filter the list">
    Choose the agent, branch, version, or time filters relevant to your review. Set `page_size` and request the first page.

    The response includes `conversations`, `has_more`, and `next_cursor`. When more records are available, pass the returned cursor to the next request rather than assuming the first page is complete.
  </Step>

  <Step title="Read the details">
    Open the intended conversation ID. Review its status, metadata, transcript, and associated `branch_id` and `version_id` when present.

    Use those identifiers to connect the record to the saved configuration. A conversation status describes that record; it does not establish that all current execution paths are available.
  </Step>

  <Step title="Check summary coverage">
    The summary defaults to a maximum of 40 messages. Inspect `messages_omitted` and request details when the summary is not sufficient for the review.
  </Step>

  <Step title="Retrieve audio only when available">
    Check the record's audio availability before requesting a recording. A transcript does not imply that audio was recorded or retained.
  </Step>

  <Step title="Record the evidence">
    Keep the conversation, agent, branch, and version IDs with the issue you observed. Use that evidence to propose a prompt, knowledge, or tool change without sharing private transcripts publicly.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for An explicitly labeled synthetic conversation with transcript and version metadata. This illustration is not a product screenshot." />
</Frame>

## Current analysis and search limits

Message text and semantic search currently have placeholder implementations. Agent topic results are also placeholders. Analysis and evaluation run routes currently read the existing conversation rather than perform new analysis. Do not rely on these routes to discover records or calculate review results.

Use filtered conversation lists and direct record reads for this workflow. Treat any `analysis` in a detail response as stored data, and inspect its provenance before using it to make decisions.

## Deletion and privacy

[Delete conversation](/api-reference/agents-platform/delete-conversation) is a distinct operation that should be used only for the intended record by an authorized caller. A deletion response or a saved retention setting is not a guarantee of deletion from backups or every connected service.

Automatic retention and zero-storage enforcement are not established by the documented implementation. Do not rely on those settings to meet your data-deletion requirements.

## Troubleshooting

If the list is empty, check filters, pagination, workspace access, and whether records actually exist. If details or audio are unavailable, check the identifier, permission, and recording status. See [API errors](/api-reference/errors) for request diagnostics and [versions and drafts](/agents-platform/deploy/versioning) for configuration traceability.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does every transcript have an audio recording?">No. Check audio availability and access before retrieving a recording.</Accordion>
  <Accordion title="Does a summary contain every message?">The summary has a message limit. Inspect messages\_omitted and read full details when needed.</Accordion>
  <Accordion title="Does an analysis run route compute new results?">The documented route reads the existing conversation. Treat returned analysis as stored data and inspect its provenance.</Accordion>
</AccordionGroup>


# Cost optimization
Source: https://docs.threetone.in/agents-platform/monitor/cost-optimization

Prepare measurable cost changes using model selection, context limits, and consistent historical evidence.

Optimize for the cost of a satisfactory outcome. A smaller prompt or cheaper model is useful only if it still meets the task's requirements.

<Note>
  Both [expected LLM usage](/api-reference/agents-platform/calculate-expected-llm-usage) endpoints, including the [agent-specific estimate](/api-reference/agents-platform/calculate-expected-llm-usage-for-an-agent), currently return an unavailable error. Do not use them as price quotes or savings estimates.
</Note>

Begin with a saved configuration, representative scenarios, and any trustworthy historical cost data available in your deployment.

| Configuration choice | Review question |
| - | - |
| `conversation_config.agent.prompt.llm` | Does an available model meet the same task requirements? |
| `conversation_config.agent.prompt.max_tokens` | Is the output limit appropriate for the expected answer? |
| Prompt and knowledge context | Can repeated or irrelevant content be removed? |
| Backup model configuration | Does the comparison account for possible fallback choices? |

<Steps>
  <Step title="Establish a baseline">
    Record the configuration version and [analytics](/agents-platform/monitor/analytics) interval. Keep counts and total cost together; avoid comparing averages from different populations.
  </Step>

  <Step title="Prepare one change">
    Use [available models](/api-reference/agents-platform/list-available-llms) and preserve a reviewable draft. Reuse the same [test definitions](/agents-platform/monitor/testing).
  </Step>

  <Step title="Wait for measurable execution">
    Record savings as unmeasured until comparable runtime results exist. Publication acceptance and lower configured limits do not prove lower total cost.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Does max_tokens cap the full conversation bill?">No. A generation limit does not account for every request, input token, analysis step, or connected service.</Accordion>
  <Accordion title="Can public workspace usage validate savings?">Not currently. That report returns placeholder rows. Use verified deployment data and keep its scope explicit.</Accordion>
</AccordionGroup>


# Experiments
Source: https://docs.threetone.in/agents-platform/monitor/experiments

Prepare a controlled agent comparison with a fixed scenario set, version references, and explicit release criteria.

An experiment compares a proposed configuration with a baseline using the same scenarios and scoring rules. Planning that comparison is useful before automated execution becomes available.

<Note>
  Threetone does not currently provide an experiment resource or an A/B experiment runner. Traffic allocation and automated tests remain subject to execution gates. This page describes a review plan, not a dashboard workflow.
</Note>

Start with an existing agent and a narrow hypothesis, such as whether a shorter instruction improves a specific handoff decision.

<Steps>
  <Step title="Record the baseline">
    Keep the agent, branch, and immutable version IDs in your review notes. Use [versions and drafts](/agents-platform/deploy/versioning) to distinguish a saved proposal from a published snapshot.
  </Step>

  <Step title="Define a controlled change">
    Change one instruction or model choice. Prepare the same [test definitions](/agents-platform/monitor/testing), synthetic inputs, and scoring rubric for both candidates.
  </Step>

  <Step title="Set the decision rule">
    Record the required outcomes, unacceptable failures, sample size, and cost or latency measurements needed. Leave result cells unmeasured until comparable execution evidence exists.
  </Step>
</Steps>

Before runtime comparisons are released, review configuration diffs and scenario coverage. Neither successful publication nor a manual prompt review establishes a measured improvement.

<AccordionGroup>
  <Accordion title="Can deployment traffic act as an experiment runner?">No. The current deployment execution gate applies, and there is no experiment assignment or statistical reporting workflow.</Accordion>
  <Accordion title="Can voice candidates be published for comparison?">Voice and custom-model publication are unavailable. Preserve eligible changes as drafts and record the blocked stage.</Accordion>
</AccordionGroup>


# Hosted MCP
Source: https://docs.threetone.in/agents-platform/monitor/hosted-mcp

Distinguish external MCP server registration from a future first-party agent-management MCP service.

There is no verified first-party hosted MCP service for managing Threetone agents. Do not configure a guessed Threetone MCP URL or assume a documentation search integration can modify workspace resources.

The existing [MCP server integration](/agents-platform/configure/integrations/mcp-servers) stores connections to external servers. It is a different workflow.

| Available configuration | What it establishes |
| - | - |
| Server URL and `transport` | A saved external endpoint using `SSE` or `STREAMABLE_HTTP` |
| Credential references and headers | Connection configuration to review |
| `approval_policy` and tool overrides | Saved approval intent |
| `conversation_config.agent.prompt.mcp_server_ids` | References in agent configuration |

[Server reads](/api-reference/agents-platform/get-mcp-server) can confirm saved configuration. They do not prove connectivity or tool execution. Connection testing is disabled, and [tool discovery](/api-reference/agents-platform/list-mcp-server-tools) returns an unavailable result.

## Prepare for a future service

Before connecting an assistant to an agent-management service, require a published endpoint, supported authentication, workspace scoping, and an explicit list of read and write tools. Review how it requests approval for publication, deletion, and credential changes.

Keep the current public API as the reference for supported management operations. No MCP client configuration or SDK import is required for those API workflows.

<AccordionGroup>
  <Accordion title="Does adding a server host it in Threetone?">No. Registration stores an external server connection; it does not provision or operate that server.</Accordion>
  <Accordion title="Does a saved approval policy enforce confirmations?">Runtime enforcement still needs a released and verified execution path.</Accordion>
</AccordionGroup>


# Insights
Source: https://docs.threetone.in/agents-platform/monitor/insights/overview

Turn saved conversations and available analytics into reviewable findings with a clear sample, source, and follow-up.

An insight is a finding you can trace to evidence and act on. Use existing conversation records and available dashboard measurements to identify a specific improvement, then keep the source and review method with the finding.

## Choose evidence that exists

| Evidence | Current boundary |
| - | - |
| [Saved conversations](/agents-platform/monitor/conversations) | Read transcripts, metadata, and analysis already present in a record. |
| [Workspace analytics](/agents-platform/monitor/analytics) | Dashboard metrics depend on the deployment's analytics configuration and recorded data. |
| [Topics](/agents-platform/monitor/topics) | Automated topic discovery is unavailable; prepare a taxonomy through manual review. |
| [Analysis](/agents-platform/monitor/analysis/overview) | A saved definition or existing result is not proof of a new analysis run. |
| [Real-time insights](/agents-platform/monitor/insights/real-time-insights) | The current public live read is a workspace counter, not a transcript or insight stream. |

Public workspace usage and API-request reports currently return placeholder results. Do not use an empty report to conclude that there was no activity or that a cost is zero.

## Produce a reviewable finding

<Steps>
  <Step title="Define the question">
    Choose one question, such as why users abandon a setup step. Record the agent, time interval, time zone, and selection rule. Follow pagination when gathering saved records.
  </Step>

  <Step title="Review the underlying records">
    Read full details when summaries omit messages. Separate what the user requested, what the agent did, and the observed outcome. Preserve unknown outcomes rather than counting them as failures or successes.
  </Step>

  <Step title="Record evidence and uncertainty">
    Keep safe conversation identifiers, the reviewed sample size, the matching cases, and any missing data. Separate a direct observation from a proposed explanation. A small sample can suggest a change without establishing a population-wide rate.
  </Step>

  <Step title="Assign and recheck the change">
    Give the proposed prompt, source, or configuration change an owner. Record the version used before and after it, then compare the same review criteria when new verified records become available.
  </Step>
</Steps>

Keep customer transcripts in access-controlled review systems. Share only the excerpts needed to explain the finding and follow the workspace's [privacy review](/agents-platform/monitor/privacy/overview).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this page describe an automated insight generator?">No. It describes an evidence review workflow using current reads. Automated topic discovery and analysis execution have separate implementation requirements.</Accordion>
  <Accordion title="Can I compare periods with different filters?">Record the difference and account for it. A change in agent, time zone, sampling, or data availability can explain a changed metric without a change in agent quality.</Accordion>
</AccordionGroup>


# Real-time insights
Source: https://docs.threetone.in/agents-platform/monitor/insights/real-time-insights

Interpret the current workspace live counter and prepare freshness, access, and event requirements for future live insights.

The current live conversation read returns a count from the workspace's shared cache. It does not identify sessions, stream transcripts, calculate sentiment, or produce live recommendations.

## Read the available signal

Use [Get live conversation count](/api-reference/agents-platform/get-live-conversation-count) with a permitted workspace API key. The current implementation ignores `agent_id` and `agent_ids`; the result remains workspace-wide even when those parameters are supplied.

| Result | Interpretation |
| - | - |
| A count is returned | A cached workspace value was read. Confirm the producer and freshness before operational reliance. |
| Zero is returned | The cached value may be zero, or the cache key may be absent. This alone does not prove there are no active sessions. |
| An unavailable error is returned | The cache may be unavailable or its stored value invalid. Preserve the error state instead of displaying a fabricated zero. |

## Design a useful live display

<Steps>
  <Step title="Label the scope">
    Display the selected workspace and identify the value as a workspace count. Do not present it as an agent-specific metric or a list of active calls.
  </Step>

  <Step title="Expose freshness and failures">
    Record when your application last completed a successful read. This is a fetch time, not proof of when the underlying counter changed. Use a bounded refresh policy and display stale or unavailable state after failed reads.
  </Step>

  <Step title="Verify the producer before alerting">
    In a deployment with a supported runtime, confirm that authorized test sessions change the counter as expected and that ended sessions are reconciled. Establish operational thresholds only after the counter's behavior and freshness are understood.
  </Step>
</Steps>

The saved `monitoring_enabled` and `monitoring_events` fields do not establish a subscribable live event stream. Future transcript or insight streaming needs a released event schema, conversation-level authorization, delivery behavior, and retention policy. Review [real-time monitoring](/agents-platform/monitor/real-time-monitoring) and [WebSocket preparation](/agents-platform/deploy/server/websockets).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I alert on zero as proof that all conversations ended?">Not without additional evidence. A missing cache key also returns zero, and the read does not report producer freshness.</Accordion>
  <Accordion title="Will enabling monitoring create a live transcript dashboard?">No. Saved preferences are separate from a working producer, transport, authorization path, and interface.</Accordion>
</AccordionGroup>


# Merge proposals
Source: https://docs.threetone.in/agents-platform/monitor/merge-proposals

Review a branch merge preview and prepare an approval record without assuming a proposal-management workflow.

A merge review should explain what changes, which branch receives the change, and what evidence supports it. The API provides branch previews and merge operations for this review.

<Note>
  Proposal creation, reviewer approvals, and proposal comments are planned. The dashboard merge-review action is not connected. Use the public preview API and keep the human review record in your own review process.
</Note>

You need access to the agent and distinct source and target branches. The supported merge direction is a non-main source branch into main.

<Steps>
  <Step title="Identify the proposed change">
    Record the source and main branch IDs, current version IDs, reason for the change, and any [triage ticket](/agents-platform/monitor/triage).
  </Step>

  <Step title="Inspect the merge preview">
    Request [Preview merged configuration](/api-reference/agents-platform/preview-merged-configuration) with `target_branch_id`. Read the combined configuration and conflict information. The `force` option changes conflict selection; it is not reviewer approval.
  </Step>

  <Step title="Review publication readiness">
    Refresh the preview if either branch changes. An authorized [merge](/api-reference/agents-platform/merge-agent-branch) must pass publication validation. Managed-model text-only configurations can be eligible; voice and custom-model configurations are blocked.
  </Step>
</Steps>

Publication and deployment are separate. A merged configuration does not demonstrate successful runtime execution. Keep unresolved conflicts and unexecuted tests visible in the review record.

<AccordionGroup>
  <Accordion title="Does a preview modify a branch?">No. Previewing and merging are separate operations. Review the exact inputs again before a merge.</Accordion>
  <Accordion title="Can I require an approval inside Threetone?">There is no released proposal approval resource or connected approval workflow for branch merges.</Accordion>
</AccordionGroup>


# OpenTelemetry
Source: https://docs.threetone.in/agents-platform/monitor/opentelemetry

Request stored trace payloads with conversation details and plan instrumentation without assuming an exporter exists.

Trace data can help correlate a conversation with work performed by its supporting services. Threetone currently exposes a representation for trace data already stored with a conversation.

<Note>
  The conversation read path does not generate spans or export telemetry. No first-party collector setup or end-to-end trace production workflow is released by this API.
</Note>

You need an accessible conversation ID. A transcript alone does not imply that trace data exists.

<Steps>
  <Step title="Request the trace representation">
    Call [Get conversation details](/api-reference/agents-platform/get-conversation-details) with `format=opentelemetry`. The default format is `json`.
  </Step>

  <Step title="Inspect stored coverage">
    Check `otlp_traces` for an existing payload. If it is absent or null, record that trace evidence is unavailable. Repeating the request does not instrument an older conversation.
  </Step>

  <Step title="Keep correlation context">
    Retain the conversation, agent, branch, and version IDs with any trace investigation. Confirm timestamps and the producing service before attributing a delay to a model or tool.
  </Step>
</Steps>

Workspace webhook settings also accept `webhooks.transcript_format=opentelemetry`. Webhook delivery is unavailable, so this preference does not configure a functioning exporter. A future rollout needs verified producers, propagation, sampling, redaction, and a supported destination.

<AccordionGroup>
  <Accordion title="Does the format parameter create traces?">No. It exposes a stored field when present.</Accordion>
  <Accordion title="Can I configure a collector URL here?">There is no verified public collector configuration or automatic export workflow to document yet.</Accordion>
</AccordionGroup>


# Review agent activity
Source: https://docs.threetone.in/agents-platform/monitor/overview

Inspect saved conversations, trace configuration versions, and turn observed problems into reviewable agent changes.

Start with the data that was actually stored. Connect a conversation record to its agent configuration, inspect the available transcript and media, and describe an observed issue before proposing a change.

## Review process

<Steps>
  <Step title="Find the relevant record">Use the conversation list's supported filters and pagination. Check the workspace and identifier before inspecting private data.</Step>
  <Step title="Trace the configuration">Keep the agent, branch, and version identifiers with the record. Compare the stored configuration with the behavior you expected.</Step>
  <Step title="Inspect available evidence">Read details and summary coverage. Retrieve audio only when it exists and you have access. Treat stored analysis as existing data rather than a newly computed result.</Step>
  <Step title="Propose a focused change">Describe the observed behavior, intended outcome, and relevant prompt or resource change. Review the complete configuration diff before publication.</Step>
</Steps>

<CardGroup>
  <Card title="Inspect conversations" icon="comments" href="/agents-platform/monitor/conversations">Read transcripts, summaries, metadata, and available recordings.</Card>
  <Card title="Review versions" icon="code-branch" href="/agents-platform/deploy/versioning">Connect an issue to an identifiable configuration snapshot.</Card>
  <Card title="Improve instructions" icon="pen" href="/agents-platform/configure/agent-behavior/prompting">Revise one clear task or boundary at a time.</Card>
</CardGroup>

## Current limits

Message search, topic aggregation, and generated analysis are not complete implementations in the documented source. Automated response-test execution is also gated. Use direct record reads and manual review for the workflow above; do not infer a measured improvement from configuration acceptance.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use the search routes to find conversations?">The current search implementations are placeholders. Use supported list filters and follow the returned pagination cursor.</Accordion>
  <Accordion title="Does saving a test prove it passed?">No. A saved test definition and a completed invocation are different. Automated execution requires its own released path and recorded results.</Accordion>
</AccordionGroup>


# Audio and redaction
Source: https://docs.threetone.in/agents-platform/monitor/privacy/audio-and-redaction

Review audio and redaction preferences without assuming recording suppression or PII removal is enforced.

Audio, transcripts, and extracted analysis can contain different copies of the same private information. Review each category independently when deciding what a workflow should retain.

<Warning>
  The current fields store configuration intent. Recording suppression, automatic audio deletion, and transcript or audio redaction are not established enforcement guarantees. The Security editor remains a disabled preview.
</Warning>

All fields below belong to `platform_settings.privacy`.

| Field | Default or accepted shape |
| - | - |
| `record_voice` | true |
| `delete_audio` | false |
| `delete_transcript_and_pii` | false |
| `conversation_history_redaction.enabled` | false |
| `conversation_history_redaction.entities` | A list of supported entity names |

Entity choices include `name`, `email_address`, `contact_number`, and narrower names such as `name.name_given`. Accepted values describe intended targets; they do not prove that a detector removed them.

<Steps>
  <Step title="Review the intended data use">
    Decide whether the review needs audio, text, or a small extracted value. Prefer synthetic data while enforcement is pending.
  </Step>

  <Step title="Inspect saved preferences">
    Review the full privacy object through [versions and drafts](/agents-platform/deploy/versioning). Preserve unrelated settings when preparing a change.
  </Step>

  <Step title="Check the actual record">
    [Conversation details](/api-reference/agents-platform/get-conversation-details) expose `has_audio`. Retrieve media only when authorized and available. A transcript does not establish that a recording exists or has been redacted.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Does record_voice=false remove existing audio?">No. The field does not establish historical deletion, and current enforcement is not guaranteed.</Accordion>
  <Accordion title="Can I assume a redacted transcript makes audio safe to share?">No. Inspect and authorize each representation separately before sharing it.</Accordion>
</AccordionGroup>


# Conversation privacy
Source: https://docs.threetone.in/agents-platform/monitor/privacy/overview

Review saved privacy preferences and distinguish configuration from implemented storage and deletion behavior.

Privacy review starts with the data your workflow collects: transcripts, audio, analysis, tool payloads, and copies sent to connected services. Record why each category is needed and who can access it.

<Warning>
  Threetone stores privacy preferences, but automatic retention, redaction, and zero-retention enforcement are not implemented guarantees. The Security editor is a disabled preview. Do not depend on a saved preference to satisfy a storage or deletion requirement.
</Warning>

Agent preferences live under `platform_settings.privacy` and can be reviewed through the API draft workflow.

| Area | Fields to inspect |
| - | - |
| [Retention](/agents-platform/monitor/privacy/retention) | `retention_days`, `apply_to_existing_conversations` |
| [Audio and redaction](/agents-platform/monitor/privacy/audio-and-redaction) | `record_voice`, deletion flags, `conversation_history_redaction` |
| [Zero retention](/agents-platform/monitor/privacy/zero-retention) | `zero_retention_mode` |

<Steps>
  <Step title="Inventory the data">
    List stored records and any downstream copies your own integration creates. Include logs and exported review files in that inventory.
  </Step>

  <Step title="Review the saved intent">
    Inspect privacy fields in the selected configuration. Use [versions and drafts](/agents-platform/deploy/versioning) to preserve a reviewable proposal without claiming enforcement.
  </Step>

  <Step title="Verify each operation's scope">
    For an authorized removal, review [Delete conversation](/api-reference/agents-platform/delete-conversation). Confirm which record is affected and separately account for copies outside that operation.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Does saving privacy settings activate deletion jobs?">No implemented automatic deletion workflow is established by those settings.</Accordion>
  <Accordion title="Does a deleted conversation prove every copy is gone?">No. Account for exports, backups, logs, and connected services separately.</Accordion>
</AccordionGroup>


# Retention settings
Source: https://docs.threetone.in/agents-platform/monitor/privacy/retention

Record retention intent and understand the limits of automatic deletion and historical cleanup.

A retention period states how long a data category should remain available. Treat that policy separately from the mechanism that performs and verifies deletion.

<Warning>
  Automatic retention enforcement and scheduled cleanup are not implemented. Saving the fields below does not start a deletion job or establish a retention deadline.
</Warning>

| Configuration field | Current meaning |
| - | - |
| `platform_settings.privacy.retention_days` | Saved period; default `-1` represents no configured limit |
| `platform_settings.privacy.apply_to_existing_conversations` | Saved historical-application intent; default false |
| Workspace `rag_retention` | Separate saved knowledge-related preference |
| Workspace `conversation_embedding_retention_days` | Separate saved embedding-retention preference |

The [workspace settings contract](/api-reference/agents-platform/update-agents-platform-settings) accepts those workspace preferences. They are not proof of a working cleanup process.

<Steps>
  <Step title="Define the scope">
    Specify the data category, intended period, policy owner, and whether existing records are included. Avoid using one transcript setting as a policy for every copy.
  </Step>

  <Step title="Save intent for review">
    Review the agent's full privacy configuration in an [agent draft](/api-reference/agents-platform/create-agent-draft). Read it back and record enforcement as pending.
  </Step>

  <Step title="Handle explicit removals separately">
    Use [Delete conversation](/api-reference/agents-platform/delete-conversation) only for an identified, authorized record. Keep external exports and connected-service copies in your removal checklist.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Will apply_to_existing_conversations clean up history?">No. It records intent without an implemented historical cleanup job.</Accordion>
  <Accordion title="Does retention_days guarantee deletion on that day?">No. A released scheduler, deletion scope, and verification process are required before making that guarantee.</Accordion>
</AccordionGroup>


# Zero retention
Source: https://docs.threetone.in/agents-platform/monitor/privacy/zero-retention

Record a zero-retention requirement while tracking the enforcement and provider checks needed before relying on it.

Zero retention is a requirement about actual data handling across the full workflow. A single configuration flag cannot establish what every service, provider, or export stores.

<Warning>
  `platform_settings.privacy.zero_retention_mode` is a saved boolean, default false. Threetone does not currently provide an implemented zero-retention guarantee. Setting it to true does not establish suppression of transcripts, audio, analysis, logs, or provider storage.
</Warning>

Use the field to record intent in a reviewed [agent draft](/api-reference/agents-platform/create-agent-draft). Keep the requirement marked unverified until the relevant execution and storage paths support it.

## Release checks to require

| Area | Evidence needed before reliance |
| - | - |
| Conversation storage | Defined behavior for transcript, audio, analysis, and metadata |
| Models and fallbacks | Eligibility of every selected provider and backup path |
| Tools and webhooks | Review of payloads and downstream storage |
| Operations | Defined logs, traces, failure handling, and deletion scope |

The current [platform-managed backup order](/api-reference/agents-platform/get-the-platform-managed-llm-backup-order) does not establish zero-retention filtering. A model's appearance in a catalog is also not evidence of a retention commitment.

Before using data with a strict no-storage requirement, obtain verified handling details for the released workflow. Configuration read-back can confirm the flag was saved; it cannot confirm those details.

<AccordionGroup>
  <Accordion title="Does enabling the flag make all fallback models eligible?">No. Each model and fallback path needs its own verified handling policy and enforced selection rules.</Accordion>
  <Accordion title="Does the flag erase existing conversations?">No. It does not establish retroactive cleanup or removal of prior copies.</Accordion>
</AccordionGroup>


# Real-time monitoring
Source: https://docs.threetone.in/agents-platform/monitor/real-time-monitoring

Read the workspace live counter and distinguish it from unreleased event streams and live conversation monitoring.

The live-count endpoint provides a snapshot of a shared activity counter. It does not return individual sessions, transcripts, or a connection for observing conversations.

<Note>
  [Get live conversation count](/api-reference/agents-platform/get-live-conversation-count) reads a workspace-level counter. Its `agent_id` and `agent_ids` parameters are currently ignored, so filtered requests must not be presented as agent-specific counts.
</Note>

You need a permitted API key and a deployment with the shared cache available.

<Steps>
  <Step title="Read the workspace counter">
    Request the live count and record when you received it. Use the value only for that workspace snapshot, alongside its request success or failure.
  </Step>

  <Step title="Separate zero from unavailable">
    A missing counter key returns zero. An unavailable cache or invalid stored value produces an error. Preserve that error state instead of displaying it as zero activity.
  </Step>

  <Step title="Plan richer monitoring separately">
    Agent configuration includes `conversation_config.conversation.monitoring_enabled` and `monitoring_events`. These saved fields do not provide a released event subscription, WebSocket connection, or live transcript viewer.
  </Step>
</Steps>

Before relying on real-time monitoring, verify the released execution path, counter updates, freshness, and event delivery behavior. The counter read itself does not establish those guarantees.

<AccordionGroup>
  <Accordion title="Can I monitor one agent with agent_ids?">Not currently. The handler reads the same workspace counter regardless of those filters.</Accordion>
  <Accordion title="Does monitoring_enabled start a stream?">No released subscription workflow is established by saving that field.</Accordion>
</AccordionGroup>


# Agent testing
Source: https://docs.threetone.in/agents-platform/monitor/testing

Author reusable response, tool-call, and simulation test definitions while tracking the separate execution gate.

A test definition records a scenario and the expected outcome. Keep it alongside the configuration change it is intended to check.

<Note>
  Test creation, editing, folders, and existing invocation reads are available through the API. Running or resubmitting tests is gated by agent execution availability. Saving a test does not run it.
</Note>

You need an authorized workspace credential and a specific behavior to evaluate.

| Test type | Definition to prepare |
| - | - |
| `llm` | `success_condition`, with optional success and failure examples |
| `tool` | Expected `tool_call_parameters` and `check_any_tool_matches` |
| `simulation` | Conversation scenario and `success_conditions` |

<Frame>
  <img alt="Recording pending for Create and inspect a test definition. No playable video is available yet." />
</Frame>

<Steps>
  <Step title="Write one observable expectation">
    For example, require the agent to ask for a missing booking date before requesting a reservation. Include relevant `chat_history` and synthetic `dynamic_variables`.
  </Step>

  <Step title="Save and inspect the definition">
    Use [Create test](/api-reference/tests/create-test), then [Get test](/api-reference/tests/get-test). Confirm the returned type, scenario, and expected outcome. Organize related definitions with [test folders](/api-reference/test-folders/create-folder).
  </Step>

  <Step title="Associate and record readiness">
    Agent configuration supports `platform_settings.testing.attached_tests`. Review attachment details with the agent draft. Mark execution pending until a released runner produces a completed invocation for the intended version.
  </Step>
</Steps>

[Existing invocations](/api-reference/test-invocations/list-test-invocations) can be read independently. Managed-model text-only publication does not remove the test execution gate; voice and custom-model publication remain unavailable.

<AccordionGroup>
  <Accordion title="Can I use the run-tests route now?">The public contract exists, but the current execution gate prevents a new run. Do not interpret a saved definition as a passing result.</Accordion>
  <Accordion title="Should a test contain customer secrets?">Use synthetic values and only the context needed to reproduce the behavior.</Accordion>
</AccordionGroup>


# Conversation topics
Source: https://docs.threetone.in/agents-platform/monitor/topics

Plan a useful topic taxonomy and understand the current limits of automated topic discovery.

Topics group conversations by the work a user needs done, such as changing a reservation or correcting an invoice. A useful taxonomy separates the request from the outcome and sentiment.

<Note>
  Automated topic discovery is unavailable. [Get agent conversation topics](/api-reference/agents-insights/get-agent-conversation-topics) currently returns an empty placeholder page. The topic-discovery toggle in Analysis is local preview state, not a saved enablement control.
</Note>

You can prepare a taxonomy through manual review of records you are allowed to access.

<Steps>
  <Step title="Choose a review sample">
    Use [conversation list filters](/agents-platform/monitor/analysis/searching) to select an agent and time interval. Record the sampling rule so another reviewer can repeat it.
  </Step>

  <Step title="Define topic boundaries">
    Give each proposed topic a short name, inclusion rule, and counterexample. Keep an explicit uncategorized bucket for requests the taxonomy does not cover.
  </Step>

  <Step title="Check reviewer agreement">
    Compare manual labels on the same sample. Revise overlapping definitions before expecting automated counts to guide product decisions.
  </Step>
</Steps>

Future topic reporting needs a working discovery process, traceable source conversations, and defined time-window behavior. The current empty response cannot establish that an agent has no recurring topics.

<AccordionGroup>
  <Accordion title="Will changing the topic toggle start discovery?">No. The current control does not persist or trigger a discovery job.</Accordion>
  <Accordion title="Can I rank the placeholder response by sentiment?">The contract describes ranking parameters, but the current handler does not calculate topic rankings.</Accordion>
</AccordionGroup>


# Conversation triage
Source: https://docs.threetone.in/agents-platform/monitor/triage

Create API-backed review tickets, attach transcript evidence, and assign a responsible workspace member.

Triage turns an observed problem into a trackable review item. Ticket creation, reads, assignments, comments, and status updates are implemented through the public API.

<Note>
  Use the API workflow below. There is no connected triage dashboard to follow, and automatic classification or clustering is not established by the response fields.
</Note>

You need access to the agent and a permitted workspace credential. For a conversation ticket, inspect the saved transcript first.

<Frame>
  <img alt="Recording pending for Review and assign a conversation ticket. No playable video is available yet." />
</Frame>

<Steps>
  <Step title="Create a specific finding">
    [Create a conversation ticket](/api-reference/create-agent-conversation-ticket) with `conversation_id` and a concise `qa_comment`. Optional `turn_comments` use a zero-based `turn_index`. Describe the observed action and expected behavior.
  </Step>

  <Step title="Assign an eligible reviewer">
    [List assignable users](/api-reference/list-assignable-users), then check `has_access`. [Update the ticket](/api-reference/update-ticket) with `assignee_user_id`; the assignee must be a workspace member with agent access. Passing null unassigns it.
  </Step>

  <Step title="Track the resolution">
    Use `open`, `in_progress`, or `resolved` to describe review progress. Add [comments](/api-reference/add-comment) with the proposed configuration change and verification evidence. Read the ticket back to confirm the saved state.
  </Step>
</Steps>

[Manual tickets](/api-reference/create-manual-ticket) support agent follow-up work without a conversation. The `merged` status and `needs_clustering` field do not establish an automatic ticket-merging workflow.

<AccordionGroup>
  <Accordion title="Should I copy the entire transcript into a comment?">Prefer the conversation ID and relevant turn indexes. Include only the private information needed to understand the finding.</Accordion>
  <Accordion title="Does resolved mean an automated test passed?">No. Record the actual review evidence and identify any verification still blocked by execution availability.</Accordion>
</AccordionGroup>


# Conversation users
Source: https://docs.threetone.in/agents-platform/monitor/users

Find end users represented in saved conversations and inspect their contact history through the API.

Conversation users are people represented in your conversation history. They are separate from workspace members who manage Threetone.

<Note>
  Use the API for this workflow. The Users dashboard currently displays sample data and is not a view of your saved customer records.
</Note>

You need workspace access, a permitted API key, and saved conversations with an end-user identity.

<Steps>
  <Step title="Choose the population">
    [List conversation users](/api-reference/agents-platform/list-conversation-users) with an optional `agent_id`, `branch_id`, or `call_start_after_unix` and `call_start_before_unix` window. These filters determine which conversations contribute to the counts.
  </Step>

  <Step title="Find an identity">
    Set `search` to the complete `user_id` for an exact match. It is not a partial name or email search. Sort by `last_contact_unix_secs` or `conversation_count`, and follow `next_cursor` while `has_more` is true.
  </Step>

  <Step title="Inspect the contributing history">
    Review `conversation_count`, first and last contact times, and `last_contact_conversation_id`. Use [List conversations](/api-reference/agents-platform/list-conversations) with `user_id` to inspect the underlying records.
  </Step>
</Steps>

Identity comes from the stored end-user ID, with legacy fallbacks to initiation data or a caller number. Treat it as a conversation identifier, not verified ownership of a phone number or account.

<AccordionGroup>
  <Accordion title="Does this create a customer profile?">No. The list groups existing conversation records. It does not create a separate contact or workspace membership.</Accordion>
  <Accordion title="Why is sentiment missing?">Only stored, valid sentiment results contribute. Check `scored_conversation_count` before interpreting averages.</Accordion>
</AccordionGroup>


# Agents Platform
Source: https://docs.threetone.in/agents-platform/overview

Learn the resources and workflows for configuring agents, managing changes, connecting knowledge and tools, and inspecting conversation records.

Agents Platform organizes the configuration and resources needed for an agent's
task. Start with instructions and model choices, attach knowledge and tools,
review configuration changes, and inspect existing conversation records.

<Frame>
  <img alt="Recording pending for the Agents Platform tour. No playable video is available yet." />
</Frame>

## Start with one task

<CardGroup>
  <Card title="Create a configuration" icon="robot" href="/agents-platform/get-started/first-agent">
    Use the dashboard to create an agent and review its saved settings.
  </Card>

  <Card title="Create with the API" icon="brackets-curly" href="/agents-platform/get-started/api-quickstart">
    Authenticate, select model and voice identifiers, and create an agent.
  </Card>
</CardGroup>

## Configure

| Goal | Guide | Result |
| - | - | - |
| Set the agent's behavior | [Agent configuration](/agents-platform/configure/agent-behavior/overview) | Understand the greeting, instructions and resource references. |
| Write clearer instructions | [Prompting](/agents-platform/configure/agent-behavior/prompting) | Define the task, boundaries and handling of missing information. |
| Select models and languages | [Models and voices](/overview/models) | Choose compatible identifiers and language policies. |
| Add supporting material | [Knowledge base](/agents-platform/configure/knowledge-base/overview) | Manage sources and inspect document dependencies. |
| Define actions | [Tools](/agents-platform/configure/tools/overview) | Configure tool definitions and attach their IDs. |

## Review changes and resources

| Goal | Guide | Result |
| - | - | - |
| Keep track of changes | [Branches and versions](/agents-platform/deploy/versioning) | Distinguish drafts, published snapshots and deployment. |
| Inspect existing interactions | [Conversations](/agents-platform/monitor/conversations) | Read details, summaries and available media. |
| Prepare a phone configuration | [Phone integration](/agents-platform/deploy/telephony/overview) | Understand provider prerequisites and number records. |
| Set workspace access | [Members and access](/overview/administration/workspaces/members) | Distinguish membership, resource roles and API-key permissions. |

## How an agent configuration fits together

A language model receives the agent's instructions and resource references. A
speech configuration also selects recognition and generation models plus a saved
voice. Knowledge documents and tools are workspace resources referenced by ID.
Branches and versions let you inspect a particular configuration snapshot.

Conversation records contain the interaction data that was stored. The existence
of an agent configuration, a phone-number record or a conversation schema does not
prove that a complete runtime workflow is available.

## Current availability

<Note>
  The guides in this section cover configuration, resource management and
  inspection. Live conversation initiation through the public signed-token
  paths, outbound calling, traffic deployment and automated response-test
  execution are currently unavailable in the documented API implementation.
  A published configuration version is not confirmation of a running agent.
</Note>

Voice and custom-model configurations can be created or saved as drafts, but their later publication is unavailable. Managed text-only publication has its own model, resource, and workflow checks. Creation and an initial version do not prove runtime readiness.

## Explore the platform

<CardGroup>
  <Card title="Monitor" icon="chart-line" href="/agents-platform/monitor/overview">Review users, tests, analytics, privacy, and conversation evidence.</Card>
  <Card title="Advanced configuration" icon="sliders" href="/agents-platform/advanced/overview">Understand events, custom models, fallback routing, and post-call webhooks.</Card>
  <Card title="SDK resources" icon="code" href="/agents-platform/resources/overview">Use Python and TypeScript REST examples and review package availability.</Card>
  <Card title="Implementation guides" icon="book" href="/agents-platform/guides/overview">Prepare website integrations, chat, research, and capacity workflows.</Card>
  <Card title="Legal guidance" icon="scale-balanced" href="/agents-platform/legal/overview">Review consent, AI disclosure, sensitive data, and first-party policies.</Card>
</CardGroup>

Some operations remain listed in the API reference while their runtime behavior
is unavailable. Check the relevant guide before building a workflow around
service accounts, WhatsApp outbound operations, batch calling, generated
conversation analysis, message search or workspace webhook delivery.

For current setup and account questions, use the
[Help Center](https://help.threetone.in/en) or
[contact support](mailto:support@threetone.in).


# Developer resources
Source: https://docs.threetone.in/agents-platform/resources/overview

Find language client guidance, UI integration preparation, and the public API contract.

Use the public API contract as the request and response reference. Keep client libraries, browser integration, and agent runtime availability separate when choosing a development path.

<CardGroup>
  <Card title="SDK resources" icon="code" href="/agents-platform/resources/sdks/overview">Review Python and TypeScript package readiness and usable REST read examples.</Card>
  <Card title="UI integration" icon="window-maximize" href="/agents-platform/resources/ui-components">Prepare an interface against a released client and session contract.</Card>
  <Card title="API reference" icon="book" href="/api-reference/introduction">Inspect generated public operation schemas and authentication.</Card>
  <Card title="Command-line workflows" icon="terminal" href="/agents-platform/monitor/cli">Use documented API requests without inventing a product CLI.</Card>
</CardGroup>

## Choose the right contract

The private dashboard client is generated from internal-web APIs. It is not the public SDK contract and should not be copied into customer applications. Likewise, a starter application or widget bundle does not establish a published package or a supported session transport.

Keep server-side API keys in private configuration. Use [Guides](/agents-platform/guides/overview) for task-oriented integration preparation and [current availability](/agents-platform/overview#current-availability) for execution limits.


# SDKs
Source: https://docs.threetone.in/agents-platform/resources/sdks/overview

Check Threetone SDK availability and use Python or TypeScript REST examples to read agent records.

Use Threetone's REST API from your server-side Python or TypeScript application. The language pages provide read examples with authentication, timeouts, response checks, and pagination.

<Note>
  First-party Python and TypeScript SDKs are planned. No verified installable first-party SDK release has been identified. The examples use Requests and Node.js `fetch`; there is no Threetone package installation or SDK import to copy yet.
</Note>

## Choose a language

<CardGroup>
  <Card title="Python SDK" icon="python" href="/agents-platform/resources/sdks/python">
    Check planned SDK availability and list agents with Requests.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/agents-platform/resources/sdks/typescript">
    Check planned SDK availability and list agents with Node.js fetch.
  </Card>
</CardGroup>

## Prepare your integration

1. Create a personal [API key](/overview/administration/workspaces/api-keys) with access to the resources you need.
2. Keep the key in server-side configuration and send it in the `x-api-key` header. Read [Authentication](/api-reference/authentication) for credential requirements.
3. Start with [List agents](/api-reference/agents-platform/list-agents), then use [Get agent](/api-reference/agents-platform/get-agent) to inspect an existing configuration.
4. Retain the status code and request ID when a request fails. Use [Errors and retries](/api-reference/errors) before adding retries.

The read examples do not create resources, publish versions, or start sessions. Review [current availability](/agents-platform/overview#current-availability) before building an execution workflow. Voice and custom-LLM configuration publication are currently unavailable.

## Work with the public contract

Use the endpoint reference for request fields, response fields, and permissions. An endpoint's presence in the reference does not establish that every associated runtime feature is available.

For agent lists, choose a `page_size` between 1 and 100. The default is 30. Follow the returned `next_cursor` while `has_more` is true, keeping the same filters between pages. Treat the cursor as an opaque value.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I install a Threetone SDK today?">
    No verified first-party package release is documented here. Use the REST examples until a package name, supported version, and installation instructions are published.
  </Accordion>

  <Accordion title="Can I put the API key in a browser application?">
    Keep personal API keys on your server. Call your own authenticated server route from the browser and let that route make the Threetone request.
  </Accordion>

  <Accordion title="Does reading an agent confirm that it can run?">
    No. A successful read confirms access to the stored record. Session access, publication, and execution have separate requirements and availability limits.
  </Accordion>
</AccordionGroup>


# Python SDK
Source: https://docs.threetone.in/agents-platform/resources/sdks/python

Check planned Python SDK availability and read Threetone agent records with a validated Requests example.

Read agent records from a server-side Python script using Requests. This example checks your API key, limits network waits, validates the response fields it uses, and supports pagination.

<Note>
  The first-party Threetone Python SDK is planned. No verified installable release has been identified. `requests` is an HTTP library, and the example below calls the public REST API directly.
</Note>

## Before you start

Use a supported Python release and a personal [API key](/overview/administration/workspaces/api-keys) with permission to read agents. Set `THREETONE_API_KEY` in the environment where your script runs. Keep it out of source files and logs.

Install the HTTP dependency:

```bash theme={null}
python -m pip install requests
```

## Read a page of agents

Save this as `list_agents.py`. It reads up to 20 agents through [List agents](/api-reference/agents-platform/list-agents).

```python list_agents.py theme={null}
import os

import requests

api_key = os.environ.get("THREETONE_API_KEY")
if not api_key or not api_key.strip():
    raise RuntimeError("Set THREETONE_API_KEY in your server environment.")


def list_agents(cursor=None):
    params = {"page_size": 20}
    if cursor is not None:
        params["cursor"] = cursor

    try:
        response = requests.get(
            "https://api.threetone.in/v1/convai/agents",
            headers={"x-api-key": api_key},
            params=params,
            timeout=(5, 30),
            allow_redirects=False,
        )
    except requests.RequestException:
        raise RuntimeError(
            "GET /v1/convai/agents failed before a usable response arrived."
        ) from None

    request_id = response.headers.get("X-Request-Id", "unavailable")[:128]
    context = (
        f"GET /v1/convai/agents status={response.status_code} "
        f"request_id={request_id!r}"
    )
    if response.status_code != 200:
        raise RuntimeError(context)

    try:
        page = response.json()
    except ValueError:
        raise RuntimeError(f"Invalid JSON; {context}") from None

    if not isinstance(page, dict) or not isinstance(page.get("agents"), list):
        raise RuntimeError(f"Invalid agents response; {context}")
    if type(page.get("has_more")) is not bool:
        raise RuntimeError(f"Invalid pagination response; {context}")
    next_cursor = page.get("next_cursor")
    if next_cursor is not None and not isinstance(next_cursor, str):
        raise RuntimeError(f"Invalid cursor; {context}")
    if page["has_more"] and not next_cursor:
        raise RuntimeError(f"Missing next cursor; {context}")
    for agent in page["agents"]:
        if (
            not isinstance(agent, dict)
            or not isinstance(agent.get("agent_id"), str)
            or not isinstance(agent.get("name"), str)
        ):
            raise RuntimeError(f"Invalid agent entry; {context}")

    return page["agents"], page["has_more"], next_cursor


agents, has_more, next_cursor = list_agents()
for agent in agents:
    print(agent["agent_id"], agent["name"])
print("More agents available:", has_more)
```

Run the script in the environment that contains your key:

```bash theme={null}
python list_agents.py
```

A successful request prints the ID and name of each returned agent, followed by whether another page is available. An empty list prints no agent rows. The example checks only the fields it consumes, not the complete response schema.

The timeout sets a five-second connection wait and a 30-second read inactivity limit. It is not a deadline for the entire download. Redirects are disabled to avoid forwarding the API key to another destination.

## Read the next page

When `has_more` is true, call `list_agents(cursor=next_cursor)` to read the next page. Continue with each newly returned cursor until `has_more` is false. Do not alter or construct cursor values.

`page_size` accepts 1 to 100 and defaults to 30 when omitted. The example uses 20. If you add filters, keep them the same while following a cursor. Use [Get agent](/api-reference/agents-platform/get-agent) when you need one agent's complete saved configuration.

## Troubleshoot a request

For `401`, check the key and its expiry. For `403`, check its permissions and workspace access. For `429`, follow `Retry-After` when supplied. See [Errors and retries](/api-reference/errors) before adding automatic retries.

The error context includes the method, path, status, and an escaped request ID limited to 128 characters. It excludes the key and response body. A connection failure or timeout may have no response status or request ID.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is requests the Threetone SDK?">
    No. It is a general-purpose Python HTTP library. The Threetone Python SDK is planned, and no first-party package name is documented for installation yet.
  </Accordion>

  <Accordion title="Does this example create or change an agent?">
    No. It sends a GET request and reads existing records. A successful read does not start a conversation or verify execution availability.
  </Accordion>

  <Accordion title="Why is my agent list empty?">
    Confirm that the key belongs to the intended workspace and can access its agents. The list excludes archived agents by default. Check the filters in [List agents](/api-reference/agents-platform/list-agents).
  </Accordion>
</AccordionGroup>


# TypeScript SDK
Source: https://docs.threetone.in/agents-platform/resources/sdks/typescript

Check planned TypeScript SDK availability and read Threetone agent records with Node.js fetch and response validation.

Read agent records from a server-side TypeScript application using Node.js `fetch`. This example checks your API key, adds a timeout, validates response fields, and supports pagination.

<Note>
  The first-party Threetone TypeScript SDK is planned. No verified installable release has been identified. This example uses built-in Node.js APIs and has no Threetone package installation or import.
</Note>

## Before you start

Use Node.js 24 or later and a personal [API key](/overview/administration/workspaces/api-keys) with permission to read agents. Set `THREETONE_API_KEY` in your server environment. Do not expose it through a public environment variable or browser bundle.

The `.mts` example uses Node.js TypeScript support. You do not need an additional HTTP library to run it.

## Read a page of agents

Save this as `list-agents.mts`. It reads up to 20 agents through [List agents](/api-reference/agents-platform/list-agents).

```typescript list-agents.mts theme={null}
export {};

const apiKey = process.env.THREETONE_API_KEY;
if (!apiKey?.trim()) {
  throw new Error("Set THREETONE_API_KEY in your server environment.");
}

function parseAgentPage(value: unknown) {
  if (
    typeof value !== "object" || value === null ||
    !("agents" in value) || !Array.isArray(value.agents) ||
    !("has_more" in value) || typeof value.has_more !== "boolean"
  ) {
    throw new Error("Invalid agents response.");
  }
  const nextCursor = "next_cursor" in value ? value.next_cursor : null;
  if (nextCursor !== null && typeof nextCursor !== "string") {
    throw new Error("Invalid cursor.");
  }
  if (value.has_more && !nextCursor) {
    throw new Error("Missing next cursor.");
  }
  const agents = value.agents.map((agent: unknown) => {
    if (
      typeof agent !== "object" || agent === null ||
      !("agent_id" in agent) || typeof agent.agent_id !== "string" ||
      !("name" in agent) || typeof agent.name !== "string"
    ) {
      throw new Error("Invalid agent entry.");
    }
    return { agent_id: agent.agent_id, name: agent.name };
  });
  return { agents, has_more: value.has_more, next_cursor: nextCursor };
}

async function listAgents(apiKey: string, cursor?: string) {
  const url = new URL("https://api.threetone.in/v1/convai/agents");
  url.searchParams.set("page_size", "20");
  if (cursor !== undefined) url.searchParams.set("cursor", cursor);

  let response: Response;
  try {
    response = await fetch(url, {
      headers: { "x-api-key": apiKey },
      signal: AbortSignal.timeout(30_000),
      redirect: "error",
    });
  } catch {
    throw new Error(
      "GET /v1/convai/agents failed before a usable response arrived.",
    );
  }

  const requestId = JSON.stringify(
    (response.headers.get("X-Request-Id") ?? "unavailable").slice(0, 128),
  );
  const context =
    `GET /v1/convai/agents status=${response.status} request_id=${requestId}`;
  if (response.status !== 200) throw new Error(context);

  try {
    const value: unknown = await response.json();
    return parseAgentPage(value);
  } catch {
    throw new Error(`Unreadable or invalid agents response; ${context}`);
  }
}

try {
  const page = await listAgents(apiKey);
  for (const agent of page.agents) {
    console.log(agent.agent_id, agent.name);
  }
  console.log("More agents available:", page.has_more);
} catch (error) {
  console.error(error instanceof Error ? error.message : "Agent read failed.");
  process.exitCode = 1;
}
```

Run the file in the environment that contains your key:

```bash theme={null}
node list-agents.mts
```

A successful request prints the ID and name of each returned agent, followed by whether another page is available. An empty list prints no agent rows. The parser validates only the fields this example consumes. TypeScript types alone do not validate JSON received over the network.

The request aborts after 30 seconds. Redirects are disabled to avoid forwarding the API key to another destination.

## Read the next page

When `page.has_more` is true and `page.next_cursor` is a string, pass it to `listAgents(apiKey, page.next_cursor)`. Continue with each newly returned cursor until `has_more` is false. Keep cursor values unchanged.

`page_size` accepts 1 to 100 and defaults to 30 when omitted. The example uses 20. Keep any filters unchanged between pages. Use [Get agent](/api-reference/agents-platform/get-agent) to inspect one agent's complete saved configuration.

## Troubleshoot a request

For `401`, check the key and its expiry. For `403`, check its permissions and workspace access. For `429`, follow `Retry-After` when supplied. Read [Errors and retries](/api-reference/errors) before adding automatic retries.

The error context includes the method, path, status, and a JSON-escaped request ID limited to 128 characters. It excludes the key and response body. A connection failure or timeout may have no response status or request ID.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Which Threetone npm package should I install?">
    No verified first-party package release is documented yet. The SDK is planned. This example runs with Node.js and does not install a Threetone package.
  </Accordion>

  <Accordion title="Can I run this in a React component?">
    Keep this request on your server because it uses a personal API key. Let browser code call your own authenticated server route.
  </Accordion>

  <Accordion title="Does Node.js check the TypeScript types at runtime?">
    No. Node.js removes the supported type syntax when running this file. The explicit response checks validate the fields used by the example. Run your project's TypeScript checker separately.
  </Accordion>
</AccordionGroup>


# UI components
Source: https://docs.threetone.in/agents-platform/resources/ui-components

Prepare a conversation interface while the public Threetone component and client transport contracts are being established.

An interface needs more than a visual widget. It must have a supported session-access design, event contract, input permissions, loading and failure states, and a defined cleanup lifecycle.

No verified public Threetone UI component package is established in this documentation. Private dashboard components and starter applications are implementation examples, not a supported distribution contract.

## Prepare the interface

Define the interface's connection, permission-request, active, interrupted, reconnecting, and ended states. Give controls accessible names, keyboard behavior, visible focus, and appropriate announcements. Keep transcript text readable at narrow widths and support the language direction of the content.

Use [client events](/agents-platform/advanced/events/client-events) to plan the displayed data and [authentication](/agents-platform/configure/authentication/overview) to separate browser session access from server credentials. Do not copy a workspace API key into a component prop or browser bundle.

## Release requirements

The public component release must document installation, supported client versions, session creation, event handlers, cleanup, styling boundaries, accessibility behavior, and error handling. Test against the real released transport before embedding it in customer pages.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I install the dashboard's internal components as an SDK?">They are private application code, not a verified public package. Use the public API and resource documentation for the supported boundary.</Accordion>
  <Accordion title="Can an attractive preview prove the conversation works?">No. Validate authentication, session connection, actual input/output, failure handling, and cleanup separately from presentation.</Accordion>
</AccordionGroup>


# Add comment
Source: https://docs.threetone.in/api-reference/add-comment

/api-reference/openapi.json post /v1/convai/triage-tickets/{agentqa_ticket_id}/comments
Append a comment discussing how to resolve the ticket. Requires viewer access to the ticket's agent



# Add turn comment
Source: https://docs.threetone.in/api-reference/add-turn-comment

/api-reference/openapi.json post /v1/convai/triage-tickets/{agentqa_ticket_id}/turn-comments
Append a turn-level comment to a ticket. Requires viewer access to the ticket's agent



# Get agent conversation topics
Source: https://docs.threetone.in/api-reference/agents-insights/get-agent-conversation-topics

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/topics
Returns the latest topic discovery run results for a given agent.



# Add tag to conversation
Source: https://docs.threetone.in/api-reference/agents-platform/add-tag-to-conversation

/api-reference/openapi.json post /v1/convai/conversations/{conversation_id}/tags
Assign one or more conversation tags to a conversation. Tags that are already assigned are ignored. Tags must belong to the same workspace.



# Calculate expected LLM usage
Source: https://docs.threetone.in/api-reference/agents-platform/calculate-expected-llm-usage

/api-reference/openapi.json post /v1/convai/llm-usage/calculate
Reserved compatibility operation. Product-owned LLM cost estimates are not currently available, so authorized requests return llm_estimate_unavailable (HTTP 503).



# Calculate expected LLM usage for an agent
Source: https://docs.threetone.in/api-reference/agents-platform/calculate-expected-llm-usage-for-an-agent

api-reference/openapi.json POST /v1/convai/agent/{agent_id}/llm-usage/calculate
Reserved compatibility endpoint. Authorized requests return HTTP 503 while LLM cost estimates are unavailable.

<Warning>
  LLM cost estimates are currently unavailable. This endpoint returns `llm_estimate_unavailable` with HTTP 503. Retrying the request does not make an estimate available.
</Warning>


# Cancel batch call
Source: https://docs.threetone.in/api-reference/agents-platform/cancel-batch-call

/api-reference/openapi.json post /v1/convai/batch-calling/{batch_id}/cancel
Cancel a running batch call and set all recipients to cancelled status



# Compile procedures
Source: https://docs.threetone.in/api-reference/agents-platform/compile-procedures

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/compile
Compile procedure drafts into a workflow



# Create agent
Source: https://docs.threetone.in/api-reference/agents-platform/create-agent

/api-reference/openapi.json post /v1/convai/agents/create
Create an agent from a config object



# Create agent branch
Source: https://docs.threetone.in/api-reference/agents-platform/create-agent-branch

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/branches
Create a new branch from a given version of any branch



# Create agent draft
Source: https://docs.threetone.in/api-reference/agents-platform/create-agent-draft

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/drafts
Create a new draft for an agent



# Create batch call
Source: https://docs.threetone.in/api-reference/agents-platform/create-batch-call

/api-reference/openapi.json post /v1/convai/batch-calling/submit
Submit a batch call request to schedule calls for multiple recipients



# Create document RAG index
Source: https://docs.threetone.in/api-reference/agents-platform/create-document-rag-index

/api-reference/openapi.json post /v1/convai/knowledge-base/{documentation_id}/rag-index
In case the document is not RAG indexed, it triggers RAG indexing task, otherwise it just returns the current status



# Create environment variable
Source: https://docs.threetone.in/api-reference/agents-platform/create-environment-variable

/api-reference/openapi.json post /v1/convai/environment-variables
Create a new environment variable for the workspace



# Create knowledge base document from file
Source: https://docs.threetone.in/api-reference/agents-platform/create-knowledge-base-document-from-file

/api-reference/openapi.json post /v1/convai/knowledge-base/file
Create a knowledge base document generated form the uploaded file



# Create knowledge base document from text
Source: https://docs.threetone.in/api-reference/agents-platform/create-knowledge-base-document-from-text

/api-reference/openapi.json post /v1/convai/knowledge-base/text
Create a knowledge base document containing the provided text



# Create knowledge base document from URL
Source: https://docs.threetone.in/api-reference/agents-platform/create-knowledge-base-document-from-url

/api-reference/openapi.json post /v1/convai/knowledge-base/url
Create a knowledge base document generated by scraping the given webpage



# Create MCP server
Source: https://docs.threetone.in/api-reference/agents-platform/create-mcp-server

/api-reference/openapi.json post /v1/convai/mcp-servers
Create a new MCP server configuration in the workspace



# Create MCP server tool approval
Source: https://docs.threetone.in/api-reference/agents-platform/create-mcp-server-tool-approval

/api-reference/openapi.json post /v1/convai/mcp-servers/{mcp_server_id}/tool-approvals
Add approval for a specific MCP tool when using per-tool approval mode



# Create MCP tool configuration override
Source: https://docs.threetone.in/api-reference/agents-platform/create-mcp-tool-configuration-override

/api-reference/openapi.json post /v1/convai/mcp-servers/{mcp_server_id}/tool-configs
Create configuration overrides for a specific MCP tool



# Create or update agent deployments
Source: https://docs.threetone.in/api-reference/agents-platform/create-or-update-agent-deployments

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/deployments
Create a new deployment for an agent



# Create procedure
Source: https://docs.threetone.in/api-reference/agents-platform/create-procedure

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures
Create a new procedure for the agent on a branch



# Create RAG indexes
Source: https://docs.threetone.in/api-reference/agents-platform/create-rag-indexes

/api-reference/openapi.json post /v1/convai/knowledge-base/rag-index
Retrieves and/or creates RAG indexes for multiple knowledge base documents in a single request. Maximum 100 items per request



# Create tag
Source: https://docs.threetone.in/api-reference/agents-platform/create-tag

/api-reference/openapi.json post /v1/convai/tags
Create a new conversation tag for the workspace.



# Create tool
Source: https://docs.threetone.in/api-reference/agents-platform/create-tool

/api-reference/openapi.json post /v1/convai/tools
Add a new tool to the available tools in the workspace



# Create workspace secret
Source: https://docs.threetone.in/api-reference/agents-platform/create-workspace-secret

/api-reference/openapi.json post /v1/convai/secrets
Create a new secret for the workspace



# Delete agent
Source: https://docs.threetone.in/api-reference/agents-platform/delete-agent

/api-reference/openapi.json delete /v1/convai/agents/{agent_id}
Delete an agent



# Delete agent draft
Source: https://docs.threetone.in/api-reference/agents-platform/delete-agent-draft

/api-reference/openapi.json delete /v1/convai/agents/{agent_id}/drafts
Delete a draft for an agent



# Delete Agent Hold Audio
Source: https://docs.threetone.in/api-reference/agents-platform/delete-agent-hold-audio

/api-reference/openapi.json delete /v1/convai/agents/{agent_id}/hold-audio
Removes the agent's custom hold audio; queued callers hear the default hold tone again.



# Delete batch call
Source: https://docs.threetone.in/api-reference/agents-platform/delete-batch-call

/api-reference/openapi.json delete /v1/convai/batch-calling/{batch_id}
Permanently delete a batch call and all recipient records. Conversations remain in history



# Delete conversation
Source: https://docs.threetone.in/api-reference/agents-platform/delete-conversation

/api-reference/openapi.json delete /v1/convai/conversations/{conversation_id}
Delete a particular conversation



# Delete conversation file
Source: https://docs.threetone.in/api-reference/agents-platform/delete-conversation-file

/api-reference/openapi.json delete /v1/convai/conversations/{conversation_id}/files/{file_id}
Remove a file upload from a conversation. Only possible if the file hasn't already been used in the conversation.



# Delete knowledge base document or folder
Source: https://docs.threetone.in/api-reference/agents-platform/delete-knowledge-base-document-or-folder

/api-reference/openapi.json delete /v1/convai/knowledge-base/{documentation_id}
Delete a document or folder from the knowledge base



# Delete knowledge base documents
Source: https://docs.threetone.in/api-reference/agents-platform/delete-knowledge-base-documents

/api-reference/openapi.json post /v1/convai/knowledge-base/bulk-delete
Delete multiple documents or folders from the knowledge base. Each ID succeeds or fails independently



# Delete MCP server
Source: https://docs.threetone.in/api-reference/agents-platform/delete-mcp-server

/api-reference/openapi.json delete /v1/convai/mcp-servers/{mcp_server_id}
Delete a specific MCP server configuration from the workspace



# Delete MCP server tool approval
Source: https://docs.threetone.in/api-reference/agents-platform/delete-mcp-server-tool-approval

/api-reference/openapi.json delete /v1/convai/mcp-servers/{mcp_server_id}/tool-approvals/{tool_name}
Remove approval for a specific MCP tool when using per-tool approval mode



# Delete MCP tool configuration override
Source: https://docs.threetone.in/api-reference/agents-platform/delete-mcp-tool-configuration-override

/api-reference/openapi.json delete /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}
Remove configuration overrides for a specific MCP tool



# Delete phone number
Source: https://docs.threetone.in/api-reference/agents-platform/delete-phone-number

/api-reference/openapi.json delete /v1/convai/phone-numbers/{phone_number_id}
Delete Phone Number by ID



# Delete procedure
Source: https://docs.threetone.in/api-reference/agents-platform/delete-procedure

/api-reference/openapi.json delete /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/{procedure_id}
Remove a procedure from the agent's draft working set



# Delete procedure draft
Source: https://docs.threetone.in/api-reference/agents-platform/delete-procedure-draft

/api-reference/openapi.json delete /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/{procedure_id}/draft
Delete user's draft for a procedure, resetting to the committed version



# Delete RAG index
Source: https://docs.threetone.in/api-reference/agents-platform/delete-rag-index

/api-reference/openapi.json delete /v1/convai/knowledge-base/{documentation_id}/rag-index/{rag_index_id}
Delete RAG index for the knowledgebase document



# Delete tag
Source: https://docs.threetone.in/api-reference/agents-platform/delete-tag

/api-reference/openapi.json delete /v1/convai/tags/{tag_id}
Delete a conversation tag. Restricted to the tag owner or a workspace admin.



# Delete tool
Source: https://docs.threetone.in/api-reference/agents-platform/delete-tool

/api-reference/openapi.json delete /v1/convai/tools/{tool_id}
Delete tool from the workspace



# Delete WhatsApp account
Source: https://docs.threetone.in/api-reference/agents-platform/delete-whatsapp-account

/api-reference/openapi.json delete /v1/convai/whatsapp-accounts/{phone_number_id}
Delete a WhatsApp account



# Delete workspace secret
Source: https://docs.threetone.in/api-reference/agents-platform/delete-workspace-secret

/api-reference/openapi.json delete /v1/convai/secrets/{secret_id}
Delete a workspace secret if it's not in use



# Duplicate agent
Source: https://docs.threetone.in/api-reference/agents-platform/duplicate-agent

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/duplicate
Create a new agent by duplicating an existing one



# Export batch call results
Source: https://docs.threetone.in/api-reference/agents-platform/export-batch-call-results

/api-reference/openapi.json get /v1/convai/batch-calling/{batch_id}/export
Download all recipients and conversation results for a terminal batch call as CSV



# Get agent
Source: https://docs.threetone.in/api-reference/agents-platform/get-agent

/api-reference/openapi.json get /v1/convai/agents/{agent_id}
Retrieve config for an agent



# Get agent branch
Source: https://docs.threetone.in/api-reference/agents-platform/get-agent-branch

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{branch_id}
Get information about a single agent branch



# Get agent knowledge base size
Source: https://docs.threetone.in/api-reference/agents-platform/get-agent-knowledge-base-size

/api-reference/openapi.json get /v1/convai/agent/{agent_id}/knowledge-base/size
Returns the number of pages in the agent's knowledge base



# Get agent version metadata
Source: https://docs.threetone.in/api-reference/agents-platform/get-agent-version-metadata

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/versions/{version_id}
Get metadata for a specific agent version



# Get agent widget configuration
Source: https://docs.threetone.in/api-reference/agents-platform/get-agent-widget-configuration

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/widget
Retrieve the widget configuration for an agent



# Get Agents Platform dashboard settings
Source: https://docs.threetone.in/api-reference/agents-platform/get-agents-platform-dashboard-settings

/api-reference/openapi.json get /v1/convai/settings/dashboard
Retrieve Convai dashboard settings for the workspace



# Get Agents Platform settings
Source: https://docs.threetone.in/api-reference/agents-platform/get-agents-platform-settings

/api-reference/openapi.json get /v1/convai/settings
Retrieve Convai settings for the workspace



# Get available AI model
Source: https://docs.threetone.in/api-reference/agents-platform/get-available-ai-model

/api-reference/openapi.json get /v1/convai/models/lookup
Returns one model and its eligible variants from the current reviewed catalog release



# Get batch call
Source: https://docs.threetone.in/api-reference/agents-platform/get-batch-call

/api-reference/openapi.json get /v1/convai/batch-calling/{batch_id}
Get detailed information about a batch call including all recipients



# Get conversation audio
Source: https://docs.threetone.in/api-reference/agents-platform/get-conversation-audio

/api-reference/openapi.json get /v1/convai/conversations/{conversation_id}/audio
Get the audio recording of a particular conversation



# Get conversation details
Source: https://docs.threetone.in/api-reference/agents-platform/get-conversation-details

/api-reference/openapi.json get /v1/convai/conversations/{conversation_id}
Get the details of a particular conversation



# Get conversation summary
Source: https://docs.threetone.in/api-reference/agents-platform/get-conversation-summary

/api-reference/openapi.json get /v1/convai/conversations/{conversation_id}/summary
Return a lightweight conversation summary without tool calls, tool results, or contextual updates. Use the conversation details endpoint for the full transcript



# Get conversation token
Source: https://docs.threetone.in/api-reference/agents-platform/get-conversation-token

/api-reference/openapi.json get /v1/convai/conversation/token
Get a WebRTC session token for real-time communication.



# Get document RAG indexes
Source: https://docs.threetone.in/api-reference/agents-platform/get-document-rag-indexes

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/rag-index
Provides information about all RAG indexes of the specified knowledgebase document



# Get environment variable
Source: https://docs.threetone.in/api-reference/agents-platform/get-environment-variable

/api-reference/openapi.json get /v1/convai/environment-variables/{env_var_id}
Get a specific environment variable by ID



# Get knowledge base document
Source: https://docs.threetone.in/api-reference/agents-platform/get-knowledge-base-document

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}
Get details about a specific documentation making up the agent's knowledge base



# Get knowledge base document chunk
Source: https://docs.threetone.in/api-reference/agents-platform/get-knowledge-base-document-chunk

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/chunk/{chunk_id}
Get details about a specific documentation part used by RAG



# Get knowledge base document content
Source: https://docs.threetone.in/api-reference/agents-platform/get-knowledge-base-document-content

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/content
Get the entire content of a document from the knowledge base



# Get knowledge base source file URL
Source: https://docs.threetone.in/api-reference/agents-platform/get-knowledge-base-source-file-url

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/source-file-url
Get a signed URL to download the original source file of a file-type document from the knowledge base



# Get live conversation count
Source: https://docs.threetone.in/api-reference/agents-platform/get-live-conversation-count

/api-reference/openapi.json get /v1/convai/analytics/live-count
Get the live count of the ongoing conversations



# Get MCP server
Source: https://docs.threetone.in/api-reference/agents-platform/get-mcp-server

/api-reference/openapi.json get /v1/convai/mcp-servers/{mcp_server_id}
Retrieve a specific MCP server configuration from the workspace



# Get MCP tool configuration override
Source: https://docs.threetone.in/api-reference/agents-platform/get-mcp-tool-configuration-override

/api-reference/openapi.json get /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}
Retrieve configuration overrides for a specific MCP tool



# Get phone number
Source: https://docs.threetone.in/api-reference/agents-platform/get-phone-number

/api-reference/openapi.json get /v1/convai/phone-numbers/{phone_number_id}
Retrieve Phone Number details by ID



# Get procedure
Source: https://docs.threetone.in/api-reference/agents-platform/get-procedure

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/{procedure_id}
Retrieve a procedure at a specific version or the current branch HEAD



# Get procedure draft
Source: https://docs.threetone.in/api-reference/agents-platform/get-procedure-draft

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/{procedure_id}/draft
Get user's draft for a procedure



# Get RAG index overview
Source: https://docs.threetone.in/api-reference/agents-platform/get-rag-index-overview

/api-reference/openapi.json get /v1/convai/knowledge-base/rag-index
Provides total size and other information of RAG indexes used by knowledgebase documents



# Get shareable agent link
Source: https://docs.threetone.in/api-reference/agents-platform/get-shareable-agent-link

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/link
Get the current link used to share the agent with others



# Get signed URL
Source: https://docs.threetone.in/api-reference/agents-platform/get-signed-url

/api-reference/openapi.json get /v1/convai/conversation/get-signed-url
Get a signed URL to start a conversation with an agent with an agent that requires authorization



# Get SIP messages for a conversation
Source: https://docs.threetone.in/api-reference/agents-platform/get-sip-messages-for-a-conversation

/api-reference/openapi.json get /v1/convai/conversations/{conversation_id}/sip-messages
Get SIP messages associated with a conversation's phone call



# Get SIP messages for a phone number
Source: https://docs.threetone.in/api-reference/agents-platform/get-sip-messages-for-a-phone-number

/api-reference/openapi.json get /v1/convai/phone-numbers/{phone_number_id}/sip-messages
Get SIP messages for a phone number



# Get tag
Source: https://docs.threetone.in/api-reference/agents-platform/get-tag

/api-reference/openapi.json get /v1/convai/tags/{tag_id}
Get a conversation tag by ID.



# Get the platform-managed LLM backup order
Source: https://docs.threetone.in/api-reference/agents-platform/get-the-platform-managed-llm-backup-order

/api-reference/openapi.json get /v1/convai/llm/cascade-config
Resolve the platform-managed backup order for a selectable primary LLM. The response contains public model identities only.



# Get tool
Source: https://docs.threetone.in/api-reference/agents-platform/get-tool

/api-reference/openapi.json get /v1/convai/tools/{tool_id}
Get tool that is available in the workspace



# Get WhatsApp account
Source: https://docs.threetone.in/api-reference/agents-platform/get-whatsapp-account

/api-reference/openapi.json get /v1/convai/whatsapp-accounts/{phone_number_id}
Get a WhatsApp account



# Get workspace secret
Source: https://docs.threetone.in/api-reference/agents-platform/get-workspace-secret

/api-reference/openapi.json get /v1/convai/secrets/{secret_id}
Get a workspace secret by ID



# Import phone number
Source: https://docs.threetone.in/api-reference/agents-platform/import-phone-number

/api-reference/openapi.json post /v1/convai/phone-numbers
Import Phone Number from provider configuration (Twilio, Exotel, or SIP trunk)



# List agent branches
Source: https://docs.threetone.in/api-reference/agents-platform/list-agent-branches

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches
Returns a list of branches an agent has



# List agent summaries
Source: https://docs.threetone.in/api-reference/agents-platform/list-agent-summaries

/api-reference/openapi.json get /v1/convai/agents/summaries
Returns summaries for the specified agents



# List agents
Source: https://docs.threetone.in/api-reference/agents-platform/list-agents

/api-reference/openapi.json get /v1/convai/agents
Returns a list of your agents and their metadata



# List agents using knowledge base document
Source: https://docs.threetone.in/api-reference/agents-platform/list-agents-using-knowledge-base-document

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/dependent-agents
Get a list of agents depending on this knowledge base document



# List agents using knowledge base documents
Source: https://docs.threetone.in/api-reference/agents-platform/list-agents-using-knowledge-base-documents

/api-reference/openapi.json post /v1/convai/knowledge-base/dependent-agents
Get a list of agents depending on any of the given knowledge base documents



# List agents using tool
Source: https://docs.threetone.in/api-reference/agents-platform/list-agents-using-tool

/api-reference/openapi.json get /v1/convai/tools/{tool_id}/dependent-agents
Get a list of agents depending on this tool



# List available AI models
Source: https://docs.threetone.in/api-reference/agents-platform/list-available-ai-models

/api-reference/openapi.json get /v1/convai/models
Returns the caller's provider-grouped models from the current reviewed catalog release, including exact capability and language support



# List available LLMs
Source: https://docs.threetone.in/api-reference/agents-platform/list-available-llms

/api-reference/openapi.json get /v1/convai/llm/list
List the LLMs available to the workspace, including capabilities and deprecation status



# List conversation users
Source: https://docs.threetone.in/api-reference/agents-platform/list-conversation-users

/api-reference/openapi.json get /v1/convai/users
Get distinct users from conversations with pagination



# List conversations
Source: https://docs.threetone.in/api-reference/agents-platform/list-conversations

/api-reference/openapi.json get /v1/convai/conversations
Get all conversations of agents that user owns. With option to restrict to a specific agent.



# List environment variables
Source: https://docs.threetone.in/api-reference/agents-platform/list-environment-variables

/api-reference/openapi.json get /v1/convai/environment-variables
List all environment variables for the workspace with optional filtering



# List knowledge base documents
Source: https://docs.threetone.in/api-reference/agents-platform/list-knowledge-base-documents

/api-reference/openapi.json get /v1/convai/knowledge-base
Get a list of available knowledge base documents



# List knowledge base summaries
Source: https://docs.threetone.in/api-reference/agents-platform/list-knowledge-base-summaries

/api-reference/openapi.json get /v1/convai/knowledge-base/summaries
Gets multiple knowledge base document summaries by their IDs



# List MCP server tools
Source: https://docs.threetone.in/api-reference/agents-platform/list-mcp-server-tools

/api-reference/openapi.json get /v1/convai/mcp-servers/{mcp_server_id}/tools
Retrieve all tools available for a specific MCP server configuration



# List MCP servers
Source: https://docs.threetone.in/api-reference/agents-platform/list-mcp-servers

/api-reference/openapi.json get /v1/convai/mcp-servers
Retrieve all MCP server configurations available in the workspace



# List phone numbers
Source: https://docs.threetone.in/api-reference/agents-platform/list-phone-numbers

/api-reference/openapi.json get /v1/convai/phone-numbers
Retrieve all Phone Numbers



# List Phone Numbers Page
Source: https://docs.threetone.in/api-reference/agents-platform/list-phone-numbers-page

/api-reference/openapi.json get /v1/convai/v2/phone-numbers
Retrieve a page of Phone Numbers



# List procedures
Source: https://docs.threetone.in/api-reference/agents-platform/list-procedures

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures
List an agent branch's procedures and draft status. Use the procedure detail endpoint to retrieve content



# List RAG chunks for document
Source: https://docs.threetone.in/api-reference/agents-platform/list-rag-chunks-for-document

/api-reference/openapi.json get /v1/convai/knowledge-base/{documentation_id}/chunks
Get all RAG chunks for a specific knowledge base document



# List secret dependencies
Source: https://docs.threetone.in/api-reference/agents-platform/list-secret-dependencies

/api-reference/openapi.json get /v1/convai/secrets/{secret_id}/dependencies/{resource_type}
Get paginated list of resources that depend on a specific secret, filtered by resource type



# List tags
Source: https://docs.threetone.in/api-reference/agents-platform/list-tags

/api-reference/openapi.json get /v1/convai/tags
List conversation tags for the workspace, ordered by most recently created first.



# List tool executions
Source: https://docs.threetone.in/api-reference/agents-platform/list-tool-executions

/api-reference/openapi.json get /v1/convai/tools/{tool_id}/executions
Get paginated list of tool executions for a specific tool



# List tools
Source: https://docs.threetone.in/api-reference/agents-platform/list-tools

/api-reference/openapi.json get /v1/convai/tools
Get all available tools in the workspace



# List WhatsApp accounts
Source: https://docs.threetone.in/api-reference/agents-platform/list-whatsapp-accounts

/api-reference/openapi.json get /v1/convai/whatsapp-accounts
List all WhatsApp accounts



# List workspace batch calls
Source: https://docs.threetone.in/api-reference/agents-platform/list-workspace-batch-calls

/api-reference/openapi.json get /v1/convai/batch-calling/workspace
Get all batch calls for the current workspace



# List workspace secrets
Source: https://docs.threetone.in/api-reference/agents-platform/list-workspace-secrets

/api-reference/openapi.json get /v1/convai/secrets
Get all workspace secrets for the user



# Merge agent branch
Source: https://docs.threetone.in/api-reference/agents-platform/merge-agent-branch

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge
Merge a branch into a target branch



# Post Agent Hold Audio
Source: https://docs.threetone.in/api-reference/agents-platform/post-agent-hold-audio

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/hold-audio
Sets the custom hold audio played on loop to callers waiting in the agent's concurrency wait queue. Replaces any previously uploaded clip.



# Preview merged configuration
Source: https://docs.threetone.in/api-reference/agents-platform/preview-merged-configuration

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{source_branch_id}/merge-preview
Returns the result of merging the source branch into the target branch without performing the merge. Useful for showing an accurate diff before confirming



# Preview rebased configuration
Source: https://docs.threetone.in/api-reference/agents-platform/preview-rebased-configuration

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/branches/{branch_id}/rebase-preview
Returns the result of rebasing the branch onto main without performing the rebase. Useful for showing an accurate diff before confirming



# Query agent knowledge base
Source: https://docs.threetone.in/api-reference/agents-platform/query-agent-knowledge-base

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/knowledge-base/rag-query
Run the agent's current RAG retrieval for an ad hoc query and return ranked chunks without creating a conversation



# Rebase agent branch onto main
Source: https://docs.threetone.in/api-reference/agents-platform/rebase-agent-branch-onto-main

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/branches/{branch_id}/rebase
Rebase a branch onto the latest main branch, incorporating main's changes while preserving the branch's own changes



# Refresh knowledge base URL
Source: https://docs.threetone.in/api-reference/agents-platform/refresh-knowledge-base-url

/api-reference/openapi.json post /v1/convai/knowledge-base/{documentation_id}/refresh
Manually refresh a URL document by re-fetching its content from the source URL



# Register Twilio call
Source: https://docs.threetone.in/api-reference/agents-platform/register-twilio-call

/api-reference/openapi.json post /v1/convai/twilio/register-call
Register a Twilio call and return TwiML to connect the call



# Remove tag from conversation
Source: https://docs.threetone.in/api-reference/agents-platform/remove-tag-from-conversation

/api-reference/openapi.json delete /v1/convai/conversations/{conversation_id}/tags/{tag_id}
Remove a single conversation tag from a conversation.



# Replace knowledge base file
Source: https://docs.threetone.in/api-reference/agents-platform/replace-knowledge-base-file

/api-reference/openapi.json patch /v1/convai/knowledge-base/{documentation_id}/update-file
Replace a file document's source file, content, and metadata. This overwrites manual content edits



# Resolve conversation reference
Source: https://docs.threetone.in/api-reference/agents-platform/resolve-conversation-reference

/api-reference/openapi.json get /v1/convai/conversations/resolve
Resolve a supported Slack or Zendesk conversation URL to an existing Threetone conversation ID



# Retry batch call
Source: https://docs.threetone.in/api-reference/agents-platform/retry-batch-call

/api-reference/openapi.json post /v1/convai/batch-calling/{batch_id}/retry
Retry a batch call, calling failed and no-response recipients again



# Search knowledge base content
Source: https://docs.threetone.in/api-reference/agents-platform/search-knowledge-base-content

/api-reference/openapi.json get /v1/convai/knowledge-base/search
Fuzzy text search over knowledge base document content



# Send conversation feedback
Source: https://docs.threetone.in/api-reference/agents-platform/send-conversation-feedback

/api-reference/openapi.json post /v1/convai/conversations/{conversation_id}/feedback
Send the feedback for the given conversation



# Send outbound message via WhatsApp
Source: https://docs.threetone.in/api-reference/agents-platform/send-outbound-message-via-whatsapp

/api-reference/openapi.json post /v1/convai/whatsapp/outbound-message
Send an outbound message via WhatsApp



# Smart search
Source: https://docs.threetone.in/api-reference/agents-platform/smart-search

/api-reference/openapi.json get /v1/convai/conversations/messages/smart-search
Search conversation transcripts by semantic similarity to surface relevant messages based on meaning and intent, rather than exact keyword matches



# Start outbound call via Exotel
Source: https://docs.threetone.in/api-reference/agents-platform/start-outbound-call-via-exotel

/api-reference/openapi.json post /v1/convai/exotel/outbound-call
Handle an outbound call via Exotel Connect API



# Start outbound call via SIP trunk
Source: https://docs.threetone.in/api-reference/agents-platform/start-outbound-call-via-sip-trunk

/api-reference/openapi.json post /v1/convai/sip-trunk/outbound-call
Handle an outbound call via SIP trunk



# Start outbound call via Twilio
Source: https://docs.threetone.in/api-reference/agents-platform/start-outbound-call-via-twilio

/api-reference/openapi.json post /v1/convai/twilio/outbound-call
Handle an outbound call via Twilio



# Start outbound call via WhatsApp
Source: https://docs.threetone.in/api-reference/agents-platform/start-outbound-call-via-whatsapp

/api-reference/openapi.json post /v1/convai/whatsapp/outbound-call
Make an outbound call via WhatsApp



# Text search
Source: https://docs.threetone.in/api-reference/agents-platform/text-search

/api-reference/openapi.json get /v1/convai/conversations/messages/text-search
Search through conversation transcript messages by full-text and fuzzy search



# Update agent
Source: https://docs.threetone.in/api-reference/agents-platform/update-agent

/api-reference/openapi.json patch /v1/convai/agents/{agent_id}
Patches an Agent settings



# Update agent branch
Source: https://docs.threetone.in/api-reference/agents-platform/update-agent-branch

/api-reference/openapi.json patch /v1/convai/agents/{agent_id}/branches/{branch_id}
Update agent branch properties such as archiving status and protection level



# Update Agents Platform dashboard settings
Source: https://docs.threetone.in/api-reference/agents-platform/update-agents-platform-dashboard-settings

/api-reference/openapi.json patch /v1/convai/settings/dashboard
Update Convai dashboard settings for the workspace



# Update Agents Platform settings
Source: https://docs.threetone.in/api-reference/agents-platform/update-agents-platform-settings

/api-reference/openapi.json patch /v1/convai/settings
Update Convai settings for the workspace



# Update document
Source: https://docs.threetone.in/api-reference/agents-platform/update-document

/api-reference/openapi.json patch /v1/convai/knowledge-base/{documentation_id}
Update the name and/or content of a document



# Update environment variable
Source: https://docs.threetone.in/api-reference/agents-platform/update-environment-variable

/api-reference/openapi.json patch /v1/convai/environment-variables/{env_var_id}
Replace an environment variable's values. Use null to remove an environment (except production)



# Update MCP server configuration
Source: https://docs.threetone.in/api-reference/agents-platform/update-mcp-server-configuration

/api-reference/openapi.json patch /v1/convai/mcp-servers/{mcp_server_id}
Update the configuration settings for an MCP server



# Update MCP tool configuration override
Source: https://docs.threetone.in/api-reference/agents-platform/update-mcp-tool-configuration-override

/api-reference/openapi.json patch /v1/convai/mcp-servers/{mcp_server_id}/tool-configs/{tool_name}
Update configuration overrides for a specific MCP tool



# Update phone number
Source: https://docs.threetone.in/api-reference/agents-platform/update-phone-number

/api-reference/openapi.json patch /v1/convai/phone-numbers/{phone_number_id}
Update assigned agent of a phone number



# Update procedure draft
Source: https://docs.threetone.in/api-reference/agents-platform/update-procedure-draft

/api-reference/openapi.json patch /v1/convai/agents/{agent_id}/branches/{branch_id}/procedures/{procedure_id}/draft
Create or update user's draft for a procedure



# Update tag
Source: https://docs.threetone.in/api-reference/agents-platform/update-tag

/api-reference/openapi.json patch /v1/convai/tags/{tag_id}
Update a conversation tag's title and/or description. Restricted to the tag owner or a workspace admin.



# Update tool
Source: https://docs.threetone.in/api-reference/agents-platform/update-tool

/api-reference/openapi.json patch /v1/convai/tools/{tool_id}
Update tool that is available in the workspace



# Update WhatsApp account
Source: https://docs.threetone.in/api-reference/agents-platform/update-whatsapp-account

/api-reference/openapi.json patch /v1/convai/whatsapp-accounts/{phone_number_id}
Update a WhatsApp account



# Update workspace secret
Source: https://docs.threetone.in/api-reference/agents-platform/update-workspace-secret

/api-reference/openapi.json patch /v1/convai/secrets/{secret_id}
Update an existing secret for the workspace



# Upload agent avatar
Source: https://docs.threetone.in/api-reference/agents-platform/upload-agent-avatar

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/avatar
Sets the avatar for an agent displayed in the widget



# Upload conversation file
Source: https://docs.threetone.in/api-reference/agents-platform/upload-conversation-file

/api-reference/openapi.json post /v1/convai/conversations/{conversation_id}/files
Upload an image or PDF file for a conversation. Returns a unique file ID that can be used to reference the file in the conversation.



# Run conversation analysis
Source: https://docs.threetone.in/api-reference/agents-workspace-analytics/run-conversation-analysis

/api-reference/openapi.json post /v1/convai/conversations/{conversation_id}/analysis/run
Run the analysis for a conversation using the agent's current evaluation criteria and data collection settings.



# Run conversation evaluation
Source: https://docs.threetone.in/api-reference/agents-workspace-analytics/run-conversation-evaluation

/api-reference/openapi.json post /v1/convai/conversations/{conversation_id}/analysis/evaluations/run
Rerun a specific evaluation for a conversation.



# Authentication
Source: https://docs.threetone.in/api-reference/authentication

Authenticate Threetone API requests with a scoped API key in the x-api-key header.

Use an API key for server-to-server requests to the Threetone API.

## Create an API key

Open [API Keys](https://threetone.in/app/developers/api-keys) in the Threetone dashboard and create a key for the integration. Use a separate key for each deployed service and grant only the permissions that service needs.

The secret is shown when the key is created. Store it in a server-side secret manager or environment variable.

```bash theme={null}
export THREETONE_API_KEY="your_api_key"
```

## Send the header

Pass the key in the `x-api-key` request header:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.threetone.in/v1/convai/agents \
    --header "x-api-key: $THREETONE_API_KEY"
  ```

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

  response = requests.get(
      "https://api.threetone.in/v1/convai/agents",
      headers={"x-api-key": os.environ["THREETONE_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.threetone.in/v1/convai/agents", {
    headers: {
      "x-api-key": process.env.THREETONE_API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`Threetone API returned ${response.status}`);
  }

  console.log(await response.json());
  ```
</CodeGroup>

Send the key as a header value. Do not put it in a URL, query string, request body, browser bundle, log, or error report.

<Warning>
  Do not send both `x-api-key` and `Authorization` in one request. Threetone rejects requests with ambiguous credentials.
</Warning>

## Handle authentication failures

A `401 Unauthorized` response means the API could not accept the credential. Confirm that the header contains the complete secret and that the key has not expired, been revoked, or been disabled.

A `403 Forbidden` response means the credential was recognized but cannot perform the operation. Check the key's permissions, workspace access, and IP restrictions.

Keep the response's `X-Request-Id` when investigating an error. Never include the API key in a support request.

## Rotate or revoke a key

Create a replacement key, deploy it to every service that needs it, confirm requests succeed, and then revoke the old key. Revoke a key immediately if its value may have been exposed.


# Cancel crawl job
Source: https://docs.threetone.in/api-reference/conversational-ai/cancel-crawl-job

/api-reference/openapi.json post /v1/convai/knowledge-base/crawl/{crawl_job_id}/cancel
Cancel a crawl job and delete all associated documents and folders



# Create crawl job
Source: https://docs.threetone.in/api-reference/conversational-ai/create-crawl-job

/api-reference/openapi.json post /v1/convai/knowledge-base/crawl
Create a crawl job to crawl the given URL with the specified page limit



# Create knowledge base folder
Source: https://docs.threetone.in/api-reference/conversational-ai/create-knowledge-base-folder

/api-reference/openapi.json post /v1/convai/knowledge-base/folder
Create a folder used for grouping documents together



# Get crawl job
Source: https://docs.threetone.in/api-reference/conversational-ai/get-crawl-job

/api-reference/openapi.json get /v1/convai/knowledge-base/crawl/{crawl_job_id}
Get details about a specific crawl job including status and progress



# List crawl jobs
Source: https://docs.threetone.in/api-reference/conversational-ai/list-crawl-jobs

/api-reference/openapi.json get /v1/convai/knowledge-base/crawl
Get a list of ongoing and recent crawl jobs for the user



# Move knowledge base item
Source: https://docs.threetone.in/api-reference/conversational-ai/move-knowledge-base-item

/api-reference/openapi.json post /v1/convai/knowledge-base/{document_id}/move
Moves the entity from one folder to another



# Move knowledge base items
Source: https://docs.threetone.in/api-reference/conversational-ai/move-knowledge-base-items

/api-reference/openapi.json post /v1/convai/knowledge-base/bulk-move
Moves multiple entities from one folder to another



# Create Agent Conversation Ticket
Source: https://docs.threetone.in/api-reference/create-agent-conversation-ticket

/api-reference/openapi.json post /v1/convai/triage-tickets
Raise a ticket about an agent's performance on a conversation, for triage with Architect. Provide an overall comment and/or turn-level comments describing what went wrong.



# Create manual ticket
Source: https://docs.threetone.in/api-reference/create-manual-ticket

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/triage-tickets
Manually raise a follow-up ticket against an agent, not tied to any conversation (for example a task like 'add the KB about X'). The comment is shown as the ticket title. Requires viewer access to the agent.



# Delete ticket
Source: https://docs.threetone.in/api-reference/delete-ticket

/api-reference/openapi.json delete /v1/convai/triage-tickets/{agentqa_ticket_id}
Delete an agent conversation ticket. Restricted to the ticket creator or a workspace admin



# Disable API key
Source: https://docs.threetone.in/api-reference/disable-api-key

/api-reference/openapi.json post /v1/user/api-keys/disable
Allow an authenticated key to revoke only itself when policy permits



# Errors and retries
Source: https://docs.threetone.in/api-reference/errors

Read Threetone API error responses, retain request IDs, and retry only transient failures.

Threetone uses standard HTTP status codes. Read the response body before deciding whether to change the request or retry it.

## API error response

Authentication, authorization, conflict, not-found, and server errors use a `detail` object:

```json theme={null}
{
  "detail": {
    "status": "invalid_api_key",
    "message": "Invalid API key",
    "request_id": "req_01J..."
  }
}
```

The `status` value is machine readable. The `message` explains the failure, and `request_id` identifies the request in Threetone logs.

## Validation error response

A `422 Unprocessable Entity` response uses a list of validation errors:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

Use `loc` to find the invalid path, query parameter, header, or request-body field. Correct the request before sending it again.

## Common status codes

| Status | Meaning | Action |
| - | - | - |
| `400` | The request cannot be processed as submitted. | Correct the request. |
| `401` | Authentication is missing or invalid. | Check the `x-api-key` header. |
| `403` | The credential lacks access. | Check permissions, workspace access, and key restrictions. |
| `404` | The resource was not found or is not visible to the credential. | Check the identifier and workspace. |
| `409` | The request conflicts with the current resource state. | Refresh the resource and resolve the conflict. |
| `422` | One or more inputs failed validation. | Fix the fields listed in `detail`. |
| `429` | The request exceeded a rate limit. | Wait for `Retry-After` before retrying. |
| `500` | The server could not complete the request. | Retry only when the operation is safe to repeat. |

## Retry safely

Retry transient `429` and `5xx` responses with exponential backoff and jitter. Honor `Retry-After` when present.

Before retrying a mutation, check whether the endpoint supports an idempotency key or whether the resource was already created or updated. Do not automatically retry a validation, authentication, authorization, or not-found response.

Keep the `X-Request-Id` response header, status code, method, path, and timestamp for any failure that needs investigation.


# Get ticket
Source: https://docs.threetone.in/api-reference/get-ticket

/api-reference/openapi.json get /v1/convai/triage-tickets/{agentqa_ticket_id}
Get an agent conversation ticket by ID



# Get user info
Source: https://docs.threetone.in/api-reference/get-user-info

/api-reference/openapi.json get /v1/user
Gets information about the user



# Get user subscription info
Source: https://docs.threetone.in/api-reference/get-user-subscription-info

/api-reference/openapi.json get /v1/user/subscription
Gets extended information about the user's subscription



# API overview
Source: https://docs.threetone.in/api-reference/introduction

Use the Threetone API to manage Agents Platform resources and shared workspace configuration.

The Threetone API exposes the Agents Platform and shared workspace resources through a versioned REST interface. Endpoint pages in this reference are generated from the public OpenAPI contract used by the API server.

## Base URL

```text theme={null}
https://api.threetone.in
```

All public endpoints begin with `/v1`. Send requests over HTTPS.

## Authentication

Programmatic requests use an API key in the `x-api-key` header.

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.threetone.in/v1/convai/agents?page_size=20' \
  --header "x-api-key: $THREETONE_API_KEY"
```

Create and manage keys on the [API Keys page](https://threetone.in/app/developers/api-keys). Keep each key in a server-side secret store and grant only the permissions its integration needs.

See [Authentication](/api-reference/authentication) for credential handling and common authentication failures.

## Resources

The API reference is organized by resource:

* Agents Platform contains agents, conversations, tests, tools, knowledge bases, telephony, integrations, MCP servers, and batch calls.
* Workspace contains members, invitations, groups, service accounts, API key policies, audit logs, webhooks, and usage.
* Shared resources contains resources used across platform features, such as voices.
* Utilities contains supporting operations, such as local time-zone resolution.

Work Platform will have its own section when its public API is available.

## Responses

Successful responses use the status code and schema shown on each endpoint page. Most responses are JSON. Download operations can return another documented media type, such as CSV.

List operations document their own filters and pagination fields. Do not assume every list endpoint uses the same cursor or response envelope.

## Request IDs

Threetone returns an `X-Request-Id` response header. Keep it with the request method, path, timestamp, and response status when troubleshooting. You may send a valid `X-Request-Id` header to correlate a request with your own logs.

## Rate limits

Production requests are rate limited. Successful responses can include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429 Too Many Requests` response also includes `Retry-After`.

Limits are deployment and credential specific, so read the response headers instead of relying on a fixed value.

See [Errors and retries](/api-reference/errors) for response shapes and retry guidance.


# List assignable users
Source: https://docs.threetone.in/api-reference/list-assignable-users

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/triage-tickets/assignable-users
List workspace members who can be assigned to an agent conversation ticket, including members who still need access to the agent



# List tickets
Source: https://docs.threetone.in/api-reference/list-tickets

/api-reference/openapi.json get /v1/convai/agents/{agent_id}/triage-tickets
List an agent's conversation triage tickets, ordered newest first



# List Workspace Conversation Tickets
Source: https://docs.threetone.in/api-reference/list-workspace-conversation-tickets

/api-reference/openapi.json get /v1/convai/triage-tickets
List conversation triage tickets across every agent the caller can access, newest first. Filter by status or assignee and use cursor pagination. For one agent's tickets, use the per-agent endpoint.



# Start outbound call
Source: https://docs.threetone.in/api-reference/outbound-calls/start-outbound-call

/api-reference/openapi.json post /v1/convai/outbound-call
Initiate a single outbound call to a phone number using an agent



# List phone number inventory
Source: https://docs.threetone.in/api-reference/phone-numbers/list-phone-number-inventory

/api-reference/openapi.json get /v1/phone-numbers/inventory
List available phone number countries, number types, and prices for the authenticated user



# Bulk move tests to folder
Source: https://docs.threetone.in/api-reference/test-folders/bulk-move-tests-to-folder

/api-reference/openapi.json post /v1/convai/agent-testing/bulk-move
Moves multiple tests or folders from one folder to another.



# Create folder
Source: https://docs.threetone.in/api-reference/test-folders/create-folder

/api-reference/openapi.json post /v1/convai/agent-testing/folders
Creates a folder for organizing agent tests.



# Delete folder
Source: https://docs.threetone.in/api-reference/test-folders/delete-folder

/api-reference/openapi.json delete /v1/convai/agent-testing/folders/{folder_id}
Deletes an agent test folder by ID. Use force=true to delete a non-empty folder and all its contents.



# Get folder
Source: https://docs.threetone.in/api-reference/test-folders/get-folder

/api-reference/openapi.json get /v1/convai/agent-testing/folders/{folder_id}
Gets an agent test folder by ID, including its folder path.



# Update folder
Source: https://docs.threetone.in/api-reference/test-folders/update-folder

/api-reference/openapi.json patch /v1/convai/agent-testing/folders/{folder_id}
Updates an agent test folder. Currently only supports updating the folder name.



# Get test invocation
Source: https://docs.threetone.in/api-reference/test-invocations/get-test-invocation

/api-reference/openapi.json get /v1/convai/test-invocations/{test_invocation_id}
Gets a test invocation by ID.



# List test invocations
Source: https://docs.threetone.in/api-reference/test-invocations/list-test-invocations

/api-reference/openapi.json get /v1/convai/test-invocations
Lists all test invocations with pagination support and optional search filtering.



# Resubmit test invocation
Source: https://docs.threetone.in/api-reference/test-invocations/resubmit-test-invocation

/api-reference/openapi.json post /v1/convai/test-invocations/{test_invocation_id}/resubmit
Resubmits specific test runs from a test invocation.



# Create test
Source: https://docs.threetone.in/api-reference/tests/create-test

/api-reference/openapi.json post /v1/convai/agent-testing/create
Creates a new agent response test.



# Delete test
Source: https://docs.threetone.in/api-reference/tests/delete-test

/api-reference/openapi.json delete /v1/convai/agent-testing/{test_id}
Deletes an agent response test by ID.



# Get test
Source: https://docs.threetone.in/api-reference/tests/get-test

/api-reference/openapi.json get /v1/convai/agent-testing/{test_id}
Gets an agent response test by ID.



# Get test summaries
Source: https://docs.threetone.in/api-reference/tests/get-test-summaries

/api-reference/openapi.json post /v1/convai/agent-testing/summaries
Gets agent response test summaries for the requested test IDs.



# List tests
Source: https://docs.threetone.in/api-reference/tests/list-tests

/api-reference/openapi.json get /v1/convai/agent-testing
Lists all agent response tests with pagination support and optional search filtering.



# Run tests on agent
Source: https://docs.threetone.in/api-reference/tests/run-tests-on-agent

/api-reference/openapi.json post /v1/convai/agents/{agent_id}/run-tests
Run selected tests on the agent with provided configuration. If the agent configuration is provided, it will be used to override default agent configuration.



# Update test
Source: https://docs.threetone.in/api-reference/tests/update-test

/api-reference/openapi.json put /v1/convai/agent-testing/{test_id}
Updates an agent response test by ID.



# Resolve a local wall time
Source: https://docs.threetone.in/api-reference/time-zones/resolve-a-local-wall-time

/api-reference/openapi.json post /v1/time-zones/resolve-local
Rejects daylight-saving gaps. For a repeated wall time, resolve once with `earlier` and once with `later` to inspect both possible instants



# Update ticket
Source: https://docs.threetone.in/api-reference/update-ticket

/api-reference/openapi.json patch /v1/convai/triage-tickets/{agentqa_ticket_id}
Update a ticket's comment, status, and/or assignee. Requires editor access to the ticket's agent



# Get a saved voice
Source: https://docs.threetone.in/api-reference/voices/get-a-saved-voice

/api-reference/openapi.json get /v1/voices/{voice_id}
Get one voice saved in the current workspace library, including its current availability.



# List my voices
Source: https://docs.threetone.in/api-reference/voices/list-my-voices

/api-reference/openapi.json get /v1/voices
List voices saved by the current workspace, including unavailable bookmarks.



# Add member to user group
Source: https://docs.threetone.in/api-reference/workspace/add-member-to-user-group

/api-reference/openapi.json post /v1/workspace/groups/{group_id}/members
Adds a member of your workspace to the specified group. Requires `group_members_manage` permission



# Create service account API key
Source: https://docs.threetone.in/api-reference/workspace/create-service-account-api-key

/api-reference/openapi.json post /v1/service-accounts/{service_account_user_id}/api-keys
Create a new API key for a service account



# Create workspace auth connection
Source: https://docs.threetone.in/api-reference/workspace/create-workspace-auth-connection

/api-reference/openapi.json post /v1/workspace/auth-connections
Store a manual auth connection for the workspace. This does not test the remote provider



# Create workspace group
Source: https://docs.threetone.in/api-reference/workspace/create-workspace-group

/api-reference/openapi.json post /v1/workspace/groups
Creates an application-managed human group in WorkOS and projects it into the workspace



# Create workspace service account
Source: https://docs.threetone.in/api-reference/workspace/create-workspace-service-account

/api-reference/openapi.json post /v1/service-accounts
Create a service account for the workspace



# Create workspace webhook
Source: https://docs.threetone.in/api-reference/workspace/create-workspace-webhook

/api-reference/openapi.json post /v1/workspace/webhooks
Create a new webhook for the workspace with the specified authentication type



# Delete service account API key
Source: https://docs.threetone.in/api-reference/workspace/delete-service-account-api-key

/api-reference/openapi.json delete /v1/service-accounts/{service_account_user_id}/api-keys/{api_key_id}
Delete an existing API key for a service account



# Delete workspace auth connection
Source: https://docs.threetone.in/api-reference/workspace/delete-workspace-auth-connection

/api-reference/openapi.json delete /v1/workspace/auth-connections/{auth_connection_id}
Delete an auth connection



# Delete workspace group
Source: https://docs.threetone.in/api-reference/workspace/delete-workspace-group

/api-reference/openapi.json delete /v1/workspace/groups/{group_id}
Deletes an application-managed human group through WorkOS



# Delete workspace invitation
Source: https://docs.threetone.in/api-reference/workspace/delete-workspace-invitation

/api-reference/openapi.json delete /v1/workspace/invites
Invalidate a pending workspace invitation. Requires the workspace members invite permission



# Delete workspace webhook
Source: https://docs.threetone.in/api-reference/workspace/delete-workspace-webhook

/api-reference/openapi.json delete /v1/workspace/webhooks/{webhook_id}
Delete the specified workspace webhook



# Get resource
Source: https://docs.threetone.in/api-reference/workspace/get-resource

/api-reference/openapi.json get /v1/workspace/resources/{resource_id}
Gets the metadata of a resource by ID



# Get workspace audit logs
Source: https://docs.threetone.in/api-reference/workspace/get-workspace-audit-logs

/api-reference/openapi.json get /v1/workspace/audit-logs
Returns the audit log for the workspace. Requires enterprise tier and the audit_log_read permission



# Get workspace usage
Source: https://docs.threetone.in/api-reference/workspace/get-workspace-usage

/api-reference/openapi.json post /v1/workspace/analytics/query/usage-by-product-over-time
Returns credit usage broken down by product type over time. The response is a tabular structure with columns, column_types, column_units, and rows



# Invite multiple users
Source: https://docs.threetone.in/api-reference/workspace/invite-multiple-users

/api-reference/openapi.json post /v1/workspace/invites/add-bulk
Email invitations to multiple addresses on a verified domain. Requires the workspace members invite permission and an available seat for each accepted invitation



# Invite user
Source: https://docs.threetone.in/api-reference/workspace/invite-user

/api-reference/openapi.json post /v1/workspace/invites/add
Email an invitation to join the workspace. Requires the workspace members invite permission and an available seat



# List API requests
Source: https://docs.threetone.in/api-reference/workspace/list-api-requests

/api-reference/openapi.json post /v1/workspace/analytics/requests
List API requests with time, column, search, and sort filters. Provide at least one of start_time or end_time



# List service account API keys
Source: https://docs.threetone.in/api-reference/workspace/list-service-account-api-keys

/api-reference/openapi.json get /v1/service-accounts/{service_account_user_id}/api-keys
Get all API keys for a service account



# List workspace auth connections
Source: https://docs.threetone.in/api-reference/workspace/list-workspace-auth-connections

/api-reference/openapi.json get /v1/workspace/auth-connections
Get all auth connections for the workspace



# List workspace groups
Source: https://docs.threetone.in/api-reference/workspace/list-workspace-groups

/api-reference/openapi.json get /v1/workspace/groups
Get all groups in the workspace



# List workspace service accounts
Source: https://docs.threetone.in/api-reference/workspace/list-workspace-service-accounts

/api-reference/openapi.json get /v1/service-accounts
List all service accounts in the workspace



# List workspace webhooks
Source: https://docs.threetone.in/api-reference/workspace/list-workspace-webhooks

/api-reference/openapi.json get /v1/workspace/webhooks
List all webhooks for a workspace



# Remove member from workspace group
Source: https://docs.threetone.in/api-reference/workspace/remove-member-from-workspace-group

/api-reference/openapi.json post /v1/workspace/groups/{group_id}/members/remove
Removes a member from the specified group. Requires `group_members_manage` permission



# Resend workspace invitation
Source: https://docs.threetone.in/api-reference/workspace/resend-workspace-invitation

/api-reference/openapi.json post /v1/workspace/invites/resend
Requests delivery for an existing pending WorkOS invitation. WorkOS owns delivery before category cutover; the Threetone mail pipeline owns it after cutover



# Search user groups
Source: https://docs.threetone.in/api-reference/workspace/search-user-groups

/api-reference/openapi.json get /v1/workspace/groups/search
Searches for user groups in the workspace. Multiple or no groups may be returned



# Set workspace third-party disabling policy
Source: https://docs.threetone.in/api-reference/workspace/set-workspace-third-party-disabling-policy

/api-reference/openapi.json post /v1/workspaces/api-keys/third-party-disabling
Set whether holders of workspace API keys may disable their own keys. Pass null to restore each key's policy; workspace administrators only



# Share workspace resource
Source: https://docs.threetone.in/api-reference/workspace/share-workspace-resource

/api-reference/openapi.json post /v1/workspace/resources/{resource_id}/share
Grant a user or group a role on a workspace resource. You must have administrator access to the resource



# Unshare workspace resource
Source: https://docs.threetone.in/api-reference/workspace/unshare-workspace-resource

/api-reference/openapi.json post /v1/workspace/resources/{resource_id}/unshare
Remove a user or group's role from a workspace resource. You must have administrator access to the resource



# Update member
Source: https://docs.threetone.in/api-reference/workspace/update-member

/api-reference/openapi.json post /v1/workspace/members
Update the specified fields of a workspace member. Workspace administrators only



# Update service account API key
Source: https://docs.threetone.in/api-reference/workspace/update-service-account-api-key

/api-reference/openapi.json patch /v1/service-accounts/{service_account_user_id}/api-keys/{api_key_id}
Update an existing API key for a service account



# Update workspace auth connection
Source: https://docs.threetone.in/api-reference/workspace/update-workspace-auth-connection

/api-reference/openapi.json patch /v1/workspace/auth-connections/{auth_connection_id}
Update an auth connection



# Update workspace group
Source: https://docs.threetone.in/api-reference/workspace/update-workspace-group

/api-reference/openapi.json patch /v1/workspace/groups/{group_id}
Updates an application-managed human group through WorkOS



# Update workspace webhook
Source: https://docs.threetone.in/api-reference/workspace/update-workspace-webhook

/api-reference/openapi.json patch /v1/workspace/webhooks/{webhook_id}
Update the specified workspace webhook



# Account
Source: https://docs.threetone.in/overview/administration/account

Review your profile, update your name, manage two-factor authentication, and find workspace and subscription settings.

Your account identifies you when you sign in. A workspace holds the team's resources and access settings. Check both before changing a shared agent or subscription.

<Frame>
  <img alt="Recording pending for Review account settings. No playable video is available yet." />
</Frame>

## Open your profile

Open your user menu and select **Profile Settings**, or go directly to [Settings](https://threetone.in/app/settings). The **Profile** tab shows your email, full name, current plan, and two-factor authentication status. The **Workspaces** tab is separate from your personal profile.

<Frame>
  <img alt="Screenshot pending for the Threetone profile settings. This illustration is not a product screenshot." />
</Frame>

## Update your name

<Steps>
  <Step title="Open the name editor">Beside **Full name**, select **Update Name**.</Step>
  <Step title="Enter your name">Enter the name you want teammates to see. Use a nonempty value.</Step>
  <Step title="Save and verify">Select **Save**. Reopen your profile and confirm the updated name.</Step>
</Steps>

Your email is currently displayed as account information. This page does not provide a verified email-change workflow. Use the [Help Center](https://help.threetone.in/en) if your sign-in identity needs attention.

## Add two-factor authentication

Two-factor authentication adds a verification step to your sign-in. Prepare an authenticator application before starting.

<Steps>
  <Step title="Start setup">Select **Add Two-Factor Authentication**. If the dashboard requires a recent sign-in, authenticate again and restart setup.</Step>
  <Step title="Configure your authenticator">Scan the displayed QR code or enter the manual setup code in your authenticator. Keep both codes private.</Step>
  <Step title="Verify the code">Enter the current **Verification Code**, then select **Verify & Enable**.</Step>
  <Step title="Store the backup code">Save the displayed **Backup Code** in a private, secure location before closing the dialog. Confirm the profile now shows two-factor authentication enabled.</Step>
</Steps>

<Warning>
  Never share the QR code, setup secret, verification code, or backup code in a screenshot, recording, repository, or support message. The backup code is used by the supported removal workflow; do not assume it provides every kind of account recovery.
</Warning>

To remove two-factor authentication, select **Remove Two-Factor Authentication**, enter **Your Backup Code**, and confirm **Remove 2FA**. Review your account security before removing the additional verification step.

## Find related settings

<CardGroup>
  <Card title="Workspace administration" icon="users" href="/overview/administration/workspaces/overview">Review shared resources, membership, and access.</Card>
  <Card title="Billing" icon="credit-card" href="/overview/administration/billing">Review subscriptions and the billing-management workflow.</Card>
  <Card title="API keys" icon="key" href="/overview/administration/workspaces/api-keys">Manage credentials used by server-side integrations.</Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does changing my profile name change my workspace?">No. Your profile name identifies your account. Workspace settings and shared resources have their own administration workflow.</Accordion>
  <Accordion title="Can I delete my account from Settings?">The displayed Delete account control is not connected to a completed deletion workflow in the documented implementation. Contact support for an account request; do not treat the control as confirmation that account or workspace data was erased.</Accordion>
  <Accordion title="Why does authentication setup ask me to sign in again?">Security changes can require a recent authenticated session. Complete the sign-in and restart the setup rather than reusing an expired challenge.</Accordion>
  <Accordion title="Can I share a backup code with support?">No. Keep authentication codes private. Describe the error and the affected account without sending a credential.</Accordion>
</AccordionGroup>


# Workspace assets
Source: https://docs.threetone.in/overview/administration/assets

Inventory agents, documents, tools, and media through their existing resource workflows.

An asset inventory helps you identify what a workspace owns, who uses it, and what would be affected by a change. Start with resource IDs and dependencies rather than relying on names alone.

<Note>
  Manage resources through their existing product pages and APIs. There is no verified unified Assets library or generic asset-upload workflow. The resource-type enum alone does not establish support for every named asset category.
</Note>

| Resource | Management guide |
| - | - |
| Agents and configuration snapshots | [Versions and drafts](/agents-platform/deploy/versioning) |
| Knowledge documents and source files | [Knowledge base](/agents-platform/configure/knowledge-base/overview) |
| Tool definitions and integration references | [Tools](/agents-platform/configure/tools/overview) |
| Model and voice choices | [Models and voices](/overview/models) |
| Saved transcripts and available recordings | [Conversations](/agents-platform/monitor/conversations) |

## Build a useful inventory

<Frame>
  <img alt="Recording pending for a workspace resource inventory. No playable video is available yet." />
</Frame>

You need access to each resource you intend to review. Visibility in one list does not grant access to every related credential or file.

<Steps>
  <Step title="Record identity and purpose">
    Capture the resource type, ID, readable name, workspace, and responsible person. For agent behavior, keep the branch and version IDs too.
  </Step>

  <Step title="Review dependencies and access">
    Identify agents that reference a document, tool, or integration before changing it. Use [sharing metadata](/overview/administration/workspaces/sharing-resources) where supported to review resource grants.
  </Step>

  <Step title="Use the resource-specific lifecycle">
    Follow the relevant update or deletion operation. Confirm the resulting record and review downstream references; removing one resource does not establish deletion of every exported copy.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Are secrets ordinary downloadable assets?">No. Use the dedicated credential workflow and avoid including secret values in an inventory or export.</Accordion>
  <Accordion title="Does a voice in the catalog belong to my workspace?">Catalog availability identifies a selectable offering. It does not by itself establish ownership or unrestricted redistribution rights.</Accordion>
</AccordionGroup>


# Billing
Source: https://docs.threetone.in/overview/administration/billing

Understand subscriptions, credit information, billing access, and the planned prepaid usage model for Threetone.

Use billing settings to review the selected workspace's subscription and the payment options available to your account. Subscription management uses the signed-in dashboard; it is separate from API-key access.

## Choose a billing task

<CardGroup>
  <Card title="Manage a subscription" icon="credit-card" href="/overview/administration/billing/subscriptions">Review checkout, the billing portal, and scheduled cancellation.</Card>
  <Card title="Understand credits" icon="chart-simple" href="/overview/administration/billing/credits-and-usage">Interpret saved balances and usage fields.</Card>
  <Card title="Planned pricing" icon="list" href="/overview/administration/billing/pricing">Review the draft plan structure before its release.</Card>
  <Card title="Pay as you go" icon="wallet" href="/overview/administration/pay-as-you-go">Understand the planned prepaid model and its availability.</Card>
</CardGroup>

## Subscriptions and usage

A subscription selects a plan and billing interval. Credits represent the usage balance recorded for your workspace. Model choice and the work performed determine how usage should be measured; a credit balance alone is not a guarantee of a fixed number of calls or completed tasks.

Open [Subscriptions](https://threetone.in/app/subscriptions) from **Billing** in your user menu. Confirm the workspace and review the plan, interval, and available controls. Before paying, read the actual checkout amount, currency, and terms.

<Frame>
  <img alt="Screenshot pending for Threetone subscription settings. This illustration contains no actual pricing or payment information." />
</Frame>

## Current and planned behavior

The current source includes subscription checkout, a customer billing portal, scheduled cancellation, and saved subscription reads. Pay-as-you-go top-ups are planned. The [draft pricing page](/overview/administration/billing/pricing) describes the intended commercial direction and does not replace the active checkout catalog.

Plan changes, credit renewal, rollover, refunds, and usage limits need their own published policy and matching implementation. Do not infer a new charge or entitlement from a button label, a zero-valued field, or a planned feature.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can an API key manage billing?">No. Checkout, portal access, and cancellation use dashboard authentication and billing-management permission. The public subscription endpoint is a read operation.</Accordion>
  <Accordion title="Are the draft prices the amounts charged today?">No. The intended plan structure differs from the currently configured INR catalog. Confirm the amount and currency in checkout before making a purchase.</Accordion>
  <Accordion title="Does a paid plan prove an agent can execute?">No. Billing, configuration, resource access, and runtime availability are separate. Review the [Agents Platform availability note](/agents-platform/overview#current-availability) for the documented execution limits.</Accordion>
</AccordionGroup>


# Credits and usage
Source: https://docs.threetone.in/overview/administration/billing/credits-and-usage

Interpret saved subscription balances, distinguish usage totals from period measurements, and check current billing information.

Credit information helps you understand the balance recorded for your workspace. Read the fields together with subscription status and billing-period dates rather than treating one number as a complete usage report.

## Read the subscription information

Use the dashboard or [Get user subscription info](/api-reference/get-user-subscription-info) to inspect the saved information.

| Field | How to interpret it |
| - | - |
| `tier`, `plan_name` | The saved plan identity and display name. |
| `status` | The subscription state reported by the API. |
| `credits_balance` | The recorded wallet balance. |
| `credits_limit` | The included-credit field returned for the subscription. Confirm the effective plan policy before relying on it. |
| `credits_used` | A stored usage total. It is not established as current-month consumption. |
| Billing-period timestamps | The period associated with the saved subscription. |
| `cancel_at_period_end` | Whether cancellation is scheduled at the period boundary. |

## Review a balance change

Check the active workspace, the subscription status, and whether a payment or subscription update has completed. Compare the current response with a previously saved response for the same workspace. Keep timestamps and identifiers when asking support to investigate.

The detailed usage dashboard is not implemented in the documented source. Saved subscription information does not provide a complete breakdown by agent, model, API key, or current billing month.

## Renewals, rollover, and additional usage

The release policy must define how included usage is allocated, when it expires, and how a change of plan affects it. The [planned pricing](/overview/administration/billing/pricing) and [pay-as-you-go](/overview/administration/pay-as-you-go) pages describe the intended direction. They are not evidence that the current wallet enforces every planned rule.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does credits_used show this month's usage?">Not necessarily. The documented projection reads a wallet usage total. Do not label it current-month usage without a period-specific report.</Accordion>
  <Accordion title="Does zero overage mean additional usage is free?">No. The documented overage field is not a verified metered-charge calculation. Consult the effective pricing and checkout terms for charges.</Accordion>
  <Accordion title="How many free credits do I receive?">The current source contains inconsistent free-allocation values. Confirm your actual balance and the effective offer in the dashboard; this guide does not promise a fixed free allotment.</Accordion>
  <Accordion title="Can credits be converted into guaranteed call minutes?">A recorded credit balance alone does not define that conversion. Use the effective plan's allowances and measurement policy; model and carrier charges can be separate.</Accordion>
</AccordionGroup>


# Planned pricing
Source: https://docs.threetone.in/overview/administration/billing/pricing

Review Threetone's draft monthly agent plans and usage rates before the billing catalog and released product are aligned.

<Note>
  These are draft commercial terms selected for the next pricing release. They are not the current checkout catalog or a promise of released capacity. The dashboard and checkout must be aligned before these terms become effective.
</Note>

## Draft monthly plans

| Plan | Monthly price, USD | Included call minutes | Intended concurrent calls |
| - | -: | -: | -: |
| Free | \$0 | 15 | 4 |
| Starter | \$6 | 75 | 6 |
| Creator | \$22 | 275 | 10 |
| Pro | \$99 | 1,238 | 20 |
| Scale | \$299 | 3,738 | 30 |
| Business | \$990 | 12,375 | 40 |
| Enterprise | Contract-specific | Contract-specific | Contract-specific |

No introductory discounts are included in this draft. Annual pricing, local-currency amounts, taxes, seat allocations, and enterprise commitments must appear in the effective offer before purchase.

## Draft usage rates

| Usage | Intended rate |
| - | - |
| Additional call time | \$0.08 per minute. |
| Eligible burst call time | \$0.16 per minute, subject to a separately released concurrency policy. |
| Text messages | \$0.003 per message, where the supported channel is available. |
| Language model usage | Charged separately according to the selected model and measured usage. |
| External carrier usage | Charged according to the connected provider's terms. |

Minute allowances and credit balances are different units. The conversion, rounding, measurement boundaries, failure charging, and renewal rules need an explicit effective policy. Planned prices do not establish that a live call, text channel, or burst capacity is available.

## Current catalog

The documented source currently configures paid subscriptions in INR for Starter, Pro, and Scale. Its prices, credit allocations, and treatment of model costs differ from this draft. Creator, Business, and prepaid top-ups need matching product configuration and implementation before they can be purchased under the intended terms.

Until alignment is released, review the amount and currency shown by the actual checkout. Use [subscription management](/overview/administration/billing/subscriptions) for the supported workflow.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I buy these draft plans now?">Only plans offered by the current checkout are purchasable. This table records the intended future catalog, not an enabled checkout option.</Accordion>
  <Accordion title="Are model and carrier charges included?">The intended policy separates language-model and external carrier charges. The current source uses different wording, so that policy must be reconciled before release.</Accordion>
  <Accordion title="Does Enterprise imply a specific certification or SLA?">No. Security, support, service levels, and other commitments need an approved agreement and verified implementation. A plan name alone does not establish them.</Accordion>
</AccordionGroup>


# Subscriptions
Source: https://docs.threetone.in/overview/administration/billing/subscriptions

Review your plan, start a supported checkout, open billing management, and understand scheduled subscription cancellation.

Review the subscription in the intended workspace before making a billing change. You need billing-management permission for checkout, portal access, and cancellation.

<Frame>
  <img alt="Recording pending for Review subscription management. No playable video is available yet." />
</Frame>

## Review your plan

Open [Subscriptions](https://threetone.in/app/subscriptions). The page uses **Manage your plan**, with **Monthly** and **Yearly** options. Review the saved plan and billing-period details. For a programmatic read, use [Get user subscription info](/api-reference/get-user-subscription-info).

## Start a subscription checkout

This procedure is for starting a new subscription. If you already have a paid subscription, use the billing portal or contact support before choosing another paid-plan checkout. The documented plan buttons do not establish a completed subscription migration workflow.

<Steps>
  <Step title="Choose an available plan">Review the offered paid plan and billing interval. The current catalog is separate from the [planned pricing](/overview/administration/billing/pricing).</Step>
  <Step title="Review checkout">Select the plan's purchase action. In the returned checkout, check the product, amount, currency, interval, and terms before confirming payment.</Step>
  <Step title="Confirm the saved subscription">Return to the dashboard and refresh the subscription information. Read [Get user subscription info](/api-reference/get-user-subscription-info) to verify the saved plan, actual status, period, and balance. The displayed Active badge and a successful return URL are not independent confirmation that payment or subscription processing finished.</Step>
</Steps>

## Open billing management

For an existing paid subscription, select **Manage Billing**. The dashboard opens the customer portal in another tab. Review the options the portal actually provides for payment details, invoices, and subscription settings.

If the portal is unavailable, check workspace access and whether a provider customer exists for the subscription. Keep the error's request identifier when contacting support. Do not send card details or credentials.

## Schedule cancellation

<Steps>
  <Step title="Open the confirmation">Select **Cancel Subscription** and read **Cancel subscription?**.</Step>
  <Step title="Confirm the intended action">Select **Keep Subscription** to leave it active, or **Yes, Cancel** to request cancellation.</Step>
  <Step title="Verify the saved state">Refresh the subscription and check `cancel_at_period_end` and its billing-period end. Cancellation is scheduled for the billing boundary; it is not an immediate deletion or refund request.</Step>
</Steps>

<Warning>
  The documented plan grid does not provide a verified complete upgrade, downgrade, or same-tier interval-change workflow. A different paid-plan button can start another checkout, while some displayed choices have no completed action. Contact support before treating those controls as a plan migration.
</Warning>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does the checkout return page confirm payment?">The return page reflects the checkout URL's status. Verify the saved subscription and balance after returning; do not use the URL alone as payment evidence.</Accordion>
  <Accordion title="Does cancellation delete agents or account data?">No deletion is performed by this cancellation workflow. Data access, retention, and account deletion are separate matters.</Accordion>
  <Accordion title="What if no invoices appear?">An empty view can mean no invoices were returned or that a provider lookup failed. Check the customer portal and contact support with the relevant transaction context. Do not conclude that no payment occurred solely from an empty list.</Accordion>
</AccordionGroup>


# Consolidated billing
Source: https://docs.threetone.in/overview/administration/consolidated-billing

Prepare a billing review across workspaces and understand the limits of existing subscription and quota reads.

Consolidated billing would let a finance team review several workspaces under an agreed payer and invoice arrangement. Prepare the workspace inventory and allocation rules before changing who pays for shared work.

<Note>
  Self-service consolidated invoicing and workspace billing-group management are not available. Existing subscription reads and some group-aware quota calculations do not establish pooled credits, a shared invoice, or a consolidated payment agreement.
</Note>

## Prepare the billing review

You need the workspace owners, current subscription details, and a finance contact authorized to approve the proposed arrangement.

<Steps>
  <Step title="Inventory each workspace">
    Record the workspace name and ID, business owner, plan, currency, billing interval, and current payer. Keep unrelated legal entities and environments identifiable.
  </Step>

  <Step title="Read current subscription information">
    Use [subscription information](/api-reference/get-user-subscription-info) for the selected workspace. Review `status`, `credits_balance`, `credits_used`, billing-period fields, and `open_invoices`. This response does not enumerate every workspace in a billing group.
  </Step>

  <Step title="Define the proposed arrangement">
    Document which workspaces should be included, who receives invoices, and how costs should be allocated. Review [billing groups](/overview/administration/workspaces/billing-groups) for the distinction between saved grouping and billing operations.
  </Step>
</Steps>

Existing professional-voice slot counts can include workspaces in an already configured billing group. That narrow aggregation does not imply that other balances or limits are shared.

Before relying on consolidation, confirm the supported setup process, invoice scope, effective date, tax details, and treatment of existing subscriptions through the [Help Center](https://help.threetone.in/en).

<AccordionGroup>
  <Accordion title="Can I combine invoices from the dashboard?">There is no released consolidated-invoice control. Review current invoices through the existing subscription workflow.</Accordion>
  <Accordion title="Does belonging to a billing group pool credits?">No pooled-credit guarantee follows from the current group metadata or quota reads.</Accordion>
</AccordionGroup>


# Data residency
Source: https://docs.threetone.in/overview/administration/data-residency

Document regional data-handling requirements and the evidence needed before relying on a residency commitment.

Data residency concerns where data is stored and processed. Review it for each category your workflow uses, including uploaded documents, conversations, recordings, credentials, analysis, and operational logs.

<Warning>
  Threetone does not currently expose a verified workspace region-selection or data-migration workflow. A country, language, or time-zone setting does not enforce where data is stored or processed. Do not treat those values as a residency commitment.
</Warning>

## Prepare a residency assessment

Work with the person responsible for your organization's data requirements and the owners of connected systems.

| Requirement | Information to record |
| - | - |
| Storage | Permitted regions for primary data, replicas, backups, and exports |
| Processing | Where model, speech, document, and tool operations may run |
| Access | Who may access the data and from which locations |
| Transfer | Which connected services receive each data category |
| Lifecycle | Retention, deletion, and any migration requirements |

<Steps>
  <Step title="Map the workflow">
    List the [assets](/overview/administration/assets) and external integrations involved. Include data copied into your own application, logs, and review exports.
  </Step>

  <Step title="Request specific confirmation">
    Use the [Help Center](https://help.threetone.in/en) to confirm supported arrangements for the intended deployment. Ask for the scope of any commitment rather than inferring it from a provider name or endpoint hostname.
  </Step>

  <Step title="Record unresolved requirements">
    Keep unsupported regions, transfers, and migration needs visible before using affected data. Review [privacy settings](/agents-platform/monitor/privacy/overview) separately; saved preferences do not prove enforcement.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Does changing my time zone move workspace data?">No. Time-zone preferences control temporal context or presentation, not deployment location.</Accordion>
  <Accordion title="Can I migrate an existing workspace to another region?">No verified self-service region migration is available. Confirm an explicitly supported process before planning a move.</Accordion>
</AccordionGroup>


# Pay as you go
Source: https://docs.threetone.in/overview/administration/pay-as-you-go

Understand Threetone's planned prepaid usage model and the controls that must be available before top-ups are released.

<Note>
  Pay-as-you-go top-ups are planned and are not available through a verified Threetone purchase workflow yet. This page explains the intended model; it contains no instructions to make an unsupported payment.
</Note>

## Intended model

Prepaid usage lets a workspace add funds before consuming additional usage. The intended order is to use included subscription allowance first, then the prepaid balance. Adding funds does not automatically change the underlying plan or its resource and concurrency limits.

Manual top-ups are the first purchase workflow to document once enabled. Automatic top-ups would require a saved payment method, explicit authorization, a trigger threshold, a purchase amount, and clearly visible spend limits.

## Planned controls

| Control | What the release needs to explain |
| - | - |
| Available balance | Amount, currency, and how it maps to measured usage. |
| Manual top-up | Minimum purchase, checkout confirmation, and payment-failure handling. |
| Automatic top-up | Explicit opt-in, threshold, amount, spend cap, and disabling future purchases. |
| Low balance | What stops at exhaustion and how pending work is handled. |
| Plan changes | Whether the stored monetary balance is converted at a new plan's rate. |
| Expiry and refunds | Effective expiry dates, refund terms, and transaction records. |

The [planned pricing](/overview/administration/billing/pricing) describes intended rates. Limits and payment rules must match the released billing system before a balance can be purchased. No top-up cap, expiry period, automatic charge, or refund restriction is established by this page.

## Before relying on prepaid usage

Check that your workspace has a released purchase workflow, a confirmed transaction, a visible balance, and a published usage policy. Confirm the underlying agent and channel are operational separately from payment availability.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I add funds today?">No verified top-up purchase workflow is documented yet. Use the currently offered subscription options and contact support about future prepaid access.</Accordion>
  <Accordion title="Will top-ups upgrade my plan?">The intended model treats prepaid balance and plan entitlement separately. Adding funds should not be assumed to unlock a higher plan's limits.</Accordion>
  <Accordion title="Will my card be charged automatically?">No automatic top-up behavior is established here. Any future automatic purchase must have an explicit opt-in and published controls.</Accordion>
  <Accordion title="Will this work with a paid subscription?">That is the intended model, with included allowance consumed first. It must be verified in the released wallet and billing workflow before customers can rely on it.</Accordion>
</AccordionGroup>


# Usage analytics
Source: https://docs.threetone.in/overview/administration/usage-analytics

Separate saved subscription balances, operational dashboard metrics, and planned public usage reports.

Choose the data source that answers your question. A subscription balance, a conversation-cost chart, and a list of API requests describe different parts of workspace activity.

| Source | Current availability |
| - | - |
| [Subscription information](/api-reference/get-user-subscription-info) | Reads saved plan, credit, period, and invoice information |
| [Agents dashboard analytics](/agents-platform/monitor/analytics) | Reads operational analytics when the deployment has the required data connection |
| [Workspace usage](/api-reference/workspace/get-workspace-usage) | Returns an empty placeholder report |
| [API requests](/api-reference/workspace/list-api-requests) | Returns an empty placeholder report |

<Note>
  The public usage and API-request reports are not working activity reports. Their empty rows do not demonstrate zero usage, zero requests, or a complete audit history.
</Note>

## Review an interval

You need read access to the intended workspace and a clearly defined reporting period.

<Steps>
  <Step title="Confirm scope">
    Record the workspace, reporting dates, time zone, and any agent filters. Keep billing periods separate from custom analysis windows.
  </Step>

  <Step title="Read balances and operational metrics">
    Inspect `credits_balance`, `credits_limit`, and `credits_used` in the subscription response. Compare dashboard metrics with known conversation records before interpreting an empty chart.
  </Step>

  <Step title="Label the report's limits">
    Record missing data and the source of each figure. Do not derive invoices, pooled balances, or request-level accountability from placeholder reports.
  </Step>
</Steps>

For cost decisions, use [cost optimization](/agents-platform/monitor/cost-optimization). For charges and payment terms, review the actual subscription and invoice workflow.

<AccordionGroup>
  <Accordion title="Can I group public usage by billing group?">The contract includes grouping fields, but the current implementation does not calculate report rows.</Accordion>
  <Accordion title="Are operational costs the final invoice amount?">Do not assume equivalence. Keep operational measurements and billing records identified separately.</Accordion>
</AccordionGroup>


# API keys
Source: https://docs.threetone.in/overview/administration/workspaces/api-keys

Create a scoped personal API key in Threetone, store it securely, and replace or revoke it when your integration changes.

Use a personal API key to authenticate requests from your server or integration. Create and manage these keys in the dashboard, then send the secret in the `x-api-key` header. Give each deployed service its own key so you can replace or revoke it independently.

<Frame>
  <img alt="Recording pending for Create, rotate, and revoke an API key. No playable video is available yet." />
</Frame>

## Before you begin

Sign in to the workspace your integration should use. You need permission to create personal API keys and access to the operations you intend to grant. Have a server-side secret manager or environment variable ready to store the new secret.

## Create a key

<Steps>
  <Step title="Open API keys">
    Open [Developers > API Keys](https://threetone.in/app/developers/api-keys), then select **Create key**.
  </Step>

  <Step title="Name and scope the key">
    Use a name that identifies the service and environment, such as `Support integration staging`. Keep **Restrict key** enabled and select only the available permissions your integration needs.

    Write access includes read access for the same API area. The permission choices are limited by what your own account can grant.
  </Step>

  <Step title="Choose expiry and IP restrictions">
    Set **Expire after** to match the integration's lifetime and your rotation policy. If requests come from known outbound addresses, enable **Restrict by IP address** and enter those addresses or CIDR ranges.
  </Step>

  <Step title="Create and store the secret">
    Select **Create key**, then copy the secret from the confirmation dialog before closing it. Save it in your server-side secret store. The key list does not reveal the complete secret again.
  </Step>

  <Step title="Verify a permitted request">
    Follow the [authentication examples](/api-reference/authentication#send-the-header) to send `x-api-key`. Choose a read operation covered by the key's permissions and confirm that the response belongs to the intended workspace.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for API-key metadata list with names and permissions, with every secret hidden. This illustration is not a product screenshot." />
</Frame>

The key should appear in your API-key list, and a permitted request should authenticate successfully. This verifies the key's access to that operation; it does not confirm that an agent or external integration has executed.

<Warning>
  Never put an API key in a browser bundle, URL, public repository, screenshot, recording, log, or support message. Do not send both `x-api-key` and `Authorization` in one request.
</Warning>

## Replace or revoke a key

For a planned rotation, create a replacement key with the required permissions. Update every service that uses the old key, verify its requests, then use the old key's **Revoke** action and confirm **Revoke key**.

If a secret may have been exposed, revoke it immediately and replace it in the affected services. A revoked key must no longer be used for requests.

Review a key's permissions, expiry, and IP restrictions when an integration changes. Editing permissions can produce a replacement secret. If the dashboard shows a new secret, save it and update the integration before closing the dialog.

## Personal keys and service accounts

Personal key creation and management use the Threetone dashboard. The public API reference is not a separate personal-key creation workflow.

Service accounts and their API-key operations are currently unavailable. Their reference endpoints are present, but they return HTTP `501`. Use a permitted personal key for the workflow described here. See [Create workspace service account](/api-reference/workspace/create-workspace-service-account) for the reserved operation's schema.

## Troubleshooting

| Result | What to check |
| - | - |
| The secret was not saved | Create a replacement key. The full secret is shown only when it is created. |
| `401 Unauthorized` | Check the complete header value and whether the key expired, was disabled, or was revoked. |
| `403 Forbidden` | Check the key's permissions, the owner's workspace access, and the caller's outbound IP address. |
| Key creation is unavailable | Confirm that your account can create keys and that the permission list loaded successfully. |

Keep the response's `X-Request-Id` when requesting help, and remove the key from any shared evidence. The [authentication guide](/api-reference/authentication) covers header examples and credential errors.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I reveal a complete key after creation?">The list does not reveal the full secret again. Create a replacement if the secret was not stored.</Accordion>
  <Accordion title="How should I replace a key?">Create the replacement, update the integration, verify permitted requests, then revoke the old key. If it was exposed, revoke it promptly.</Accordion>
  <Accordion title="Can I create a service-account key instead?">The documented service-account operations remain unavailable. Use the supported personal-key workflow with the required permissions.</Accordion>
</AccordionGroup>


# Audit logs
Source: https://docs.threetone.in/overview/administration/workspaces/audit-logs

Prepare an administrative event-review policy and understand the current placeholder audit-log API.

An administrative audit trail should answer who acted, what changed, which workspace and resource were affected, and whether the action succeeded. That requires collected events with a defined coverage and retention policy.

<Warning>
  [Get workspace audit logs](/api-reference/workspace/get-workspace-audit-logs) currently returns `entries=[]`, `has_more=false`, and `next_cursor=null`. It does not query a collected audit trail. An empty response cannot establish that no administrative actions occurred.
</Warning>

## Prepare an audit review

Work with the workspace administrator and the person responsible for access reviews or incident response.

<Steps>
  <Step title="Define required events">
    List membership changes, group changes, resource grants, credential operations, configuration publication, and billing actions your review must cover. Identify the responsible system for each event.
  </Step>

  <Step title="Define investigation fields">
    Record the actor, workspace, resource, timestamp, action, outcome, and request identifier you need. Keep credentials and unnecessary transcript content out of review notes.
  </Step>

  <Step title="Track missing evidence">
    Use current member lists, resource metadata, and version reads to inspect present state. Label them as snapshots; they cannot reconstruct an unrecorded history of changes.
  </Step>
</Steps>

The public contract includes `actor_uid`, `class_name`, `activity_name`, and millisecond time-window filters. Those fields describe a future query shape; the current handler ignores them. A released audit workflow needs verified event collection, access controls, pagination, retention, and export behavior before use as an accountability record.

<AccordionGroup>
  <Accordion title="Does the API request report provide the missing audit trail?">No. That report also returns placeholder rows, and request logs would not automatically establish full administrative event coverage.</Accordion>
  <Accordion title="Can current access metadata prove who granted access?">No. A current grant shows present state, not a complete historical record of its creation or changes.</Accordion>
</AccordionGroup>


# Billing groups
Source: https://docs.threetone.in/overview/administration/workspaces/billing-groups

Understand existing group-aware billing metadata and prepare a workspace allocation plan.

A billing group associates workspaces for a defined commercial purpose. It is separate from a user group, which organizes people and resource access.

<Note>
  There is no released public API or dashboard workflow to create billing groups, change their membership, or assign a shared payer. Existing group-aware quota reads are a limited implementation, not a complete billing-management feature.
</Note>

## Understand the existing read behavior

[Subscription information](/api-reference/get-user-subscription-info) includes `professional_voice_slots_used` and `professional_voice_slots_used_in_workspace`. When a billing group is already configured, the first count can include linked workspaces, while the second identifies the selected workspace's portion. This does not establish shared credits or group-wide invoice management.

## Prepare a group proposal

You need the workspace owners and an authorized billing contact.

<Steps>
  <Step title="List proposed members">
    Record each workspace ID, owner, current subscription, and intended cost center. Specify who should approve additions and removals.
  </Step>

  <Step title="Define allocation rules">
    Separate the intended payer, usage attribution, quotas, and access rules. Being billed together must not be assumed to grant people access to another workspace.
  </Step>

  <Step title="Confirm the supported arrangement">
    Review [consolidated billing](/overview/administration/consolidated-billing) and request confirmation through the [Help Center](https://help.threetone.in/en). Keep implementation and commercial approval pending until both are established.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Can a workspace user group act as a billing group?">No. User-group membership and resource permissions do not create a billing association.</Accordion>
  <Accordion title="Do group-wide quota counts prove pooled credits?">No. Only the specific reported quota is aggregated by that read path.</Accordion>
</AccordionGroup>


# Domain verification
Source: https://docs.threetone.in/overview/administration/workspaces/domain-verification

Prepare domain ownership and identity-routing requirements without assuming a self-service verification workflow.

Domain verification establishes that an organization controls a domain used for an identity configuration. It is separate from verifying one person's email address or inviting that person into a workspace.

<Note>
  Threetone has no released self-service domain-claim, DNS-challenge, or verification-status management workflow. The SSO sign-in entry uses organization-domain lookup, but that lookup is not a domain-verification process or proof of exclusive domain ownership.
</Note>

## Prepare the domain review

You need the workspace owner, the domain's DNS administrator, and the person managing your identity provider.

<Steps>
  <Step title="Inventory the domains">
    Record primary email domains, subdomains, aliases, and any domains shared by separate organizations. Identify who can authorize changes to each one.
  </Step>

  <Step title="Define routing and membership expectations">
    Decide which workspace an employee should reach and how external collaborators should sign in. Domain matching must not be assumed to grant membership or resource access.
  </Step>

  <Step title="Obtain supported setup instructions">
    Contact the [Help Center](https://help.threetone.in/en) with the workspace and domain requirements. Use only challenge values and DNS records supplied through an approved setup process. No generic TXT value is documented here.
  </Step>
</Steps>

Continue with the [SSO readiness guide](/overview/administration/workspaces/sso) to plan provider configuration, recovery access, and provisioning separately. Do not remove an existing sign-in route until the intended users and administrators can use its replacement.

<AccordionGroup>
  <Accordion title="Does verifying my email verify the company domain?">No. Email verification identifies control of a mailbox; domain administration is a separate responsibility.</Accordion>
  <Accordion title="Does a matching domain automatically add workspace members?">No such automatic membership guarantee is established by the SSO domain lookup.</Accordion>
</AccordionGroup>


# Members and access
Source: https://docs.threetone.in/overview/administration/workspaces/members

Invite teammates, review workspace seats and groups, and understand how resource sharing differs from API-key permissions.

Workspace membership gives a person access to your team in Threetone. Their seat, workspace permissions, and access to individual resources determine what they can do. Review each of these when adding or changing a member.

<Frame>
  <img alt="Recording pending for Invite a member and review access. No playable video is available yet." />
</Frame>

## Before you begin

Confirm that you are in the correct workspace. To invite someone, you need permission to invite workspace members and an available seat of the selected type. Changing an existing member's seat or disabling their access requires workspace administration permission.

Have the person's email address ready. If they need an existing group's access, identify that group before sending the invitation.

## Invite a member

<Steps>
  <Step title="Open the members page">
    Open [Workspace > Members](https://threetone.in/app/workspace/members). Review the seat allocation and current members before creating another invitation.
  </Step>

  <Step title="Enter the invitation details">
    Select **Invite member** and enter the person's email address. Choose an available **Basic seat** or **Full seat**, then select any groups they should join.
  </Step>

  <Step title="Send and review the invitation">
    Submit the invitation, then check the pending invitations on the members page. The recipient must accept the invitation before it becomes an active membership.
  </Step>

  <Step title="Check access after acceptance">
    Confirm that the person appears in the members list with the intended seat. Review their groups and the resources they need to use.
  </Step>
</Steps>

<Frame>
  <img alt="Screenshot pending for Members and access showing a synthetic invitation and separate seat and resource roles. This illustration is not a product screenshot." />
</Frame>

An invitation is not confirmation that the person has joined. If it is still pending, check the address and use the pending invitation's resend or cancellation action as appropriate.

## Understand the access controls

| Control | What to review |
| - | - |
| Workspace seat | The members page labels seats as Admin, Full seat, or Basic seat. Choose a seat appropriate to the person's responsibilities and available allocation. |
| Workspace permissions | Permissions govern actions such as inviting members, managing groups, or accessing product areas. Do not infer every permission from the seat label. |
| Groups | Group membership lets you organize people and share resources with the group. Review membership when responsibilities change. |
| Resource role | A shared resource can grant `admin`, `editor`, `commenter`, or `viewer` access to a person or group. This role applies to that resource. |
| API-key permissions | An integration key has its own allowed API operations. Creating a key does not grant additional workspace authority to its owner. |

Open [Workspace > Groups](https://threetone.in/app/workspace/groups) to review groups. You can create an application-managed group and manage its members. Some system or directory-managed groups have restricted controls.

When using the [resource sharing API](/api-reference/workspace/share-workspace-resource), supply the resource type, role, and a user or group target. Setting `group_id` to `default` gives every workspace member that baseline role. Review this choice carefully before sharing sensitive resources.

## Change or disable a member's access

On the members page, find the person and review their current seat before making a change. Confirm any administrator promotion or demotion in the dialog. Demoting your own administrator seat removes your administration access.

Disabling a member and deleting their data are different actions. Permanent member deletion is not currently available from this page. The workspace owner's membership is protected from seat or access changes until ownership is transferred.

## Use the workspace API

* [Invite user](/api-reference/workspace/invite-user) accepts `email` and optional `seat_type`, `group_ids`, and `usage_limit`.
* [Invite multiple users](/api-reference/workspace/invite-multiple-users) requires a verified domain and an available seat for each accepted invitation.
* [Update member](/api-reference/workspace/update-member) accepts the member's `email`, optional `is_locked`, and optional `workspace_seat_type`.
* [List workspace groups](/api-reference/workspace/list-workspace-groups), [add a member to a group](/api-reference/workspace/add-member-to-user-group), and [remove a member from a group](/api-reference/workspace/remove-member-from-workspace-group) manage group membership.
* [Share](/api-reference/workspace/share-workspace-resource) and [unshare](/api-reference/workspace/unshare-workspace-resource) change access to an individual resource.

API seat values are `workspace_admin`, `workspace_member`, and `workspace_lite_member`. Use the endpoint's request schema rather than sending dashboard display labels.

## Troubleshooting

* **A seat cannot be selected:** review the seat allocation. The invitation form disables seat types with no available allocation.
* **An invitation is not accepted:** confirm the email address and check whether the invitation is still pending before resending it.
* **A member cannot see a resource:** check their groups and the resource's sharing settings as well as their workspace membership.
* **A member change is blocked:** check your administration permission and whether the target is the protected workspace owner or a directory-managed member.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does an invitation immediately grant resource access?">An invitation and an accepted membership are different states. Resource sharing and operation permissions must also be reviewed.</Accordion>
  <Accordion title="Can I remove the workspace owner like another member?">Owner changes require the supported ownership-transfer process. The owner is protected from ordinary member-removal operations.</Accordion>
  <Accordion title="Is a resource role the same as a seat type?">No. Seat type describes membership; a resource role describes access to the shared resource. Do not infer one from the other.</Accordion>
</AccordionGroup>


# Model approvals
Source: https://docs.threetone.in/overview/administration/workspaces/model-approvals

Review workspace model availability and prepare model-admission requirements without assuming an approval editor exists.

A model review should cover the intended task, capabilities, data handling, quality criteria, and cost evidence. Keep those decisions separate from whether a model appears in a catalog response.

<Note>
  The model catalog applies published availability and workspace entitlement rules. There is no released workspace approval-request queue or self-service model allowlist editor. Reading an eligible model does not grant permission to change catalog policy or prove runtime availability.
</Note>

## Review available models

You need access to the workspace and its model catalog.

<Steps>
  <Step title="Read the workspace catalog">
    Use [List available AI models](/api-reference/agents-platform/list-available-ai-models), optionally filtered by `family`. Inspect [one model](/api-reference/agents-platform/get-available-ai-model) using its `model_id`. Record `catalog_release_id` and `published_at` with your review.
  </Step>

  <Step title="Document the decision">
    Record the use case, reviewer, acceptable data categories, expected output, and the evidence required for approval. Include backup models and any custom endpoint in the review scope.
  </Step>

  <Step title="Validate the proposed configuration">
    Follow [models and voices](/overview/models) and inspect the saved agent configuration. Publication still applies compatibility checks. Voice and custom-model publication remain unavailable, and execution has its own gate.
  </Step>
</Steps>

A model absent from your response may be unavailable to the workspace or excluded by the catalog query. Do not bypass that result with an invented model ID. Request an availability review through the [Help Center](https://help.threetone.in/en).

<AccordionGroup>
  <Accordion title="Can I approve a model through the listing endpoint?">No. Catalog listing and detail operations are reads.</Accordion>
  <Accordion title="Does catalog eligibility guarantee zero retention?">No. Data-handling requirements need separately verified provider and execution behavior.</Accordion>
</AccordionGroup>


# Workspaces
Source: https://docs.threetone.in/overview/administration/workspaces/overview

Review your Threetone workspace, update its name, and find members, groups, subscription details, and API keys.

A workspace brings your team's agents, knowledge base, tools, and access settings together. Start by checking the workspace name and owner before changing shared resources or inviting people.

<Frame>
  <img alt="Recording pending for Review your workspace. No playable video is available yet." />
</Frame>

## Before you begin

Sign in to Threetone with a membership in the workspace you want to manage. You need permission to manage workspace settings to change shared settings. Ask a workspace administrator if an action is unavailable to your account.

## Review your workspace

<Steps>
  <Step title="Open workspace settings">
    Open [Workspace](https://threetone.in/app/workspace). On the **General** page, confirm the workspace name and owner match the team you intend to manage.
  </Step>

  <Step title="Check access and allocation">
    Review the displayed member permissions, current plan, credit balance, and seat allocation. Use [Members](https://threetone.in/app/workspace/members) to inspect membership and [Groups](https://threetone.in/app/workspace/groups) to review how people are organized.
  </Step>

  <Step title="Choose the administration task">
    Continue to [members and access](/overview/administration/workspaces/members) to invite someone or review sharing. Open [API keys](/overview/administration/workspaces/api-keys) when a server or integration needs programmatic access.
  </Step>
</Steps>

You should now know which workspace you are managing, who owns it, and where to review team access. A displayed setting describes the current value; it does not necessarily have an editable control on the General page.

## Change the workspace name

On [Workspace](https://threetone.in/app/workspace), select **Change workspace name**. Enter a non-empty name of up to 100 characters, then select **Save**. Confirm that the new name appears under Workspace details after the save succeeds.

Choose a name your team can recognize when working across multiple workspaces. Renaming a workspace is separate from changing its members or resource access.

## Find the right settings

| Task | Where to go |
| - | - |
| Review workspace details and allocation | [Workspace > General](https://threetone.in/app/workspace) |
| Invite a person or review their seat | [Workspace > Members](https://threetone.in/app/workspace/members) |
| Organize workspace members into groups | [Workspace > Groups](https://threetone.in/app/workspace/groups) |
| Review your subscription | [Subscriptions](https://threetone.in/app/subscriptions) |
| Create or revoke a personal API key | [Developers > API Keys](https://threetone.in/app/developers/api-keys) |
| Review your personal account settings | [Account settings](https://threetone.in/app/settings) |

Subscription changes require billing-management access. Check the current terms shown in the dashboard before confirming a billing change.

For API access to existing workspace resources, see [Get resource](/api-reference/workspace/get-resource) and [List workspace groups](/api-reference/workspace/list-workspace-groups). The [subscription response](/api-reference/get-user-subscription-info) provides subscription information; personal dashboard settings are not all public API operations.

## Troubleshooting

* **Details do not load:** use **Retry** on the affected section. Confirm that you are signed in and still have access to the workspace.
* **A change is rejected:** check that your account has the required workspace permission. A visible page does not grant permission to change every setting.
* **The wrong team appears:** check the workspace name before continuing. Do not invite people or create integration keys until you are in the intended workspace.

For account or workspace help, use the [Help Center](https://help.threetone.in/en).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Is my account the same as my workspace?">Your account identifies you. The workspace is the context for shared resources and membership. Check the selected workspace before changing shared settings.</Accordion>
  <Accordion title="Do seat labels define every permission?">No. Membership, resource roles, API-key permissions, and operation authorization are separate. Review each where it applies.</Accordion>
</AccordionGroup>


# Service accounts
Source: https://docs.threetone.in/overview/administration/workspaces/service-accounts

Prepare machine identities and access requirements while service-account operations are unavailable.

A service account represents an application or automated job independently of a person's sign-in. Define its owner, purpose, and required permissions before issuing machine credentials.

<Note>
  Service accounts are being rebuilt around machine-to-machine authentication. Listing, creation, and service-account API-key operations currently return HTTP 501. The dashboard page and public contracts do not establish a usable service-account lifecycle.
</Note>

## Prepare an automation identity

Work with the workspace administrator and the person responsible for the application.

<Steps>
  <Step title="Describe the workload">
    Record the application name, environment, owner, and expected API operations. Separate a production workload from development or local testing.
  </Step>

  <Step title="Specify access">
    List required resources and read or write actions. Identify any publication, deletion, or credential-management actions that need an explicit review step.
  </Step>

  <Step title="Define credential operations">
    Assign responsibility for credential storage, rotation, revocation, and incident response. Record how the application should behave when access expires or is removed.
  </Step>
</Steps>

The [service-account list](/api-reference/workspace/list-workspace-service-accounts) and [creation contract](/api-reference/workspace/create-workspace-service-account) remain reference material for the unavailable operations. Repeated requests will not enable them.

[Personal API keys](/overview/administration/workspaces/api-keys) have a separate implemented lifecycle. They retain human ownership and should not be described as service accounts. If that ownership model does not meet your workload's requirements, keep the integration's identity setup pending.

<AccordionGroup>
  <Accordion title="Can I create one using the visible dashboard form?">The current backend rejects service-account operations with HTTP 501, including requests from that form.</Accordion>
  <Accordion title="Can an old service-account key workflow be reused?">The prior API-key-backed implementation has been removed. Wait for the supported replacement lifecycle.</Accordion>
</AccordionGroup>


# Sharing resources
Source: https://docs.threetone.in/overview/administration/workspaces/sharing-resources

Inspect resource grants and share eligible workspace resources with a member or group through the API.

Resource sharing grants a person or group access to a specific workspace resource. Review the target and role together; a viewer grant and an editor grant support different work.

<Note>
  Resource metadata and grant operations are implemented. Native integration tools remain owner-only and reject sharing until credential-use approval is supported. A resource grant does not transfer a private credential or enable an unavailable runtime operation.
</Note>

You need the resource ID and type, an existing workspace recipient, and permission to manage that resource's sharing.

<Steps>
  <Step title="Inspect current access">
    [Get resource](/api-reference/workspace/get-resource) with the correct `resource_type`. Review `role_to_group_ids` and `share_options`. Names and creator metadata may be absent, so keep the resource ID in your review.
  </Step>

  <Step title="Choose a specific recipient">
    [Share workspace resource](/api-reference/workspace/share-workspace-resource) accepts exactly one of `user_email` or `group_id`, together with `resource_type` and `role`. The accepted roles are `viewer`, `commenter`, `editor`, and `admin`. Choose the access needed for the intended work.
  </Step>

  <Step title="Read the resulting grants">
    Request the metadata again and verify the target and role. Use [Unshare workspace resource](/api-reference/workspace/unshare-workspace-resource) when removing the grant, then review other direct or group grants that may still provide access.
  </Step>
</Steps>

The special `group_id` value `default` targets the workspace. Use it only when workspace-wide sharing is intended. This is distinct from selecting a named [user group](/overview/administration/workspaces/user-groups).

<AccordionGroup>
  <Accordion title="Does sharing invite someone who is not a member?">No. The recipient must resolve to an existing workspace member or group. Manage invitations separately.</Accordion>
  <Accordion title="Does unsharing one grant remove all access?">Not necessarily. Other memberships, groups, or grants may still authorize access.</Accordion>
</AccordionGroup>


# Single sign-on
Source: https://docs.threetone.in/overview/administration/workspaces/sso

Use the existing SSO entry for configured organizations and prepare provider, provisioning, and recovery requirements.

Single sign-on lets an organization authenticate people through its identity provider. Authentication, workspace membership, and resource permissions remain separate decisions.

<Note>
  An SSO sign-in entry exists for organizations with a configured identity connection. Self-service provider-connection setup, domain administration, and a verified SCIM rollout are not released workflows. Sign-in availability depends on the deployment's organization and provider configuration.
</Note>

## Sign in to a configured organization

Use this flow only when your administrator has confirmed that the organization is configured.

<Steps>
  <Step title="Open SSO sign-in">
    Open [Continue with SSO](https://threetone.in/app/sso), enter your company address in **Email**, and select **Continue**.
  </Step>

  <Step title="Follow the configured provider flow">
    The application looks up an organization using the email domain and starts authorization. If no matching workspace is found, ask the administrator to verify the domain and organization mapping.
  </Step>

  <Step title="Confirm workspace access">
    After a successful sign-in, confirm the selected workspace and available resources. A successful identity-provider login alone does not establish every workspace permission.
  </Step>
</Steps>

## Prepare provider and SCIM setup

Use the focused preparation guides for [Microsoft Entra SAML SSO](/overview/administration/workspaces/sso/microsoft-entra-saml), [Okta SAML SSO](/overview/administration/workspaces/sso/okta-saml), and [SCIM](/overview/administration/workspaces/sso/scim).

| Area | Review before rollout |
| - | - |
| Provider connection | Organization, supported protocol, issuer or metadata, exact redirect endpoints, and certificate lifecycle |
| User mapping | Stable identity, email changes, workspace membership, and external collaborators |
| SCIM provisioning | Authoritative directory, user activation and removal, group mapping, and reconciliation behavior |
| Recovery | Administrator recovery access and a tested response to provider failure |

Existing directory-related fields or badges do not prove that provisioning and deprovisioning work end to end. Obtain supported setup instructions through the [Help Center](https://help.threetone.in/en) and verify the complete lifecycle before enforcing a new sign-in policy.

<AccordionGroup>
  <Accordion title="Is SSO the same as SCIM?">No. SSO handles authentication; SCIM concerns directory provisioning. Each needs a separately supported and verified setup.</Accordion>
  <Accordion title="Can I enforce SSO from this page?">No self-service enforcement control is documented. Do not infer enforcement from the presence of a sign-in form.</Accordion>
  <Accordion title="Which provider metadata should I paste into Threetone?">Wait for the supported connection instructions for your organization. Do not guess entity IDs, redirect URLs, certificates, or provisioning tokens.</Accordion>
</AccordionGroup>


# Microsoft Entra SAML SSO
Source: https://docs.threetone.in/overview/administration/workspaces/sso/microsoft-entra-saml

Prepare Microsoft Entra connection details and a controlled sign-in review for a supported Threetone organization.

Microsoft Entra SAML setup connects an organization's enterprise application to its configured sign-in service. Prepare the tenant, connection values, and test users before changing access policy.

<Note>
  Threetone does not offer a released self-service Entra connection wizard. The existing [SSO sign-in entry](/overview/administration/workspaces/sso) can route an already configured organization, but this guide does not supply a universal ACS URL or Entity ID.
</Note>

## Before you begin

You need an Entra administrator allowed to manage the enterprise application, a Threetone workspace owner, an agreed test cohort, and exact connection details supplied through the supported setup process.

| Entra field | Value to obtain |
| - | - |
| Identifier, or Entity ID | The identifier for the intended SAML connection |
| Reply URL, or ACS URL | The connection's assertion-consumer endpoint |
| App Federation Metadata URL | Metadata from the organization's Entra application |

These field relationships are documented in [WorkOS's Entra SAML guide](https://workos.com/docs/integrations/entra-id-saml). They do not establish a Threetone setup control.

<Steps>
  <Step title="Confirm the tenant and application">
    Record the tenant, enterprise application, intended workspace, and authorized users. Keep test and production connection details separate.
  </Step>

  <Step title="Review connection and identity mapping">
    Compare the supplied Entity ID and ACS URL with the application configuration. Review email and identity claims, user assignments, and signing-certificate ownership using [Microsoft's SAML setup documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso).
  </Step>

  <Step title="Verify the agreed rollout">
    Once the connection is configured, test the Threetone SSO entry with representative users. Confirm the resulting workspace and permissions, an unassigned user's behavior, and administrator recovery before changing sign-in requirements.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Can I use the Threetone sign-in URL as the ACS URL?">Do not substitute it. Use the exact ACS value issued for the configured SAML connection.</Accordion>
  <Accordion title="Does Entra app assignment provision workspace groups?">Do not assume that. Directory provisioning and group mapping require a separately verified [SCIM workflow](/overview/administration/workspaces/sso/scim).</Accordion>
</AccordionGroup>


# Okta SAML SSO
Source: https://docs.threetone.in/overview/administration/workspaces/sso/okta-saml

Prepare Okta connection values, application assignments, and sign-in checks for an approved Threetone setup.

An Okta SAML integration defines where Okta sends assertions and which users may access the application. Match that configuration to the intended Threetone organization before inviting a wider audience.

<Note>
  A self-service Okta connection workflow is not released in Threetone. Use this page to prepare and review an explicitly supported setup. The existing company-email SSO entry is not an Okta metadata or certificate editor.
</Note>

## Before you begin

Coordinate an Okta application administrator, the Threetone workspace owner, test users, and the exact connection settings from the supported setup process.

| Okta field | Review |
| - | - |
| Single sign-on URL | The connection's ACS endpoint |
| Audience URI, or SP Entity ID | The intended SAML audience |
| Name ID and attribute mapping | The agreed stable identity and email mapping |
| Application assignments | The users allowed to test and use the integration |

Okta defines the ACS and audience fields in its [SAML field reference](https://help.okta.com/en-us/content/topics/apps/aiw-saml-reference.htm). Follow the configuration supplied for this connection rather than values copied from another application.

<Steps>
  <Step title="Collect the connection record">
    Record the Okta organization, application, target workspace, metadata, and certificate owner. [WorkOS's Okta SAML guide](https://workos.com/docs/integrations/okta-saml) explains the provider-side exchange of connection details.
  </Step>

  <Step title="Review a limited assignment">
    Start the rollout plan with a small test cohort. Check identity attributes and the expected workspace role without assuming that an Okta group automatically grants Threetone resource access.
  </Step>

  <Step title="Verify sign-in and recovery">
    After supported configuration is complete, use the [Threetone SSO flow](/overview/administration/workspaces/sso). Verify workspace access, denied access for an unassigned user, and administrator recovery before changing sign-in policy.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Should I guess the Audience URI from the website domain?">No. Obtain the exact Entity ID for the intended connection.</Accordion>
  <Accordion title="Does a successful SAML login verify deprovisioning?">No. Review user removal, group changes, and session behavior separately in the [SCIM plan](/overview/administration/workspaces/sso/scim).</Accordion>
</AccordionGroup>


# SCIM provisioning
Source: https://docs.threetone.in/overview/administration/workspaces/sso/scim

Prepare directory ownership, user and group mappings, and lifecycle verification before relying on automated provisioning.

SCIM provisioning synchronizes directory identity data with an application. Plan creation, updates, suspension, reactivation, and group changes separately from the SSO sign-in test.

<Note>
  Threetone has identity-event processing and directory-related membership fields, but no released self-service SCIM setup or verified end-to-end provisioning rollout. There is no documented Threetone tenant-URL and token wizard to follow.
</Note>

## Prepare the directory plan

You need the directory administrator, workspace owner, a small test cohort, and an agreed authority for identities and group membership. [WorkOS directory provisioning](https://workos.com/docs/authkit/directory-provisioning) requires organization-specific setup; provider capability alone does not activate it in Threetone.

<Steps>
  <Step title="Define authoritative identities">
    Record stable user identifiers, primary emails, group IDs, and the intended workspace. Decide how contractors, duplicate emails, renamed users, and existing manual memberships should be handled.
  </Step>

  <Step title="Specify mappings and credentials">
    Document the intended user and group mappings. Obtain endpoint and credential details only through the supported setup process. Store provisioning credentials securely and identify their rotation owner.
  </Step>

  <Step title="Verify the complete lifecycle">
    Once provisioning is supported, test creation, attribute updates, group addition and removal, suspension, and reactivation. Inspect workspace membership, resource access, and existing-session behavior after each change. Record delayed or failed synchronization separately.
  </Step>
</Steps>

Treat deactivation, account deletion, and directory disconnection as distinct actions. WorkOS documents different behavior for deprovisioning a user and deleting a directory; neither should be assumed to erase application data. See [retention limits](/agents-platform/monitor/privacy/retention).

The current [user-group view](/overview/administration/workspaces/user-groups) can display directory metadata. A Directory badge is not evidence that all lifecycle checks passed.

<AccordionGroup>
  <Accordion title="Does disabling SSO remove a workspace member?">Do not assume it. Authentication, membership status, resource grants, and active sessions need separate verification.</Accordion>
  <Accordion title="Should I edit a directory-managed group manually?">Follow the group's management source. The dashboard restricts manual controls for directory-managed or frozen groups.</Accordion>
</AccordionGroup>


# User groups
Source: https://docs.threetone.in/overview/administration/workspaces/user-groups

Create and maintain workspace groups, review membership, and distinguish group access from billing allocation.

User groups organize workspace members so you can review team membership and share eligible resources with several people together. They do not create billing groups or substitute for workspace membership.

You need permission to manage groups and existing members to add. System groups and directory-managed or frozen groups are not editable through the manual group controls.

<Steps>
  <Step title="Create a manual group">
    Open [Workspace > Groups](https://threetone.in/app/workspace/groups). Select **Create group**, enter a **Group name**, and save it. Choose a name that describes a team or responsibility. Names must contain 1 to 100 characters.
  </Step>

  <Step title="Review membership">
    Open the group's **Manage Group** action and review **Members**. Member selections issue their own add or remove requests. Use **Save changes** for a renamed group, then reopen it to verify the result.
  </Step>

  <Step title="Inspect permissions and resource grants">
    **Manage Access** displays currently assigned permissions; it is a read-only view. Use the supported [resource-sharing workflow](/overview/administration/workspaces/sharing-resources) for an eligible resource grant.
  </Step>
</Steps>

The API supports [list](/api-reference/workspace/list-workspace-groups), [create](/api-reference/workspace/create-workspace-group), update, delete, and membership operations. Creation requires an `Idempotency-Key`. Preserve it when retrying the same request after an uncertain outcome; changing the request requires a new key.

Review affected resource access before removing members or deleting a group. A directory badge identifies management metadata, not proof of a complete [SCIM deployment](/overview/administration/workspaces/sso).

<AccordionGroup>
  <Accordion title="Does Create group invite new people?">No. Add existing workspace members, and use the separate invitation workflow for new members.</Accordion>
  <Accordion title="Can I change every group from the dashboard?">No. System, directory-managed, and frozen groups have restricted manual controls. Review their management source first.</Accordion>
</AccordionGroup>


# Introduction
Source: https://docs.threetone.in/overview/intro

Understand Threetone Agents Platform, its core resources, and the guides for configuring agents and managing your workspace.

Threetone brings agent configuration, knowledge, tools and conversation records
into a shared workspace. Use the dashboard to author configurations and review
resources. Use the public API to connect those resources to your own systems.

## How Threetone fits together

<Frame>
  <img alt="Recording pending for the Threetone introduction. No playable video is available yet." />
</Frame>

Start with an agent's purpose, instructions and model choices. Add the knowledge
sources and tool definitions it needs. Review changes as configuration snapshots,
and inspect conversation records when they are available.

<Note>
  These guides distinguish configuration from execution. Saving an agent or
  publishing a configuration version does not establish that a channel or live
  conversation is ready. See [current availability](/agents-platform/overview#current-availability)
  before planning a live deployment.
</Note>

## Core concepts

| Resource | What it represents | Learn more |
| - | - | - |
| Workspace | The context for shared resources, members and permissions. | [Workspace administration](/overview/administration/workspaces/overview) |
| Agent | Instructions, models, knowledge and tool references for a task. | [Agent configuration](/agents-platform/configure/agent-behavior/overview) |
| Model and voice | A selected provider/model and, for speech, a compatible saved voice. | [Models and voices](/overview/models) |
| Knowledge source | A text, URL or file document, optionally organized in a folder. | [Knowledge base](/agents-platform/configure/knowledge-base/overview) |
| Tool | A definition of an action the agent can be configured to use. | [Tool configuration](/agents-platform/configure/tools/overview) |
| Branch and version | A place to review changes and a saved configuration snapshot. | [Branches and versions](/agents-platform/deploy/versioning) |
| Conversation | A stored record of an interaction, its metadata and available media. | [Conversation inspection](/agents-platform/monitor/conversations) |

## Choose your next task

<CardGroup>
  <Card title="Create your first agent" icon="robot" href="/agents-platform/get-started/first-agent">
    Create a configuration in the dashboard and review what was saved.
  </Card>

  <Card title="Manage your workspace" icon="users" href="/overview/administration/workspaces/overview">
    Understand shared resources, membership and workspace settings.
  </Card>

  <Card title="Build with the API" icon="brackets-curly" href="/agents-platform/get-started/api-quickstart">
    Authenticate, choose compatible models and create an agent with the API.
  </Card>

  <Card title="Find product help" icon="life-ring" href="https://help.threetone.in/en">
    Get account, setup and troubleshooting guidance in the Help Center.
  </Card>
</CardGroup>

## Work with the public API

The API base URL is `https://api.threetone.in`. Send an API key in the `x-api-key`
header for programmatic requests. The [API reference](/api-reference/introduction)
provides methods, parameters and schemas from the committed public contract.

Create and manage personal keys in the dashboard. Follow the
[API-key guide](/overview/administration/workspaces/api-keys) for ownership and rotation, and the
[authentication reference](/api-reference/authentication) for request examples.


# Models and voices
Source: https://docs.threetone.in/overview/models

Choose compatible language, speech-recognition and speech-generation models, saved voices, and language settings for an agent configuration.

An agent configuration selects the models used for its task. Model availability
and language support vary by provider, so use the current catalog rather than
assuming that every model supports the same options.

<Frame>
  <img alt="Recording pending for choosing models and a saved voice. No playable video is available yet." />
</Frame>

## Understand the choices

| Choice | Configuration field | Purpose |
| - | - | - |
| Language model | `agent.prompt.llm` | Select the model for the agent's responses and tool decisions. |
| Speech recognition | `asr.model_id` and `asr.recognition` | Define a speech-recognition model and its input-language policy. |
| Speech generation | `tts.model_id` | Select a text-to-speech model. |
| Saved voice | `tts.voice_id` | Reference a voice available in your workspace. |
| Base language | `agent.language` | Set the agent's base language. |
| Response-language policy | `agent.response_language_policy` | Choose the base language or the recognized input language for responses. |

These paths are relative to `conversation_config`. A saved speech configuration
does not by itself confirm that a live conversation can start.

<Note>
  The dashboard submits the **LLM** selection through publication, which requires an eligible managed text-only configuration. Its **Voices**, **Language**, and **ASR**
  controls are currently previews whose changes are not saved. Use the
  [voice and language API workflow](/agents-platform/configure/voice-and-language/overview)
  for speech and language settings, then confirm the saved server draft. Voice and custom-model publication remain unavailable.
</Note>

## Choose a compatible configuration

<Steps>
  <Step title="Check the model catalog">
    Use [List available AI models](/api-reference/agents-platform/list-available-ai-models)
    and [Get available AI model](/api-reference/agents-platform/get-available-ai-model)
    to inspect the model you intend to configure. Model identifiers use
    provider-qualified values such as `provider/model`.
  </Step>

  <Step title="Choose a saved voice">
    Use [List my voices](/api-reference/voices/list-my-voices) to find a workspace
    `voice_id`. Check that it is compatible with the selected TTS provider and
    model. A provider's public voice identifier is not automatically a saved
    workspace voice.
  </Step>

  <Step title="Set input and response languages">
    Choose the ASR recognition policy and the agent's response-language policy
    separately. Confirm that the selected recognition model, response model and
    voice support the intended languages.
  </Step>

  <Step title="Review the saved values">
    Submit speech and language changes through [Update agent](/api-reference/agents-platform/update-agent)
    with an explicit `branch_id`, then read the selected branch or version back.
    Check the model IDs, voice ID and language policies before making further changes.
  </Step>
</Steps>

## Input and response language policies

The public configuration defines these ASR modes:

* `fixed`: select a single input language.
* `automatic_provider_languages`: use the provider-supported automatic recognition mode.
* `automatic_selected_languages`: restrict automatic recognition to selected languages.

Only choose a mode that the selected model supports. The request schema in
[Create agent](/api-reference/agents-platform/create-agent) describes the fields
required for each mode.

For responses, `base_language` uses the configured base language.
`recognized_language` requests the recognized input language. Choosing a response
policy does not expand a model's or voice's language coverage.

## When a choice is rejected

* A model may be unavailable to the workspace or incompatible with the requested options.
* A saved voice may belong to a different provider or may no longer be accessible.
* Voice authoring can store ASR and TTS settings in a server draft. Voice publication remains unavailable even with compatible settings.
* Copying a model ID from a screenshot can leave an outdated identifier in your request.

Read the returned validation error and recheck the catalog. Do not substitute an
unverified model or voice ID just to get past an error.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I use any provider voice ID directly?">
    Select a saved workspace voice through [List my voices](/api-reference/voices/list-my-voices). Its provider and model must be compatible with the TTS configuration. A public provider ID alone does not establish workspace access.
  </Accordion>

  <Accordion title="Does automatic recognition support every language?">
    No. Recognition modes and language coverage depend on the selected ASR model. Review the current catalog and the input policy separately from the response-language policy.
  </Accordion>
</AccordionGroup>