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

> Create a new conversation linked to a specific project. You must create a conversation before sending messages to participants.

# Create a conversation

## Next steps

<CardGroup cols={2}>
  <Card title="Send a message" icon="paper-plane" href="/messaging/create-a-message">
    Use the conversation UID to send messages to participants.
  </Card>

  <Card title="Messaging guide" icon="book" href="/docs/Messaging/messaging-overview-copy">
    Read the full messaging guide for best practices.
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v1/messaging/conversations
openapi: 3.0.0
info:
  title: Partner API
  description: Public API for partner integrations
  version: '1.0'
  contact: {}
servers:
  - url: https://api-staging.respondent.io
security: []
tags: []
paths:
  /v1/messaging/conversations:
    post:
      tags:
        - messaging
      summary: Create a conversation
      description: |-
        Create a conversation.
        This must be done before sending a message.
      operationId: ConversationsController_create
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
        - name: x-api-secret
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
components:
  schemas:
    CreateConversationDto:
      type: object
      properties:
        projectId:
          type: string
          description: ProjectId of the project the coversation belongs to.
          format: ObjectId
        participantUserIds:
          description: >-
            UserId(s) of participants of conversation (not including
            researcher).

            Minimum 1 participant required.
          type: array
          items:
            type: string
            format: ObjectId
        externalResearcherId:
          type: string
          description: Derived from project values.
          deprecated: true
        externalTeamId:
          type: string
          description: Derived from project values.
          deprecated: true
        externalCompanyId:
          type: string
          description: Derived from project values.
          deprecated: true
      required:
        - projectId
        - participantUserIds
    Conversation:
      type: object
      properties:
        createdAt:
          type: string
        updatedAt:
          type: string
        uid:
          type: string
          description: Unique identifier of conversation.
        name:
          type: string
          description: Name of conversation.
        deleted:
          type: boolean
          description: If conversation is marked as deleted.
        locked:
          type: boolean
          description: If conversation is locked.
        read:
          type: boolean
          deprecated: true
        metadata:
          description: Metadata of conversation.
          allOf:
            - $ref: '#/components/schemas/ConversationMetadata'
        user:
          description: >-
            User who created the conversation.

            This will be the API owner/admin account for the api team.

            First name and last name will belong to api team user, not external
            researcher name.

            External researcherId will be stored in metadata, which can be used
            to lookup your external researcher's info internally.
          allOf:
            - $ref: '#/components/schemas/MessagingUser'
        participants:
          description: |-
            All participants of conversation including the researcher.
            The researcher will be the API owner/admin account for the api team.
          type: array
          items:
            $ref: '#/components/schemas/ConversationParticipant'
        messages:
          description: All messages in conversation.
          type: array
          items:
            $ref: '#/components/schemas/MinimalMessage'
        latestMessage:
          description: Latest message in conversation.
          allOf:
            - $ref: '#/components/schemas/LatestMessage'
        messagesCount:
          type: number
          description: Count of messages in conversation.
      required:
        - createdAt
        - uid
        - name
        - deleted
        - locked
        - read
        - user
        - participants
        - messages
        - latestMessage
        - messagesCount
    ConversationMetadata:
      type: object
      properties:
        projectId:
          type: string
          description: ProjectId of the project the coversation belongs to.
          format: ObjectId
        surveyResponseId:
          type: string
          description: ScreenerResponseId for the project, if exists.
          format: ObjectId
        externalResearcherId:
          type: string
          description: ExternalResearcherId for the project, if exists.
        externalTeamId:
          type: string
          description: ExternalTeamId for the project, if exists.
        externalCompanyId:
          type: string
          description: ExternalCompanyId for the project, if exists.
    MessagingUser:
      type: object
      properties:
        uid:
          type: string
          description: Unique identifier for messaging user.
        foreignId:
          type: string
          description: UserId of messaging user.
        firstName:
          type: string
          description: First name of user.
        lastName:
          type: string
          description: Last name initial of user.
      required:
        - uid
        - firstName
        - lastName
    ConversationParticipant:
      type: object
      properties:
        uid:
          type: string
          description: Unique identifier for messaging user.
        foreignId:
          type: string
          description: UserId of messaging user.
        firstName:
          type: string
          description: First name of user.
        lastName:
          type: string
          description: Last name initial of user.
        read:
          type: boolean
          description: Whether the participant has read the conversation.
        deleted:
          type: boolean
          description: Whether the participant has muted the conversation.
      required:
        - uid
        - firstName
        - lastName
        - read
        - deleted
    MinimalMessage:
      type: object
      properties:
        createdAt:
          type: string
        updatedAt:
          type: string
        uid:
          type: string
          description: Unique identifier of message.
        body:
          type: string
          description: Body of message.
        sender:
          description: Sender of message.
          allOf:
            - $ref: '#/components/schemas/MessagingUser'
      required:
        - createdAt
        - uid
        - body
        - sender
    LatestMessage:
      type: object
      properties:
        createdAt:
          type: string
        updatedAt:
          type: string
        uid:
          type: string
          description: Unique identifier for the message.
        body:
          type: string
          description: Body of the message.
      required:
        - createdAt
        - uid
        - body

````