> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ListVoiceWidgetConversationsAPI mirrors erdo_voice_widget_conversation_list.
The optional widget


> handle, the since/until window and paging ride the query string; the organization always comes from the caller's identity. Each row carries the lead the conversation produced: \`contact\` (null = not analysed yet, {} = analysed and nobody reachable, else the visitor's details), \`lead\_status\`, \`lead\_saved\_at\`, and the permanent lead as \`canonical\_lead\_id\` / \`lead\_reference\`. The \`canonical\_lead\_id\` parameter (lead UUID or 22-character reference) narrows to one lead.




## OpenAPI

````yaml /api/openapi.json get /v1/voice/widget-conversations
openapi: 3.0.0
info:
  title: Erdo API
  description: >-
    Erdo's REST API: query and write datasets, run agents, manage threads,
    integrations, pages, evals, workstreams, experiments, and bounded outreach.
    Authenticate with a Bearer API key (erdo_api_...) or scoped token
    (erdo_token_...).
  version: '2026-11-21'
servers:
  - url: https://api.erdo.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/voice/widget-conversations:
    get:
      summary: >
        ListVoiceWidgetConversationsAPI mirrors
        erdo_voice_widget_conversation_list.

        The optional widget
      description: >
        handle, the since/until window and paging ride the query string; the
        organization always comes from the caller's identity. Each row carries
        the lead the conversation produced: \`contact\` (null = not analysed
        yet, {} = analysed and nobody reachable, else the visitor's details),
        \`lead\_status\`, \`lead\_saved\_at\`, and the permanent lead as
        \`canonical\_lead\_id\` / \`lead\_reference\`. The
        \`canonical\_lead\_id\` parameter (lead UUID or 22-character reference)
        narrows to one lead.
      operationId: GET:mcp.ListVoiceWidgetConversationsAPI
      parameters:
        - allowEmptyValue: true
          explode: true
          in: query
          name: widget
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: since
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: until
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: limit
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: offset
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: cursor
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: canonical_lead_id
          required: false
          schema:
            type: string
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  conversations:
                    items:
                      $ref: '#/components/schemas/voice.WidgetConversationSummary'
                    type: array
                  count:
                    format: int64
                    type: integer
                  limit:
                    format: int64
                    type: integer
                  next_cursor:
                    type: string
                  offset:
                    format: int64
                    type: integer
                  public_key:
                    type: string
                  total:
                    description: >
                      request, read in the same snapshot as this page and
                      independent of limit/offset/cursor. It is live: a
                      conversation captured between two page requests changes
                      it, so a walk across pages is complete when next\_cursor
                      is absent, never when the rows collected reach Total. It
                      is what a dashboard tile counts without fetching every
                      row.
                    format: int64
                    title: >
                      Total is how many conversations match the filter at the
                      moment of THIS
                    type: integer
                  turn_metrics_contract_version:
                    format: int64
                    type: integer
                  widget_id:
                    description: >
                      are empty when the list spans the whole organization — the
                      per-row widget fields carry that information instead.
                    title: >
                      WidgetID / WidgetName / PublicKey describe the widget the
                      caller named, and
                    type: string
                  widget_name:
                    type: string
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    voice.WidgetConversationSummary:
      description: >
        metadata and whether a transcript was captured — but never the
        transcript payload itself (the list query never selects
        transcript\_json; TOAST discipline). Each row names its own widget,
        because the list spans every widget in the organization unless the
        caller narrowed it to one.
      properties:
        booked_at:
          description: >
            moment the widget's booking tool (voice, text or video) created the
            calendar event and recorded it — and BookedStart is the slot. Both
            describe the newest such booking. BookedAt is null when nothing was
            booked; BookedStart is also null for a booking whose start the tool
            could not read. The same two fields, meaning the same thing, as the
            call list.
          format: date-time
          title: |
            BookedAt is when a meeting was booked DURING this conversation — the
          type: string
        booked_start:
          format: date-time
          type: string
        canonical_lead_id:
          description: >
            resolved to — the id to match a lead page on, rather than the
            visitor's email or phone. Empty while the conversation awaits its
            write, when the lead dataset is not enrolled in lead identity, when
            capture was off, and on every conversation recorded before
            conversations carried the identity (there is no backfill).
          title: |
            CanonicalLeadID is the permanent lead this conversation's lead write
          type: string
        contact:
          allOf:
            - $ref: '#/components/schemas/leadcontact.Contact'
          description: >
            cron. Deliberately NOT omitempty, for the reason topics is not: null
            means "not analysed yet" and {} means "analysed, nobody reachable",
            and a consumer looking for conversations that produced a lead must
            be able to tell a conversation nobody has read from one that named
            nobody.
          title: >
            Contact is what the visitor gave about themselves, extracted by the
            summary
          nullable: true
        created_at:
          format: date-time
          type: string
        duration_seconds:
          format: int32
          maximum: 2147483647
          minimum: -2147483648
          type: integer
        ended_at:
          format: date-time
          type: string
        has_transcript:
          type: boolean
        lead_reference:
          description: |
            link or an SMS carries; empty exactly when CanonicalLeadID is.
          title: >
            LeadReference is the same identity as a 22-character reference, the
            form a
          type: string
        lead_saved_at:
          format: date-time
          title: |
            LeadSavedAt is when that outcome was recorded, null while awaiting.
          type: string
          nullable: true
        lead_status:
          description: >
            still awaiting one, then created | existing | disabled | refused |
            test.
          title: >
            LeadStatus is what the lead writer did with this conversation: ""
            while it is
          type: string
        modality:
          type: string
        origin:
          type: string
        session_id:
          type: string
        topics:
          description: >
            Deliberately NOT omitempty: null means "not analysed yet" and \[]
            means "analysed, nothing found", and a consumer counting topics must
            be able to tell a conversation nobody has read from one that was
            about nothing.
          items:
            type: string
          title: >
            Topics are what the visitor asked about, extracted by the summary
            cron.
          type: array
          nullable: true
        transcript_summary:
          type: string
        widget:
          description: |
            endpoints, unchanged by a rename.
          title: |
            Widget is the widget's public key — the handle to pass back to these
          type: string
        widget_id:
          type: string
        widget_name:
          type: string
      title: >
        WidgetConversationSummary is one row of a conversation list. It carries
        session
      type: object
    leadcontact.Contact:
      description: >
        dataset has columns for; there is deliberately no company. EmailCheck
        and NameCheck say how the person gave the value beside them (a Check\*
        constant) and EmailAlternative is the other form of the address when the
        person's spelling and what was heard disagree. They are evidence about
        the values, so they travel with the value they describe (Merge) and are
        blank whenever it is. A conversation extracted before they existed
        carries none, which reads as "not recorded", never "unconfirmed".
      properties:
        email:
          type: string
        email_alternative:
          type: string
        email_check:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        name_check:
          type: string
        phone:
          type: string
      title: >
        Contact is what a person told us about themselves. The four value fields
        are the

        ones the leads
      type: object
  responses:
    APIError:
      content:
        application/json:
          schema:
            externalDocs:
              url: https://pkg.go.dev/encore.dev/beta/errs#Error
            properties:
              code:
                description: Error code
                example: not_found
                externalDocs:
                  url: https://pkg.go.dev/encore.dev/beta/errs#ErrCode
                type: string
              details:
                description: Error details
                type: object
              message:
                description: Error message
                type: string
            title: APIError
            type: object
      description: Error response
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An Erdo API key (erdo_api_...) or scoped token (erdo_token_...).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.