---
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.
  - `finished_at` string, date-time, nullable — When conversation finished (calculated from segments duration if not provided)
  - `geolocation` Geolocation
    - `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' | '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
  - `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-06-30** `fbfe4956e141` — 2 warning
  - removed the optional property `detail/items/ctx` from the response with the `422` status
  - removed the optional property `detail/items/input` from the response with the `422` status
- **2026-06-30** `c2ab717efdbc` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-06-30** `fbfe4956e141` — 2 warning
  - removed the optional property `detail/items/ctx` from the response with the `422` status
  - removed the optional property `detail/items/input` from the response with the `422` status
- **2026-06-30** `c2ab717efdbc` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-06-30** `fbfe4956e141` — 2 warning
  - removed the optional property `detail/items/ctx` from the response with the `422` status
  - removed the optional property `detail/items/input` from the response with the `422` status

[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/fbfe4956e141/schema)