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

# Create conversation

> Assignment rules:
- Assignees must belong to the same workspace as the API key.
- Chat conversations can be assigned to users, unassigned, or only the conversation's original chat agent.
- Email conversations can be assigned to users, unassigned, or only the workspace's active email agent.




## OpenAPI

````yaml /api-reference/openapi.json post /conversations
openapi: 3.1.0
info:
  title: Weav API
  version: 1.0.0
  description: |
    Public API for Weav workspace integrations.
    Base URL is versioned under /v1 and requires bearer token authentication.
    Token abilities are enforced:
    - `external-api:read` for read endpoints
    - `external-api:write` for write endpoints
    - `external-api:write` also grants read access
servers:
  - url: https://api.weav.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
  - name: Companies
  - name: Conversations
  - name: Customers
  - name: Messages
  - name: Training Data
  - name: Webhooks
paths:
  /conversations:
    post:
      tags:
        - Conversations
      summary: Create conversation
      description: >
        Assignment rules:

        - Assignees must belong to the same workspace as the API key.

        - Chat conversations can be assigned to users, unassigned, or only the
        conversation's original chat agent.

        - Email conversations can be assigned to users, unassigned, or only the
        workspace's active email agent.
      operationId: createConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
      responses:
        '201':
          description: Conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid assignee or assignee type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ConversationCreateRequest:
      type: object
      required:
        - channel
        - customer_id
      properties:
        channel:
          type: string
          enum:
            - email
            - chat
        customer_id:
          type: string
          format: uuid
        subject:
          type: string
          nullable: true
          maxLength: 500
        status:
          type: string
          enum:
            - open
            - closed
          nullable: true
        priority:
          type: string
          enum:
            - low
            - normal
            - high
            - urgent
          nullable: true
        assignee_id:
          type: string
          format: uuid
          nullable: true
          description: >
            User or agent UUID to assign. Set null to unassign.

            Must belong to the same workspace.

            For chat, agent assignment is limited to the conversation's original
            chat agent.

            For email, agent assignment is limited to the workspace active email
            agent.
        assignee_type:
          type: string
          enum:
            - user
            - agent
          nullable: true
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        channel:
          type: string
          enum:
            - email
            - chat
        customer_id:
          type: string
          format: uuid
        subject:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
        priority:
          type: string
          enum:
            - low
            - normal
            - high
            - urgent
        assignee_id:
          type: string
          format: uuid
          nullable: true
          description: >
            User or agent UUID to assign. Must belong to the same workspace.

            For chat, agent assignment is limited to the conversation's original
            chat agent.

            For email, agent assignment is limited to the workspace active email
            agent.
        assignee_type:
          type: string
          enum:
            - user
            - agent
          nullable: true
        closed_at:
          type: string
          format: date-time
          nullable: true
        first_response_at:
          type: string
          format: date-time
          nullable: true
        last_message_at:
          type: string
          format: date-time
          nullable: true
        is_spam:
          type: boolean
        spam_score:
          type: number
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error message
        code:
          type: string
          nullable: true
          example: UNAUTHENTICATED
        errors:
          type: object
          additionalProperties: true
          nullable: true
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: |
        Workspace API token.
        Include abilities `external-api:read` and/or `external-api:write`.

````