---
title: "Import Conversations"
method: POST
path: "/core/conversations/import"
tags: ["Conversations"]
---

# Import Conversations

`POST /core/conversations/import`

## Request

- Base URL: `https://api.anyreach.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.anyreach.ai/core/conversations/import`
- Auth: HTTP bearer

Import historical conversations into the database (no dispatch side-effects).

This endpoint is intended for bulk CSV/ETL loads. It only inserts rows in the
`conversations` table and stores transcripts in the `conversation` JSON field.

## Headers

- `x-anyreach-org` string, nullable: Organization ID for user PATs (pat_ prefix tokens)

## Request body

- ConversationImportRequest
  - `conversations` ConversationImportItem[], required
    - `channel` 'telephone' | 'webrtc' | 'email' | 'text' | 'webchat', required: Channel type for the conversation.
    - `user_id` string, required
    - `direction` 'inbound' | 'outbound', required: Direction of the conversation.
    - `agent_config` AgentConfig: Top-level agent configuration.
      - `version` '1'
      - `agent` StaticPromptAgent, required: Static prompt configuration.
        - `type` 'static_prompt'
        - `instructions` string
        - `starting_message` union, required
          - UserInitiatesMessage: User initiates starting message configuration.
            - `type` 'user_initiates'
            - `action_grid` StartingActionGrid: Optional action grid shown alongside the starting message (chat UI). Rendered on WebRTC sessions as a grid of quick-action buttons. Each item's ``label`` is sent back verbatim as the action value when the user taps it.
              - …
          - BotInitiatesStaticMessage: Bot initiates static starting message configuration.
            - `type` 'bot_initiates_static'
            - `text` string, required
            - `literal` boolean: Say the text exactly as written, without rendering it as a template. Set on text that holds values from outside the agent config, such as a web widget's conversation starters.
            - `allow_interruptions` boolean
            - `action_grid` StartingActionGrid: Optional action grid shown alongside the starting message (chat UI). Rendered on WebRTC sessions as a grid of quick-action buttons. Each item's ``label`` is sent back verbatim as the action value when the user taps it.
              - …
            - `pregenerated_greeting_audio` boolean: When true, the agent looks up a pre-generated recording of this greeting — synthesized once with the configured TTS voice and stored in the recording S3 bucket, content-addressed over ``text`` + the full TTS config — and plays it instead of synthesizing ``text`` with TTS on every conversation. Useful for truly-static greetings (e.g. inbound) where the same opening line is spoken every time. The recording is keyed by a fingerprint the runtime recomputes from the rendered text + TTS config, so if no recording matches (e.g. the text was edited but not regenerated, or the voice changed) the agent transparently falls back to live TTS. Only meaningful for non-templated ``text``; the builder pre-generates the recording.
          - BotInitiatesDynamicMessage: Bot initiates dynamic starting message configuration.
            - `type` 'bot_initiates_dynamic'
            - `prompt` string, required
            - `allow_interruptions` boolean
            - `action_grid` StartingActionGrid: Optional action grid shown alongside the starting message (chat UI). Rendered on WebRTC sessions as a grid of quick-action buttons. Each item's ``label`` is sent back verbatim as the action value when the user taps it.
              - …
        - `tools` ToolCall[], required
          - `name` string, required
          - `description` string, required
          - `properties` object
          - `required` string[]
          - `actions` union[], required
            - union
              - …
          - `actions_on_error` union[]
            - union
              - …
          - `output` string, nullable
          - `skip_reply` string, nullable: Jinja expression evaluated after the tool finishes, whether its actions succeeded, failed or the identity gate refused it. True means the model writes no reply to this call. Reads arguments, data, steps, error (the failure's message or None) and refused (the refusal text or None). When the model calls several tools at once, the reply is skipped only if every one of them skips it
          - `requires_verified_identity` RequiresVerifiedIdentity: Gate a tool on a non-expired verified identity.
            - `subject_type` string, required
            - `methods` string[], nullable: Accepted verification methods; any method when omitted
            - `unverified_result` string, nullable: Jinja template the model gets instead of the default refusal
        - `built_in_tools` BuiltInTools: Configuration for platform built-in tools.
          - `time_tool` TimeToolConfig: Configuration for the get_current_time built-in tool.
            - `default_timezone` string, nullable: Default IANA timezone name (e.g., 'America/New_York'). Falls back to UTC if not provided.
          - `widgets` WidgetsConfig: Configuration for widget tools.
            - `allowed` WidgetType[], nullable: List of allowed widget types. If None/omitted, ALL widget types are enabled.
          - `forms` FormsConfig: Configuration for data-collection form tools shown during conversations.
            - `forms` FormDefinition[], required: Data-collection forms that can be shown as widgets during conversations.
              - …
          - `web_search` WebSearchToolConfig: Configuration for the web_search built-in tool.
          - `retrieve_webpage` RetrieveWebpageToolConfig: Configuration for the retrieve_webpage built-in tool.
          - `continue_on_phone` ContinueOnPhoneToolConfig: Configuration for the continue_on_phone built-in tool.
            - `agent_id` string, nullable: Agent to use for the phone call. Falls back to the current agent if not set.
            - `version` integer, nullable: Specific agent version number. Only used with agent_id. Uses latest published if not set.
            - `agent_number` string, nullable: E.164 phone number to call FROM. Falls back to the number assigned to the agent if not set.
          - `images` ImagesToolConfig: Configuration for the images built-in tool suite (analyze_image / list_images). `images: {}` (an empty object) enables the cheap default: floor schema only, fast tier, uploads allowed. `None` means the feature is off.
            - `routes` ImageTypeRoute[]
              - …
            - `default_tier` string
            - `tiers` ImageTierConfig: Override of the platform tier ladder. Each slot holds one resolved provider.
              - …
            - `max_escalations_per_conversation` integer
            - `max_analyses_per_conversation` integer
            - `allow_user_uploads` boolean
            - `floor_overrides` object, nullable
            - `pii_fields` string[]
            - `on_blocked` 'refuse' | 'flag'
          - `cart` CartToolConfig: Lets the agent add to, change and open the shopper's cart on the website, through the web widget. Platform- neutral: the widget's own ``v1.cart`` switch decides whether a site carries the actions out, and the embed loader's adapter for the store's platform (Shopify today) does them.
            - `max_quantity_per_line` integer: The most of one item the agent can add or set in one call.
            - `action_timeout_seconds` number: How long the agent waits for the shopper's browser to confirm.
        - `language` AgentLanguage: Agent language configuration.
          - `languages` string[], required
        - `stack` union, required
          - SttLlmTtsStack: STT-LLM-TTS stack configuration.
            - `type` 'stt_llm_tts'
            - `turn_detection` TurnDetection, required: Turn Detection configuration.
              - …
            - `stt` Stt, required: STT configuration.
              - …
            - `llm` Llm, required: LLM configuration.
              - …
            - `tts` Tts, required: TTS configuration.
              - …
            - `vad` Vad: VAD configuration.
              - …
            - `vision_llm` VisionLlm: Vision LLM for processing video frames.
              - …
            - `interruption` InterruptionConfig: Interruption handling configuration.
              - …
            - `endpointing` EndpointingConfig: Endpointing configuration.
              - …
            - `text_normalization` TextNormalizationConfig: Text normalization applied to LLM output before TTS.
              - …
          - RealtimeStack: Realtime stack configuration.
            - `type` 'realtime'
            - `llm` Llm, required: LLM configuration.
              - …
            - `turn_detection` TurnDetection: Turn Detection configuration.
              - …
            - `stt` Stt: STT configuration.
              - …
            - `vad` Vad: VAD configuration.
              - …
            - `vision_llm` VisionLlm: Vision LLM for processing video frames.
              - …
        - `allow_interruptions` boolean, nullable
        - `video_input` boolean, nullable
        - `screen_share_input` boolean, nullable
        - `max_tool_steps` integer, nullable: Maximum number of tool invocations per conversation turn. Defaults to 3 if not specified.
        - `channel_overrides` object, nullable: Group 1 — per-channel LLM steering (append/replace instructions, greeting, tool budget).
        - `channel_properties` object, nullable: Group 2 — per-channel transport/presentation (body template, segments, subject, signature, enabled).
      - `metadata` object, nullable
      - `noise_cancellation` NoiseCancellation: Noise cancellation configuration.
        - `models` LivekitProvider[], required
          - `provider` 'livekit'
          - `model` union, required
            - LivekitBVCModel: LiveKit BVC model configuration.
              - …
            - LivekitBVCTelephonyModel: LiveKit BVC Telephony model configuration.
              - …
      - `custom_recording_locations` union[], nullable
        - union
          - S3RecordingLocation: S3 recording location provider.
            - `provider` 's3'
            - `bucket` string, required
            - `region` string, required
            - `access_key` string, required
            - `secret_access_key` string, required
            - `file_type` 'ogg' | 'mp4'
          - GcpRecordingLocation: GCP recording location provider.
            - `provider` 'gcp'
            - `bucket` string, required
            - `credentials` string, required
            - `file_type` 'ogg' | 'mp4'
          - AzureRecordingLocation: Azure recording location provider.
            - `provider` 'azure'
            - `container_name` string, required
            - `account_name` string, required
            - `account_key` string, required
            - `file_type` 'ogg' | 'mp4'
      - `pre_conversation_workflow` WorkflowAction
        - `id` string, nullable: Name of this action's result in steps (steps.<id>). Defaults to its position counted from 1: steps.1, steps.2, … and steps.on_error_1, … in Actions on Error
        - `type` 'workflow'
        - `workflow_id` string, nullable
        - `workflow_version` integer, nullable
        - `initial_step` string, nullable
        - `definition` object, nullable: Inline workflow definition (mutually exclusive with workflow_id/workflow_version)
        - `condition` string, nullable
        - `reject_on_error` boolean: If true, abort the conversation when the workflow fails
        - `verifies_identity` VerifiesIdentity: Marks a workflow as an identity verifier: the only writer of ``verified_identities``; its ``custom_metadata`` output is never saved.
          - `subject_type` string, required
          - `output_schema` object, nullable: JSON Schema checked against {"identifiers": ..., "attributes": ...}
          - `ttl` integer: How long a verification stays valid; at most 7 days
          - `lockout` VerifierLockout: Per-conversation limit on a verifier tool's rejected attempts.
            - `max_failures` integer: Rejected tool-trigger attempts in one conversation before the verifier locks
        - `input_exclude` string[], nullable: Conversation parts left out of the workflow's input: agent_instructions, transcript, tool_outputs, transcript_internals. Unset sends everything
        - `include_page_view` boolean: Web chat with page context: add what was on the visitor's screen when they sent their latest message (conversation_metadata.page_view), if it was read. Off sends only where each message was sent from.
      - `identity_verifiers` IdentityVerifier[]
        - `id` string, nullable: Name of this action's result in steps (steps.<id>). Defaults to its position counted from 1: steps.1, steps.2, … and steps.on_error_1, … in Actions on Error
        - `type` 'workflow'
        - `workflow_id` string, nullable
        - `workflow_version` integer, nullable
        - `initial_step` string, nullable
        - `definition` object, nullable: Inline workflow definition (mutually exclusive with workflow_id/workflow_version)
        - `condition` string, nullable
        - `reject_on_error` boolean: If true, abort the conversation when the workflow fails
        - `verifies_identity` VerifiesIdentity: Marks a workflow as an identity verifier: the only writer of ``verified_identities``; its ``custom_metadata`` output is never saved.
          - `subject_type` string, required
          - `output_schema` object, nullable: JSON Schema checked against {"identifiers": ..., "attributes": ...}
          - `ttl` integer: How long a verification stays valid; at most 7 days
          - `lockout` VerifierLockout: Per-conversation limit on a verifier tool's rejected attempts.
            - `max_failures` integer: Rejected tool-trigger attempts in one conversation before the verifier locks
        - `input_exclude` string[], nullable: Conversation parts left out of the workflow's input: agent_instructions, transcript, tool_outputs, transcript_internals. Unset sends everything
        - `include_page_view` boolean: Web chat with page context: add what was on the visitor's screen when they sent their latest message (conversation_metadata.page_view), if it was read. Off sends only where each message was sent from.
        - `timing` 'background' | 'before_start': Conversation start only: before the greeting, or alongside it
      - `post_conversation_workflow` WorkflowAction
        - `id` string, nullable: Name of this action's result in steps (steps.<id>). Defaults to its position counted from 1: steps.1, steps.2, … and steps.on_error_1, … in Actions on Error
        - `type` 'workflow'
        - `workflow_id` string, nullable
        - `workflow_version` integer, nullable
        - `initial_step` string, nullable
        - `definition` object, nullable: Inline workflow definition (mutually exclusive with workflow_id/workflow_version)
        - `condition` string, nullable
        - `reject_on_error` boolean: If true, abort the conversation when the workflow fails
        - `verifies_identity` VerifiesIdentity: Marks a workflow as an identity verifier: the only writer of ``verified_identities``; its ``custom_metadata`` output is never saved.
          - `subject_type` string, required
          - `output_schema` object, nullable: JSON Schema checked against {"identifiers": ..., "attributes": ...}
          - `ttl` integer: How long a verification stays valid; at most 7 days
          - `lockout` VerifierLockout: Per-conversation limit on a verifier tool's rejected attempts.
            - `max_failures` integer: Rejected tool-trigger attempts in one conversation before the verifier locks
        - `input_exclude` string[], nullable: Conversation parts left out of the workflow's input: agent_instructions, transcript, tool_outputs, transcript_internals. Unset sends everything
        - `include_page_view` boolean: Web chat with page context: add what was on the visitor's screen when they sent their latest message (conversation_metadata.page_view), if it was read. Off sends only where each message was sent from.
      - `extraction_workflow` WorkflowAction
        - `id` string, nullable: Name of this action's result in steps (steps.<id>). Defaults to its position counted from 1: steps.1, steps.2, … and steps.on_error_1, … in Actions on Error
        - `type` 'workflow'
        - `workflow_id` string, nullable
        - `workflow_version` integer, nullable
        - `initial_step` string, nullable
        - `definition` object, nullable: Inline workflow definition (mutually exclusive with workflow_id/workflow_version)
        - `condition` string, nullable
        - `reject_on_error` boolean: If true, abort the conversation when the workflow fails
        - `verifies_identity` VerifiesIdentity: Marks a workflow as an identity verifier: the only writer of ``verified_identities``; its ``custom_metadata`` output is never saved.
          - `subject_type` string, required
          - `output_schema` object, nullable: JSON Schema checked against {"identifiers": ..., "attributes": ...}
          - `ttl` integer: How long a verification stays valid; at most 7 days
          - `lockout` VerifierLockout: Per-conversation limit on a verifier tool's rejected attempts.
            - `max_failures` integer: Rejected tool-trigger attempts in one conversation before the verifier locks
        - `input_exclude` string[], nullable: Conversation parts left out of the workflow's input: agent_instructions, transcript, tool_outputs, transcript_internals. Unset sends everything
        - `include_page_view` boolean: Web chat with page context: add what was on the visitor's screen when they sent their latest message (conversation_metadata.page_view), if it was read. Off sends only where each message was sent from.
      - `on_idle` OnIdleConfig: Where a quiet conversation is filed in the helpdesk (the idle archive). The same actions, conditions and ``steps`` as a tool, with no ``arguments``: no model called anything. Workflows run in order, and the first ``handoff`` whose condition holds and which has a connection on this channel is the route; nothing after it runs. None holding means the conversation is not filed. Of a ``handoff`` only the route and the condition apply: an archive says nothing to the customer. See ``services/handoff_archive.py``.
        - `actions` union[], required
          - union
            - WorkflowAction
              - …
            - HandoffAction: Hand this conversation to a human, as an action on any config tool. This is the ONLY way to define an escalation — there is no built-in handoff tool, exactly as there is no built-in cold transfer. The reason is routing: with Gladly the entry point + group IS the queue, so a support desk with billing / returns / technical needs one rule each. Domain-named tools (``escalate_billing_dispute``) also make the model markedly better at choosing than one generic tool plus a free-text reason. Everything here is per-ROUTE. Everything that belongs to the helpdesk rather than the route — the credentials, how long it takes to answer, what context it wants — lives on the ``handoff_connections`` row and is folded in by ``handoff_intent.resolve_handoff_action_config``. The split test is simply whether the value depends on the helpdesk or on this particular escalation. Customer-facing copy is deliberately here and not on the connection: it is spoken in the agent's voice and language, and one connection is shared by every agent in the org. ``custom_channel_id`` is rarely set. In Gladly a custom channel CONTAINS entry points, so queues under one channel share its id and only the entry point address varies; it exists for the one-channel-per-queue topology. The route fields above are the DEFAULT route. ``channels`` overrides them per channel, because a helpdesk generally exposes chat and email as separate integrations: same escalation, same description the model routes on, two destinations. Nothing else is per-channel — the copy is spoken in the agent's voice regardless of the medium. Like every other action this records INTENT and returns; the runtime opens the handoff at its own boundary. Nothing here raises across layers.
              - …
      - `scorecard_ids` string[], nullable
      - `voicemail_detection` VoicemailDetectionConfig: Configuration for voicemail detection and response behavior.
        - `beep_detection_threshold` number, required: Confidence threshold (0.0-1.0) for background beep detection. Having above 0.95 yields better result
        - `beep_detection_timeout` integer, required: Max seconds to run background beep detection
        - `tool_call_overrides` VoicemailToolCallOverrides: Overrides for voicemail tool-call based detection and prompt handling. If not provided, then the default values will be used. beep_detection_threshold: 0.9 beep_detection_timeout: 10 name: voicemail_detected description: whenever you hear 'you have reached a voicemail'
          - `beep_detection_threshold` number: Confidence threshold (0.0-1.0) for beep after voice prompt
          - `beep_detection_timeout` integer: Max seconds to wait for beep after voicemail voice prompt
          - `name` string: Tool call function name the LLM can invoke (e.g., 'voicemail_detected')
          - `description` string: Description/when to invoke the tool (e.g., when voicemail greeting is detected)
        - `play_message` VoicemailPlayMessageAction
          - `message` string, required
          - `generate` boolean
      - `inactivity_nudge` InactivityNudgeConfig: Nudge the user on silence, then hang up after the nudges go unanswered. Voice only (telephony + WebRTC voice). Driven by LiveKit's VAD-based ``away`` user state, so it has no effect on text/chat conversations. Always on — there is no enable/disable toggle; tune the timings and nudge copy instead.
        - `timeout_seconds` number: Silence before the first nudge (feeds LiveKit user_away_timeout).
        - `nudge_interval_seconds` number: Delay between nudges, and the final grace period before hangup.
        - `nudges` union[]: Ordered, one per attempt (escalating copy). Hang up after the last.
          - union
            - NudgeStaticMessage: Inactivity nudge spoken as exact text (verbatim via TTS).
              - …
            - NudgeDynamicMessage: Inactivity nudge generated by the LLM from instructions.
              - …
      - `screen_pop` object, nullable: Named links that /<org>/screen-pop/<caller>?target=<name> opens for a human taking over a call from this agent.
    - `agent_version_id` string, nullable
    - `agent_id` string, nullable
    - `agent_number` string, nullable
    - `trunk_id` string, nullable
    - `trunk_config` object, nullable
    - `web_widget_id` string, nullable
    - `duration` integer, nullable
    - `recording_details` RecordingDetail
      - `egress_id` string, required
      - `filepath` string, required
      - `default_location` union, required
        - S3RecordingLocation: S3 recording location provider.
          - `provider` 's3'
          - `bucket` string, required
          - `region` string, required
          - `access_key` string, required
          - `secret_access_key` string, required
          - `file_type` 'ogg' | 'mp4'
        - GcpRecordingLocation: GCP recording location provider.
          - `provider` 'gcp'
          - `bucket` string, required
          - `credentials` string, required
          - `file_type` 'ogg' | 'mp4'
        - AzureRecordingLocation: Azure recording location provider.
          - `provider` 'azure'
          - `container_name` string, required
          - `account_name` string, required
          - `account_key` string, required
          - `file_type` 'ogg' | 'mp4'
      - `custom_locations` union[]
        - union
          - S3RecordingLocation: S3 recording location provider.
            - `provider` 's3'
            - `bucket` string, required
            - `region` string, required
            - `access_key` string, required
            - `secret_access_key` string, required
            - `file_type` 'ogg' | 'mp4'
          - GcpRecordingLocation: GCP recording location provider.
            - `provider` 'gcp'
            - `bucket` string, required
            - `credentials` string, required
            - `file_type` 'ogg' | 'mp4'
          - AzureRecordingLocation: Azure recording location provider.
            - `provider` 'azure'
            - `container_name` string, required
            - `account_name` string, required
            - `account_key` string, required
            - `file_type` 'ogg' | 'mp4'
    - `custom_metadata` object, nullable
    - `conversation` object, nullable: Arbitrary JSON payload; recommended to store transcript here
    - `sip` object, nullable
    - `status` 'token_created' | 'triggered' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'transferred' | 'unanswered': Status of the conversation.
    - `service_version` string
    - `live_transcription_enabled` boolean, nullable

## Response `200`

Successful Response

- ConversationImportResponse
  - `inserted` integer, required
  - `conversation_ids` string[], required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/anyreach/apis/anyreach-api.md) - [All operations](https://skmtc.dev/anyreach/apis/anyreach-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anyreach/apis/anyreach-api/revisions/2eddf40c8c93?raw)