> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a tool > Creates a tool. Without `agent_id` it is project-wide, so any agent of the project can use it; with `agent_id` it is private to that agent and attached to the agent's draft straight away. The shape of `configs` depends on `type` (default `http`). A tool reaches live calls only once an agent using it is published. ## OpenAPI ````yaml api-reference/voice-openapi.json POST /v1/projects/{projectId}/tools openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: >- Voice agents and their tools, outbound calls, conversations, campaigns, telephony, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. - name: Phone numbers description: >- The phone numbers of a project, where their calls come from, and how agents call out from them. - name: Inbound SIP trunks description: Bring calls from your own SIP infrastructure to Clarity agents. - name: Outbound SIP trunks description: >- The SIP endpoints Clarity dials through for outbound calls from your numbers. - name: Tools description: The tools agents call during a conversation, and which agents use them. paths: /v1/projects/{projectId}/tools: parameters: - $ref: '#/components/parameters/ProjectIdPath' post: tags: - Tools summary: Create a tool description: >- Creates a tool. Without `agent_id` it is project-wide, so any agent of the project can use it; with `agent_id` it is private to that agent and attached to the agent's draft straight away. The shape of `configs` depends on `type` (default `http`). A tool reaches live calls only once an agent using it is published. operationId: createTool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' example: name: lookup_order description: Look up an order by its number and return its status. type: http configs: url: https://api.example.com/orders method: GET query_params: - name: number value: '{{order_number}}' authentication: type: bearer token: vault:orders_api_token parameters: type: object required: - order_number properties: order_number: type: string description: The order number the caller reads out. hold_message: One moment while I check that order. responses: '201': description: The tool was created. content: application/json: schema: $ref: '#/components/schemas/Tool' example: id: 6e2a4c8d-1b3f-4a5c-9d7e-0f1a2b3c4d5e project_id: 3f6c1a52-8d0e-4b8f-9a51-2c7d4e0b9f13 agent_id: null name: lookup_order description: Look up an order by its number and return its status. type: http configs: url: https://api.example.com/orders method: GET query_params: - name: number value: '{{order_number}}' authentication: type: bearer token: vault:orders_api_token parameters: type: object required: - order_number properties: order_number: type: string description: The order number the caller reads out. parameter_mapping: null hold_message: One moment while I check that order. hold_messages: null async_config: null session: null updated_at: 1794393600000 library_tool_id: null library_revision: null library_channels: null '400': description: >- A knowledge base tool names an article or collection your organization does not have (`support_kb_unknown_article`, `support_kb_unknown_collection`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: Your credential has no administrative access to the project. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: The project does not exist or your key cannot reach it. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- A tool with this name already exists in the same scope (the agent's private tools for an `agent_id` body, the project-wide tools otherwise; `error: tool_name_already_exists_for_agent`), or a resource the tool points at is not usable: a messaging or handoff channel, template or chat agent (`messaging_tool_invalid`, `handoff_tool_invalid`, with `detail`), a workflow that is missing or not started by a webhook (`workflow_missing`, `workflow_not_webhook`), or a knowledge base your organization does not have (`support_kb_org_missing`, `support_kb_org_empty`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: tool_name_already_exists_for_agent project_id: 3f6c1a52-8d0e-4b8f-9a51-2c7d4e0b9f13 agent_id: null name: lookup_order hint: A project-global tool with this name already exists. '422': description: >- The body failed validation: a bad `name`, an unknown `type`, `configs` that do not fit the `type`, or invalid `async_config` or `session`. `issues` locates each problem; for `configs` the message names the offending field. A tool shared through the organization tool library is also refused here when its `channels` do not suit it (`channel_not_allowed`, `voice_only_setting`). content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: >- configs: For type http, configs.url is required (a non-empty string) issues: - path: configs code: custom message: >- For type http, configs.url is required (a non-empty string) '502': description: >- A service the tool depends on (your support platform, for a workflow, knowledge base, messaging or handoff tool, or the organization tool library) could not be reached. Retry later. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: CreateToolRequest: type: object required: - name description: Fields not listed here are ignored. properties: name: type: string minLength: 1 pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ description: >- The name the model calls the tool by: a letter, then letters, digits and underscores. Unique among the project-wide tools, or among the agent's private tools. description: type: string description: >- What the tool does and when to use it. The model reads it to decide when to call the tool. agent_id: type: string nullable: true description: >- Make the tool private to this agent and attach it to the agent's draft. Leave it out (or `null`) for a project-wide tool. type: type: string enum: - http - knowledgebase - code - builtin - workflow - messaging - handoff - ticket default: http description: >- `http` calls your API, `knowledgebase` searches your organization's knowledge base, `code` runs your Python code, `builtin` controls the call (transfer it, collect keypad digits, end it), `workflow` runs a Clarity workflow, `messaging` sends a WhatsApp message or an email, `handoff` moves the conversation to a chat agent. configs: $ref: '#/components/schemas/ToolConfigs' parameters: type: object nullable: true additionalProperties: true description: >- JSON Schema (`type: object`, `properties`, `required`) of the arguments the model passes. A `knowledgebase` tool always takes one `query` string, whatever you send. example: type: object required: - order_number properties: order_number: type: string description: The order number the caller reads out. parameter_mapping: type: object nullable: true additionalProperties: type: string description: >- Renames arguments before the request is built, `{argument: request_field}`. hold_message: type: string nullable: true description: >- What the agent says while the tool runs. Blank or `null` says nothing. hold_messages: type: object nullable: true additionalProperties: type: string description: >- The hold message per language of a multilingual agent, keyed by the agent's language label (such as `English (US)`). A missing language falls back to `hold_message`. async_config: $ref: '#/components/schemas/ToolAsyncConfig' session: $ref: '#/components/schemas/ToolSession' channels: type: array minItems: 1 maxItems: 2 uniqueItems: true items: type: string enum: - chat - voice description: >- Used only when your organization shares tools between projects through its tool library: which kinds of agents can use this project-wide tool. Ignored otherwise. Tool: type: object description: >- A tool an agent can call during a conversation. Project-wide tools (`agent_id: null`) can be attached to any agent of the project; a private tool belongs to one agent. required: - id - project_id - agent_id - name - description - type - configs - parameters - parameter_mapping - hold_message - hold_messages - async_config - session - updated_at properties: id: type: string description: Tool id. project_id: type: string agent_id: type: string nullable: true description: The agent the tool is private to, or `null` for a project-wide tool. name: type: string description: The name the model calls the tool by. description: type: string description: What the tool does and when to use it, as the model reads it. type: type: string description: >- What the tool does, which decides the shape of `configs`: `http`, `knowledgebase`, `code`, `builtin`, `workflow`, `messaging`, `handoff` or `ticket`. configs: type: object additionalProperties: true description: >- The tool's configuration, in the shape of its `type` (see `configs` in Create a tool). It can also carry values Clarity fills in on save, such as a workflow's `url` or a knowledge base's search target. parameters: type: object additionalProperties: true description: >- JSON Schema of the arguments the model passes when it calls the tool. parameter_mapping: type: object nullable: true additionalProperties: type: string description: >- Renames arguments before the request is built, `{argument: request_field}`. `null` when none. hold_message: type: string nullable: true description: What the agent says while the tool runs, or `null` for nothing. hold_messages: type: object nullable: true additionalProperties: type: string description: >- The hold message per language of a multilingual agent, keyed by language label. async_config: type: object nullable: true additionalProperties: true description: >- Settings that let the conversation go on while the tool runs, in the shape of `async_config` in Create a tool. `null` means the agent waits for the result. session: $ref: '#/components/schemas/ToolSession' updated_at: type: integer format: int64 nullable: true description: >- When the tool was last changed, in milliseconds since the Unix epoch. `null` for a tool not changed since this field was added. library_tool_id: type: string nullable: true description: >- The organization tool library entry this tool comes from, or `null` for a tool that belongs to this project only. library_revision: type: integer nullable: true description: The library entry's revision this tool holds, or `null`. library_channels: type: array nullable: true items: type: string description: >- Which kinds of agents (`chat`, `voice`) can use the library entry, or `null`. used_by_count: type: integer description: >- How many agents of the project have the tool attached. A published agent keeps calling the tool it was published with until it is published again, whatever this count says. Present on reads and lists. used_by_agents: type: array description: >- The agents the tool is attached to. Returned when you get one tool, not in lists. items: type: object required: - id - name properties: id: type: string name: type: string Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place a call or answer one itself — a campaign, an outbound caller ID, a dispatched call, an eval; a number's inbound dispatch rule accepts one; the body carries `agent_type` and `agent_id`), `ASSIST_FLEET_NOT_CONFIGURED` (422 on a dispatch rule naming a Voice Assist agent in a project whose LiveKit has no Voice Assist listener), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `INVALID_CUSTOMER_TIMEZONE` (400, `customer_timezone` is not a time zone name; the body carries the value), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503), `REGION_PROFILE_CONFLICT` (503), `LLM_SERVICE_TIER_UNAVAILABLE` (422, an agent's processing speed is not offered by its model or not enabled for the organization; `reason` says which) and `AUTH_UPSTREAM_UNAVAILABLE` (503 on any endpoint, with `Retry-After`: the credential could not be checked right now; it was not rejected and the request was not carried out). ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. A refused processing speed answers with `error` and `code` both `LLM_SERVICE_TIER_UNAVAILABLE` and the fields `path`, `reason`, `tier`, `provider` and `model`. properties: error: type: string code: type: string description: >- A machine-readable code, on the failures that carry one: `LLM_SERVICE_TIER_UNAVAILABLE` for a processing speed the agent cannot use. message: type: string path: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: the refused field, `agent_model_config.llm_service_tier`. reason: type: string enum: - model - organization description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: `model` when the language model does not offer the speed (or the value is not a speed at all), `organization` when your organization does not have it. tier: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the refused value, as text. provider: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model provider. model: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model. issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} ToolConfigs: description: >- The tool's configuration. Its shape depends on the tool's `type`, and it is checked against that type; on update without `type`, against the stored type. `builtin` takes one of three shapes, by `action`. anyOf: - $ref: '#/components/schemas/HttpToolConfig' - $ref: '#/components/schemas/KnowledgeBaseToolConfig' - $ref: '#/components/schemas/CodeToolConfig' - $ref: '#/components/schemas/GetDtmfToolConfig' - $ref: '#/components/schemas/ConnectToHumanToolConfig' - $ref: '#/components/schemas/OtherBuiltinToolConfig' - $ref: '#/components/schemas/WorkflowToolConfig' - $ref: '#/components/schemas/MessagingToolConfig' - $ref: '#/components/schemas/HandoffToolConfig' - $ref: '#/components/schemas/TicketToolConfig' ToolAsyncConfig: type: object nullable: true additionalProperties: false required: - enabled description: >- Lets the conversation go on while the tool runs instead of waiting for the result. Not allowed on `builtin` tools. `null` turns it off. properties: enabled: type: boolean description: Turns the other settings on. ack_message: type: string nullable: true description: >- What the agent says when the tool starts. `null` falls back to `hold_message`. ack_messages: type: object nullable: true additionalProperties: type: string description: '`ack_message` per language label.' filler_phrases: type: array nullable: true items: type: string description: Phrases the agent picks from while it waits. filler_phrases_by_language: type: object nullable: true additionalProperties: type: array items: type: string description: '`filler_phrases` per language label.' filler_delay_ms: type: integer minimum: 0 description: Accepted for compatibility and ignored. Use `filler_interval_ms`. filler_interval_ms: type: integer minimum: 1 nullable: true description: >- Milliseconds of silence before a filler phrase, and between two of them. `null` plays none. filler_max_plays: type: integer minimum: 1 nullable: true description: The most filler phrases per run. Needs `filler_interval_ms`. on_duplicate: type: string enum: - allow - reject description: >- What happens when the model calls the tool again while it is running. Default `reject`. cancellable: type: boolean description: The caller may cancel a run in progress. Default false. max_lifetime_ms: type: integer minimum: 1000 maximum: 900000 description: How long a run may take before it is given up, in milliseconds. ToolSession: type: object nullable: true additionalProperties: false description: >- The tool's part in the call-scoped caller authentication session. Null means the tool takes no part. A non-null `verification` makes it a verification tool and carries the verification policy; caller authentication is on for an agent exactly when an attached tool verifies the caller or requires a verified caller. On PATCH, an absent key keeps the stored value and an explicit null clears it. properties: requires_verified_caller: type: boolean description: >- The runtime refuses the tool until a verification tool verified the caller. stores: type: array maxItems: 20 items: type: object additionalProperties: false required: - from - as - visibility properties: from: type: string description: Dot path into the JSON response. as: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: Session name, referenced as {{session.}}. visibility: type: string enum: - private - visible verification: type: object nullable: true additionalProperties: false properties: success: type: object additionalProperties: false properties: status_in: type: array items: type: integer minimum: 100 maximum: 599 field: type: string equals: oneOf: - type: string - type: number - type: boolean ttl_from: type: string max_attempts: type: integer minimum: 1 maximum: 10 description: >- Failed verifications allowed per call (default 3). With several verifiers on an agent, the smallest wins. on_exhausted: type: string enum: - end_call - transfer - continue description: >- What happens when the attempts run out (default end_call). Taken from the verifier with the smallest max_attempts. `transfer` needs a connect_to_human tool attached to the agent. unreachable_counts_as_failure: type: boolean description: >- Count a timeout / connection error / 5xx as a failed attempt (default false; true on any verifier wins). default_ttl_s: type: integer nullable: true minimum: 60 maximum: 86400 description: >- Session lifetime when the response gives none (null - until the call ends). The smallest non-null value wins. HttpToolConfig: title: http type: object additionalProperties: false required: - url description: >- `type: http`. Calls your API. Values in `header_list`, `query_params` and the body may include `{{argument}}` placeholders. A secret can be given as `vault:` instead of its value. properties: url: type: string minLength: 1 method: type: string description: The HTTP method, such as `GET` or `POST`. authentication: type: object additionalProperties: false properties: type: type: string enum: - none - bearer - api_key - oauth2 token: type: string description: '`bearer`: the token, or `vault:`.' key: type: string description: '`api_key`: the key, or `vault:`.' header: type: string description: '`api_key`: the header that carries the key.' credential: type: string minLength: 1 description: >- `oauth2` (required): the name of an OAuth credential of the project. Clarity gets a token for each call. scopes: type: array items: type: string description: '`oauth2`: scopes to ask for, a subset of the credential''s.' header_list: type: array items: $ref: '#/components/schemas/ToolNameValue' description: Request headers, in order. query_params: type: array items: $ref: '#/components/schemas/ToolNameValue' description: Query-string parameters, in order. body_type: type: string enum: - none - form_data - json - raw description: >- How the body is built. Without it the arguments are placed by `request_placement`. body_form: type: array items: $ref: '#/components/schemas/ToolNameValue' description: '`body_type: form_data`: the form fields.' body_json: type: string description: '`body_type: json`: the JSON body as text.' body_raw: type: string description: '`body_type: raw`: the body text.' body_content_type: type: string description: '`body_type: raw`: its content type. Default `text/plain`.' headers: type: object additionalProperties: type: string description: Older form of `header_list`, a map of header to value. request_placement: type: string enum: - body - query - path description: >- Older form. Where arguments go when `parameter_placement` does not say. parameter_placement: type: object additionalProperties: type: string description: >- Older form. Where each argument goes (`body`, `query` or `path`), by request field. timeout_ms: type: integer minimum: 1 description: Request timeout in milliseconds. unresolved: type: boolean description: >- Set by Clarity when the OAuth credential cannot be found. Leave it out. KnowledgeBaseToolConfig: title: knowledgebase type: object additionalProperties: false required: - source - all_articles description: >- `type: knowledgebase`. Searches your organization's knowledge base. With `all_articles: false`, send exactly one of `collection_ids` and `article_ids`. properties: source: type: string enum: - support_org all_articles: type: boolean description: >- Search every article. `collection_ids` and `article_ids` must then be empty. collection_ids: type: array uniqueItems: true items: type: string minLength: 1 description: Search only these collections. article_ids: type: array uniqueItems: true items: minimum: 1 type: integer description: Search only these articles. article_titles: type: object additionalProperties: type: string description: Article titles by id, for display. max_articles: type: integer minimum: 1 maximum: 20 description: The most articles a search returns. Default 5. embedding_config: type: object nullable: true additionalProperties: true description: >- How queries are embedded, when your articles were indexed with a non-default setup. `null` clears it. proxy_url: type: string description: Filled in by Clarity on save. Leave it out. server_url: type: string description: Filled in by Clarity on save. Leave it out. collection_id: type: string description: Filled in by Clarity on save. Leave it out. api_key: type: string description: Filled in by Clarity on save. Leave it out. CodeToolConfig: title: code type: object additionalProperties: false required: - code description: '`type: code`. Runs your Python code, which defines `execute(args)`.' properties: code: type: string minLength: 1 description: >- Python source defining `execute(args)`. Its return value is the tool result. timeout_ms: type: integer minimum: 1000 maximum: 120000 description: How long the code may run, in milliseconds. Default 30000. secrets: type: object additionalProperties: type: string description: >- Values passed to the code with the arguments but never shown to the model, by name. A value can be `vault:`. session_inputs: type: array maxItems: 20 items: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Call-session values passed to the code as arguments, by name. Another attached tool must store each one. sheet_refs: type: object additionalProperties: type: string description: Accepted and not stored. Set `sheet_refs` on the agent instead. executor_url: type: string description: Reserved. Leave it out. GetDtmfToolConfig: title: builtin get_dtmf type: object additionalProperties: false required: - action - num_digits description: >- `type: builtin`, `action: get_dtmf`. Collects digits the caller types on the keypad. properties: action: type: string enum: - get_dtmf num_digits: type: integer minimum: 1 maximum: 32 description: How many digits to collect. ask_for_confirmation: type: boolean description: Read the digits back and ask the caller to confirm them. extra_instructions: type: string maxLength: 500 dtmf_input_timeout: type: number minimum: 0.5 maximum: 30 description: Seconds to wait for the next digit. ConnectToHumanToolConfig: title: builtin connect_to_human type: object additionalProperties: false required: - action description: >- `type: builtin`, `action: connect_to_human`. Transfers the call. Without `routing` (or with `number`) it goes to `destination_number`. With `routing: team` the model picks one of `teams` (a number, or the Voice Assist queue for your agents), the top-level transfer fields are refused, and `default_team` is required unless the only destination is an agents destination. properties: action: type: string enum: - connect_to_human routing: type: string enum: - number - team destination_number: type: string description: >- Where to transfer: an international number (`+966501234567`), a short number or extension of 2 to 10 digits, a `sip:` URI or a `tel:` URI. transfer_mode: type: string enum: - cold - warm description: >- `cold` hands the call over directly; `warm` briefs the person who answers first. share_conversation_history: type: boolean description: >- Only with `transfer_mode: warm`. Share the conversation in the briefing. ringing_timeout_sec: type: number minimum: 5 maximum: 120 description: How long to ring before giving up. teams: type: array minItems: 1 maxItems: 10 description: 'Only with `routing: team`. The destinations the model chooses from.' items: oneOf: - $ref: '#/components/schemas/TransferPhoneDestination' - $ref: '#/components/schemas/TransferAgentsDestination' default_team: type: string description: >- Only with `routing: team` and two or more destinations. The `name` of the destination to use when the model cannot tell. ask_when_unclear: type: boolean description: >- Only with `routing: team` and two or more destinations. Ask the caller when the right destination is unclear. OtherBuiltinToolConfig: title: builtin (other) type: object additionalProperties: true description: >- `type: builtin` with any other `action`, such as `end_call`, or none. This configuration is not checked. properties: action: type: string example: end_call WorkflowToolConfig: title: workflow type: object additionalProperties: true required: - workflow_id description: >- `type: workflow`. Runs a Clarity workflow started by a webhook. Clarity fills in `url`, `method`, `authentication` and `workflow_display_name` on save. properties: workflow_id: type: string minLength: 1 description: The workflow's id. expect_response: type: boolean description: >- Wait for the workflow to finish and give its response to the model, instead of only starting it. MessagingToolConfig: title: messaging description: >- `type: messaging`. Sends the caller a WhatsApp message or an email during the call. oneOf: - type: object title: WhatsApp additionalProperties: false required: - channel - wa_channel_id - messages properties: channel: type: string enum: - whatsapp wa_channel_id: type: integer minimum: 1 description: Your WhatsApp channel in the support platform. wa_provider: type: string enum: - meta - twilio description: Filled in by Clarity on save. messages: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/MessagingWhatsappMessage' allow_spoken_number: type: boolean description: >- Send to a number the caller says, not only to the number they call from. notify_text_replies: type: boolean description: Tell the agent when the caller replies in writing. max_sends_per_call: type: integer minimum: 1 maximum: 20 description: Default 5. allow_resend: type: boolean test_recipient: type: string nullable: true minLength: 1 description: >- The only recipient during test and demo calls, as an E.164 number with `+`. - type: object title: Email additionalProperties: false required: - channel - email_channel_id - subject - body properties: channel: type: string enum: - email email_channel_id: type: integer minimum: 1 description: Your email channel in the support platform. subject: type: string minLength: 1 maxLength: 255 body: type: string minLength: 1 maxLength: 10000 description: Each `{{key}}` needs a placeholder. placeholders: type: array items: $ref: '#/components/schemas/MessagingPlaceholder' attachment_ids: type: array maxItems: 5 items: minimum: 1 type: integer allow_document_url: type: boolean code: type: object additionalProperties: false required: - recipient_session description: >- Makes the email a one-time code that verifies the caller. The body must contain `{{code}}` exactly once, and may use `{{code_minutes}}`; no other placeholders, attachments or links. properties: length: type: integer minimum: 4 maximum: 8 description: Default 6. ttl_s: type: integer minimum: 60 maximum: 1800 description: Seconds the code is valid. Default 600. entry: type: string enum: - spoken - keypad - either description: How the caller gives the code back. Default `either`. recipient_session: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: The call-session value that holds the address to send to. notify_text_replies: type: boolean max_sends_per_call: type: integer minimum: 1 maximum: 20 description: Default 5, or 3 with `code`. allow_resend: type: boolean test_recipient: type: string nullable: true minLength: 1 description: >- The only recipient during test and demo calls, as an email address. HandoffToolConfig: title: handoff description: >- `type: handoff`. Moves the conversation to a chat agent on WhatsApp or email, starting with an opening message. oneOf: - type: object title: WhatsApp additionalProperties: false required: - channel - chat_agent_id - wa_channel_id - opener properties: channel: type: string enum: - whatsapp chat_agent_id: type: string minLength: 1 maxLength: 100 description: The chat agent that continues the conversation. chat_agent_name: type: string nullable: true maxLength: 200 description: Filled in by Clarity on save. wa_channel_id: minimum: 1 type: integer wa_provider: type: string enum: - meta - twilio description: Filled in by Clarity on save. allow_spoken_number: type: boolean opener: description: >- The first message, an approved template or (inside WhatsApp's 24-hour window) a text. oneOf: - type: object additionalProperties: false required: - kind - template_id properties: kind: type: string enum: - template template_id: type: string minLength: 1 variables: type: array items: $ref: '#/components/schemas/MessagingTemplateVariable' - type: object additionalProperties: false required: - kind - text properties: kind: type: string enum: - text text: type: string minLength: 1 maxLength: 4096 end_call_after: type: boolean description: End the call after a successful handoff. Default true. test_recipient: type: string minLength: 1 nullable: true max_handoffs_per_day: type: integer nullable: true minimum: 1 maximum: 50 description: The most handoffs per customer per day. Default 3. tool_id: type: string maxLength: 100 description: Ignored. - type: object title: Email additionalProperties: false required: - channel - chat_agent_id - email_channel_id - opener properties: channel: type: string enum: - email chat_agent_id: type: string minLength: 1 maxLength: 100 chat_agent_name: type: string nullable: true maxLength: 200 description: Filled in by Clarity on save. email_channel_id: minimum: 1 type: integer opener: type: object additionalProperties: false required: - subject - text properties: kind: type: string enum: - email subject: type: string minLength: 1 maxLength: 255 text: type: string minLength: 1 maxLength: 10000 end_call_after: type: boolean description: Default true. test_recipient: type: string minLength: 1 nullable: true max_handoffs_per_day: type: integer nullable: true minimum: 1 maximum: 50 tool_id: type: string maxLength: 100 description: Ignored. TicketToolConfig: title: ticket description: >- `type: ticket`. Lets the agent act, during a call, on the caller's chat with you (website, app or WhatsApp): send a message or files, show a screen, write a staff note, change the ticket, or tell the chat assistant what to do next. Screens, files and option ids are checked when an action runs, so one that is removed later fails that action only. On update the configuration is replaced whole. type: object additionalProperties: false required: - actions properties: actions: type: array minItems: 1 uniqueItems: true items: type: string enum: - message - screen - note - update - instruct_chat_ai description: What the agent may do. allowed_screens: type: array maxItems: 50 uniqueItems: true items: type: string pattern: ^[A-Za-z0-9_.:-]{1,100}$ description: >- The screen template keys the agent may show. Required (at least one) with the `screen` action, and only with it. allowed_changes: type: object additionalProperties: false required: - fields description: >- What an update may change. Required with the `update` action, and only with it. properties: fields: type: array minItems: 1 uniqueItems: true items: type: string enum: - status - category - team - custom_attributes custom_attribute_keys: type: array minItems: 1 maxItems: 20 uniqueItems: true items: type: string pattern: ^[A-Za-z0-9_.:-]{1,100}$ description: Only when `custom_attributes` is in `fields`. status_options: $ref: '#/components/schemas/TicketChangeOptions' category_options: $ref: '#/components/schemas/TicketChangeOptions' team_options: $ref: '#/components/schemas/TicketChangeOptions' files: type: array maxItems: 10 description: >- Files the agent may send by key, with the `message` action only. Keys must not repeat. items: type: object additionalProperties: false required: - key - attachment_id - description properties: key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ attachment_id: type: integer minimum: 1 description: >- The file in your Clarity support workspace. The agent never sees it. description: type: string minLength: 1 maxLength: 500 description: What the file is, as the agent reads it. allow_document_url: type: boolean description: >- Lets the agent send a document by link, with the `message` action only. max_actions_per_call: type: integer minimum: 1 maximum: 20 description: The most actions of this tool in one call. Default 5. tool_id: type: string maxLength: 100 description: Ignored. ToolNameValue: type: object additionalProperties: false required: - name - value properties: name: type: string minLength: 1 value: type: string description: >- May include `{{argument}}` and call variables, filled in when the tool runs. TransferPhoneDestination: type: object additionalProperties: false required: - name - description - destination_number description: A transfer destination that is a phone number. properties: type: type: string enum: - number name: type: string minLength: 1 maxLength: 40 description: Unique in the list, case-insensitive. No double quote. description: type: string minLength: 1 maxLength: 500 description: When to route callers here. The model reads it. destination_number: type: string description: >- An international number, a 2 to 10 digit extension, a `sip:` URI or a `tel:` URI. transfer_mode: type: string enum: - cold - warm share_conversation_history: type: boolean description: 'Only with `transfer_mode: warm`.' ringing_timeout_sec: type: number minimum: 5 maximum: 120 TransferAgentsDestination: type: object additionalProperties: false required: - type - target - assist_agent_id - text_context - voice_context description: >- A transfer destination that is your agents, through the queue of a Voice Assist agent. `name` and `description` are required when the list has two or more destinations, and refused when it has one. properties: type: type: string enum: - agents name: type: string minLength: 1 maxLength: 40 description: type: string minLength: 1 maxLength: 500 target: description: Who can take the call. oneOf: - type: object additionalProperties: false required: - kind properties: kind: type: string enum: - any_agent - type: object additionalProperties: false required: - kind - team_id properties: kind: type: string enum: - team team_id: type: string pattern: ^\d{1,20}$ description: Your support platform team id, as a decimal string. - type: object additionalProperties: false required: - kind - user_id properties: kind: type: string enum: - user user_id: type: string pattern: ^\d{1,20}$ description: Your support platform user id, as a decimal string. assist_agent_id: type: string format: uuid description: The Voice Assist agent whose queue the call waits in. text_context: type: boolean description: The agent who takes the call gets a written summary. voice_context: type: boolean description: The agent who takes the call gets a spoken briefing first. full_conversation: type: boolean description: >- Only with `text_context`. Also show the whole conversation with the AI agent. MessagingWhatsappMessage: type: object additionalProperties: false required: - id - description - kind description: >- One message the agent may send. `template` needs `template_id`; `text` and `buttons` need `text` (and `buttons` 1 to 3 buttons); `document` needs `attachment_ids` or `allow_document_url`. properties: id: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: Unique in the tool. The model picks the message by it. description: type: string minLength: 1 description: When to send it. The model reads it. kind: type: string enum: - template - text - document - buttons template_id: type: string minLength: 1 description: '`template`: an approved WhatsApp template.' variables: type: array items: $ref: '#/components/schemas/MessagingTemplateVariable' description: '`template`: its variables.' buttons_wait_s: type: integer minimum: 10 maximum: 1800 nullable: true description: >- `buttons`, or a template with quick replies: seconds to wait for a tap. text: type: string description: >- `text` and `buttons`: the message. Each `{{key}}` needs a placeholder. placeholders: type: array items: $ref: '#/components/schemas/MessagingPlaceholder' buttons: type: array items: type: object additionalProperties: false required: - id - label properties: id: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ label: type: string minLength: 1 maxLength: 20 description: '`buttons`: 1 to 3 reply buttons. Not on a Twilio channel.' attachment_ids: type: array maxItems: 5 items: minimum: 1 type: integer description: '`document`: files from your support platform to send.' allow_document_url: type: boolean description: '`document`: the model may send a document by link.' caption: type: string description: '`document`: the caption.' expects_image: type: boolean description: '`text` or `template`: the caller is expected to answer with a photo.' image_wait_s: type: integer minimum: 10 maximum: 1800 nullable: true description: >- Only with `expects_image`. Seconds to wait for the photo. Default 120. MessagingPlaceholder: type: object additionalProperties: false required: - key - description description: A `{{key}}` in the text that the model fills in. properties: key: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$ description: type: string minLength: 1 MessagingTemplateVariable: oneOf: - type: object additionalProperties: false required: - key - mode - value description: A value Clarity fills in. properties: key: type: string minLength: 1 maxLength: 64 mode: type: string enum: - fixed value: type: string minLength: 1 - type: object additionalProperties: false required: - key - mode - description description: A value the model fills in. properties: key: type: string minLength: 1 maxLength: 64 mode: type: string enum: - agent description: type: string minLength: 1 description: What the model should put there. TicketChangeOptions: type: array minItems: 1 maxItems: 100 description: >- The values an update may set this field to, with labels the agent reads. Ids must not repeat. Only when the field is in `fields`; without it, any value is allowed. items: type: object additionalProperties: false required: - id - label properties: id: minimum: 1 type: integer label: type: string minLength: 1 maxLength: 200 responses: Unauthorized: description: >- No credential was sent, or the API key is invalid or revoked. A key that could not be checked at all answers 503 `AUTH_UPSTREAM_UNAVAILABLE` instead (see Errors). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.