Telnyx API — Conversations

naftiko: 1.0.0-alpha2
info:
  label: Telnyx API — Conversations
  description: 'Telnyx API — Conversations. 20 operations. Lead operation: List conversations. Self-contained Naftiko capability
    covering one Telnyx business surface.'
  tags:
  - Telnyx
  - Conversations
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TELNYX_API_KEY: TELNYX_API_KEY
capability:
  consumes:
  - type: http
    namespace: telnyx-conversations
    baseUri: https://api.telnyx.com/v2
    description: Telnyx API — Conversations business capability. Self-contained, no shared references.
    resources:
    - name: ai-conversations
      path: /ai/conversations
      operations:
      - name: getconversationspublicconversationsget
        method: GET
        description: List conversations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: query
          type: string
          description: Filter by conversation ID (e.g. id=eq.123)
        - name: name
          in: query
          type: string
          description: Filter by conversation Name (e.g. `name=like.Voice%`)
        - name: created_at
          in: query
          type: string
          description: Filter by creation datetime (e.g., `created_at=gte.2025-01-01`)
        - name: last_message_at
          in: query
          type: string
          description: Filter by last message datetime (e.g., `last_message_at=lte.2025-06-01`)
        - name: metadata->assistant_id
          in: query
          type: string
          description: Filter by assistant ID (e.g., `metadata->assistant_id=eq.assistant-123`)
        - name: metadata->call_control_id
          in: query
          type: string
          description: Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
        - name: metadata->telnyx_agent_target
          in: query
          type: string
          description: Filter by the phone number, SIP URI, or other identifier for the agent (e.g., `metadata->telnyx_agent_target=eq.+13128675309`)
        - name: metadata->telnyx_end_user_target
          in: query
          type: string
          description: Filter by the phone number, SIP URI, or other identifier for the end user (e.g., `metadata->telnyx_end_user_target=eq.+13128675309`)
        - name: metadata->telnyx_conversation_channel
          in: query
          type: string
          description: Filter by conversation channel (e.g., `metadata->telnyx_conversation_channel=eq.phone_call`)
        - name: limit
          in: query
          type: integer
          description: Limit the number of returned conversations (e.g., `limit=10`)
        - name: order
          in: query
          type: string
          description: Order the results by specific fields (e.g., `order=created_at.desc` or `order=last_message_at.asc`)
        - name: or
          in: query
          type: string
          description: Apply OR conditions using PostgREST syntax (e.g., `or=(created_at.gte.2025-04-01,last_message_at.gte.2025-04-01)`)
      - name: createnewconversationpublicconversationspost
        method: POST
        description: Create a conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-insight-groups
      path: /ai/conversations/insight-groups
      operations:
      - name: getallinsightgroups
        method: GET
        description: Get Insight Template Groups
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: page
          in: query
          type: object
          description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      - name: createinsightgroup
        method: POST
        description: Create Insight Template Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-insight-groups-group_id
      path: /ai/conversations/insight-groups/{group_id}
      operations:
      - name: deleteinsightgroupbyid
        method: DELETE
        description: Delete Insight Template Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: group_id
          in: path
          type: string
          description: The ID of the insight group
          required: true
      - name: getinsightgroupbyid
        method: GET
        description: Get Insight Template Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: group_id
          in: path
          type: string
          description: The ID of the insight group
          required: true
      - name: updateinsightgroupbyid
        method: PUT
        description: Update Insight Template Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: group_id
          in: path
          type: string
          description: The ID of the insight group
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-insight-groups-group_id-insights-insight_id-assign
      path: /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
      operations:
      - name: assigninsighttogroup
        method: POST
        description: Assign Insight Template To Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: group_id
          in: path
          type: string
          description: The ID of the insight group
          required: true
        - name: insight_id
          in: path
          type: string
          description: The ID of the insight
          required: true
    - name: ai-conversations-insight-groups-group_id-insights-insight_id-unassign
      path: /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
      operations:
      - name: unassigninsightfromgroup
        method: DELETE
        description: Unassign Insight Template From Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: group_id
          in: path
          type: string
          description: The ID of the insight group
          required: true
        - name: insight_id
          in: path
          type: string
          description: The ID of the insight
          required: true
    - name: ai-conversations-insights
      path: /ai/conversations/insights
      operations:
      - name: getallinsights
        method: GET
        description: Get Insight Templates
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: page
          in: query
          type: object
          description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      - name: createinsight
        method: POST
        description: Create Insight Template
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-insights-insight_id
      path: /ai/conversations/insights/{insight_id}
      operations:
      - name: deleteinsightbyid
        method: DELETE
        description: Delete Insight Template
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: string
          description: The ID of the insight
          required: true
      - name: getinsightbyid
        method: GET
        description: Get Insight Template
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: string
          description: The ID of the insight
          required: true
      - name: updateinsightbyid
        method: PUT
        description: Update Insight Template
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: string
          description: The ID of the insight
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-conversation_id
      path: /ai/conversations/{conversation_id}
      operations:
      - name: deleteconversationbyidpublicconversationsdelete
        method: DELETE
        description: Delete a conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          description: The ID of the conversation to delete
          required: true
      - name: getconversationbyidpublicconversationsget
        method: GET
        description: Get a conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          description: The ID of the conversation to retrieve
          required: true
      - name: updateconversationbyidpublicconversationsput
        method: PUT
        description: Update conversation metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          description: The ID of the conversation to update
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-conversation_id-conversations-insights
      path: /ai/conversations/{conversation_id}/conversations-insights
      operations:
      - name: getconversationspublicconversationidinsightsget
        method: GET
        description: Get insights for a conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          required: true
    - name: ai-conversations-conversation_id-message
      path: /ai/conversations/{conversation_id}/message
      operations:
      - name: addnewmessage
        method: POST
        description: Create Message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          description: The ID of the conversation
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: ai-conversations-conversation_id-messages
      path: /ai/conversations/{conversation_id}/messages
      operations:
      - name: getconversationspublicconversationidmessagesget
        method: GET
        description: Get conversation messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversation_id
          in: path
          type: string
          required: true
        - name: page[size]
          in: query
          type: integer
          description: The number of messages to return per page.
        - name: page[number]
          in: query
          type: integer
          description: The page number to retrieve.
    authentication:
      type: bearer
      token: '{{env.TELNYX_API_KEY}}'
  exposes:
  - type: rest
    namespace: telnyx-conversations-rest
    port: 8080
    description: REST adapter for Telnyx API — Conversations. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/ai/conversations
      name: ai-conversations
      description: REST surface for ai-conversations.
      operations:
      - method: GET
        name: getconversationspublicconversationsget
        description: List conversations
        call: telnyx-conversations.getconversationspublicconversationsget
        with:
          id: rest.id
          name: rest.name
          created_at: rest.created_at
          last_message_at: rest.last_message_at
          metadata->assistant_id: rest.metadata->assistant_id
          metadata->call_control_id: rest.metadata->call_control_id
          metadata->telnyx_agent_target: rest.metadata->telnyx_agent_target
          metadata->telnyx_end_user_target: rest.metadata->telnyx_end_user_target
          metadata->telnyx_conversation_channel: rest.metadata->telnyx_conversation_channel
          limit: rest.limit
          order: rest.order
          or: rest.or
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createnewconversationpublicconversationspost
        description: Create a conversation
        call: telnyx-conversations.createnewconversationpublicconversationspost
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insight-groups
      name: ai-conversations-insight-groups
      description: REST surface for ai-conversations-insight-groups.
      operations:
      - method: GET
        name: getallinsightgroups
        description: Get Insight Template Groups
        call: telnyx-conversations.getallinsightgroups
        with:
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createinsightgroup
        description: Create Insight Template Group
        call: telnyx-conversations.createinsightgroup
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insight-groups/{group-id}
      name: ai-conversations-insight-groups-group-id
      description: REST surface for ai-conversations-insight-groups-group_id.
      operations:
      - method: DELETE
        name: deleteinsightgroupbyid
        description: Delete Insight Template Group
        call: telnyx-conversations.deleteinsightgroupbyid
        with:
          group_id: rest.group_id
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getinsightgroupbyid
        description: Get Insight Template Group
        call: telnyx-conversations.getinsightgroupbyid
        with:
          group_id: rest.group_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updateinsightgroupbyid
        description: Update Insight Template Group
        call: telnyx-conversations.updateinsightgroupbyid
        with:
          group_id: rest.group_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insight-groups/{group-id}/insights/{insight-id}/assign
      name: ai-conversations-insight-groups-group-id-insights-insight-id-assign
      description: REST surface for ai-conversations-insight-groups-group_id-insights-insight_id-assign.
      operations:
      - method: POST
        name: assigninsighttogroup
        description: Assign Insight Template To Group
        call: telnyx-conversations.assigninsighttogroup
        with:
          group_id: rest.group_id
          insight_id: rest.insight_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insight-groups/{group-id}/insights/{insight-id}/unassign
      name: ai-conversations-insight-groups-group-id-insights-insight-id-unassign
      description: REST surface for ai-conversations-insight-groups-group_id-insights-insight_id-unassign.
      operations:
      - method: DELETE
        name: unassigninsightfromgroup
        description: Unassign Insight Template From Group
        call: telnyx-conversations.unassigninsightfromgroup
        with:
          group_id: rest.group_id
          insight_id: rest.insight_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insights
      name: ai-conversations-insights
      description: REST surface for ai-conversations-insights.
      operations:
      - method: GET
        name: getallinsights
        description: Get Insight Templates
        call: telnyx-conversations.getallinsights
        with:
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createinsight
        description: Create Insight Template
        call: telnyx-conversations.createinsight
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/insights/{insight-id}
      name: ai-conversations-insights-insight-id
      description: REST surface for ai-conversations-insights-insight_id.
      operations:
      - method: DELETE
        name: deleteinsightbyid
        description: Delete Insight Template
        call: telnyx-conversations.deleteinsightbyid
        with:
          insight_id: rest.insight_id
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getinsightbyid
        description: Get Insight Template
        call: telnyx-conversations.getinsightbyid
        with:
          insight_id: rest.insight_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updateinsightbyid
        description: Update Insight Template
        call: telnyx-conversations.updateinsightbyid
        with:
          insight_id: rest.insight_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/{conversation-id}
      name: ai-conversations-conversation-id
      description: REST surface for ai-conversations-conversation_id.
      operations:
      - method: DELETE
        name: deleteconversationbyidpublicconversationsdelete
        description: Delete a conversation
        call: telnyx-conversations.deleteconversationbyidpublicconversationsdelete
        with:
          conversation_id: rest.conversation_id
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getconversationbyidpublicconversationsget
        description: Get a conversation
        call: telnyx-conversations.getconversationbyidpublicconversationsget
        with:
          conversation_id: rest.conversation_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: updateconversationbyidpublicconversationsput
        description: Update conversation metadata
        call: telnyx-conversations.updateconversationbyidpublicconversationsput
        with:
          conversation_id: rest.conversation_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/{conversation-id}/conversations-insights
      name: ai-conversations-conversation-id-conversations-insights
      description: REST surface for ai-conversations-conversation_id-conversations-insights.
      operations:
      - method: GET
        name: getconversationspublicconversationidinsightsget
        description: Get insights for a conversation
        call: telnyx-conversations.getconversationspublicconversationidinsightsget
        with:
          conversation_id: rest.conversation_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/{conversation-id}/message
      name: ai-conversations-conversation-id-message
      description: REST surface for ai-conversations-conversation_id-message.
      operations:
      - method: POST
        name: addnewmessage
        description: Create Message
        call: telnyx-conversations.addnewmessage
        with:
          conversation_id: rest.conversation_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ai/conversations/{conversation-id}/messages
      name: ai-conversations-conversation-id-messages
      description: REST surface for ai-conversations-conversation_id-messages.
      operations:
      - method: GET
        name: getconversationspublicconversationidmessagesget
        description: Get conversation messages
        call: telnyx-conversations.getconversationspublicconversationidmessagesget
        with:
          conversation_id: rest.conversation_id
          page[size]: rest.page[size]
          page[number]: rest.page[number]
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: telnyx-conversations-mcp
    port: 9090
    transport: http
    description: MCP adapter for Telnyx API — Conversations. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-conversations
      description: List conversations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getconversationspublicconversationsget
      with:
        id: tools.id
        name: tools.name
        created_at: tools.created_at
        last_message_at: tools.last_message_at
        metadata->assistant_id: tools.metadata->assistant_id
        metadata->call_control_id: tools.metadata->call_control_id
        metadata->telnyx_agent_target: tools.metadata->telnyx_agent_target
        metadata->telnyx_end_user_target: tools.metadata->telnyx_end_user_target
        metadata->telnyx_conversation_channel: tools.metadata->telnyx_conversation_channel
        limit: tools.limit
        order: tools.order
        or: tools.or
      outputParameters:
      - type: object
        mapping: $.
    - name: create-conversation
      description: Create a conversation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: telnyx-conversations.createnewconversationpublicconversationspost
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insight-template-groups
      description: Get Insight Template Groups
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getallinsightgroups
      with:
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: create-insight-template-group
      description: Create Insight Template Group
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: telnyx-conversations.createinsightgroup
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-insight-template-group
      description: Delete Insight Template Group
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: telnyx-conversations.deleteinsightgroupbyid
      with:
        group_id: tools.group_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insight-template-group
      description: Get Insight Template Group
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getinsightgroupbyid
      with:
        group_id: tools.group_id
      outputParameters:
      - type: object
        mapping: $.
    - name: update-insight-template-group
      description: Update Insight Template Group
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: telnyx-conversations.updateinsightgroupbyid
      with:
        group_id: tools.group_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: assign-insight-template-group
      description: Assign Insight Template To Group
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: telnyx-conversations.assigninsighttogroup
      with:
        group_id: tools.group_id
        insight_id: tools.insight_id
      outputParameters:
      - type: object
        mapping: $.
    - name: unassign-insight-template-group
      description: Unassign Insight Template From Group
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: telnyx-conversations.unassigninsightfromgroup
      with:
        group_id: tools.group_id
        insight_id: tools.insight_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insight-templates
      description: Get Insight Templates
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getallinsights
      with:
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: create-insight-template
      description: Create Insight Template
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: telnyx-conversations.createinsight
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-insight-template
      description: Delete Insight Template
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: telnyx-conversations.deleteinsightbyid
      with:
        insight_id: tools.insight_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insight-template
      description: Get Insight Template
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getinsightbyid
      with:
        insight_id: tools.insight_id
      outputParameters:
      - type: object
        mapping: $.
    - name: update-insight-template
      description: Update Insight Template
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: telnyx-conversations.updateinsightbyid
      with:
        insight_id: tools.insight_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-conversation
      description: Delete a conversation
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: telnyx-conversations.deleteconversationbyidpublicconversationsdelete
      with:
        conversation_id: tools.conversation_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-conversation
      description: Get a conversation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getconversationbyidpublicconversationsget
      with:
        conversation_id: tools.conversation_id
      outputParameters:
      - type: object
        mapping: $.
    - name: update-conversation-metadata
      description: Update conversation metadata
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: telnyx-conversations.updateconversationbyidpublicconversationsput
      with:
        conversation_id: tools.conversation_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insights-conversation
      description: Get insights for a conversation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getconversationspublicconversationidinsightsget
      with:
        conversation_id: tools.conversation_id
      outputParameters:
      - type: object
        mapping: $.
    - name: create-message
      description: Create Message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: telnyx-conversations.addnewmessage
      with:
        conversation_id: tools.conversation_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-conversation-messages
      description: Get conversation messages
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-conversations.getconversationspublicconversationidmessagesget
      with:
        conversation_id: tools.conversation_id
        page[size]: tools.page[size]
        page[number]: tools.page[number]
      outputParameters:
      - type: object
        mapping: $.