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

# Create an interaction

> Creates a new `Interaction` with an agent.

<RequestExample>
  ```ts TypeScript/JavaScript SDK theme={null}
  import { ProficientClient } from "@proficient/client";

  const proficient = new ProficientClient({
    apiKey: process.env.PROFICIENT_AI_PUBLISHABLE_KEY,
    userExternalId: "...", // The user's unique ID in your system
  });

  const agentId = "ag_Lad8YCGGiDLiqIZPWRXmc2ix";

  const { interaction } = await proficient.interactions.create({ agentId });
  ```
</RequestExample>


## OpenAPI

````yaml client-openapi POST /interactions
openapi: 3.0.1
info:
  title: api
  version: 0.0.1
servers:
  - url: https://api.proficientai.com
    description: Production (The production environment)
  - url: https://main-64bxvpctea-uc.a.run.app
    description: Staging (The staging environment)
  - url: http://localhost:8080
    description: Development (The local environment)
security: []
paths:
  /interactions:
    post:
      tags:
        - Interactions
      summary: Create an interaction
      description: Creates a new `Interaction` with an agent.
      operationId: interactions_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractionCreateParams'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionCreateResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    InteractionCreateParams:
      title: InteractionCreateParams
      type: object
      description: The data with which an interaction is created.
      properties:
        agent_id:
          $ref: '#/components/schemas/AgentId'
      required:
        - agent_id
    InteractionCreateResponse:
      title: InteractionCreateResponse
      type: object
      description: >-
        An object that contains the initial interaction data including the
        `Interaction` object itself and the initial messages associated with it.
      properties:
        interaction:
          $ref: '#/components/schemas/Interaction'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
        - interaction
        - messages
    ApiError:
      title: ApiError
      type: object
      description: >-
        Represents the general interface of an API error. The body of every
        error returned by the API contains `code` and `message` fields.
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
    AgentId:
      title: AgentId
      type: string
      description: The unique identifier of the agent
    Interaction:
      title: Interaction
      type: object
      description: >-
        <p>Users communicate with agents via <i>interactions</i>. You can think
        of each interaction as a conversation between an agent and user.</p>
      properties:
        id:
          $ref: '#/components/schemas/InteractionId'
        object:
          $ref: '#/components/schemas/InteractionObjectType'
        agent_id:
          $ref: '#/components/schemas/AgentId'
        archived:
          $ref: '#/components/schemas/InteractionArchived'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        initial_turn:
          $ref: '#/components/schemas/InitialTurn'
        name:
          $ref: '#/components/schemas/InteractionName'
        total_message_count:
          $ref: '#/components/schemas/InteractionTotalMessageCount'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        user_id:
          $ref: '#/components/schemas/UserId'
      required:
        - id
        - object
        - agent_id
        - archived
        - created_at
        - initial_turn
        - name
        - total_message_count
        - updated_at
        - user_id
    Message:
      title: Message
      type: object
      description: >-
        <p>Each interaction holds a number of <i>messages</i> and every message
        belongs to an interaction. The `sent_by` property of a message indicates
        whether a message was created by an agent or a user.</p>
      properties:
        id:
          $ref: '#/components/schemas/MessageId'
        object:
          $ref: '#/components/schemas/MessageObjectType'
        content:
          $ref: '#/components/schemas/MessageContent'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        depth:
          $ref: '#/components/schemas/MessageDepth'
        interaction_id:
          $ref: '#/components/schemas/InteractionId'
        parent_id:
          $ref: '#/components/schemas/MessageParentId'
          nullable: true
        sent_by:
          $ref: '#/components/schemas/InteractionParticipant'
      required:
        - id
        - object
        - content
        - created_at
        - depth
        - interaction_id
        - sent_by
    ApiErrorBody:
      title: ApiErrorBody
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ApiErrorCode'
        message:
          type: string
      required:
        - code
        - message
    InteractionId:
      title: InteractionId
      type: string
      description: The unique identifier of the interaction
    InteractionObjectType:
      title: InteractionObjectType
      type: string
      enum:
        - interaction
      description: The type of the `Interaction` object
    InteractionArchived:
      title: InteractionArchived
      type: boolean
      description: Whether the interaction has been archived by the user
    CreatedAt:
      title: CreatedAt
      type: integer
      description: >-
        The time at which the object was created, measured in milliseconds since
        the Unix epoch
    InitialTurn:
      $ref: '#/components/schemas/InteractionParticipant'
      title: InitialTurn
      description: >-
        Indicates who sends the first message in each interaction. Defaults to
        `"user"`.
    InteractionName:
      title: InteractionName
      type: string
      description: The name of the interaction
    InteractionTotalMessageCount:
      title: InteractionTotalMessageCount
      type: integer
      description: The total number of messages in the interaction
    UpdatedAt:
      title: UpdatedAt
      type: integer
      description: >-
        The time at which the object was last updated, measured in milliseconds
        since the Unix epoch
    UserId:
      title: UserId
      type: string
      description: The unique identifier of the user
    MessageId:
      title: MessageId
      type: string
      description: The unique identifier of the message
    MessageObjectType:
      title: MessageObjectType
      type: string
      enum:
        - message
      description: The type of the `Message` object
    MessageContent:
      title: MessageContent
      type: string
      description: The content of the message
    MessageDepth:
      title: MessageDepth
      type: integer
      description: >-
        The depth of the message node in the interaction tree. This will be 0
        for all root-level messages that mark the beginning of the interaction
        and increase as the conversation grows longer.
    MessageParentId:
      title: MessageParentId
      type: string
      nullable: true
      description: >-
        The ID of the message that directly precedes a given message within a
        particular conversation.
    InteractionParticipant:
      title: InteractionParticipant
      type: string
      enum:
        - user
        - agent
      description: >-
        Represents the type of the participant in a given interaction. As an
        example, message are created by interaction participants so the
        `sent_by` property of a `Message` object must be an
        `InteractionParticipant`.
    ApiErrorCode:
      title: ApiErrorCode
      type: string
      enum:
        - invalid_request
        - invalid_credentials
        - forbidden
        - resource_not_found
        - conflict
        - unavailable
        - unknown

````