> ## Documentation Index > Fetch the complete documentation index at: https://docs.bridge.new/llms.txt > Use this file to discover all available pages before exploring further. # Creates a new conversation with flexible user identification. > Create a new conversation with flexible user identification. External users can be identified by ID, email, or phone. Internal users are only assigned when explicitly specified; otherwise, conversations are auto-assigned by round-robin through a team or left open for any available internal user. ## OpenAPI ````yaml /api-reference/openapi.yaml post /bridge/api/v1/workspaces/{workspaceId}/conversations openapi: 3.1.0 info: title: Bridge API summary: Bridge API specification for chat system management. description: >- Bridge API specification including webhook receiver endpoints, Contact CRUD operations, and comprehensive chat system. This API includes: 1. Webhook Receiver API - for CRM clients to receive event notifications from Bridge 2. Contact CRUD API - for clients to manage contacts in Bridge 3. Conversations API - for managing conversations with flexible user identification and participant management 4. Messages API - for sending messages and files to a conversation 5. Files API - for managing files in a message 6. Custom attributes API - for consult custom attributes of an specific workspace **Multi-Tenant Architecture**: All operations are scoped to a specific workspace using workspaceId. termsOfService: https://www.sainapsis.com/legal/terms-of-service contact: name: Bridge Support url: https://app.bridge.new/ email: support@sainapsis.com license: name: MIT License url: https://spdx.org/licenses/MIT.html version: 1.0.0 servers: - url: https://api-connect-us.bridge.new description: Production server security: [] paths: /bridge/api/v1/workspaces/{workspaceId}/conversations: post: tags: - Conversations API summary: Creates a new conversation with flexible user identification. description: >- Create a new conversation with flexible user identification. External users can be identified by ID, email, or phone. Internal users are only assigned when explicitly specified; otherwise, conversations are auto-assigned by round-robin through a team or left open for any available internal user. operationId: >- create_conversation_bridge_api_v1_workspaces__workspaceId__conversations_post parameters: - name: workspaceId in: path required: true schema: type: string format: uuid description: Unique identifier of the workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Unique identifier of the workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateConversationRequest' description: Request body for creating a new conversation. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConversationResponse' '400': description: Bad Request content: application/json: examples: MIN_PARTICIPANTS_REQUIRED: value: title: Min Participants Required status: 400 code: BRIDGE_CONVERSATION_0210 schema: $ref: '#/components/schemas/Problem' '403': description: Forbidden content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: '#/components/schemas/Problem' '404': description: Not Found content: application/json: examples: WORKSPACE_NOT_FOUND: value: title: Workspace Not Found status: 404 code: BRIDGE_WORKSPACE_0001 INTERNAL_USER_NOT_FOUND: value: title: Internal User Not Found status: 404 code: BRIDGE_INTERNAL_0001 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_EXTERNAL_0001 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: CONVERSATION_WITH_SAME_PARTICIPANTS_ALREADY_EXISTS: value: title: Conversation With Same Participants Already Exists status: 409 code: BRIDGE_CONVERSATION_0003 EXTERNAL_USER_NOT_IN_WORKSPACE: value: title: External User Not In Workspace status: 409 code: BRIDGE_EXTERNAL_0004 INTERNAL_USERS_NOT_IN_WORKSPACE: value: title: Internal Users Not In Workspace status: 409 code: BRIDGE_INTERNAL_0002 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - x-api-key: [] components: schemas: CreateConversationRequest: properties: participants: $ref: '#/components/schemas/CreateParticipantsOnConversationRequest' title: Participants description: Participants to add to conversation. name: anyOf: - type: string - type: 'null' title: Name description: Optional name/title for the conversation. examples: - Bridge Support Team - null status: $ref: '#/components/schemas/ConversationStatus' title: Status description: >- Initial conversation status - 'active' for visible conversations, 'ghost' for invisible until first interaction. default: ACTIVE examples: - ACTIVE teamId: anyOf: - type: string format: uuid - type: 'null' title: Team Identifier description: >- Team UUID for round-robin assignment (optional, mutually exclusive with internalParticipants). examples: - 9fd1468d-e5ca-4ba3-98d1-13017e6f3808 additionalProperties: false type: object required: - participants title: CreateConversationRequest description: Request body for creating a new conversation. ConversationResponse: properties: id: type: string title: Identifier description: Unique identifier of the conversation (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Unique identifier of the workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 participants: $ref: '#/components/schemas/ConversationParticipantsResponse' title: Participants description: Participants of the conversation. name: anyOf: - type: string - type: 'null' title: Name description: Optional name/title for the conversation. examples: - Bridge Support Team status: anyOf: - $ref: '#/components/schemas/ConversationStatus' - type: 'null' title: Status description: >- Current conversation status - 'ACTIVE' for visible conversations, 'GHOST' for invisible until first interaction. examples: - ACTIVE createdAt: type: string format: date-time title: Created At description: Timestamp when the conversation was created. examples: - '2003-04-10T09:00:00.000Z' updatedAt: type: string format: date-time title: Updated At description: Timestamp when the conversation was last updated. examples: - '2003-04-10T09:00:00.000Z' type: object required: - id - workspaceId - participants - createdAt - updatedAt title: ConversationResponse description: Response body for conversation details. Problem: properties: title: type: string title: Title description: Short, summary of the problem type. status: type: integer title: Status description: >- HTTP status code generated by the origin server for this occurrence of the problem. detail: anyOf: - type: string - type: 'null' title: Detail description: Explanation specific to this occurrence of the problem. instance: anyOf: - type: string - type: 'null' title: Instance description: >- A URI reference that identifies the specific occurrence of the problem. traceId: anyOf: - type: string - type: 'null' title: Traceid description: Trace ID for debugging purposes. code: anyOf: - type: string - type: 'null' title: Code description: >- Error code for identification, view the error codes page for more details. errors: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Errors description: List of error details. extra: anyOf: - additionalProperties: true type: object - type: 'null' title: Extra description: Extra information about the problem. type: object required: - title - status title: Problem description: Object representing a Problem response body. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CreateParticipantsOnConversationRequest: properties: externals: items: $ref: '#/components/schemas/ExternalUserIdentifierRequest' type: array title: Externals description: Array of external user identifiers. internals: items: $ref: '#/components/schemas/InternalUserIdentifierRequest' type: array title: Internals description: >- Array of internal user identifiers (optional, mutually exclusive with teamId). type: object title: CreateParticipantsOnConversationRequest description: Request body for participants when creating a new conversation. ConversationStatus: type: string enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED title: ConversationStatus ConversationParticipantsResponse: properties: externals: items: $ref: '#/components/schemas/ExternalParticipant' type: array title: Externals description: List of external participants. internals: items: $ref: '#/components/schemas/InternalParticipant' type: array title: Internals description: List of internal participants. type: object required: - externals - internals title: ConversationParticipantsResponse description: Response body for conversation participants. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ExternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: User identifier value. examples: - john.doe@example.com - '+13802098869' - 37673840-6259-40f9-bbe5-a7db40f8e3cf identifierType: type: string enum: - ID - EMAIL - PHONE title: Identifier Type description: Type of identifier for external users (ID, EMAIL or PHONE). examples: - EMAIL - PHONE - ID messageProviderType: anyOf: - $ref: '#/components/schemas/MessageProviderType' - type: 'null' title: Message Provider Type description: Message provider type of the conversation. examples: - WHATSAPP - null providerChannelId: anyOf: - type: string - type: 'null' title: Provider Channel Identifier description: >- Provider channel id of channel that be used by Bridge to communicate with user. type: object required: - identifier - identifierType title: ExternalUserIdentifierRequest description: Body to identify an external user in Bridge System. InternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: User identifier value. examples: - john.doe@example.com - '+13802098869' - 37673840-6259-40f9-bbe5-a7db40f8e3cf identifierType: $ref: '#/components/schemas/InternalParticipantIdentifierType' title: Identifier Type description: Type of identifier for internal users (ID or EMAIL). examples: - EMAIL - ID type: object required: - identifier - identifierType title: InternalUserIdentifierRequest description: Body to identify an internal user in Bridge System. ExternalParticipant: properties: identifier: type: string title: Identifier description: Participant identifier value. examples: - ef7ee722-5f95-415a-9a98-81eeae178b11 identifierType: type: string enum: - ID - EMAIL - PHONE title: Identifier Type description: Type of identifier for external participants (ID, EMAIL, or PHONE). examples: - EMAIL - PHONE - ID role: $ref: '#/components/schemas/UserType' title: Role description: Participant role in the conversation. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Timestamp when participant joined the conversation. examples: - '2004-04-10T09:00:00.000Z' lastSeenAt: anyOf: - type: string format: date-time - type: 'null' title: Last Seen At description: Timestamp when participant was last seen. examples: - null - '2004-04-10T09:00:00.000Z' type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Object representing the external participant in the conversation. InternalParticipant: properties: identifier: type: string title: Identifier description: Participant identifier value. examples: - ef7ee722-5f95-415a-9a98-81eeae178b11 identifierType: $ref: '#/components/schemas/InternalParticipantIdentifierType' title: Identifier Type description: Type of identifier for internal participants (ID or EMAIL). examples: - EMAIL - ID role: $ref: '#/components/schemas/UserType' title: Role description: Participant role in the conversation. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Timestamp when participant joined the conversation. examples: - '2004-04-10T09:00:00.000Z' lastSeenAt: anyOf: - type: string format: date-time - type: 'null' title: Last Seen At description: Timestamp when participant was last seen. examples: - null - '2004-04-10T09:00:00.000Z' type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Object representing the internal participant in the conversation. MessageProviderType: type: string enum: - WHATSAPP - SMS - TELEGRAM - INSTAGRAM - TWITTER - LINE - FACEBOOK - IMESSAGE - WHATSAPP_TEST - HEYGIA title: MessageProviderType InternalParticipantIdentifierType: type: string enum: - ID - EMAIL title: InternalParticipantIdentifierType UserType: type: string enum: - INTERNAL - EXTERNAL - BOT title: UserType securitySchemes: x-api-key: type: apiKey description: Copy the API key as provided by the Bridge Console. in: header name: x-api-key ````