openapi: 3.1.0 info: title: Speech-to-speech (EVI) version: 1.0.0 paths: /v0/evi/chat/{chat_id}/send: post: operationId: send summary: Send Message description: Send a message to a specific chat. tags: - subpackage_controlPlane parameters: - name: chat_id in: path required: true schema: type: string - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/controlPlane_send_Response_200' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' requestBody: content: application/json: schema: $ref: '#/components/schemas/ControlPlanePublishEvent' /v0/evi/configs: post: operationId: create-config summary: Create config description: >- Creates a **Config** which can be applied to EVI. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_config_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_config' get: operationId: list-configs summary: List configs description: >- Fetches a paginated list of **Configs**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each config. To include all versions of each config in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: name in: query description: Filter to only include configs with this name. required: false schema: type: string - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_configs' /v0/evi/configs/{id}: get: operationId: list-config-versions summary: List config versions description: >- Fetches a list of a **Config's** versions. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each config. To include all versions of each config in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_configs' post: operationId: create-config-version summary: Create config version description: >- Updates a **Config** by creating a new version of the **Config**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_config_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_config_version' patch: operationId: update-config-name summary: Update config name description: >- Updates the name of a **Config**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/configs_update-config-name_Response_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_config_name' delete: operationId: delete-config summary: Delete config description: >- Deletes a **Config** and its versions. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/configs_delete-config_Response_200' /v0/evi/configs/{id}/version/{version}: get: operationId: get-config-version summary: Get config version description: >- Fetches a specified version of a **Config**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_config_public' patch: operationId: update-config-description summary: Update config description description: >- Updates the description of a **Config**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_config_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_config_version_description' delete: operationId: delete-config-version summary: Delete config version description: >- Deletes a specified version of a **Config**. For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration). tags: - subpackage_configs parameters: - name: id in: path description: Identifier for a Config. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/configs_delete-config-version_Response_200' /v0/evi/prompts: post: operationId: create-prompt summary: Create prompt description: >- Creates a **Prompt** that can be added to an [EVI configuration](/reference/speech-to-speech-evi/configs/create-config). See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_prompt_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_prompt' get: operationId: list-prompts summary: List prompts description: >- Fetches a paginated list of **Prompts**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each prompt. To include all versions of each prompt in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: name in: query description: Filter to only include prompts with name. required: false schema: type: string - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_prompts' /v0/evi/prompts/{id}: get: operationId: list-prompt-versions summary: List prompt versions description: >- Fetches a list of a **Prompt's** versions. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path required: true schema: type: string format: uuid - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each prompt. To include all versions of each prompt in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_prompts' post: operationId: create-prompt-version summary: Create prompt version description: >- Updates a **Prompt** by creating a new version of the **Prompt**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_prompt_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_prompt_version' patch: operationId: update-prompt-name summary: Update prompt name description: >- Updates the name of a **Prompt**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/prompts_update-prompt-name_Response_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_prompt_name' delete: operationId: delete-prompt summary: Delete prompt description: >- Deletes a **Prompt** and its versions. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/prompts_delete-prompt_Response_200' /v0/evi/prompts/{id}/version/{version}: get: operationId: get-prompt-version summary: Get prompt version description: >- Fetches a specified version of a **Prompt**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Prompt. Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_prompt_public' patch: operationId: update-prompt-description summary: Update prompt description description: >- Updates the description of a **Prompt**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Prompt. Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_prompt_public' requestBody: content: application/json: schema: $ref: '#/components/schemas/patched_prompt_version_description' delete: operationId: delete-prompt-version summary: Delete prompt version description: >- Deletes a specified version of a **Prompt**. See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt. tags: - subpackage_prompts parameters: - name: id in: path description: Identifier for a Prompt. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Prompt. Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/prompts_delete-prompt-version_Response_200' /v0/evi/tools: post: operationId: create-tool summary: Create tool description: >- Creates a **Tool** that can be added to an [EVI configuration](/reference/speech-to-speech-evi/configs/create-config). Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_user_defined_tool' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_user_defined_tool' get: operationId: list-tools summary: List tools description: >- Fetches a paginated list of **Tools**. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each tool. To include all versions of each tool in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: name in: query description: Filter to only include tools with name. required: false schema: type: string - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_user_defined_tools' /v0/evi/tools/{id}: get: operationId: list-tool-versions summary: List tool versions description: >- Fetches a list of a **Tool's** versions. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path required: true schema: type: string format: uuid - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: restrict_to_most_recent in: query description: >- By default, `restrict_to_most_recent` is set to true, returning only the latest version of each tool. To include all versions of each tool in the list, set `restrict_to_most_recent` to false. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_user_defined_tools' post: operationId: create-tool-version summary: Create tool version description: >- Updates a **Tool** by creating a new version of the **Tool**. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/return_user_defined_tool' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_user_defined_tool_version' patch: operationId: update-tool-name summary: Update tool name description: >- Updates the name of a **Tool**. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/tools_update-tool-name_Response_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_user_defined_tool_name' delete: operationId: delete-tool summary: Delete tool description: >- Deletes a **Tool** and its versions. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/tools_delete-tool_Response_200' /v0/evi/tools/{id}/version/{version}: get: operationId: get-tool-version summary: Get tool version description: >- Fetches a specified version of a **Tool**. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Tool. Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Tool. Each update to the Tool increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_user_defined_tool' patch: operationId: update-tool-description summary: Update tool description description: >- Updates the description of a specified **Tool** version. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Tool. Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Tool. Each update to the Tool increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_user_defined_tool' requestBody: content: application/json: schema: $ref: '#/components/schemas/posted_user_defined_tool_version_description' delete: operationId: delete-tool-version summary: Delete tool version description: >- Deletes a specified version of a **Tool**. Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI. tags: - subpackage_tools parameters: - name: id in: path description: Identifier for a Tool. Formatted as a UUID. required: true schema: type: string format: uuid - name: version in: path description: >- Version number for a Tool. Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Tool. Each update to the Tool increments its version number. required: true schema: type: integer - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/tools_delete-tool-version_Response_200' /v0/evi/chats: get: operationId: list-chats summary: List chats description: Fetches a paginated list of **Chats**. tags: - subpackage_chats parameters: - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: config_id in: query description: Filter to only include chats that used this config. required: false schema: type: string format: uuid - name: status in: query description: Chat status to apply to the chat. String from the ChatStatus enum. required: false schema: type: string - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_chats' /v0/evi/chats/{id}: get: operationId: list-chat-events summary: List chat events description: Fetches a paginated list of **Chat** events. tags: - subpackage_chats parameters: - name: id in: path description: Identifier for a Chat. Formatted as a UUID. required: true schema: type: string format: uuid - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_chat_paged_events' /v0/evi/chats/{id}/audio: get: operationId: get-audio summary: Get chat audio description: >- Fetches the audio of a previous **Chat**. For more details, see our guide on audio reconstruction [here](/docs/speech-to-speech-evi/faq#can-i-access-the-audio-of-previous-conversations-with-evi). tags: - subpackage_chats parameters: - name: id in: path description: Identifier for a Chat. Formatted as a UUID. required: true schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ReturnChatAudioReconstruction' /v0/evi/chat_groups: get: operationId: list-chat-groups summary: List chat_groups description: Fetches a paginated list of **Chat Groups**. tags: - subpackage_chatGroups parameters: - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: config_id in: query description: |- The unique identifier for an EVI configuration. Filter Chat Groups to only include Chats that used this `config_id` in their most recent Chat. required: false schema: type: string format: uuid - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_chat_groups' /v0/evi/chat_groups/{id}: get: operationId: get-chat-group summary: Get chat_group description: Fetches a **ChatGroup** by ID, including a paginated list of **Chats** associated with the **ChatGroup**. tags: - subpackage_chatGroups parameters: - name: id in: path description: Identifier for a Chat Group. Formatted as a UUID. required: true schema: type: string format: uuid - name: status in: query description: Chat status to apply to the chat. String from the ChatStatus enum. required: false schema: type: string - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_chat_group_paged_chats' /v0/evi/chat_groups/{id}/audio: get: operationId: get-audio summary: Get chat group audio description: >- Fetches a paginated list of audio for each **Chat** within the specified **Chat Group**. For more details, see our guide on audio reconstruction [here](/docs/speech-to-speech-evi/faq#can-i-access-the-audio-of-previous-conversations-with-evi). tags: - subpackage_chatGroups parameters: - name: id in: path description: Identifier for a Chat Group. Formatted as a UUID. required: true schema: type: string format: uuid - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_chat_group_paged_audio_reconstructions' /v0/evi/chat_groups/{id}/events: get: operationId: list-chat-group-events summary: List chat events from a specific chat_group description: Fetches a paginated list of **Chat** events associated with a **Chat Group**. tags: - subpackage_chatGroups parameters: - name: id in: path description: Identifier for a Chat Group. Formatted as a UUID. required: true schema: type: string format: uuid - name: page_size in: query description: >- Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10. required: false schema: type: integer - name: page_number in: query description: >- Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page. required: false schema: type: integer default: 0 - name: ascending_order in: query description: >- Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true. required: false schema: type: boolean - name: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_chat_group_paged_events' servers: - url: https://api.hume.ai webhooks: chat-ended: post: operationId: chat-ended summary: Chat Ended description: Sent when an EVI chat ends. responses: '200': description: Webhook received successfully requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEventChatEnded' chat-started: post: operationId: chat-started summary: Chat Started description: Sent when an EVI chat is started. responses: '200': description: Webhook received successfully requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEventChatStarted' tool-call: post: operationId: tool-call summary: Tool Call description: Sent when EVI triggers a tool call responses: '200': description: Webhook received successfully requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEventToolCall' components: schemas: Encoding: type: string enum: - linear16 title: Encoding AudioConfiguration: type: object properties: channels: type: integer description: Number of audio channels. codec: type: - string - 'null' description: Optional codec information. encoding: $ref: '#/components/schemas/Encoding' description: Encoding format of the audio input, such as `linear16`. sample_rate: type: integer description: Audio sample rate. Number of samples per second in the audio input, measured in Hertz. required: - channels - encoding - sample_rate title: AudioConfiguration BuiltInTool: type: string enum: - web_search - hang_up title: BuiltInTool BuiltinToolConfig: type: object properties: fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM if the tool call fails. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation. name: $ref: '#/components/schemas/BuiltInTool' required: - name title: BuiltinToolConfig ContextType: type: string enum: - persistent - temporary title: ContextType Context: type: object properties: text: type: string description: >- The context to be injected into the conversation. Helps inform the LLM's response by providing relevant information about the ongoing conversation. This text will be appended to the end of user messages based on the chosen persistence level. For example, if you want to remind EVI of its role as a helpful weather assistant, the context you insert will be appended to the end of user messages as `{Context: You are a helpful weather assistant}`. type: $ref: '#/components/schemas/ContextType' description: >- The persistence level of the injected context. Specifies how long the injected context will remain active in the session. There are three possible context types: - **Persistent**: The context is appended to all user messages for the duration of the session. - **Temporary**: The context is appended only to the next user message. - **Editable**: The original context is updated to reflect the new context. If the type is not specified, it will default to `temporary`. required: - text title: Context ToolType: type: string enum: - builtin - function title: ToolType Tool: type: object properties: description: type: - string - 'null' description: >- An optional description of what the tool does, used by the supplemental LLM to choose when and how to call the function. fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM if the tool call fails. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation. name: type: string description: Name of the user-defined tool to be enabled. parameters: type: string description: >- Parameters of the tool. Is a stringified JSON schema. These parameters define the inputs needed for the tool's execution, including the expected data type and description for each input field. Structured as a JSON schema, this format ensures the tool receives data in the expected format. type: $ref: '#/components/schemas/ToolType' description: Type of tool. Set to `function` for user-defined tools. required: - name - parameters - type title: Tool SessionSettings: type: object properties: audio: oneOf: - $ref: '#/components/schemas/AudioConfiguration' - type: 'null' description: >- Configuration details for the audio input used during the session. Ensures the audio is being correctly set up for processing. This optional field is only required when the audio input is encoded in PCM Linear 16 (16-bit, little-endian, signed PCM WAV data). For detailed instructions on how to configure session settings for PCM Linear 16 audio, please refer to the [Session Settings section](/docs/empathic-voice-interface-evi/configuration#session-settings) on the EVI Configuration page. builtin_tools: type: - array - 'null' items: $ref: '#/components/schemas/BuiltinToolConfig' description: >- List of built-in tools to enable for the session. Tools are resources used by EVI to perform various tasks, such as searching the web or calling external APIs. Built-in tools, like web search, are natively integrated, while user-defined tools are created and invoked by the user. To learn more, see our [Tool Use Guide](/docs/empathic-voice-interface-evi/tool-use). Currently, the only built-in tool Hume provides is **Web Search**. When enabled, Web Search equips EVI with the ability to search the web for up-to-date information. context: oneOf: - $ref: '#/components/schemas/Context' - type: 'null' description: >- Field for injecting additional context into the conversation, which is appended to the end of user messages for the session. When included in a Session Settings message, the provided context can be used to remind the LLM of its role in every user message, prevent it from forgetting important details, or add new relevant information to the conversation. Set to `null` to clear injected context. custom_session_id: type: - string - 'null' description: >- Unique identifier for the session. Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. If included, the response sent from Hume to your backend will include this ID. This allows you to correlate frontend users with their incoming messages. It is recommended to pass a `custom_session_id` if you are using a Custom Language Model. Please see our guide to [using a custom language model](/docs/empathic-voice-interface-evi/custom-language-model) with EVI to learn more. language_model_api_key: type: - string - 'null' description: >- Third party API key for the supplemental language model. When provided, EVI will use this key instead of Hume's API key for the supplemental LLM. This allows you to bypass rate limits and utilize your own API key as needed. metadata: type: - object - 'null' additionalProperties: description: Any type system_prompt: type: - string - 'null' description: >- Instructions used to shape EVI's behavior, responses, and style for the session. When included in a Session Settings message, the provided Prompt overrides the existing one specified in the EVI configuration. If no Prompt was defined in the configuration, this Prompt will be the one used for the session. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/empathic-voice-interface-evi/prompting). tools: type: - array - 'null' items: $ref: '#/components/schemas/Tool' description: >- List of user-defined tools to enable for the session. Tools are resources used by EVI to perform various tasks, such as searching the web or calling external APIs. Built-in tools, like web search, are natively integrated, while user-defined tools are created and invoked by the user. To learn more, see our [Tool Use Guide](/docs/empathic-voice-interface-evi/tool-use). type: type: string enum: - session_settings description: >- The type of message sent through the socket; must be `session_settings` for our server to correctly identify and process it as a Session Settings message. Session settings are temporary and apply only to the current Chat session. These settings can be adjusted dynamically based on the requirements of each session to ensure optimal performance and user experience. For more information, please refer to the [Session Settings section](/docs/empathic-voice-interface-evi/configuration#session-settings) on the EVI Configuration page. variables: type: - object - 'null' additionalProperties: description: Any type description: >- This field allows you to assign values to dynamic variables referenced in your system prompt. Each key represents the variable name, and the corresponding value is the specific content you wish to assign to that variable within the session. While the values for variables can be strings, numbers, or booleans, the value will ultimately be converted to a string when injected into your system prompt. Using this field, you can personalize responses based on session-specific details. For more guidance, see our [guide on using dynamic variables](/docs/speech-to-speech-evi/features/dynamic-variables). voice_id: type: - string - 'null' description: >- Allows you to change the voice during an active chat. Updating the voice does not affect chat context or conversation history. required: - type description: >- **Settings for this chat session.** Session settings are temporary and apply only to the current Chat session. These settings can be adjusted dynamically based on the requirements of each session to ensure optimal performance and user experience. See our [Session Settings Guide](/docs/speech-to-speech-evi/configuration/session-settings) for a complete list of configurable settings. title: SessionSettings UserInput: type: object properties: custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. text: type: string description: >- User text to insert into the conversation. Text sent through a User Input message is treated as the user's speech to EVI. EVI processes this input and provides a corresponding response. Expression measurement results are not available for User Input messages, as the prosody model relies on audio input and cannot process text alone. type: type: string enum: - user_input description: >- The type of message sent through the socket; must be `user_input` for our server to correctly identify and process it as a User Input message. required: - text - type description: >- **User text to insert into the conversation.** Text sent through a User Input message is treated as the user's speech to EVI. EVI processes this input and provides a corresponding response. Expression measurement results are not available for User Input messages, as the prosody model relies on audio input and cannot process text alone. title: UserInput AssistantInput: type: object properties: custom_session_id: type: - string - 'null' text: type: string description: >- Assistant text to synthesize into spoken audio and insert into the conversation. EVI uses this text to generate spoken audio using our proprietary expressive text-to-speech model. Our model adds appropriate emotional inflections and tones to the text based on the user's expressions and the context of the conversation. The synthesized audio is streamed back to the user as an [Assistant Message](/reference/empathic-voice-interface-evi/chat/chat#receive.Assistant%20Message.type). type: type: string enum: - assistant_input description: >- The type of message sent through the socket; must be `assistant_input` for our server to correctly identify and process it as an Assistant Input message. required: - text - type description: >- **Assistant text to synthesize into spoken audio and insert into the conversation.** EVI uses this text to generate spoken audio using our proprietary expressive text-to-speech model. Our model adds appropriate emotional inflections and tones to the text based on the user's expressions and the context of the conversation. The synthesized audio is streamed back to the user as an Assistant Message. title: AssistantInput ToolResponseMessage: type: object properties: content: type: string description: Return value of the tool call. Contains the output generated by the tool to pass back to EVI. custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. tool_call_id: type: string description: >- The unique identifier for a specific tool call instance. This ID is used to track the request and response of a particular tool invocation, ensuring that the correct response is linked to the appropriate request. The specified `tool_call_id` must match the one received in the [Tool Call message](/reference/empathic-voice-interface-evi/chat/chat#receive.Tool%20Call%20Message.tool_call_id). tool_name: type: - string - 'null' tool_type: oneOf: - $ref: '#/components/schemas/ToolType' - type: 'null' type: type: string enum: - tool_response description: >- The type of message sent through the socket; for a Tool Response message, this must be `tool_response`. Upon receiving a [Tool Call message](/reference/empathic-voice-interface-evi/chat/chat#receive.Tool%20Call%20Message.type) and successfully invoking the function, this message is sent to convey the result of the function call back to EVI. required: - content - tool_call_id - type description: >- **Return value of the tool call.** Contains the output generated by the tool to pass back to EVI. Upon receiving a Tool Call message and successfully invoking the function, this message is sent to convey the result of the function call back to EVI. For built-in tools implemented on the server, you will receive this message type rather than a `ToolCallMessage`. See our [Tool Use Guide](/docs/speech-to-speech-evi/features/tool-use) for further details. title: ToolResponseMessage ErrorLevel: type: string enum: - warn title: ErrorLevel ToolErrorMessage: type: object properties: code: type: - string - 'null' description: Error code. Identifies the type of error encountered. content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the tool errors. custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. error: type: string description: Error message from the tool call, not exposed to the LLM or user. level: oneOf: - $ref: '#/components/schemas/ErrorLevel' - type: 'null' description: >- Indicates the severity of an error; for a Tool Error message, this must be `warn` to signal an unexpected event. tool_call_id: type: string description: >- The unique identifier for a specific tool call instance. This ID is used to track the request and response of a particular tool invocation, ensuring that the Tool Error message is linked to the appropriate tool call request. The specified `tool_call_id` must match the one received in the [Tool Call message](/reference/empathic-voice-interface-evi/chat/chat#receive.Tool%20Call%20Message.type). tool_type: oneOf: - $ref: '#/components/schemas/ToolType' - type: 'null' description: >- Type of tool called. Either `builtin` for natively implemented tools, like web search, or `function` for user-defined tools. type: type: string enum: - tool_error description: >- The type of message sent through the socket; for a Tool Error message, this must be `tool_error`. Upon receiving a [Tool Call message](/reference/empathic-voice-interface-evi/chat/chat#receive.Tool%20Call%20Message.type) and failing to invoke the function, this message is sent to notify EVI of the tool's failure. required: - error - tool_call_id - type description: >- **Error message from the tool call**, not exposed to the LLM or user. Upon receiving a Tool Call message and failing to invoke the function, this message is sent to notify EVI of the tool's failure. For built-in tools implemented on the server, you will receive this message type rather than a `ToolCallMessage` if the tool fails. See our [Tool Use Guide](/docs/speech-to-speech-evi/features/tool-use) for further details. title: ToolErrorMessage PauseAssistantMessage: type: object properties: custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. type: type: string enum: - pause_assistant_message description: >- The type of message sent through the socket; must be `pause_assistant_message` for our server to correctly identify and process it as a Pause Assistant message. Once this message is sent, EVI will not respond until a [Resume Assistant message](/reference/empathic-voice-interface-evi/chat/chat#send.Resume%20Assistant%20Message.type) is sent. When paused, EVI won't respond, but transcriptions of your audio inputs will still be recorded. required: - type description: >- **Pause responses from EVI.** Chat history is still saved and sent after resuming. Once this message is sent, EVI will not respond until a Resume Assistant message is sent. When paused, EVI won't respond, but transcriptions of your audio inputs will still be recorded. See our [Pause Response Guide](/docs/speech-to-speech-evi/features/pause-responses) for further details. title: PauseAssistantMessage ResumeAssistantMessage: type: object properties: custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. type: type: string enum: - resume_assistant_message description: >- The type of message sent through the socket; must be `resume_assistant_message` for our server to correctly identify and process it as a Resume Assistant message. Upon resuming, if any audio input was sent during the pause, EVI will retain context from all messages sent but only respond to the last user message. (e.g., If you ask EVI two questions while paused and then send a `resume_assistant_message`, EVI will respond to the second question and have added the first question to its conversation context.) required: - type description: >- **Resume responses from EVI.** Chat history sent while paused will now be sent. Upon resuming, if any audio input was sent during the pause, EVI will retain context from all messages sent but only respond to the last user message. See our [Pause Response Guide](/docs/speech-to-speech-evi/features/pause-responses) for further details. title: ResumeAssistantMessage ControlPlanePublishEvent: oneOf: - $ref: '#/components/schemas/SessionSettings' - $ref: '#/components/schemas/UserInput' - $ref: '#/components/schemas/AssistantInput' - $ref: '#/components/schemas/ToolResponseMessage' - $ref: '#/components/schemas/ToolErrorMessage' - $ref: '#/components/schemas/PauseAssistantMessage' - $ref: '#/components/schemas/ResumeAssistantMessage' title: ControlPlanePublishEvent controlPlane_send_Response_200: type: object properties: {} description: Empty response body title: controlPlane_send_Response_200 ValidationErrorLocItems: oneOf: - type: string - type: integer title: ValidationErrorLocItems ValidationError: type: object properties: loc: type: array items: $ref: '#/components/schemas/ValidationErrorLocItems' msg: type: string type: type: string required: - loc - msg - type title: ValidationError HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' title: HTTPValidationError PostedBuiltinToolName: type: string enum: - web_search - hang_up title: PostedBuiltinToolName posted_builtin_tool: type: object properties: fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors. name: $ref: '#/components/schemas/PostedBuiltinToolName' required: - name description: A configuration of a built-in tool to be posted to the server title: posted_builtin_tool PostedConfigEllmModel: type: object properties: allow_short_responses: type: - boolean - 'null' description: >- Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted). title: PostedConfigEllmModel PostedEventMessageSpecsOnInactivityTimeout: type: object properties: enabled: type: boolean description: |- Boolean indicating if this event message is enabled. If set to `true`, a message will be sent when the circumstances for the specific event are met. text: type: - string - 'null' description: >- Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt. required: - enabled title: PostedEventMessageSpecsOnInactivityTimeout PostedEventMessageSpecsOnMaxDurationTimeout: type: object properties: enabled: type: boolean description: |- Boolean indicating if this event message is enabled. If set to `true`, a message will be sent when the circumstances for the specific event are met. text: type: - string - 'null' description: >- Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt. required: - enabled title: PostedEventMessageSpecsOnMaxDurationTimeout PostedEventMessageSpecsOnNewChat: type: object properties: enabled: type: boolean description: |- Boolean indicating if this event message is enabled. If set to `true`, a message will be sent when the circumstances for the specific event are met. text: type: - string - 'null' description: >- Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt. required: - enabled title: PostedEventMessageSpecsOnNewChat PostedConfigEventMessages: type: object properties: on_inactivity_timeout: $ref: '#/components/schemas/PostedEventMessageSpecsOnInactivityTimeout' on_max_duration_timeout: $ref: '#/components/schemas/PostedEventMessageSpecsOnMaxDurationTimeout' on_new_chat: $ref: '#/components/schemas/PostedEventMessageSpecsOnNewChat' title: PostedConfigEventMessages posted_interruption_spec: type: object properties: min_interruption_ms: type: - integer - 'null' description: >- How long the user must speak while the agent is outputting audio before the agent stops and yields the floor. Lower values make the agent more responsive to the user speaking up, but increase the chance of noise or backchannels stopping the agent unnecessarily. Higher values make the agent harder to interrupt, allowing it to finish more of its response before yielding. Accepts values between 50 and 2000 milliseconds. description: An interruption specification posted to the server title: posted_interruption_spec ModelProviderEnum: type: string enum: - GROQ - OPEN_AI - FIREWORKS - ANTHROPIC - CUSTOM_LANGUAGE_MODEL - GOOGLE - HUME_AI - AMAZON_BEDROCK - PERPLEXITY - SAMBANOVA - CEREBRAS - X_AI title: ModelProviderEnum LanguageModelType: type: string enum: - claude-3-7-sonnet-latest - claude-opus-4-6 - claude-3-5-sonnet-latest - claude-3-5-haiku-latest - claude-3-5-sonnet-20240620 - claude-3-opus-20240229 - claude-3-sonnet-20240229 - claude-3-haiku-20240307 - claude-sonnet-4-20250514 - claude-sonnet-4-5-20250929 - claude-haiku-4-5-20251001 - us.anthropic.claude-3-5-haiku-20241022-v1:0 - us.anthropic.claude-3-5-sonnet-20240620-v1:0 - us.anthropic.claude-3-haiku-20240307-v1:0 - gpt-oss-120b - qwen-3-235b-a22b - qwen-3-235b-a22b-instruct-2507 - qwen-3-235b-a22b-thinking-2507 - gemini-1.5-pro - gemini-1.5-flash - gemini-1.5-pro-002 - gemini-1.5-flash-002 - gemini-2.0-flash - gemini-2.5-flash - gemini-2.5-flash-preview-04-17 - gpt-4-turbo - gpt-4-turbo-preview - gpt-3.5-turbo-0125 - gpt-3.5-turbo - gpt-4o - gpt-4o-mini - gpt-4.1 - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-4o-priority - gpt-4o-mini-priority - gpt-4.1-priority - gpt-5-priority - gpt-5-mini-priority - gpt-5-nano-priority - gpt-5.1 - gpt-5.1-priority - gpt-5.2 - gpt-5.2-priority - gemma-7b-it - llama3-8b-8192 - llama3-70b-8192 - llama-3.1-70b-versatile - llama-3.3-70b-versatile - llama-3.1-8b-instant - moonshotai/kimi-k2-instruct - accounts/fireworks/models/mixtral-8x7b-instruct - accounts/fireworks/models/llama-v3p1-405b-instruct - accounts/fireworks/models/llama-v3p1-70b-instruct - accounts/fireworks/models/llama-v3p1-8b-instruct - sonar - sonar-pro - sambanova - DeepSeek-R1-Distill-Llama-70B - Llama-4-Maverick-17B-128E-Instruct - Qwen3-32B - grok-4-fast-non-reasoning-latest - ellm - custom-language-model - hume-evi-3-web-search title: LanguageModelType PostedConfigLanguageModel: type: object properties: model_provider: $ref: '#/components/schemas/ModelProviderEnum' model_resource: $ref: '#/components/schemas/LanguageModelType' temperature: type: - number - 'null' format: double description: >- The model temperature, with values between 0 to 1 (inclusive). Controls the randomness of the LLM's output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses. title: PostedConfigLanguageModel PostedConfigNudges: type: object properties: enabled: type: - boolean - 'null' description: If true, EVI will 'nudge' the user to speak after a determined interval of silence. interval_secs: type: - integer - 'null' description: The interval of inactivity (in seconds) before a nudge is triggered. title: PostedConfigNudges prompt_expansion_spec: type: object properties: enabled: type: boolean description: >- Boolean indicating whether prompt expansion is enabled. Defaults to `true`. When set to `false`, no additional instructions are appended to the system prompt, giving full control over the prompt content. Only applicable when using an external supplemental language model. description: Configuration for prompt expansion behavior. title: prompt_expansion_spec PostedConfigPrompt: type: object properties: id: type: - string - 'null' description: Identifier for a Prompt. Formatted as a UUID. prompt_expansion: $ref: '#/components/schemas/prompt_expansion_spec' text: type: - string - 'null' description: Text used to create a new prompt for a particular config. version: type: - integer - 'null' description: >- Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique. title: PostedConfigPrompt PostedTimeoutSpecsInactivity: type: object properties: duration_secs: type: - integer - 'null' enabled: type: boolean required: - enabled title: PostedTimeoutSpecsInactivity PostedTimeoutSpecsMaxDuration: type: object properties: duration_secs: type: - integer - 'null' enabled: type: boolean required: - enabled title: PostedTimeoutSpecsMaxDuration PostedConfigTimeouts: type: object properties: inactivity: $ref: '#/components/schemas/PostedTimeoutSpecsInactivity' max_duration: $ref: '#/components/schemas/PostedTimeoutSpecsMaxDuration' title: PostedConfigTimeouts posted_user_defined_tool_spec: type: object properties: id: type: string description: Identifier for a Tool. Formatted as a UUID. version: type: - integer - 'null' description: >- Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique. required: - id description: A specific tool identifier to be posted to the server title: posted_user_defined_tool_spec posted_turn_detection_spec: type: object properties: end_of_turn_silence_ms: type: - integer - 'null' description: >- How long the user must be silent before EVI considers their turn complete and begins generating a response. Lower values make conversations feel snappier but increase the chance of the agent responding during a mid-thought pause. Higher values give users more room to pause and collect their thoughts before the agent responds. Accepts values between 500 and 3000 milliseconds. prefix_padding_ms: type: - integer - 'null' description: >- The duration of audio captured before the detected start of speech. This ensures the beginning of an utterance is not clipped. Accepts values between 0 and 1000 milliseconds. speech_detection_threshold: type: - number - 'null' format: double description: >- How confident the system must be that audio contains speech before it begins processing. Lower values increase sensitivity, capturing softer speech at the cost of more noise-triggered processing. Higher values require clearer, louder audio to register as speech. Accepts values between 0.0 and 1.0. description: A turn detection specification posted to the server title: posted_turn_detection_spec VoiceProvider: type: string enum: - HUME_AI - CUSTOM_VOICE title: VoiceProvider VoiceId: type: object properties: id: type: string description: The unique ID associated with the **Voice**. provider: $ref: '#/components/schemas/VoiceProvider' description: >- Specifies the source provider associated with the chosen voice. - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices. - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider to `HUME_AI`. Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are private and accessible only via requests authenticated with your API key. required: - id title: VoiceId VoiceName: type: object properties: name: type: string description: The name of a **Voice**. provider: $ref: '#/components/schemas/VoiceProvider' description: >- Specifies the source provider associated with the chosen voice. - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices. - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider to `HUME_AI`. Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are private and accessible only via requests authenticated with your API key. required: - name title: VoiceName VoiceRef: oneOf: - $ref: '#/components/schemas/VoiceId' - $ref: '#/components/schemas/VoiceName' title: VoiceRef PostedWebhookSpecEventsItems: type: string enum: - chat_started - chat_ended - tool_call description: >- The list of events the specified URL is subscribed to. See our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events. title: PostedWebhookSpecEventsItems posted_webhook_spec: type: object properties: events: type: array items: $ref: '#/components/schemas/PostedWebhookSpecEventsItems' description: >- The list of events the specified URL is subscribed to. See our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events. url: type: string description: >- The URL where event payloads will be sent. This must be a valid https URL to ensure secure communication. The server at this URL must accept POST requests with a JSON payload. required: - events - url description: URL and settings for a specific webhook to be posted to the server title: posted_webhook_spec posted_config: type: object properties: builtin_tools: type: - array - 'null' items: $ref: '#/components/schemas/posted_builtin_tool' description: Built-in tool specification for a Config. ellm_model: $ref: '#/components/schemas/PostedConfigEllmModel' event_messages: $ref: '#/components/schemas/PostedConfigEventMessages' evi_version: type: string description: EVI version to use. Only versions `3` and `4-mini` are supported. interruption: $ref: '#/components/schemas/posted_interruption_spec' language_model: $ref: '#/components/schemas/PostedConfigLanguageModel' name: type: string description: Name applied to all versions of a particular Config. nudges: $ref: '#/components/schemas/PostedConfigNudges' prompt: $ref: '#/components/schemas/PostedConfigPrompt' timeouts: $ref: '#/components/schemas/PostedConfigTimeouts' tools: type: - array - 'null' items: $ref: '#/components/schemas/posted_user_defined_tool_spec' description: Tool specification for a Config. turn_detection: $ref: '#/components/schemas/posted_turn_detection_spec' version_description: type: - string - 'null' description: An optional description of the Config version. voice: $ref: '#/components/schemas/VoiceRef' description: A voice specification associated with this Config. webhooks: type: - array - 'null' items: $ref: '#/components/schemas/posted_webhook_spec' description: Webhook config specifications for each subscriber. required: - evi_version - name description: A configuration to be posted to the server title: posted_config ReturnBuiltinToolToolType: type: string enum: - BUILTIN - FUNCTION title: ReturnBuiltinToolToolType return_builtin_tool: type: object properties: fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors. name: type: string description: >- Name of the built-in tool to use. Hume supports the following built-in tools: - **web_search:** enables EVI to search the web for up-to-date information when applicable. - **hang_up:** closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools). tool_type: $ref: '#/components/schemas/ReturnBuiltinToolToolType' required: - name - tool_type description: A specific builtin tool version returned from the server title: return_builtin_tool return_ellm_model: type: object properties: allow_short_responses: type: boolean description: >- Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted). required: - allow_short_responses description: A specific eLLM Model configuration title: return_ellm_model return_event_message_spec: type: object properties: enabled: type: boolean description: |- Boolean indicating if this event message is enabled. If set to `true`, a message will be sent when the circumstances for the specific event are met. text: type: - string - 'null' description: >- Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt. required: - enabled description: A specific event message configuration to be returned from the server title: return_event_message_spec return_event_message_specs: type: object properties: on_inactivity_timeout: $ref: '#/components/schemas/return_event_message_spec' on_max_duration_timeout: $ref: '#/components/schemas/return_event_message_spec' on_new_chat: $ref: '#/components/schemas/return_event_message_spec' description: >- Collection of event messages returned by the server. Event messages are sent by the server when specific events occur during a chat session. These messages are used to configure behaviors for EVI, such as controlling how EVI starts a new conversation. title: return_event_message_specs return_interruption_spec: type: object properties: min_interruption_ms: type: - integer - 'null' description: >- How long the user must speak while the agent is outputting audio before the agent stops and yields the floor. Lower values make the agent more responsive to the user speaking up, but increase the chance of noise or backchannels stopping the agent unnecessarily. Higher values make the agent harder to interrupt, allowing it to finish more of its response before yielding. Accepts values between 50 and 2000 milliseconds. description: An interruption configuration returned from the server title: return_interruption_spec return_language_model: type: object properties: model_provider: $ref: '#/components/schemas/ModelProviderEnum' model_resource: $ref: '#/components/schemas/LanguageModelType' temperature: type: - number - 'null' format: double description: >- The model temperature, with values between 0 to 1 (inclusive). Controls the randomness of the LLM's output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses. description: A specific LanguageModel title: return_language_model return_nudge_spec: type: object properties: enabled: type: boolean description: If true, EVI will 'nudge' the user to speak after a determined interval of silence. interval_secs: type: - integer - 'null' description: The interval of inactivity (in seconds) before a nudge is triggered. required: - enabled description: A specific nudge configuration returned from the server title: return_nudge_spec return_prompt_public: type: object properties: created_on: type: integer format: int64 description: Time at which the Prompt was created. Measured in seconds since the Unix epoch. id: type: string description: Identifier for a Prompt. Formatted as a UUID. modified_on: type: integer format: int64 description: Time at which the Prompt was last modified. Measured in seconds since the Unix epoch. name: type: string description: Name applied to all versions of a particular Prompt. prompt_expansion: $ref: '#/components/schemas/prompt_expansion_spec' text: type: string description: >- Instructions used to shape EVI's behavior, responses, and style. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/speech-to-speech-evi/guides/prompting). version: type: integer description: >- Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique. version_description: type: - string - 'null' description: An optional description of the Prompt version. version_type: type: string description: >- Indicates whether this prompt is using a fixed version number or auto-updating to the latest version. Values from the VersionType enum. required: - created_on - id - modified_on - name - text - version - version_type description: A specific prompt version returned from the server title: return_prompt_public return_timeout_spec: type: object properties: duration_secs: type: - integer - 'null' description: Duration in seconds for the timeout (e.g. 600 seconds represents 10 minutes). enabled: type: boolean description: >- Boolean indicating if this timeout is enabled. If set to false, EVI will not timeout due to a specified duration being reached. However, the conversation will eventually disconnect after 1,800 seconds (30 minutes), which is the maximum WebSocket duration limit for EVI. required: - enabled description: A specific timeout configuration to be returned from the server title: return_timeout_spec return_timeout_specs: type: object properties: inactivity: $ref: '#/components/schemas/return_timeout_spec' max_duration: $ref: '#/components/schemas/return_timeout_spec' required: - inactivity - max_duration description: >- Collection of timeout specifications returned by the server. Timeouts are sent by the server when specific time-based events occur during a chat session. These specifications set the inactivity timeout and the maximum duration an EVI WebSocket connection can stay open before it is automatically disconnected. title: return_timeout_specs ReturnUserDefinedToolToolType: type: string enum: - BUILTIN - FUNCTION title: ReturnUserDefinedToolToolType ReturnUserDefinedToolVersionType: type: string enum: - FIXED - LATEST title: ReturnUserDefinedToolVersionType return_user_defined_tool: type: object properties: created_on: type: integer format: int64 description: The timestamp when the first version of this tool was created. description: type: - string - 'null' description: >- An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function. fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors. id: type: string description: Identifier for a Tool. Formatted as a UUID. modified_on: type: integer format: int64 description: The timestamp when this version of the tool was created. name: type: string description: >- Name of the built-in tool to use. Hume supports the following built-in tools: - **web_search:** enables EVI to search the web for up-to-date information when applicable. - **hang_up:** closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools). parameters: type: string description: >- Stringified JSON defining the parameters used by this version of the Tool. These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format. tool_type: $ref: '#/components/schemas/ReturnUserDefinedToolToolType' version: type: integer description: >- Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique. version_description: type: - string - 'null' description: An optional description of the Tool version. version_type: $ref: '#/components/schemas/ReturnUserDefinedToolVersionType' required: - created_on - id - modified_on - name - parameters - tool_type - version - version_type description: A specific tool version returned from the server title: return_user_defined_tool return_turn_detection_spec: type: object properties: end_of_turn_silence_ms: type: - integer - 'null' description: >- How long the user must be silent before EVI considers their turn complete and begins generating a response. Lower values make conversations feel snappier but increase the chance of the agent responding during a mid-thought pause. Higher values give users more room to pause and collect their thoughts before the agent responds. Accepts values between 500 and 3000 milliseconds. prefix_padding_ms: type: - integer - 'null' description: >- The duration of audio captured before the detected start of speech. This ensures the beginning of an utterance is not clipped. Accepts values between 0 and 1000 milliseconds. speech_detection_threshold: type: - number - 'null' format: double description: >- How confident the system must be that audio contains speech before it begins processing. Lower values increase sensitivity, capturing softer speech at the cost of more noise-triggered processing. Higher values require clearer, louder audio to register as speech. Accepts values between 0.0 and 1.0. description: A turn detection configuration returned from the server title: return_turn_detection_spec ReturnVoice: type: object properties: compatible_octave_models: type: array items: type: string id: type: string description: ID of the voice in the `Voice Library`. name: type: string description: Name of the voice in the `Voice Library`. provider: $ref: '#/components/schemas/VoiceProvider' required: - id - name - provider description: An Octave voice available for text-to-speech title: ReturnVoice ReturnedWebhookSpecEventsItems: type: string enum: - chat_started - chat_ended - tool_call description: >- The list of events the specified URL is subscribed to. See our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events. title: ReturnedWebhookSpecEventsItems returned_webhook_spec: type: object properties: events: type: array items: $ref: '#/components/schemas/ReturnedWebhookSpecEventsItems' description: >- The list of events the specified URL is subscribed to. See our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events. url: type: string description: >- The URL where event payloads will be sent. This must be a valid https URL to ensure secure communication. The server at this URL must accept POST requests with a JSON payload. required: - events - url description: Collection of webhook URL endpoints to be returned from the server title: returned_webhook_spec return_config_public: type: object properties: builtin_tools: type: - array - 'null' items: $ref: '#/components/schemas/return_builtin_tool' description: List of built-in tools associated with this Config. created_on: type: integer format: int64 description: Time at which the Config was created. Measured in seconds since the Unix epoch. ellm_model: $ref: '#/components/schemas/return_ellm_model' event_messages: $ref: '#/components/schemas/return_event_message_specs' evi_version: type: string description: >- Specifies the EVI version to use. See our [EVI Version Guide](/docs/speech-to-speech-evi/configuration/evi-version) for differences between versions. **We're officially sunsetting EVI versions 1 and 2 on August 30, 2025**. To keep things running smoothly, be sure to [migrate to EVI 3](/docs/speech-to-speech-evi/configuration/evi-version#migrating-to-evi-3) before then. id: type: string description: Identifier for a Config. Formatted as a UUID. interruption: $ref: '#/components/schemas/return_interruption_spec' language_model: $ref: '#/components/schemas/return_language_model' modified_on: type: integer format: int64 description: Time at which the Config was last modified. Measured in seconds since the Unix epoch. name: type: string description: Name applied to all versions of a particular Config. nudges: $ref: '#/components/schemas/return_nudge_spec' prompt: $ref: '#/components/schemas/return_prompt_public' timeouts: $ref: '#/components/schemas/return_timeout_specs' tools: type: - array - 'null' items: $ref: '#/components/schemas/return_user_defined_tool' description: List of user-defined tools associated with this Config. turn_detection: $ref: '#/components/schemas/return_turn_detection_spec' version: type: integer description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. version_description: type: - string - 'null' description: An optional description of the Config version. voice: $ref: '#/components/schemas/ReturnVoice' webhooks: type: - array - 'null' items: $ref: '#/components/schemas/returned_webhook_spec' description: Map of webhooks associated with this config. description: A specific config version returned from the server title: return_config_public ReturnConfigEllmModel: type: object properties: allow_short_responses: type: boolean description: >- Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted). required: - allow_short_responses title: ReturnConfigEllmModel ReturnConfigEventMessages: type: object properties: on_inactivity_timeout: $ref: '#/components/schemas/return_event_message_spec' on_max_duration_timeout: $ref: '#/components/schemas/return_event_message_spec' on_new_chat: $ref: '#/components/schemas/return_event_message_spec' title: ReturnConfigEventMessages ReturnConfigLanguageModel: type: object properties: model_provider: $ref: '#/components/schemas/ModelProviderEnum' model_resource: $ref: '#/components/schemas/LanguageModelType' temperature: type: - number - 'null' format: double description: >- The model temperature, with values between 0 to 1 (inclusive). Controls the randomness of the LLM's output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses. title: ReturnConfigLanguageModel ReturnConfigNudges: type: object properties: enabled: type: boolean description: If true, EVI will 'nudge' the user to speak after a determined interval of silence. interval_secs: type: - integer - 'null' description: The interval of inactivity (in seconds) before a nudge is triggered. required: - enabled title: ReturnConfigNudges ReturnPromptVersionType: type: string enum: - FIXED - LATEST title: ReturnPromptVersionType ReturnConfigPrompt: type: object properties: created_on: type: integer format: int64 description: Time at which the Prompt was created. Measured in seconds since the Unix epoch. id: type: string description: Identifier for a Prompt. Formatted as a UUID. modified_on: type: integer format: int64 description: Time at which the Prompt was last modified. Measured in seconds since the Unix epoch. name: type: string description: Name applied to all versions of a particular Prompt. text: type: string description: >- Instructions used to shape EVI's behavior, responses, and style. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/speech-to-speech-evi/guides/prompting). version: type: integer description: >- Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique. version_description: type: - string - 'null' description: An optional description of the Prompt version. version_type: $ref: '#/components/schemas/ReturnPromptVersionType' required: - created_on - id - modified_on - name - text - version - version_type title: ReturnConfigPrompt ReturnConfigTimeouts: type: object properties: inactivity: $ref: '#/components/schemas/return_timeout_spec' max_duration: $ref: '#/components/schemas/return_timeout_spec' required: - inactivity - max_duration title: ReturnConfigTimeouts return_config: type: object properties: builtin_tools: type: - array - 'null' items: $ref: '#/components/schemas/return_builtin_tool' description: List of built-in tools associated with this Config. created_on: type: integer format: int64 description: Time at which the Config was created. Measured in seconds since the Unix epoch. ellm_model: $ref: '#/components/schemas/ReturnConfigEllmModel' event_messages: $ref: '#/components/schemas/ReturnConfigEventMessages' evi_version: type: string description: >- Specifies the EVI version to use. See our [EVI Version Guide](/docs/speech-to-speech-evi/configuration/evi-version) for differences between versions. **We're officially sunsetting EVI versions 1 and 2 on August 30, 2025**. To keep things running smoothly, be sure to [migrate to EVI 3](/docs/speech-to-speech-evi/configuration/evi-version#migrating-to-evi-3) before then. id: type: string description: Identifier for a Config. Formatted as a UUID. interruption: $ref: '#/components/schemas/return_interruption_spec' language_model: $ref: '#/components/schemas/ReturnConfigLanguageModel' modified_on: type: integer format: int64 description: Time at which the Config was last modified. Measured in seconds since the Unix epoch. name: type: string description: Name applied to all versions of a particular Config. nudges: $ref: '#/components/schemas/ReturnConfigNudges' prompt: $ref: '#/components/schemas/ReturnConfigPrompt' timeouts: $ref: '#/components/schemas/ReturnConfigTimeouts' tools: type: - array - 'null' items: $ref: '#/components/schemas/return_user_defined_tool' description: List of user-defined tools associated with this Config. turn_detection: $ref: '#/components/schemas/return_turn_detection_spec' version: type: integer description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. version_description: type: - string - 'null' description: An optional description of the Config version. voice: $ref: '#/components/schemas/ReturnVoice' description: A voice specification associated with this Config. webhooks: type: - array - 'null' items: $ref: '#/components/schemas/returned_webhook_spec' description: Map of webhooks associated with this config. description: A specific config version returned from the server title: return_config return_paged_configs: type: object properties: configs_page: type: array items: $ref: '#/components/schemas/return_config' description: List of configs returned for the specified `page_number` and `page_size`. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. total_pages: type: integer description: The total number of pages in the collection. required: - total_pages description: A paginated list of config versions returned from the server title: return_paged_configs posted_ellm_model: type: object properties: allow_short_responses: type: - boolean - 'null' description: >- Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted). description: A eLLM model configuration to be posted to the server title: posted_ellm_model posted_event_message_specs: type: object properties: on_inactivity_timeout: $ref: '#/components/schemas/PostedEventMessageSpecsOnInactivityTimeout' on_max_duration_timeout: $ref: '#/components/schemas/PostedEventMessageSpecsOnMaxDurationTimeout' on_new_chat: $ref: '#/components/schemas/PostedEventMessageSpecsOnNewChat' description: >- Collection of event messages returned by the server. Event messages are sent by the server when specific events occur during a chat session. These messages are used to configure behaviors for EVI, such as controlling how EVI starts a new conversation. title: posted_event_message_specs posted_language_model: type: object properties: model_provider: $ref: '#/components/schemas/ModelProviderEnum' model_resource: $ref: '#/components/schemas/LanguageModelType' temperature: type: - number - 'null' format: double description: >- The model temperature, with values between 0 to 1 (inclusive). Controls the randomness of the LLM's output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses. description: A LanguageModel to be posted to the server title: posted_language_model posted_nudge_spec: type: object properties: enabled: type: - boolean - 'null' description: If true, EVI will 'nudge' the user to speak after a determined interval of silence. interval_secs: type: - integer - 'null' description: The interval of inactivity (in seconds) before a nudge is triggered. description: A nudge specification posted to the server title: posted_nudge_spec posted_config_prompt_spec: type: object properties: id: type: - string - 'null' description: Identifier for a Prompt. Formatted as a UUID. prompt_expansion: $ref: '#/components/schemas/prompt_expansion_spec' text: type: - string - 'null' description: Text used to create a new prompt for a particular config. version: type: - integer - 'null' description: >- Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique. description: Identifies which prompt to use in a a config OR how to create a new prompt to use in the config title: posted_config_prompt_spec posted_timeout_specs: type: object properties: inactivity: $ref: '#/components/schemas/PostedTimeoutSpecsInactivity' max_duration: $ref: '#/components/schemas/PostedTimeoutSpecsMaxDuration' description: >- Collection of timeout specifications returned by the server. Timeouts are sent by the server when specific time-based events occur during a chat session. These specifications set the inactivity timeout and the maximum duration an EVI WebSocket connection can stay open before it is automatically disconnected. title: posted_timeout_specs posted_config_version: type: object properties: builtin_tools: type: - array - 'null' items: $ref: '#/components/schemas/posted_builtin_tool' description: Built-in tool specification for a Config. ellm_model: $ref: '#/components/schemas/posted_ellm_model' event_messages: $ref: '#/components/schemas/posted_event_message_specs' evi_version: type: string description: EVI version to use. Only versions `3` and `4-mini` are supported. interruption: $ref: '#/components/schemas/posted_interruption_spec' language_model: $ref: '#/components/schemas/posted_language_model' nudges: $ref: '#/components/schemas/posted_nudge_spec' prompt: $ref: '#/components/schemas/posted_config_prompt_spec' timeouts: $ref: '#/components/schemas/posted_timeout_specs' tools: type: - array - 'null' items: $ref: '#/components/schemas/posted_user_defined_tool_spec' description: Tool specification for a Config. turn_detection: $ref: '#/components/schemas/posted_turn_detection_spec' version_description: type: - string - 'null' description: An optional description of the Config version. voice: $ref: '#/components/schemas/VoiceRef' webhooks: type: - array - 'null' items: $ref: '#/components/schemas/posted_webhook_spec' description: Webhook config specifications for each subscriber. required: - evi_version description: A new version of an existing configuration to be posted to the server title: posted_config_version posted_config_name: type: object properties: name: type: string description: Name applied to all versions of a particular Config. required: - name description: A configuration name change to be posted to the server title: posted_config_name configs_update-config-name_Response_200: type: object properties: {} description: Empty response body title: configs_update-config-name_Response_200 posted_config_version_description: type: object properties: version_description: type: - string - 'null' description: An optional description of the Config version. description: A config version description to be posted to the server title: posted_config_version_description configs_delete-config_Response_200: type: object properties: {} description: Empty response body title: configs_delete-config_Response_200 configs_delete-config-version_Response_200: type: object properties: {} description: Empty response body title: configs_delete-config-version_Response_200 posted_prompt: type: object properties: name: type: string description: Name applied to all versions of a particular Prompt. prompt_expansion: $ref: '#/components/schemas/prompt_expansion_spec' text: type: string description: >- Instructions used to shape EVI's behavior, responses, and style. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/speech-to-speech-evi/guides/prompting). version_description: type: - string - 'null' description: An optional description of the Prompt version. required: - name - text description: A prompt to be posted to the server title: posted_prompt return_prompt: type: object properties: created_on: type: integer format: int64 description: Time at which the Prompt was created. Measured in seconds since the Unix epoch. id: type: string description: Identifier for a Prompt. Formatted as a UUID. modified_on: type: integer format: int64 description: Time at which the Prompt was last modified. Measured in seconds since the Unix epoch. name: type: string description: Name applied to all versions of a particular Prompt. text: type: string description: >- Instructions used to shape EVI's behavior, responses, and style. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/speech-to-speech-evi/guides/prompting). version: type: integer description: >- Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique. version_description: type: - string - 'null' description: An optional description of the Prompt version. version_type: $ref: '#/components/schemas/ReturnPromptVersionType' required: - created_on - id - modified_on - name - text - version - version_type description: A Prompt associated with this Config. title: return_prompt return_paged_prompts: type: object properties: page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. prompts_page: type: array items: $ref: '#/components/schemas/return_prompt' description: List of prompts returned for the specified `page_number` and `page_size`. total_pages: type: integer description: The total number of pages in the collection. required: - page_number - page_size - prompts_page - total_pages description: A paginated list of prompt versions returned from the server title: return_paged_prompts posted_prompt_version: type: object properties: prompt_expansion: $ref: '#/components/schemas/prompt_expansion_spec' text: type: string description: >- Instructions used to shape EVI's behavior, responses, and style. You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our [Prompting Guide](/docs/speech-to-speech-evi/guides/prompting). version_description: type: - string - 'null' description: An optional description of the Prompt version. required: - text description: A new version of an existing prompt to be posted to the server title: posted_prompt_version posted_prompt_name: type: object properties: name: type: string description: Name applied to all versions of a particular Prompt. required: - name description: A prompt name change to be posted to the server title: posted_prompt_name prompts_update-prompt-name_Response_200: type: object properties: {} description: Empty response body title: prompts_update-prompt-name_Response_200 patched_prompt_version_description: type: object properties: version_description: type: - string - 'null' description: An optional description of the Prompt version. description: A prompt version description to be patched to the server title: patched_prompt_version_description prompts_delete-prompt_Response_200: type: object properties: {} description: Empty response body title: prompts_delete-prompt_Response_200 prompts_delete-prompt-version_Response_200: type: object properties: {} description: Empty response body title: prompts_delete-prompt-version_Response_200 posted_user_defined_tool: type: object properties: description: type: - string - 'null' description: >- An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function. fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors. name: type: string description: >- Name of the built-in tool to use. Hume supports the following built-in tools: - **web_search:** enables EVI to search the web for up-to-date information when applicable. - **hang_up:** closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools). parameters: type: string description: >- Stringified JSON defining the parameters used by this version of the Tool. These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format. version_description: type: - string - 'null' description: An optional description of the Tool version. required: - name - parameters description: A tool to be posted to the server title: posted_user_defined_tool return_paged_user_defined_tools: type: object properties: page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. tools_page: type: array items: $ref: '#/components/schemas/return_user_defined_tool' description: List of tools returned for the specified `page_number` and `page_size`. total_pages: type: integer description: The total number of pages in the collection. required: - page_number - page_size - tools_page - total_pages description: A paginated list of user defined tool versions returned from the server title: return_paged_user_defined_tools posted_user_defined_tool_version: type: object properties: description: type: - string - 'null' description: >- An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function. fallback_content: type: - string - 'null' description: >- Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors. parameters: type: string description: >- Stringified JSON defining the parameters used by this version of the Tool. These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format. version_description: type: - string - 'null' description: An optional description of the Tool version. required: - parameters description: A new version of an existing tool to be posted to the server title: posted_user_defined_tool_version posted_user_defined_tool_name: type: object properties: name: type: string description: >- Name of the built-in tool to use. Hume supports the following built-in tools: - **web_search:** enables EVI to search the web for up-to-date information when applicable. - **hang_up:** closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools). required: - name description: A tool name change to be posted to the server title: posted_user_defined_tool_name tools_update-tool-name_Response_200: type: object properties: {} description: Empty response body title: tools_update-tool-name_Response_200 posted_user_defined_tool_version_description: type: object properties: version_description: type: - string - 'null' description: An optional description of the Tool version. description: A tool version description to be posted to the server title: posted_user_defined_tool_version_description tools_delete-tool_Response_200: type: object properties: {} description: Empty response body title: tools_delete-tool_Response_200 tools_delete-tool-version_Response_200: type: object properties: {} description: Empty response body title: tools_delete-tool-version_Response_200 return_config_spec: type: object properties: id: type: string description: Identifier for a Config. Formatted as a UUID. version: type: - integer - 'null' description: >- Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number. required: - id description: The Config associated with this Chat. title: return_config_spec ReturnChatStatus: type: string enum: - ACTIVE - USER_ENDED - USER_TIMEOUT - MAX_DURATION_TIMEOUT - INACTIVITY_TIMEOUT - ERROR title: ReturnChatStatus return_chat: type: object properties: chat_group_id: type: string description: >- Identifier for the Chat Group. Any chat resumed from this Chat will have the same `chat_group_id`. Formatted as a UUID. config: $ref: '#/components/schemas/return_config_spec' end_timestamp: type: - integer - 'null' format: int64 description: Time at which the Chat ended. Measured in seconds since the Unix epoch. event_count: type: - integer - 'null' format: int64 description: The total number of events currently in this chat. id: type: string description: Identifier for a Chat. Formatted as a UUID. metadata: type: - string - 'null' description: Stringified JSON with additional metadata about the chat. start_timestamp: type: integer format: int64 description: Time at which the Chat started. Measured in seconds since the Unix epoch. status: $ref: '#/components/schemas/ReturnChatStatus' required: - chat_group_id - id - start_timestamp - status description: A description of chat and its status title: return_chat ReturnPagedChatsPaginationDirection: type: string enum: - ASC - DESC title: ReturnPagedChatsPaginationDirection return_paged_chats: type: object properties: chats_page: type: array items: $ref: '#/components/schemas/return_chat' description: List of Chats and their metadata returned for the specified `page_number` and `page_size`. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnPagedChatsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. required: - chats_page - page_number - page_size - pagination_direction - total_pages description: A paginated list of chats returned from the server title: return_paged_chats ReturnChatEventRole: type: string enum: - USER - AGENT - SYSTEM - TOOL title: ReturnChatEventRole ReturnChatEventType: type: string enum: - AGENT_MESSAGE - ASSISTANT_PROSODY - CHAT_START_MESSAGE - CHAT_END_MESSAGE - FUNCTION_CALL - FUNCTION_CALL_RESPONSE - PAUSE_ONSET - RESUME_ONSET - SESSION_SETTINGS - SYSTEM_PROMPT - USER_INTERRUPTION - USER_MESSAGE - USER_RECORDING_START_MESSAGE title: ReturnChatEventType return_chat_event: type: object properties: chat_id: type: string description: Identifier for the Chat this event occurred in. Formatted as a UUID. emotion_features: type: - string - 'null' description: >- Stringified JSON containing the prosody model inference results. EVI uses the prosody model to measure 48 expressions related to speech and vocal characteristics. These results contain a detailed emotional and tonal analysis of the audio. Scores typically range from 0 to 1, with higher values indicating a stronger confidence level in the measured attribute. id: type: string description: Identifier for a Chat Event. Formatted as a UUID. message_text: type: - string - 'null' description: >- The text of the Chat Event. This field contains the message content for each event type listed in the `type` field. metadata: type: - string - 'null' description: Stringified JSON with additional metadata about the chat event. related_event_id: type: - string - 'null' description: >- Identifier for a related chat event. Currently only seen on ASSISTANT_PROSODY events, to point back to the ASSISTANT_MESSAGE that generated these prosody scores role: $ref: '#/components/schemas/ReturnChatEventRole' timestamp: type: integer format: int64 description: Time at which the Chat Event occurred. Measured in seconds since the Unix epoch. type: $ref: '#/components/schemas/ReturnChatEventType' required: - chat_id - id - role - timestamp - type description: A description of a single event in a chat returned from the server title: return_chat_event ReturnChatPagedEventsPaginationDirection: type: string enum: - ASC - DESC title: ReturnChatPagedEventsPaginationDirection ReturnChatPagedEventsStatus: type: string enum: - ACTIVE - USER_ENDED - USER_TIMEOUT - MAX_DURATION_TIMEOUT - INACTIVITY_TIMEOUT - ERROR title: ReturnChatPagedEventsStatus return_chat_paged_events: type: object properties: chat_group_id: type: string description: >- Identifier for the Chat Group. Any chat resumed from this Chat will have the same `chat_group_id`. Formatted as a UUID. config: $ref: '#/components/schemas/return_config_spec' end_timestamp: type: - integer - 'null' format: int64 description: Time at which the Chat ended. Measured in seconds since the Unix epoch. events_page: type: array items: $ref: '#/components/schemas/return_chat_event' description: List of Chat Events for the specified `page_number` and `page_size`. id: type: string description: Identifier for a Chat. Formatted as a UUID. metadata: type: - string - 'null' description: Stringified JSON with additional metadata about the chat. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnChatPagedEventsPaginationDirection' start_timestamp: type: integer format: int64 description: Time at which the Chat started. Measured in seconds since the Unix epoch. status: $ref: '#/components/schemas/ReturnChatPagedEventsStatus' total_pages: type: integer description: The total number of pages in the collection. required: - chat_group_id - events_page - id - page_number - page_size - pagination_direction - start_timestamp - status - total_pages description: A description of chat status with a paginated list of chat events returned from the server title: return_chat_paged_events ReturnChatAudioReconstructionStatus: type: string enum: - QUEUED - IN_PROGRESS - COMPLETE - ERROR - CANCELLED title: ReturnChatAudioReconstructionStatus ReturnChatAudioReconstruction: type: object properties: filename: type: - string - 'null' description: Name of the chat audio reconstruction file. id: type: string description: Identifier for the chat. Formatted as a UUID. modified_at: type: - integer - 'null' format: int64 description: >- The timestamp of the most recent status change for this audio reconstruction, formatted milliseconds since the Unix epoch. signed_audio_url: type: - string - 'null' description: Signed URL used to download the chat audio reconstruction file. signed_url_expiration_timestamp_millis: type: - integer - 'null' format: int64 description: The timestamp when the signed URL will expire, formatted as a Unix epoch milliseconds. status: $ref: '#/components/schemas/ReturnChatAudioReconstructionStatus' user_id: type: string description: Identifier for the user that owns this chat. Formatted as a UUID. required: - id - status - user_id description: List of chat audio reconstructions returned for the specified page number and page size. title: ReturnChatAudioReconstruction return_chat_group: type: object properties: active: type: boolean first_start_timestamp: type: integer format: int64 description: Time at which the first Chat in this Chat Group was created. Measured in seconds since the Unix epoch. id: type: string description: >- Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID. most_recent_chat_id: type: - string - 'null' description: The `chat_id` of the most recent Chat in this Chat Group. Formatted as a UUID. most_recent_config: $ref: '#/components/schemas/return_config_spec' most_recent_start_timestamp: type: integer format: int64 description: Time at which the most recent Chat in this Chat Group was created. Measured in seconds since the Unix epoch. num_chats: type: integer description: The total number of Chats associated with this Chat Group. required: - first_start_timestamp - id - most_recent_start_timestamp - num_chats description: A description of chat_group and its status title: return_chat_group ReturnPagedChatGroupsPaginationDirection: type: string enum: - ASC - DESC title: ReturnPagedChatGroupsPaginationDirection return_paged_chat_groups: type: object properties: chat_groups_page: type: array items: $ref: '#/components/schemas/return_chat_group' description: List of Chat Groups and their metadata returned for the specified `page_number` and `page_size`. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnPagedChatGroupsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. required: - chat_groups_page - page_number - page_size - pagination_direction - total_pages description: A paginated list of chat_groups returned from the server title: return_paged_chat_groups ReturnChatGroupPagedChatsPaginationDirection: type: string enum: - ASC - DESC title: ReturnChatGroupPagedChatsPaginationDirection return_chat_group_paged_chats: type: object properties: active: type: boolean chats_page: type: array items: $ref: '#/components/schemas/return_chat' description: List of Chats and their metadata returned for the specified `page_number` and `page_size`. first_start_timestamp: type: integer format: int64 description: Time at which the first Chat in this Chat Group was created. Measured in seconds since the Unix epoch. id: type: string description: >- Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID. most_recent_start_timestamp: type: integer format: int64 description: Time at which the most recent Chat in this Chat Group was created. Measured in seconds since the Unix epoch. num_chats: type: integer description: The total number of Chats associated with this Chat Group. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnChatGroupPagedChatsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. required: - chats_page - first_start_timestamp - id - most_recent_start_timestamp - num_chats - page_number - page_size - pagination_direction - total_pages description: A description of chat_group and its status with a paginated list of each chat in the chat_group title: return_chat_group_paged_chats ReturnChatGroupPagedAudioReconstructionsPaginationDirection: type: string enum: - ASC - DESC title: ReturnChatGroupPagedAudioReconstructionsPaginationDirection return_chat_group_paged_audio_reconstructions: type: object properties: audio_reconstructions_page: type: array items: $ref: '#/components/schemas/ReturnChatAudioReconstruction' description: List of chat audio reconstructions returned for the specified page number and page size. id: type: string description: Identifier for the chat group. Formatted as a UUID. num_chats: type: integer description: Total number of chats in this chatgroup page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnChatGroupPagedAudioReconstructionsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. user_id: type: string description: Identifier for the user that owns this chat. Formatted as a UUID. required: - audio_reconstructions_page - id - num_chats - page_number - page_size - pagination_direction - total_pages - user_id description: A paginated list of chat reconstructions for a particular chatgroup title: return_chat_group_paged_audio_reconstructions ReturnChatGroupPagedEventsPaginationDirection: type: string enum: - ASC - DESC title: ReturnChatGroupPagedEventsPaginationDirection return_chat_group_paged_events: type: object properties: events_page: type: array items: $ref: '#/components/schemas/return_chat_event' description: List of Chat Events for the specified `page_number` and `page_size`. id: type: string description: >- Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID. page_number: type: integer description: >- The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing. page_size: type: integer description: |- The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request. pagination_direction: $ref: '#/components/schemas/ReturnChatGroupPagedEventsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. required: - events_page - id - page_number - page_size - pagination_direction - total_pages description: A paginated list of chat events that occurred across chats in this chat_group from the server title: return_chat_group_paged_events WebhookEventChatStatus: type: string enum: - ACTIVE - USER_ENDED - USER_TIMEOUT - INACTIVITY_TIMEOUT - MAX_DURATION_TIMEOUT - SILENCE_TIMEOUT - ERROR title: WebhookEventChatStatus WebhookEventChatEnded: type: object properties: chat_group_id: type: string description: Unique ID of the **Chat Group** associated with the **Chat** session. chat_id: type: string description: Unique ID of the **Chat** session. config_id: type: - string - 'null' description: Unique ID of the EVI **Config** used for the session. caller_number: type: - string - 'null' description: >- Phone number of the caller in E.164 format (e.g., `+12223333333`). This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. custom_session_id: type: - string - 'null' description: >- User-defined session ID. Relevant only when employing a [custom language model](/docs/empathic-voice-interface-evi/custom-language-model) in the EVI Config. duration_seconds: type: integer description: Total duration of the session in seconds. end_reason: $ref: '#/components/schemas/WebhookEventChatStatus' description: Reason for the session's termination. end_time: type: integer description: Unix timestamp (in milliseconds) indicating when the session ended. event_name: type: string enum: - chat_ended description: Always `chat_ended`. twilio_metadata: type: - object - 'null' additionalProperties: type: string description: >- Twilio metadata associated with the chat. This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. Fields may include `call_sid`, `account_sid`, `from_number`, `to_number`, `caller_name`, `caller_number`, `from_city`, `from_state`, `from_zip`, `from_country`, `to_city`, `to_state`, `to_zip`, and `to_country`.If a specific metadata is not available, this field will be set to an empty string. required: - chat_group_id - chat_id - config_id - caller_number - custom_session_id - duration_seconds - end_reason - end_time - twilio_metadata title: WebhookEventChatEnded WebhookEventChatStartType: type: string enum: - new_chat_group - resumed_chat_group title: WebhookEventChatStartType WebhookEventChatStarted: type: object properties: chat_group_id: type: string description: Unique ID of the **Chat Group** associated with the **Chat** session. chat_id: type: string description: Unique ID of the **Chat** session. config_id: type: - string - 'null' description: Unique ID of the EVI **Config** used for the session. caller_number: type: - string - 'null' description: >- Phone number of the caller in E.164 format (e.g., `+12223333333`). This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. chat_start_type: $ref: '#/components/schemas/WebhookEventChatStartType' description: >- Indicates whether the chat is the first in a new Chat Group (`new_chat_group`) or the continuation of an existing chat group (`resumed_chat_group`). custom_session_id: type: - string - 'null' description: >- User-defined session ID. Relevant only when employing a [custom language model](/docs/empathic-voice-interface-evi/custom-language-model) in the EVI Config. event_name: type: string enum: - chat_started description: Always `chat_started`. start_time: type: integer description: Unix timestamp (in milliseconds) indicating when the session started. twilio_metadata: type: - object - 'null' additionalProperties: type: string description: >- Twilio metadata associated with the chat. This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. Fields may include `call_sid`, `account_sid`, `from_number`, `to_number`, `caller_name`, `caller_number`, `from_city`, `from_state`, `from_zip`, `from_country`, `to_city`, `to_state`, `to_zip`, and `to_country`. If a specific metadata is not available, this field will be set to an empty string. required: - chat_group_id - chat_id - config_id - caller_number - chat_start_type - custom_session_id - start_time - twilio_metadata title: WebhookEventChatStarted ToolCallMessage: type: object properties: custom_session_id: type: - string - 'null' description: >- Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions. name: type: string description: Name of the tool called. parameters: type: string description: >- Parameters of the tool. These parameters define the inputs needed for the tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the tool receives data in the expected format. response_required: type: boolean description: >- Indicates whether a response to the tool call is required from the developer, either in the form of a [Tool Response message](/reference/empathic-voice-interface-evi/chat/chat#send.Tool%20Response%20Message.type) or a [Tool Error message](/reference/empathic-voice-interface-evi/chat/chat#send.Tool%20Error%20Message.type). tool_call_id: type: string description: >- The unique identifier for a specific tool call instance. This ID is used to track the request and response of a particular tool invocation, ensuring that the correct response is linked to the appropriate request. tool_type: $ref: '#/components/schemas/ToolType' description: >- Type of tool called. Either `builtin` for natively implemented tools, like web search, or `function` for user-defined tools. type: type: string enum: - tool_call description: |- The type of message sent through the socket; for a Tool Call message, this must be `tool_call`. This message indicates that the supplemental LLM has detected a need to invoke the specified tool. required: - name - parameters - response_required - tool_call_id - tool_type - type description: >- **Indicates that the supplemental LLM has detected a need to invoke the specified tool.** This message is only received for user-defined function tools. Contains the tool name, parameters (as a stringified JSON schema), whether a response is required from the developer (either in the form of a `ToolResponseMessage` or a `ToolErrorMessage`), the unique tool call ID for tracking the request and response, and the tool type. See our [Tool Use Guide](/docs/speech-to-speech-evi/features/tool-use) for further details. title: ToolCallMessage WebhookEventToolCall: type: object properties: chat_group_id: type: string description: Unique ID of the **Chat Group** associated with the **Chat** session. chat_id: type: string description: Unique ID of the **Chat** session. config_id: type: - string - 'null' description: Unique ID of the EVI **Config** used for the session. caller_number: type: - string - 'null' description: >- Phone number of the caller in E.164 format (e.g., `+12223333333`). This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. custom_session_id: type: - string - 'null' description: >- User-defined session ID. Relevant only when employing a [custom language model](/docs/empathic-voice-interface-evi/custom-language-model) in the EVI Config. event_name: type: string enum: - tool_call description: Always `tool_call`. timestamp: type: integer description: Unix timestamp (in milliseconds) indicating when the tool call was triggered. tool_call_message: $ref: '#/components/schemas/ToolCallMessage' description: The tool call. twilio_metadata: type: - object - 'null' additionalProperties: type: string description: >- Twilio metadata associated with the chat. This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. Fields may include `call_sid`, `account_sid`, `from_number`, `to_number`, `caller_name`, `caller_number`, `from_city`, `from_state`, `from_zip`, `from_country`, `to_city`, `to_state`, `to_zip`, and `to_country`.If a specific metadata is not available, this field will be set to an empty string. required: - chat_group_id - chat_id - config_id - caller_number - custom_session_id - timestamp - tool_call_message - twilio_metadata title: WebhookEventToolCall securitySchemes: bearerAuth: type: apiKey in: header name: X-Hume-Api-Key