---
title: "Create Conversation From Segments"
method: POST
path: "/v1/dev/user/conversations/from-segments"
tags: ["Conversations"]
---

# Create Conversation From Segments

`POST /v1/dev/user/conversations/from-segments`

Create a new conversation from structured transcript segments.

This endpoint is for advanced integrations that have speaker diarization and timing information.
It processes the transcript segments through the full conversation pipeline.

**Transcript Segments:**
- **text**: The text spoken (required)
- **speaker**: Speaker identifier like 'SPEAKER_00', 'SPEAKER_01' (default: 'SPEAKER_00')
- **speaker_id**: Numeric speaker ID (auto-calculated from speaker if not provided)
- **is_user**: Whether this segment is from the user (default: False)
- **person_id**: ID of known person speaking (optional)
- **start**: Start time in seconds, e.g., 0.0, 1.5, 60.2 (required)
- **end**: End time in seconds, e.g., 1.5, 3.0, 65.8 (required)

**Other Parameters:**
- **source**: Source of conversation (default: external_integration). Options:
  - omi, friend, openglass, phone, desktop, apple_watch, bee, plaud, frame, etc.
- **started_at**: When conversation started (defaults to now)
- **finished_at**: When conversation finished (calculated from last segment if not provided)
- **language**: Language code (default: 'en')
- **geolocation**: Optional geolocation data

**Example:**
```json
{
  "transcript_segments": [
    {
      "text": "Hey, how are you doing?",
      "speaker": "SPEAKER_00",
      "is_user": true,
      "start": 0.0,
      "end": 2.5
    },
    {
      "text": "I'm doing great, thanks!",
      "speaker": "SPEAKER_01",
      "is_user": false,
      "start": 2.8,
      "end": 5.2
    }
  ],
  "source": "phone",
  "language": "en"
}
```

## Request body

- CreateConversationFromTranscriptRequest
  - `client_device_id` string, nullable — Capture device id ({platform}_{hash})
  - `client_platform` string, nullable — Client platform (ios/android/macos)
  - `client_session_id` string, nullable — Stable client-generated session ID. When provided, retries return the same conversation ID.
  - `conversation_finalization_reason` 'user_stop' | 'finish_and_continue' | 'meeting_started' | 'meeting_ended' | 'max_duration_rotation' | 'crash_recovery' | 'retry', nullable
  - `conversation_role` 'ambient' | 'meeting'
  - `finished_at` string, date-time, nullable — When conversation finished (calculated from segments duration if not provided)
  - `geolocation` GeolocationInput — Released wire contract for coordinates accepted at legacy API boundaries. Bounds are enforced before any value is cached, geocoded, or persisted. Keeping this transport shape broad preserves clients released before the bound contract existed, while ``Geolocation`` remains the only usable server-side value.
    - `address` string, nullable
    - `google_place_id` string, nullable
    - `latitude` number, required
    - `location_type` string, nullable
    - `longitude` number, required
  - `language` string, nullable — Language code (ISO 639-1, e.g., 'en', 'es', 'fr')
  - `source` 'friend' | 'omi' | 'fieldy' | 'bee' | 'plaud' | 'frame' | 'friend_com' | 'apple_watch' | 'phone' | 'phone_call' | 'desktop' | 'openglass' | 'screenpipe' | 'workflow' | 'sdcard' | 'external_integration' | 'limitless' | 'rayban_meta' | 'onboarding' | 'unknown'
  - `started_at` string, date-time, nullable — When conversation started (defaults to now)
  - `transcript_segments` CreateConversationTranscriptSegment[], required — List of transcript segments with speaker and timing info
    - `end` number, required — End time in seconds (e.g., 1.5, 3.0, 65.8)
    - `is_user` boolean — Whether this segment is from the user
    - `person_id` string, nullable — ID of person speaking (if known)
    - `speaker` string, nullable — Speaker identifier (e.g., 'SPEAKER_00', 'SPEAKER_01')
    - `speaker_id` integer, nullable — Numeric speaker ID
    - `start` number, required — Start time in seconds (e.g., 0.0, 1.5, 60.2)
    - `text` string, required — The text spoken in this segment

## Response `200`

Successful Response

- ConversationCreateResponse
  - `discarded` boolean, required
  - `id` string, required
  - `meeting_treatment_eligible` boolean
  - `status` string, required

## Other responses

- `401` — Missing or invalid authentication credentials.
- `403` — Authenticated, but the token does not grant the required scope.
- `422` — Validation Error

## Changes

- **2026-08-18** `537f1535cc5c` — 1 info
  - added the optional property `meeting_treatment_eligible` to the response with the `200` status
- **2026-08-13** `b092aceb2604` — 2 info
  - added the new optional request property `conversation_finalization_reason`
  - added the new optional request property `conversation_role`
- **2026-07-26** `0060a2464242` — 1 breaking, 1 info
  - removed `#/components/schemas/Geolocation` from the `geolocation` request property `anyOf` list
  - added `#/components/schemas/GeolocationInput` to the `geolocation` request property `anyOf` list
- **2026-07-26** `ede7f7162d63` — 4 warning
  - the `geolocation/anyOf[subschema #1: Geolocation]/latitude` request property's max was set to `90.00`
  - the `geolocation/anyOf[subschema #1: Geolocation]/longitude` request property's max was set to `180.00`
  - the `geolocation/anyOf[subschema #1: Geolocation]/latitude` request property's min was set to `-90.00`
  - the `geolocation/anyOf[subschema #1: Geolocation]/longitude` request property's min was set to `-180.00`
- **2026-07-08** `03ec726f36eb` — 1 info
  - added the new `rayban_meta` enum value to the request property `source/anyOf[subschema #1: ConversationSource]/`

[Full history](https://skmtc.dev/basedhardware/apis/omi-developer-api/changes/v1/dev/user/conversations/from-segments/post.md)

---

[API](https://skmtc.dev/basedhardware/apis/omi-developer-api.md) · [All operations](https://skmtc.dev/basedhardware/apis/omi-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/basedhardware/omi-developer-api/revisions/3add0ce9bc4f/schema)