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.\n\n This\ \ API includes:\n 1. Webhook Receiver API - for CRM clients\ \ to receive event notifications from Bridge\n 2. Contact CRUD\ \ API - for clients to manage contacts in Bridge\n 3. Conversations\ \ API - for managing conversations with flexible user identification and participant\ \ management\n 4. Messages API - for sending messages and files\ \ to a conversation\n 5. Files API - for managing files in\ \ a message\n 6. Custom attributes API - for consult custom\ \ attributes of an specific workspace\n\n **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 paths: /bridge/api/health: get: tags: - Health summary: Health check description: Health check endpoint to verify that the API is up and running. operationId: health_bridge_api_health_get responses: '200': description: Successful Response content: application/json: schema: additionalProperties: true type: object title: Response Health Bridge Api Health Get '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Problem' examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 security: - x-api-key: [] /bridge/api/v1/workspaces/{workspaceId}/conversations/{conversationId}: get: tags: - Conversations API summary: Get conversation by id description: Get a specific conversation by its unique identifier within the workspace. operationId: get_conversation_by_id_bridge_api_v1_workspaces__workspaceId__conversations__conversationId__get security: - x-api-key: [] 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). - name: conversationId in: path required: true schema: type: string format: uuid description: Unique identifier of the conversation (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Unique identifier of the conversation (UUID v4). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConversationResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: CONVERSATION_NOT_FOUND: value: title: Conversation Not Found status: 404 code: BRIDGE_CONVERSATION_0001 CONVERSATION_NOT_IN_WORKSPACE: value: title: Conversation Not In Workspace status: 404 code: BRIDGE_CONVERSATION_0002 WORKSPACE_NOT_FOUND: value: title: Workspace Not Found status: 404 code: BRIDGE_WORKSPACE_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Conversations API summary: Update conversation description: 'Update conversation details including participants, status, and name. Support partial updates - only include the fields you want to change.' operationId: update_conversation_bridge_api_v1_workspaces__workspaceId__conversations__conversationId__patch security: - x-api-key: [] 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). - name: conversationId in: path required: true schema: type: string format: uuid description: Unique identifier of the conversation (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Unique identifier of the conversation (UUID v4). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateConversation' description: Request body for updating an existing conversation. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConversationResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: CONVERSATION_NOT_FOUND: value: title: Conversation Not Found status: 404 code: BRIDGE_CONVERSATION_0001 CONVERSATION_NOT_IN_WORKSPACE: value: title: Conversation Not In Workspace status: 404 code: BRIDGE_CONVERSATION_0002 WORKSPACE_NOT_FOUND: value: title: Workspace Not Found status: 404 code: BRIDGE_WORKSPACE_0001 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_EXTERNAL_0001 INTERNAL_USER_NOT_FOUND: value: title: Internal User Not Found status: 404 code: BRIDGE_INTERNAL_0001 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: INTERNAL_USER_ALREADY_IN_CONVERSATION: value: title: Internal User Already In Conversation status: 409 code: BRIDGE_CONVERSATION_0101 EXTERNAL_USER_ALREADY_IN_CONVERSATION: value: title: External User Already In Conversation status: 409 code: BRIDGE_CONVERSATION_0103 INTERNAL_USER_NOT_IN_CONVERSATION: value: title: Internal User Not In Conversation status: 409 code: BRIDGE_CONVERSATION_0102 EXTERNAL_USER_NOT_IN_CONVERSATION: value: title: External User Not In Conversation status: 409 code: BRIDGE_CONVERSATION_0104 LAST_ADMIN_REMOVAL_FORBIDDEN: value: title: Last Admin Removal Forbidden status: 409 code: BRIDGE_CONVERSATION_0204 MIN_INTERNAL_USERS_REQUIRED: value: title: Min Internal Users Required status: 409 code: BRIDGE_CONVERSATION_0205 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' /bridge/api/v1/workspaces/{workspaceId}/conversations: get: tags: - Conversations API summary: Retrieve conversations with flexible filtering options description: 'Retrieve conversations with flexible filtering options. Can search by external user identifiers (ID, email, phone) or internal participants, with support for pagination and status filtering.' operationId: get_conversations_bridge_api_v1_workspaces__workspaceId__conversations_get security: - x-api-key: [] 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). - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Number of conversations per page default: 20 title: Limit description: Number of conversations per page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor provided on before request to get next page title: Cursor description: Cursor provided on before request to get next page - name: status in: query required: false schema: anyOf: - type: string - type: 'null' title: Status description: Conversation status enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED description: Conversation status - name: internalUserIdentifier in: query required: false schema: anyOf: - type: string - type: 'null' description: Identifier of internal user, if you are sending a phone number take care to encode the request url (including params) title: Internaluseridentifier description: Identifier of internal user, if you are sending a phone number take care to encode the request url (including params) - name: internalUserIdentifierType in: query required: false schema: anyOf: - type: string - type: 'null' enum: - ID - EMAIL title: Internaluseridentifiertype - name: externalUserIdentifier in: query required: false schema: anyOf: - type: string - type: 'null' title: Externaluseridentifier - name: externalUserIdentifierType in: query required: false schema: anyOf: - type: string - type: 'null' title: Externaluseridentifiertype enum: - ID - EMAIL - PHONE responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConversationListResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: BAD_REQUEST: value: title: Bad Request status: 400 code: BRIDGE_CORE_0103 INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 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: INTERNAL_USERS_NOT_IN_WORKSPACE: value: title: Internal Users Not In Workspace status: 409 code: BRIDGE_INTERNAL_0002 EXTERNAL_USER_NOT_IN_WORKSPACE: value: title: External User Not In Workspace status: 409 code: BRIDGE_EXTERNAL_0004 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' 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 security: - x-api-key: [] 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' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: MIN_PARTICIPANTS_REQUIRED: value: title: Min Participants Required status: 400 code: BRIDGE_CONVERSATION_0210 ONBOARDING_TEMPLATE_NOT_IN_WORKSPACE: value: title: Onboarding Template Not In Workspace status: 400 code: BRIDGE_CONVERSATION_0602 ONBOARDING_TEMPLATE_NOT_APPROVED: value: title: Onboarding Template Not Approved status: 400 code: BRIDGE_CONVERSATION_0603 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 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_EXTERNAL_0001 INTERNAL_USER_NOT_FOUND: value: title: Internal User Not Found status: 404 code: BRIDGE_INTERNAL_0001 ONBOARDING_TEMPLATE_NOT_FOUND: value: title: Onboarding Template Not Found status: 404 code: BRIDGE_CONVERSATION_0601 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: Unprocessable Content content: application/json: examples: ONBOARDING_TEMPLATE_MISSING_PARAMETERS: value: title: Onboarding Template Missing Parameters status: 422 code: BRIDGE_CONVERSATION_0604 ONBOARDING_TEMPLATE_UNKNOWN_PARAMETERS: value: title: Onboarding Template Unknown Parameters status: 422 code: BRIDGE_CONVERSATION_0605 ONBOARDING_TEMPLATE_PARAMETERS_NOT_SUPPORTED: value: title: Onboarding Template Parameters Not Supported status: 422 code: BRIDGE_CONVERSATION_0606 ONBOARDING_TEMPLATE_INVALID_PARAMETER_VALUES: value: title: Onboarding Template Invalid Parameter Values status: 422 code: BRIDGE_CONVERSATION_0607 ONBOARDING_CONFIGURED_TEMPLATE_REQUIRES_CALLER_INPUT: value: title: Onboarding Configured Template Requires Caller Input status: 422 code: BRIDGE_CONVERSATION_0608 schema: $ref: '#/components/schemas/Problem' /bridge/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/release: post: tags: - Conversations API summary: Release conversation description: 'Release a conversation: mark as released, remove external participants, move to RELEASED section.' operationId: release_conversation_bridge_api_v1_workspaces__workspaceId__conversations__conversationId__release_post security: - x-api-key: [] 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). - name: conversationId in: path required: true schema: type: string format: uuid description: Unique identifier of the conversation (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Unique identifier of the conversation (UUID v4). requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/ReleaseConversationBody' - type: 'null' description: Body for POST release conversation. Optional reason. title: Body responses: '204': description: Successful Response '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 CONVERSATION_NOT_FOUND: value: title: Conversation Not Found status: 404 code: BRIDGE_CONVERSATION_0001 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: WORKSPACE_WITHOUT_CONFIGURED_FIELD: value: title: Workspace Without Configured Field status: 409 code: BRIDGE_WORKSPACE_0004 CONVERSATION_WITH_INCONSISTENT_STATE: value: title: Conversation With Inconsistent State status: 409 code: BRIDGE_CONVERSATION_0006 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: CONVERSATION_NOT_IN_WORKSPACE: value: title: Conversation Not In Workspace status: 400 code: BRIDGE_CONVERSATION_0002 CONVERSATION_NOT_ACTIVE: value: title: Conversation Not Active status: 400 code: BRIDGE_CONVERSATION_0004 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/messages: post: tags: - Messages API summary: Create a new message description: Create a new message within a specified conversation. operationId: create_message_bridge_api_v1_workspaces__workspaceId__messages_post security: - x-api-key: [] 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/MessageRequest' description: Request body for creating a new message within a specified conversation. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MessageResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: CONVERSATION_NOT_FOUND: value: title: Conversation Not Found status: 404 code: BRIDGE_CONVERSATION_0001 CONVERSATION_NOT_IN_WORKSPACE: value: title: Conversation Not In Workspace status: 404 code: BRIDGE_CONVERSATION_0002 WORKSPACE_NOT_FOUND: value: title: Workspace Not Found status: 404 code: BRIDGE_WORKSPACE_0001 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: CONVERSATION_IS_RELEASED: value: title: Conversation Is Released status: 409 code: BRIDGE_CONVERSATION_0007 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/contacts/lookup: get: tags: - Contacts API summary: Retrieve a contact by an identifier description: 'Get a specific contact by any of its identifiers within the workspace. `type=ID` returns the same contact as GET /contacts/{contactId}, which is the canonical URL for a contact and the one to prefer when the id is what you hold.' operationId: retrieve_contact_by_identifier_bridge_api_v1_workspaces__workspaceId__contacts_lookup_get security: - x-api-key: [] 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). - name: type in: query required: true schema: $ref: '#/components/schemas/ParticipantIdentifierType' description: Identifier the value is given as. description: Identifier the value is given as. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: 'The identifier itself, in the form named by `type`. A `PHONE` is read like the cellphone of a contact write: a number without a country code is read in the workspace''s default country, and spacing and separators are ignored. An `EMAIL` has its domain lowercased, but its local part is matched exactly as sent.' title: Value description: 'The identifier itself, in the form named by `type`. A `PHONE` is read like the cellphone of a contact write: a number without a country code is read in the workspace''s default country, and spacing and separators are ignored. An `EMAIL` has its domain lowercased, but its local part is matched exactly as sent.' examples: cellphone: summary: A cellphone description: Send with `type=PHONE`. A value that cannot be read as a cellphone is refused before any lookup happens. value: '+14084029292' email: summary: An email address description: Send with `type=EMAIL`. `John.Doe@example.com` and `john.doe@example.com` are different identifiers and do not resolve to the same contact. value: john.doe@example.com id: summary: The contact id description: Send with `type=ID`. Returns exactly what `GET /contacts/{contactId}` returns, which stays the canonical URL for a contact. value: 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Unprocessable Content content: application/json: examples: INVALID_FIELD_FORMAT: value: title: Invalid Field Format status: 422 code: BRIDGE_CORE_0101 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 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_EXTERNAL_0001 schema: $ref: '#/components/schemas/Problem' /bridge/api/v1/workspaces/{workspaceId}/contacts/{contactId}: get: tags: - Contacts API summary: Retrieve a contact by ID description: Get a specific contact by its unique identifier within the workspace. operationId: retrieve_contact_by_id_bridge_api_v1_workspaces__workspaceId__contacts__contactId__get security: - x-api-key: [] 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). - name: contactId in: path required: true schema: type: string format: uuid description: Unique identifier of the contact (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Unique identifier of the contact (UUID v4). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_EXTERNAL_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Contacts API summary: Update contact description: Update a contact in the specified workspace. operationId: update_contact_bridge_api_v1_workspaces__workspaceId__contacts__contactId__patch security: - x-api-key: [] 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). - name: contactId in: path required: true schema: type: string format: uuid description: Unique identifier of the contact (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Unique identifier of the contact (UUID v4). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateContactBody' description: Request body for updating an existing contact. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: MISSING_REQUIRED_FIELD: value: title: Missing Required Field status: 400 code: BRIDGE_CORE_0102 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 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: EMAIL_OWNED_BY_ANOTHER_CONTACT: value: title: Email Owned By Another Contact status: 409 code: BRIDGE_EXTERNAL_0013 CELLPHONE_OWNED_BY_ANOTHER_CONTACT: value: title: Cellphone Owned By Another Contact status: 409 code: BRIDGE_EXTERNAL_0007 EXTERNAL_USER_NOT_IN_WORKSPACE: value: title: External User Not In Workspace status: 409 code: BRIDGE_EXTERNAL_0004 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/contacts: get: tags: - Contacts API summary: List contacts description: 'Retrieve a paginated list of contacts within the workspace. Ordered by creation date. The `ownerEmail` and `search` filters are deprecated and will be removed; to find one contact by an identifier, use /contacts/lookup.' operationId: get_contacts_bridge_api_v1_workspaces__workspaceId__contacts_get security: - x-api-key: [] 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). - name: ownerEmail in: query required: false deprecated: true schema: anyOf: - type: string - type: 'null' description: Filter contacts by owner email address title: Owneremail description: 'Filter contacts by owner email address. Deprecated: will be removed. No replacement; filter on `ownerId` in your own code. See the Changelog.' - name: search in: query required: false deprecated: true schema: anyOf: - type: string - type: 'null' description: Search contacts by name, email, or cellphone example: John Doe title: Search description: 'Search contacts by name, email, or cellphone. Deprecated: will be removed. To find one contact by cellphone or email, use `GET /contacts/lookup`. See the Changelog.' - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Number of contacts per page default: 20 title: Limit description: Number of contacts per page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor provided on before request to get next page title: Cursor description: Cursor provided on before request to get next page responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactsResponseList' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Contacts API summary: Create a new contact description: Create a new contact in the specified workspace. operationId: create_contact_bridge_api_v1_workspaces__workspaceId__contacts_post security: - x-api-key: [] 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/CreateContactBody' description: Request body for creating a new contact. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: EMAIL_OWNED_BY_ANOTHER_CONTACT: value: title: Email Owned By Another Contact status: 409 code: BRIDGE_EXTERNAL_0013 CELLPHONE_OWNED_BY_ANOTHER_CONTACT: value: title: Cellphone Owned By Another Contact status: 409 code: BRIDGE_EXTERNAL_0007 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/contacts/partial: post: tags: - Contacts API summary: Create or update a contact description: Create or update a contact using only cellphone. Classifies as NORMAL or PARTIAL. operationId: create_partial_contact_bridge_api_v1_workspaces__workspaceId__contacts_partial_post security: - x-api-key: [] 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/CreatePartialContactBody' description: Request body for partial contact creation. Only cellphone is required. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContactResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: EMAIL_OWNED_BY_ANOTHER_CONTACT: value: title: Email Owned By Another Contact status: 409 code: BRIDGE_EXTERNAL_0013 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/files: post: tags: - Files API summary: Create presigned uploads for files description: 'Generates presigned URLs to upload files (Presigned PUT). Validates extension, contentType, and type-specific limits. Checksum required: send SHA-256 digest in checksumBase64 (Base64). Upload must include header x-amz-checksum-sha256 with the same value. --- To upload your files, you MUST use the returned presigned URL with the HTTP PUT method. Ensure that you upload the file exactly to the URL indicated, without modifications (as required by AWS S3 Presigned URL PUT usage). Refer to the official AWS S3 documentation on Presigned PUT URLs for details: [AWS S3 Presigned PUT Documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html). Be sure to include all required headers as specified in the response (e.g., ''x-amz-checksum-sha256'' with the correct SHA-256 value). If you fail to use the correct HTTP method or headers, AWS will reject the upload request.
TypeExtensionContent TypeMax Size
Image.jpegimage/jpeg16 MB
.jpgimage/jpeg
.pngimage/png
.webpimage/webp
GIF.gifimage/gif3 MB
.mp4video/mp4
Video.avivideo/x-msvideo64 MB
.movvideo/quicktime
.mp4video/mp4
Audio.m4aaudio/mp416 MB
.mp3audio/mpeg
.oggaudio/ogg
.wavaudio/wav
Document.docapplication/msword100 MB
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.pdfapplication/pdf
.pptapplication/vnd.ms-powerpoint
.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation
.txttext/plain
.xlsapplication/vnd.ms-excel
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
' operationId: create_preloaded_files_bridge_api_v1_workspaces__workspaceId__files_post security: - x-api-key: [] 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: type: array items: $ref: '#/components/schemas/PreloadedFileRequest' description: Request for a file to be preloaded with a presigned URL. title: Preloaded Files responses: '201': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/PreloadedFileResponse' title: Response Create Preloaded Files Bridge Api V1 Workspaces Workspaceid Files Post '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/settings/attributes: get: tags: - Custom attributes API summary: Retrieve custom attributes by workspaceId description: "Return the custom attributes for the specified workspace.\n\n\ By default, only **active** attributes are returned (those without a past\ \ `deletedAt`).\n\n**Filters:**\n- `category` — Filter by `OPEN` or `CLOSED`.\ \ Omit to return all categories.\n- `includeArchived` — Set to `true` to include\ \ archived attributes\n (those with a past `deletedAt`). Default: `false`.\n\ - `isRequired` — Set to `true` to return only required attributes,\n `false`\ \ for optional only. Omit to return all." operationId: get_custom_attributes_by_workspace_bridge_api_v1_workspaces__workspaceId__settings_attributes_get security: - x-api-key: [] 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). - name: category in: query required: false schema: anyOf: - enum: - OPEN - CLOSED type: string - type: 'null' description: Filter by attribute category. Omit to return all categories. title: Category description: Filter by attribute category. Omit to return all categories. - name: includeArchived in: query required: false schema: type: boolean description: When `true`, archived attributes (those with a past `deletedAt`) are included in the response. Default is `false`, which returns only active attributes. default: false title: Includearchived description: When `true`, archived attributes (those with a past `deletedAt`) are included in the response. Default is `false`, which returns only active attributes. - name: isRequired in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter by required flag. `true` returns only required attributes, `false` only optional. Omit to return all. title: Isrequired description: Filter by required flag. `true` returns only required attributes, `false` only optional. Omit to return all. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CustomAttributesResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/provider-channels: get: tags: - Provider channels API summary: Get provider channels by workspace id description: Get provider channels by workspace identifier. operationId: get_provider_channels_by_workspace_id_bridge_api_v1_workspaces__workspaceId__provider_channels_get security: - x-api-key: [] 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). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ProviderChannelResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/provider-channels/{messageProviderType}: get: tags: - Provider channels API summary: Get provider channels by workspace id and provider type description: Get provider channels by workspace identifier and provider type. operationId: get_provider_channels_by_workspace_id_and_provider_type_bridge_api_v1_workspaces__workspaceId__provider_channels__messageProviderType__get security: - x-api-key: [] 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). - name: messageProviderType in: path required: true schema: $ref: '#/components/schemas/MessageProviderType' description: Message provider type (e.g. WHATSAPP, HEYGIA). description: Message provider type (e.g. WHATSAPP, HEYGIA). - name: brandId in: query required: false schema: anyOf: - type: string - type: 'null' description: Optional brand identifier. When supplied, only channels whose corporate line belongs to that brand are returned. Honored for WHATSAPP only; HEYGIA providers carry no brand. title: Brandid description: Optional brand identifier. When supplied, only channels whose corporate line belongs to that brand are returned. Honored for WHATSAPP only; HEYGIA providers carry no brand. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ProviderChannelResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: PROVIDER_CHANNEL_NOT_FOUND: value: title: Provider Channel Not Found status: 404 code: BRIDGE_PROVIDER_CHANNEL_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound: post: tags: - LeadScout API summary: Initiate a LeadScout outbound conversation with a known lead description: "Start an AI-controlled outbound conversation with a known lead.\n\ \nThe template is referenced by `template.id` or `template.name`; when both\ \ are sent, the id is used.\n\nPre-flight checks run before any write: template\ \ exists and is APPROVED, contact\nexists, a WhatsApp channel resolves, a\ \ prospection agent owns it, and any\n`handoffOverride` user is valid.\n\n\ If an active conversation is already running on the chosen channel:\n- `forceSend=false`\ \ (default) → `409` with error code BRIDGE_AI_LEADSCOUT_0007.\n- `forceSend=true`\ \ → that conversation is reused; the new template and follow-ups\n are appended\ \ to it and the response sets `alreadyInitiated=true`.\n\nOtherwise a fresh\ \ conversation is opened (controlled by the prospection agent) with\nthe template\ \ as its first message; `additionalMessages` are persisted for the agent\n\ to send once the lead replies.\n\nError codes:\n- BRIDGE_AI_LEADSCOUT_0001:\ \ external user not found\n- BRIDGE_AI_LEADSCOUT_0002: internal user not found\n\ - BRIDGE_AI_LEADSCOUT_0003: internal user deleted\n- BRIDGE_AI_LEADSCOUT_0004:\ \ template not found\n- BRIDGE_AI_LEADSCOUT_0005: template not approved\n\ - BRIDGE_AI_LEADSCOUT_0006: template ordered params mismatch\n- BRIDGE_AI_LEADSCOUT_0007:\ \ active conversation already exists\n- BRIDGE_AI_LEADSCOUT_0008: all provider\ \ channels occupied\n- BRIDGE_AI_LEADSCOUT_0009: no channels for brand\n-\ \ BRIDGE_AI_LEADSCOUT_0010: provider channel not in workspace\n- BRIDGE_AI_LEADSCOUT_0011:\ \ workspace has no provider channels\n- BRIDGE_AI_LEADSCOUT_0012: no prospecting\ \ agent for channel\n- BRIDGE_AI_LEADSCOUT_0013: multiple prospecting agents\ \ for brand\n- BRIDGE_AI_LEADSCOUT_0014: multiple prospecting agents for channel\n\ - BRIDGE_AI_LEADSCOUT_0015: conversation operation failed\n- BRIDGE_AI_LEADSCOUT_0016:\ \ outbound validation error" operationId: initiate_leadscout_outbound_bridge_api_v1_workspaces__workspaceId__leadscout_outbound_post security: - x-api-key: [] 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/LeadscoutOutboundRequest' description: Request body for initiating a LeadScout outbound conversation. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LeadscoutOutboundResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: OUTBOUND_VALIDATION_ERROR: value: title: Outbound Validation Error status: 400 code: BRIDGE_AI_LEADSCOUT_0016 TEMPLATE_ORDERED_PARAMS_MISMATCH: value: title: Template Params Mismatch status: 400 code: BRIDGE_AI_LEADSCOUT_0006 schema: $ref: '#/components/schemas/Problem' '404': description: Not Found content: application/json: examples: EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0001 INTERNAL_USER_NOT_FOUND: value: title: Internal User Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0002 TEMPLATE_NOT_FOUND: value: title: Template Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0004 NO_CHANNELS_FOR_BRAND: value: title: No Channels For Brand status: 404 code: BRIDGE_AI_LEADSCOUT_0009 PROVIDER_CHANNEL_NOT_IN_WORKSPACE: value: title: Channel Not In Workspace status: 404 code: BRIDGE_AI_LEADSCOUT_0010 WORKSPACE_HAS_NO_PROVIDER_CHANNELS: value: title: No Provider Channels status: 404 code: BRIDGE_AI_LEADSCOUT_0011 NO_PROSPECTING_AGENT_FOR_CHANNEL: value: title: No Agent For Channel status: 404 code: BRIDGE_AI_LEADSCOUT_0012 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: INTERNAL_USER_DELETED: value: title: Internal User Deleted status: 409 code: BRIDGE_AI_LEADSCOUT_0003 TEMPLATE_NOT_APPROVED: value: title: Template Not Approved status: 409 code: BRIDGE_AI_LEADSCOUT_0005 ACTIVE_CONVERSATION_ALREADY_EXISTS: value: title: Active Conversation Exists status: 409 code: BRIDGE_AI_LEADSCOUT_0007 ALL_PROVIDER_CHANNELS_OCCUPIED: value: title: All Channels Occupied status: 409 code: BRIDGE_AI_LEADSCOUT_0008 MULTIPLE_PROSPECTING_AGENTS_FOR_BRAND: value: title: Multiple Agents For Brand status: 409 code: BRIDGE_AI_LEADSCOUT_0013 MULTIPLE_PROSPECTING_AGENTS_FOR_CHANNEL: value: title: Multiple Agents For Channel status: 409 code: BRIDGE_AI_LEADSCOUT_0014 schema: $ref: '#/components/schemas/Problem' '500': description: Internal Server Error content: application/json: examples: CONVERSATION_OPERATION_FAILED: value: title: Conversation Operation Failed status: 500 code: BRIDGE_AI_LEADSCOUT_0015 schema: $ref: '#/components/schemas/Problem' '422': description: Unprocessable Content content: application/json: examples: MISSING_TEMPLATE_VARIABLES: value: title: Missing Template Variables status: 422 code: BRIDGE_AI_LEADSCOUT_0019 CONFLICTING_TEMPLATE_PARAMETERS: value: title: Conflicting Template Parameters status: 422 code: BRIDGE_AI_LEADSCOUT_0020 UNKNOWN_TEMPLATE_PARAMETER_KEY: value: title: Unknown Template Parameter Key status: 422 code: BRIDGE_AI_LEADSCOUT_0021 schema: $ref: '#/components/schemas/Problem' /bridge/api/v1/workspaces/{workspaceId}/leadscout/conversations/{conversationId}/handoff: post: tags: - LeadScout API summary: Request a manual handoff of a LeadScout conversation to internal users description: 'Request a manual handoff of a LeadScout-controlled conversation to one or more internal users. The request is acknowledged with `202 Accepted`; assignment is processed asynchronously. The response echoes the requested assignees and a tracking id for correlation. Internal-user resolution (by ID or EMAIL) happens downstream and is not reflected in this response.' operationId: request_leadscout_handoff_bridge_api_v1_workspaces__workspaceId__leadscout_conversations__conversationId__handoff_post security: - x-api-key: [] 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). - name: conversationId in: path required: true schema: type: string description: Unique identifier of the conversation (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Unique identifier of the conversation (UUID v4). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HandoffRequest' description: Request body for a LeadScout manual handoff. responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HandoffResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/templates/{templateId}: get: tags: - Templates API summary: Discover a template's agnostic variable inventory description: "Return a template's variables — agnostic `key`/`label`/`callerMustSupply`/`isCustom`/`default`.\n\ \nNever a Meta slot address or index.\n\n`templateId` accepts either the template's\ \ `id` or its `name` — the send contract\n(`POST .../leadscout/outbound`)\ \ identifies a template by `name`; this discovery endpoint\nalso accepts `id`,\ \ so a caller who only has one of the two can still look it up.\n\nA variable\ \ with `callerMustSupply: true` has no declared source — the caller must include\n\ its `key` in `parameters` when sending, or the send fails with a 422 naming\ \ that same `key`.\nA variable with `callerMustSupply: false` is either resolved\ \ by Bridge on its own (e.g. the\nrecipient's first name) or already has a\ \ value the caller may optionally override.\nA variable with `isCustom: true`\ \ is a value only the caller knows, with a `default`: send it in\n`parameters`\ \ to use your own value, or leave it out (or blank) and `default` goes out.\n\ \nError codes:\n- BRIDGE_CORE_0301: workspace in the path does not match the\ \ caller's own workspace (403)\n- BRIDGE_TEMPLATE_0001: no PROVIDER_TEMPLATE\ \ found for this workspace and identifier — covers\n an unknown id/name,\ \ a template that belongs to another workspace, and a template that is\n \ \ not a PROVIDER_TEMPLATE, identically (404); this endpoint never confirms\ \ the existence of\n a template outside the caller's own workspace" operationId: get_template_discovery_bridge_api_v1_workspaces__workspaceId__templates__templateId__get security: - x-api-key: [] 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). - name: templateId in: path required: true schema: type: string description: Template id or name — either identifies the same template. examples: - order_shipped_promo - f0000040-0000-4000-8000-000000000040 title: Templateid description: Template id or name — either identifies the same template. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TemplateDiscoveryResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: PROVIDER_TEMPLATE_NOT_FOUND: value: title: Provider Template Not Found status: 404 code: BRIDGE_TEMPLATE_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/users/lookup: get: tags: - Internal Users API summary: Retrieve an internal user by an identifier description: 'Get a specific Bridge User by any of its identifiers within the workspace. `type=ID` returns the same user as GET /users/{userId}, which is the canonical URL for an internal user and the one to prefer when the id is what you hold.' operationId: retrieve_internal_user_by_identifier_bridge_api_v1_workspaces__workspaceId__users_lookup_get security: - x-api-key: [] 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). - name: type in: query required: true schema: $ref: '#/components/schemas/InternalParticipantIdentifierType' description: Identifier the value is given as. An internal user's cellphone is not one. description: Identifier the value is given as. An internal user's cellphone is not one. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: The identifier itself, in the form named by `type`. An `EMAIL` has its domain lowercased, but its local part is matched exactly as sent. title: Value description: The identifier itself, in the form named by `type`. An `EMAIL` has its domain lowercased, but its local part is matched exactly as sent. examples: email: summary: An email address description: Send with `type=EMAIL`. `John.Doe@example.com` and `john.doe@example.com` are different identifiers and do not resolve to the same internal user. value: john.doe@example.com id: summary: The internal user id description: Send with `type=ID`. Returns exactly what `GET /users/{userId}` returns, which stays the canonical URL for an internal user. value: 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/InternalUserResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: '#/components/schemas/Problem' '422': description: Unprocessable Content content: application/json: examples: INVALID_FIELD_FORMAT: value: title: Invalid Field Format status: 422 code: BRIDGE_CORE_0101 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 schema: $ref: '#/components/schemas/Problem' /bridge/api/v1/workspaces/{workspaceId}/users/{userId}: get: tags: - Internal Users API summary: Retrieve an internal user by ID description: Get a specific internal user (human agent) by its unique identifier within the workspace. operationId: retrieve_internal_user_by_id_bridge_api_v1_workspaces__workspaceId__users__userId__get security: - x-api-key: [] 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). - name: userId in: path required: true schema: type: string format: uuid description: Unique identifier of the internal user (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Userid description: Unique identifier of the internal user (UUID v4). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/InternalUserResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/users: get: tags: - Internal Users API summary: List internal users description: 'Retrieve a paginated list of internal users within the workspace. Ordered by creation date. The `email` and `status` filters are deprecated and will be removed; to find one internal user by an identifier, use /users/lookup.' operationId: get_internal_users_bridge_api_v1_workspaces__workspaceId__users_get security: - x-api-key: [] 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). - name: email in: query required: false deprecated: true schema: anyOf: - type: string - type: 'null' description: Filter internal users by exact email address. example: john.doe@example.com title: Email description: 'Filter internal users by exact email address. Deprecated: will be removed. Use `GET /users/lookup?type=EMAIL`. See the Changelog.' - name: status in: query required: false deprecated: true schema: $ref: '#/components/schemas/UserStatusFilter' description: 'Filter by status: ''active'' (default), ''disabled'', or ''all''.' default: active description: 'Filter by status: ''active'' (default), ''disabled'', or ''all''. Deprecated: will be removed. Read `status` off each row instead. See the Changelog.' - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Number of internal users per page default: 20 title: Limit description: Number of internal users per page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor provided on a previous request to get the next page title: Cursor description: Cursor provided on a previous request to get the next page responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/InternalUsersResponseList' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/agents: get: tags: - Agents API summary: List the Agents of a workspace description: 'List the workspace''s Agents with their status, availability and lines. Every Agent is listed whatever its status; `available` tells whether it can start conversations. A page can hold fewer than `limit` items; keep paging while `cursor` is not null.' operationId: list_agents_bridge_api_v1_workspaces__workspaceId__agents_get security: - x-api-key: [] 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). - name: type in: query required: false schema: anyOf: - $ref: '#/components/schemas/AgentType' - type: 'null' description: Only return Agents of this type. title: Type description: Only return Agents of this type. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Number of Agents per page default: 20 title: Limit description: Number of Agents per page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor provided on a previous request to get the next page title: Cursor description: Cursor provided on a previous request to get the next page responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentsResponseList' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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' '400': description: Bad Request content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_AI_AGENT_OUTBOUND_0007 schema: $ref: '#/components/schemas/Problem' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound: post: tags: - Agents API summary: Start an outbound conversation with a Contact as a given Agent description: "Start an outbound conversation with a known Contact, answered\ \ by the given Agent.\n\nWorks for LeadScout and Service Agents. The Contact\ \ is resolved first, then the Agent, which must exist in\nthe workspace and\ \ be available (see `GET /agents`). The template is referenced by `template.id`\ \ or\n`template.name` (the id wins when both are sent), must exist and be\ \ APPROVED, and a\n`handoffOverride` Bridge User must be valid. If `template.media.mediaId`\ \ is unknown, the request fails\nwith 400 `BRIDGE_AI_LEADSCOUT_0016` only\ \ after the conversation was created or recovered, so a retry after\nthat\ \ error may answer differently. Body rules (`consent.status=GRANTED` without\ \ `capturedAt`, `template.media`\nwithout exactly one of `mediaId` or `url`)\ \ fail with 400 `BRIDGE_CORE_0103`.\n\nThe conversation opens on one of the\ \ Agent's active WhatsApp lines, controlled by the Agent, with the template\n\ as its first message. A line is picked in this order:\n- A free line.\n- Otherwise,\ \ a line holding a released conversation with this Contact that can be recovered.\ \ Recovering\n returns `recovered=true` and replaces the previous outbound\ \ context and `agentContext`. This happens even\n with `forceSend=false`.\n\ - Otherwise, when no line is free or recoverable: `forceSend=false` (default)\ \ fails with 409\n `BRIDGE_AI_LEADSCOUT_0008`; `forceSend=true` reuses a\ \ line occupied by an active conversation with this\n Contact, preferring\ \ one this Agent controls. If the chosen conversation is held by another Agent\ \ or a\n Bridge User, the call fails with 409 `BRIDGE_AI_AGENT_OUTBOUND_0006`\ \ and nothing is written. Release it\n first, then retry. Lines whose conversation\ \ is blocked or was released without recovery are never used, so\n if no\ \ line is occupied by an active conversation the call fails with 409 `BRIDGE_AI_LEADSCOUT_0008`\ \ even\n with `forceSend=true`.\n\n`contact.providerChannelId` is a preference:\ \ the pinned line is used when it is free or recoverable;\notherwise the same\ \ order applies over all the Agent's lines. Among occupied lines, one this\ \ Agent controls\ncomes first; if none does, the pinned line is the one reused\ \ (and may fail with 0006).\n\nReusing a conversation depends on the Agent\ \ type:\n- LeadScout: if its LeadScout session is still open and not expired,\ \ the call fails with 409\n `BRIDGE_AI_LEADSCOUT_0017` (`extra` carries `conversationId`,\ \ `sessionId` and `stage`). If an expired\n session cannot be finalized,\ \ it fails with 409 `BRIDGE_AI_LEADSCOUT_0018`.\n- Service Agent: an open,\ \ unexpired service session is continued; an expired one is closed as abandoned\ \ and a\n new one opens." operationId: start_agent_outbound_bridge_api_v1_workspaces__workspaceId__agents__agentId__outbound_post security: - x-api-key: [] 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). - name: agentId in: path required: true schema: type: string format: uuid description: Unique identifier of the Agent (UUID v4), as listed by `GET /agents`. examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Agentid description: Unique identifier of the Agent (UUID v4), as listed by `GET /agents`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentOutboundRequest' description: Request body for starting an outbound conversation answered by a given Agent. responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentOutboundResponse' '429': description: Too Many Requests content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: AGENT_NOT_FOUND: value: title: Agent Not Found status: 404 code: BRIDGE_AI_AGENT_OUTBOUND_0001 NO_CHANNELS_FOR_AGENT: value: title: No Channels For Agent status: 404 code: BRIDGE_AI_AGENT_OUTBOUND_0004 EXTERNAL_USER_NOT_FOUND: value: title: External User Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0001 INTERNAL_USER_NOT_FOUND: value: title: Internal User Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0002 TEMPLATE_NOT_FOUND: value: title: Template Not Found status: 404 code: BRIDGE_AI_LEADSCOUT_0004 NO_CHANNELS_FOR_BRAND: value: title: No Channels For Brand status: 404 code: BRIDGE_AI_LEADSCOUT_0009 schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/json: examples: AGENT_NOT_AVAILABLE: value: title: Agent Not Available status: 409 code: BRIDGE_AI_AGENT_OUTBOUND_0002 ACTIVE_CONVERSATION_CONTROLLED_BY_OTHER_AGENT: value: title: Conversation Controlled By Other Agent status: 409 code: BRIDGE_AI_AGENT_OUTBOUND_0006 INTERNAL_USER_DELETED: value: title: Internal User Deleted status: 409 code: BRIDGE_AI_LEADSCOUT_0003 TEMPLATE_NOT_APPROVED: value: title: Template Not Approved status: 409 code: BRIDGE_AI_LEADSCOUT_0005 ACTIVE_CONVERSATION_ALREADY_EXISTS: value: title: Active Conversation Exists status: 409 code: BRIDGE_AI_LEADSCOUT_0007 ALL_PROVIDER_CHANNELS_OCCUPIED: value: title: All Channels Occupied status: 409 code: BRIDGE_AI_LEADSCOUT_0008 LATEST_SESSION_NOT_FINAL: value: title: Latest Session Not Final status: 409 code: BRIDGE_AI_LEADSCOUT_0017 SESSION_FINALIZATION_FAILED: value: title: Session Finalization Failed status: 409 code: BRIDGE_AI_LEADSCOUT_0018 schema: $ref: '#/components/schemas/Problem' '422': description: Unprocessable Content content: application/json: examples: AGENT_TYPE_NOT_SUPPORTED: value: title: Agent Type Not Supported status: 422 code: BRIDGE_AI_AGENT_OUTBOUND_0003 AGENT_NOT_ASSIGNED_TO_CHANNEL: value: title: Agent Not Assigned To Channel status: 422 code: BRIDGE_AI_AGENT_OUTBOUND_0005 MISSING_TEMPLATE_VARIABLES: value: title: Missing Template Variables status: 422 code: BRIDGE_AI_LEADSCOUT_0019 CONFLICTING_TEMPLATE_PARAMETERS: value: title: Conflicting Template Parameters status: 422 code: BRIDGE_AI_LEADSCOUT_0020 UNKNOWN_TEMPLATE_PARAMETER_KEY: value: title: Unknown Template Parameter Key status: 422 code: BRIDGE_AI_LEADSCOUT_0021 schema: $ref: '#/components/schemas/Problem' '400': description: Bad Request content: application/json: examples: BAD_REQUEST: value: title: Bad Request status: 400 code: BRIDGE_CORE_0103 OUTBOUND_VALIDATION_ERROR: value: title: Outbound Validation Error status: 400 code: BRIDGE_AI_LEADSCOUT_0016 TEMPLATE_ORDERED_PARAMS_MISMATCH: value: title: Template Params Mismatch status: 400 code: BRIDGE_AI_LEADSCOUT_0006 schema: $ref: '#/components/schemas/Problem' components: schemas: AgentConfigStatus: type: string enum: - DRAFT - COMPLETE title: AgentConfigStatus AgentLine: properties: providerChannelId: type: string title: Provider Channel Identifier description: Identifier of the line (the same value `providerChannelId` takes on outbound operations). type: object required: - providerChannelId title: AgentLine description: WhatsApp line an Agent answers on. AgentOutboundContactRef: properties: identifier: type: string title: Identifier description: Phone number in E.164 format identifying the contact. examples: - '+573001234567' identifierType: $ref: '#/components/schemas/ParticipantIdentifierType' title: Identifier Type description: Type of identifier. examples: - PHONE - EMAIL - ID messageProviderType: $ref: '#/components/schemas/MessageProviderType' title: Message Provider Type description: Provider used to deliver the template. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: 'null' title: Provider Channel Identifier description: 'Optional. A line of the Agent to prefer (the `providerChannelId` of one of its `lines` in `GET /agents`). When omitted, any of the Agent''s lines can be used. When given, it must be an active line of the Agent, otherwise the request fails with 422. It is a preference, not a guarantee: if that line is neither free nor recoverable, the same order applies over all the Agent''s lines (with `forceSend=true`, an occupied line this Agent controls comes first, then the pinned one), and the response does not say which line was used.' examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: AgentOutboundContactRef description: Identifies the Contact the outbound conversation will target. AgentOutboundContext: properties: notes: anyOf: - type: string maxLength: 2000 - type: 'null' title: Notes description: Free-text notes for the Agent, capped at 2000 characters. examples: - The Contact asked about pricing tiers last week. - null mediaIds: items: type: string type: array title: Media Identifiers description: Optional preloaded-file identifiers persisted on the conversation as context for the Agent. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: AgentOutboundContext description: Notes and media stored on the conversation as context for the Agent and for Bridge Users. AgentOutboundFollowUp: properties: messageBody: type: string title: Message Body description: Plain-text body for the follow-up message. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: 'Accepted but not used yet: follow-ups are stored as text only, so attachments are not sent.' examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: AgentOutboundFollowUp description: A text follow-up stored on the conversation right after the opening template. AgentOutboundHandoffOverride: properties: preAssignedUser: $ref: '#/components/schemas/AgentOutboundPreAssignedUser' title: Pre-assigned User description: 'The Bridge User to assign as advisor when the Agent hands off the conversation. Validated at request time: the request is rejected if the user does not exist, belongs to another workspace, or has been deleted.' examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: AgentOutboundHandoffOverride description: Pre-assigns the Bridge User who receives the handoff of the outbound conversation. AgentOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Value that identifies the Bridge User, interpreted according to identifierType. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: '#/components/schemas/InternalParticipantIdentifierType' title: Identifier Type description: How to resolve the identifier. ID looks up by Bridge User ID; EMAIL looks up by email address. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: AgentOutboundPreAssignedUser description: Identifies the Bridge User who should receive the handoff. AgentOutboundRequest: properties: contact: $ref: '#/components/schemas/AgentOutboundContactRef' title: Contact description: The Contact this outbound conversation targets. Must already exist in the workspace. template: $ref: '#/components/schemas/LeadscoutOutboundTemplateRef' title: Template description: The opening template to send. additionalMessages: items: $ref: '#/components/schemas/AgentOutboundFollowUp' type: array maxItems: 5 title: Additional Messages description: Up to five text follow-ups stored on the conversation right after the opening template, in the order given, and sent like the template. Attachments (`mediaIds`) are not sent yet. agentContext: anyOf: - $ref: '#/components/schemas/AgentOutboundContext' - type: 'null' title: Agent Context description: Optional notes and media stored on the conversation as context for the Agent. consent: anyOf: - $ref: '#/components/schemas/OutboundConsentRequest' - type: 'null' title: Consent description: Optional tenant-affirmed opt-in evidence recorded on the conversation. handoffOverride: anyOf: - $ref: '#/components/schemas/AgentOutboundHandoffOverride' - type: 'null' title: Handoff Override description: 'Optional. Pre-assigns a specific Bridge User as the advisor for the handoff. The Bridge User is validated before anything is written: the request is rejected if the user does not exist, belongs to another workspace, or has been deleted.' brandId: anyOf: - type: string - type: 'null' title: Brand Identifier description: Optional brand id. When given, only the Agent's lines linked to this brand are eligible; if none is, the request fails with 404. Omit to consider every line of the Agent. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: 'null' title: Campaign Identifier description: Optional campaign reference stored on the conversation for audit and reporting. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: 'Controls what happens when no line of the Agent is free or recoverable. A free line always wins, then a line holding a released conversation with this Contact that can be recovered, whatever this flag says. When neither exists: with false (default) the request fails with 409 `BRIDGE_AI_LEADSCOUT_0008`; with true, a line occupied by an active conversation with this Contact is reused, preferring one this Agent controls. If the chosen conversation is held by another Agent or a Bridge User the request fails with 409 `BRIDGE_AI_AGENT_OUTBOUND_0006` and nothing is written; release it first, then retry. Lines whose conversation is blocked or was released without recovery are never used, so with no line occupied by an active conversation the request fails with 409 `BRIDGE_AI_LEADSCOUT_0008` even with true.' default: false examples: - false - true type: object required: - contact - template title: AgentOutboundRequest description: Request body for starting an outbound conversation answered by a given Agent. AgentOutboundResponse: properties: conversation: $ref: '#/components/schemas/ConversationResponse' title: Conversation description: 'The conversation the Agent now controls: newly created, reused (`alreadyInitiated`) or recovered (`recovered`).' contact: $ref: '#/components/schemas/ContactResponse' title: Contact description: The contact the conversation was initiated with. templateSent: anyOf: - $ref: '#/components/schemas/AgentTemplateSent' - type: 'null' title: Template Sent description: Summary of the template stored to open the conversation. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Count of follow-up messages persisted on the conversation. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: True when this request landed on a pre-existing conversation (forceSend=true reuse path); false when a fresh conversation was created. Informational only — the new template and follow-ups are persisted either way. default: false examples: - false - true recovered: type: boolean title: Recovered description: True when a released conversation the Contact had on the line was recovered instead of creating a new one. Recovery replaces the previous outbound context and `agentContext`. Recoverable lines are used even with `forceSend=false`. default: false examples: - false - true type: object required: - conversation - contact title: AgentOutboundResponse description: Response body for a successful Agent outbound initiation. AgentResponse: properties: id: type: string title: Agent Identifier description: Unique identifier of the Agent. name: type: string title: Name description: Name of the Agent. description: anyOf: - type: string - type: 'null' title: Description description: Description of the Agent. Always present; null when it has none. type: $ref: '#/components/schemas/AgentType' title: Type description: Kind of Agent. examples: - LEADSCOUT - SERVICE_AGENT brandId: anyOf: - type: string - type: 'null' title: Brand Identifier description: Brand the Agent belongs to. Always present; null when it is not scoped to a brand. status: $ref: '#/components/schemas/AgentConfigStatus' title: Status description: Configuration status of the Agent. examples: - DRAFT - COMPLETE available: type: boolean title: Available description: 'Whether the Agent can start conversations: its configuration is complete and it has a line.' unavailableReason: anyOf: - type: string - type: 'null' title: Unavailable Reason description: 'Why the Agent is not available: `DRAFT` (configuration incomplete) or `NO_LINES` (no active line). Always present; null when it is available.' examples: - DRAFT - NO_LINES lines: items: $ref: '#/components/schemas/AgentLine' type: array title: Lines description: Active WhatsApp lines the Agent answers on. Empty when it has none. type: object required: - id - name - type - status - available title: AgentResponse description: An Agent of the workspace with its status and availability. AgentTemplateSent: properties: id: anyOf: - type: string - type: 'null' title: Template Identifier description: Id of the template that was sent. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Name of the template that was dispatched. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: 'null' title: Message Identifier description: Bridge message id of the template. Always present; it is not a WhatsApp `wamid`. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - name title: AgentTemplateSent description: Summary of the template stored to open the conversation. AgentType: type: string enum: - LEADSCOUT - SERVICE_AGENT title: AgentType description: Kinds of Agent exposed by the public API. AgentsResponseList: properties: agents: items: $ref: '#/components/schemas/AgentResponse' type: array title: Agents description: Array of Agents. cursor: anyOf: - type: string - type: 'null' title: Cursor description: Cursor to be sent on the next page request. Null on the last page. type: object required: - agents title: AgentsResponseList description: Response body for listing the Agents of a workspace. ClosedAttribute: properties: id: type: string title: Identifier description: Unique closed attribute identifier examples: - 62de01f0-fd48-467c-9c35-18647c51532a value: anyOf: - type: string - type: 'null' title: Value description: Value of closed attributes type: object required: - id title: ClosedAttribute description: Object representing the closed attribute values. ClosedAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Unique closed custom attribute identifier. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 closedCustomAttributeIds: items: type: string type: array title: Closed Custom Attribute Identifiers description: List of unique closed attribute value identifiers. examples: - - 62de01f0-fd48-467c-9c35-18647c51532a - 6faf42bb-7d7b-44bd-9e79-5de6fd491134 type: object required: - customAttributeId - closedCustomAttributeIds title: ClosedAttributeRequest description: Request body for closed custom attributes operations. ConsentStatus: type: string enum: - GRANTED - NOT_PROVIDED title: ConsentStatus ContactResponse: properties: id: type: string title: Identifier description: Unique identifier for the contact (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Unique identifier of the workspace this contact belongs to examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 type: $ref: '#/components/schemas/ExternalUserType' title: Contact Type description: NORMAL when all required identity and custom attribute fields are present, PARTIAL otherwise. examples: - NORMAL - PARTIAL firstName: anyOf: - type: string - type: 'null' title: First Name description: Contact's first name. examples: - John - null lastName: anyOf: - type: string - type: 'null' title: Last Name description: Contact's last name. examples: - Doe - null email: anyOf: - type: string format: email - type: 'null' title: Email description: Contact's email address. examples: - john.doe@example.com - null cellphone: anyOf: - type: string format: phone - type: 'null' title: Cellphone description: Contact's cellphone address. examples: - '+14084029292' - null customAttributes: items: $ref: '#/components/schemas/CustomAttributeResponse' type: array title: Custom Attributes description: Array of custom key-value attributes. languageCode: anyOf: - $ref: '#/components/schemas/LanguageCode' - type: 'null' title: Language Code description: Language code from external user. examples: - EN - null ownerId: anyOf: - type: string - type: 'null' title: Owner Identifier description: Id of the Bridge User who owns this contact. Resolve it with `GET /users/{userId}`. examples: - 37673840-6259-40f9-bbe5-a7db40f8e3cf - null createdAt: type: string title: Created At description: Timestamp when the contact was created. examples: - '2003-04-10T08:00:00.000Z' updatedAt: type: string title: Updated At description: Timestamp when the contact was last updated. examples: - '2003-04-10T08:00:00.000Z' type: object required: - id - workspaceId - type - createdAt - updatedAt title: ContactResponse description: Response body for contact-related operations. ContactsResponseList: properties: contacts: items: $ref: '#/components/schemas/ContactResponse' type: array title: Contacts description: Array of contacts. cursor: anyOf: - type: string - type: 'null' title: Cursor description: Cursor to be send on next page. type: object required: - contacts title: ContactsResponseList description: Response body for listing contacts. ConversationListResponse: properties: conversations: items: $ref: '#/components/schemas/ConversationResponse' type: array title: Conversations description: List of conversations. cursor: anyOf: - type: string - type: 'null' title: Cursor description: Cursor for fetching the next page of conversations. Null if there are no more pages. examples: - null - eyJ2IjoxLCJjIjp7InN0IjoxfX0 type: object required: - conversations title: ConversationListResponse description: Response body for listing conversations with pagination. 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. 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. ConversationStatus: type: string enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED title: ConversationStatus CreateContactBody: properties: firstName: type: string title: First Name description: Contact's first name. examples: - John - Alice lastName: type: string title: Last Name description: Contact's last name. examples: - Doe email: anyOf: - type: string format: email - type: 'null' title: Email description: Contact's email address. examples: - john.doe@example.com - null languageCode: $ref: '#/components/schemas/LanguageCode' title: Language Code description: Contact's language code. examples: - EN cellphone: type: string title: Cellphone description: Contact's cellphone number. Without a country code it is read in the workspace's country. examples: - '+14084029292' ownerIdentifier: anyOf: - $ref: '#/components/schemas/InternalUserIdentifierRequest' - type: 'null' title: Owner Identifier description: Identifier of the salesperson or user who owns this contact. customAttributes: $ref: '#/components/schemas/CustomAttributesBody' title: Custom Attributes description: Object with open and closed custom attributes. additionalProperties: false type: object required: - firstName - lastName - languageCode - cellphone title: CreateContactBody description: Request body for creating a new contact. 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 onboardingTemplates: items: $ref: '#/components/schemas/OnboardingTemplateRequest' type: array title: Onboarding Templates description: 'Ordered templates to open the conversation with. They replace the workspace''s configured onboarding sequence for this conversation, either entirely or only its first template, depending on how the workspace is set up; in the second case the rest of the configured sequence is still sent after yours. Position implies order. Omit to keep the workspace default. Each template must exist, belong to your workspace or the platform scope, and — for WhatsApp provider templates — be approved by Meta for the WhatsApp Business Account behind the line each participant is reached on; otherwise the request is rejected and no conversation is created. A template whose variables need values only you can provide takes them in the entry''s `parameters`. If one of the configured templates sent after yours needs values only the caller can provide, the request is rejected with 422 `BRIDGE_CONVERSATION_0608`, with `extra.templateId` naming that template and `extra.origin` set to `WORKSPACE_CONFIGURATION`. Changing the request will not help: ask a workspace admin to change the onboarding sequence.' additionalProperties: false type: object required: - participants title: CreateConversationRequest description: Request body for creating a new conversation. CreatePartialContactBody: properties: cellphone: type: string title: Cellphone description: Contact's cellphone number. Without a country code it is read in the workspace's country. Used to identify the contact for upsert. examples: - '+14084029292' firstName: anyOf: - type: string - type: 'null' title: First Name description: Contact's first name. Required for NORMAL classification. examples: - Maria - null lastName: anyOf: - type: string - type: 'null' title: Last Name description: Contact's last name. Required for NORMAL classification. examples: - Lopez - null email: anyOf: - type: string format: email - type: 'null' title: Email description: Contact's email address. examples: - maria@acme.com - null languageCode: anyOf: - $ref: '#/components/schemas/LanguageCode' - type: 'null' title: Language Code description: Contact's language code. Required for NORMAL classification. examples: - EN - null ownerIdentifier: anyOf: - $ref: '#/components/schemas/InternalUserIdentifierRequest' - type: 'null' title: Owner Identifier description: Identifier of the salesperson or user who owns this contact. examples: - identifier: jane@acme.com identifierType: EMAIL - null customAttributes: $ref: '#/components/schemas/CustomAttributesBody' title: Custom Attributes description: Object with open and closed custom attributes. examples: - closedAttributes: [] openAttributes: [] additionalProperties: false type: object required: - cellphone title: CreatePartialContactBody description: Request body for partial contact creation. Only cellphone is required. 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. CustomAttributeResponse: properties: key: type: string title: Key description: Attribute key/name values: items: type: string type: array title: Values description: Attribute value type: object required: - key title: CustomAttributeResponse description: Response body for custom attributes in contact-related operations. CustomAttributes: properties: id: type: string title: Identifier description: Unique custom attribute identifier. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 category: type: string enum: - OPEN - CLOSED title: Category description: Category of custom attribute. examples: - OPEN - CLOSED isRequired: type: boolean title: Is Required description: Define if the custom attribute is required. examples: - true - false keyName: type: string title: Key Name description: Name of custom attribute. closedAttributesValues: anyOf: - items: $ref: '#/components/schemas/ClosedAttribute' type: array - type: 'null' title: Closed Attributes Values description: List of closed attribute values. type: type: string enum: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT title: Type description: Type of the values of custom attributes. examples: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT deletedAt: anyOf: - type: string - type: 'null' title: Deleted At description: Soft-delete timestamp. Null means the attribute is active. type: object required: - id - category - isRequired - keyName - type title: CustomAttributes description: Object representing the custom attribute. CustomAttributesBody: properties: openAttributes: anyOf: - items: $ref: '#/components/schemas/OpenAttributeRequest' type: array - type: 'null' title: Open Attributes description: Array of open attributes. closedAttributes: anyOf: - items: $ref: '#/components/schemas/ClosedAttributeRequest' type: array - type: 'null' title: Closed Attributes description: Array of closed attributes. type: object title: CustomAttributesBody description: Request body for custom attributes operations. CustomAttributesResponse: properties: customAttributes: items: $ref: '#/components/schemas/CustomAttributes' type: array title: Custom Attributes description: List of custom attributes objects with their values. type: object required: - customAttributes title: CustomAttributesResponse description: Response body for custom attributes operations. ExternalOperationRequest: properties: add: items: $ref: '#/components/schemas/ExternalUserIdentifierRequest' type: array title: Add description: External participants to add. remove: items: $ref: '#/components/schemas/ExternalUserIdentifierRequest' type: array title: Remove description: External participants to remove. type: object title: ExternalOperationRequest description: Operations for external participants in a conversation. 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. 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. brandId: anyOf: - type: string - type: 'null' title: Brand Identifier description: Brand that owns the corporate line used to reach the user. When the workspace has at least one branded line, automatic line selection stays inside this brand and the request must carry either brandId or providerChannelId; naming neither is rejected. Ignored when the workspace has no branded line. type: object required: - identifier - identifierType title: ExternalUserIdentifierRequest description: Body to identify an external user in Bridge System. ExternalUserType: type: string enum: - PARTIAL - NORMAL title: ExternalUserType FileType: type: string enum: - IMAGE - VIDEO - AUDIO - DOCUMENT - STICKER - GIF - WEBSITE title: FileType HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HandoffAssignee: properties: identifier: type: string title: Identifier description: ID value or email of the internal user, depending on identifierType. examples: - u-123 - ana@acme.com identifierType: $ref: '#/components/schemas/InternalParticipantIdentifierType' title: Identifier Type description: Lookup strategy for the internal user. Only ID and EMAIL are supported. examples: - ID - EMAIL additionalProperties: false type: object required: - identifier - identifierType title: HandoffAssignee description: An internal user to assign the conversation to during a handoff. HandoffRequest: properties: assignees: items: $ref: '#/components/schemas/HandoffAssignee' type: array minItems: 1 title: Assignees description: Internal users to hand the conversation off to. At least one is required. handoffMessages: items: type: string type: array title: Handoff Messages description: Optional message bodies posted as part of the handoff. includeAiLeadSummary: type: boolean title: Include AI Lead Summary description: When true, the handoff message should include an AI-generated summary of the lead. default: false additionalProperties: false type: object required: - assignees title: HandoffRequest description: Request body for a LeadScout manual handoff. HandoffResponse: properties: trackingId: type: string title: Tracking Identifier description: Correlation id generated for this handoff request. conversationId: type: string title: Conversation Identifier description: The conversation the handoff targets. status: type: string title: Status description: Acceptance status of the handoff request. examples: - ACCEPTED assignees: items: $ref: '#/components/schemas/HandoffAssignee' type: array title: Assignees description: Echo of the assignees received in the request. type: object required: - trackingId - conversationId - status - assignees title: HandoffResponse description: Response body acknowledging an accepted handoff request. HeaderFileType: type: string enum: - IMAGE - VIDEO - GIF title: HeaderFileType InternalOperationRequest: properties: add: items: $ref: '#/components/schemas/InternalUserIdentifierRequest' type: array title: Add description: Internal participants to add. remove: items: $ref: '#/components/schemas/InternalUserIdentifierRequest' type: array title: Remove description: Internal participants to remove type: object title: InternalOperationRequest description: Operations for internal participants in a 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. InternalParticipantIdentifierType: type: string enum: - ID - EMAIL title: InternalParticipantIdentifierType 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. InternalUserResponse: properties: id: type: string title: Identifier description: Unique identifier for the internal user (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 firstName: anyOf: - type: string - type: 'null' title: First Name description: Internal user's first name. examples: - John - null lastName: anyOf: - type: string - type: 'null' title: Last Name description: Internal user's last name. examples: - Doe - null email: anyOf: - type: string - type: 'null' title: Email description: Internal user's email address. examples: - john.doe@example.com - null cellphone: anyOf: - type: string - type: 'null' title: Cellphone description: Internal user's cellphone number. examples: - '+14084029292' - null languageCode: anyOf: - $ref: '#/components/schemas/LanguageCode' - type: 'null' title: Language Code description: Language code of the internal user. examples: - EN - null status: type: string enum: - active - disabled title: Status description: '''active'' when the internal user is live, ''disabled'' when the user has been removed.' examples: - active - disabled createdAt: type: string title: Created At description: Timestamp when the internal user was created. examples: - '2003-04-10T08:00:00.000Z' updatedAt: type: string title: Updated At description: Timestamp when the internal user was last updated. examples: - '2003-04-10T08:00:00.000Z' type: object required: - id - status - createdAt - updatedAt title: InternalUserResponse description: Response body for internal-user (human agent) read operations. InternalUsersResponseList: properties: users: items: $ref: '#/components/schemas/InternalUserResponse' type: array title: Users description: Array of internal users. cursor: anyOf: - type: string - type: 'null' title: Cursor description: Cursor to be sent on the next page request. type: object required: - users title: InternalUsersResponseList description: Response body for listing internal users. LanguageCode: type: string enum: - ES - EN - AF - SQ - AR - AZ - BN - BG - CA - ZH_CN - HR - CS - DA - NL - ET - FIL - FI - FR - KA - DE - EL - GU - HA - HE - HI - HU - ID - GA - IT - JA - KN - KK - RW_RW - KO - KY_KG - LO - LV - LT - MK - MS - ML - MR - NB - FA - PL - PT_BR - PA - RO - RU - SR - SK - SL - SW - SV - TA - TE - TH - TR - UK - UR - UZ - VI - ZU title: LanguageCode LeadscoutOutboundContactRef: properties: identifier: type: string title: Identifier description: Phone number in E.164 format identifying the contact. examples: - '+573001234567' identifierType: $ref: '#/components/schemas/ParticipantIdentifierType' title: Identifier Type description: Type of identifier. examples: - PHONE - EMAIL - ID messageProviderType: $ref: '#/components/schemas/MessageProviderType' title: Message Provider Type description: Provider used to deliver the template. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: 'null' title: Provider Channel Identifier description: Optional explicit WhatsApp channel id. If omitted, the workspace's single WhatsApp channel is used; in workspaces with multiple channels this field is required. examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: LeadscoutOutboundContactRef description: Identifies the lead the outbound conversation will target. LeadscoutOutboundHandoffOverride: properties: preAssignedUser: $ref: '#/components/schemas/LeadscoutOutboundPreAssignedUser' title: Pre-assigned User description: The internal user to assign as advisor when the AI hands off the conversation. Validated at request time — if the user does not exist, is inactive, or belongs to a different workspace, the request is rejected before any conversation is created. examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: LeadscoutOutboundHandoffOverride description: Overrides the default advisor assignment for the outbound conversation. LeadscoutOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Value that identifies the internal user, interpreted according to identifier_type. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: '#/components/schemas/InternalParticipantIdentifierType' title: Identifier Type description: How to resolve the identifier. ID looks up by internal user ID; EMAIL looks up by email address. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: LeadscoutOutboundPreAssignedUser description: Identifies the internal user who should receive the handoff. LeadscoutOutboundRequest: properties: contact: $ref: '#/components/schemas/LeadscoutOutboundContactRef' title: Contact description: The lead this outbound conversation targets. Must already exist in the workspace. template: $ref: '#/components/schemas/LeadscoutOutboundTemplateRef' title: Template description: The opening template to send. additionalMessages: items: $ref: '#/components/schemas/OutboundFollowUpRequest' type: array maxItems: 5 title: Additional Messages description: Up to five follow-up messages persisted on the conversation. They are not delivered immediately; the agent decides when to send them once the lead replies. agentContext: anyOf: - $ref: '#/components/schemas/OutboundAgentContextRequest' - type: 'null' title: Agent Context description: Optional notes and media stored on the conversation as context for the agent. consent: anyOf: - $ref: '#/components/schemas/OutboundConsentRequest' - type: 'null' title: Consent description: Optional tenant-affirmed opt-in evidence recorded on the conversation. handoffOverride: anyOf: - $ref: '#/components/schemas/LeadscoutOutboundHandoffOverride' - type: 'null' title: Handoff Override description: Optional override to pre-assign a specific internal user as the handoff advisor. Validated at request time; conversation creation is aborted if validation fails. brandId: anyOf: - type: string - type: 'null' title: Brand Identifier description: Optional brand id. When provided, only channels linked to this brand are eligible. Omit to consider every channel in the workspace. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: 'null' title: Campaign Identifier description: Optional campaign reference stored on the conversation for audit and reporting. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: 'When true, bypass all blockers on the chosen channel: any active conversation (AI-prospecting or human) is ignored and a fresh outbound is created. When no providerChannelId is supplied and every workspace channel is occupied, the first candidate is used instead of raising AllProviderChannelsOccupied. When false (default), an existing active conversation on the chosen channel returns 409.' default: false examples: - false - true type: object required: - contact - template title: LeadscoutOutboundRequest description: Request body for initiating a LeadScout outbound conversation. LeadscoutOutboundResponse: properties: conversation: $ref: '#/components/schemas/ConversationResponse' title: Conversation description: The newly created AI-controlled conversation. contact: $ref: '#/components/schemas/ContactResponse' title: Contact description: The contact the conversation was initiated with. templateSent: anyOf: - $ref: '#/components/schemas/LeadscoutTemplateSent' - type: 'null' title: Template Sent description: Summary of the dispatched template. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Count of follow-up messages persisted on the conversation. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: True when this request landed on a pre-existing conversation (forceSend=true reuse path); false when a fresh conversation was created. Informational only — the new template and follow-ups are persisted either way. default: false examples: - false - true recovered: type: boolean title: Recovered description: True when this request recovered a released conversation the contact had on the chosen channel instead of creating a fresh one. default: false examples: - false - true type: object required: - conversation - contact title: LeadscoutOutboundResponse description: Response body for a successful LeadScout outbound initiation. LeadscoutOutboundTemplateRef: properties: id: anyOf: - type: string - type: 'null' title: Template Identifier description: Id of the registered template (from GET /templates). When both id and name are sent, the id is used. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f - null name: anyOf: - type: string - type: 'null' title: Template Name description: Name of the registered Meta-approved template to send. Required when id is not sent; ignored when id is sent. examples: - leadscout_outbound_fb_v1 - null orderedParams: items: type: string type: array title: Ordered Parameters description: Caller-supplied values for the template's CALLER-source parameter slots, in position order. examples: - - Maria - ACME parameters: additionalProperties: type: string type: object title: Parameters description: Caller-supplied values keyed by the template's variable key (see GET /templates/{id} for the key inventory), covering both body and button slots. Prefer this over orderedParams for any template that has a dynamic button. An unknown key, or a key that overlaps a slot already covered by orderedParams, is rejected with 422. examples: - recipient_first_name: Maria tracking_code: TRK123 media: anyOf: - $ref: '#/components/schemas/OutboundTemplateMedia' - type: 'null' title: Header Media description: Optional header media (image/video) to attach to the template message. Accepts either a preloaded mediaId or a public url. type: object title: LeadscoutOutboundTemplateRef description: References the Meta-approved template that will open the conversation. LeadscoutTemplateSent: properties: id: anyOf: - type: string - type: 'null' title: Template Identifier description: Id of the template that was sent. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Name of the template that was dispatched. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: 'null' title: Message Identifier description: Meta wamid of the dispatched template. Null on the happy path until the send pipeline propagates the wamid back to the inbound API. examples: - null - wamid.HBgM... type: object required: - name title: LeadscoutTemplateSent description: Summary of the template dispatched to open the conversation. MessageProviderType: type: string enum: - WHATSAPP - SMS - TELEGRAM - INSTAGRAM - TWITTER - LINE - FACEBOOK - IMESSAGE - WHATSAPP_TEST - HEYGIA title: MessageProviderType MessageRequest: properties: conversationId: type: string title: Conversation Identifier description: Identifier of the conversation. examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 messageBody: type: string title: Message Body description: Body of the message. examples: - Hello, welcome to Bridge! replyToMessageId: anyOf: - type: string - type: 'null' title: Reply To Message Identifier description: Identifier of the message being replied to. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 - null enableExternalBroadcast: type: boolean title: Enable External Broadcast description: Flag to enable external broadcast. examples: - true - false mediaIds: items: type: string type: array title: Media Identifiers description: List of media IDs associated with the message. examples: - - a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6 type: object required: - conversationId - messageBody - enableExternalBroadcast title: MessageRequest description: Request body for creating a new message within a specified conversation. MessageResponse: properties: messagingProduct: type: string title: Messaging Product description: Product name. default: bridge examples: - bridge messageId: type: string title: Message Identifier description: Unique message identifier as a UUID string. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 type: object required: - messageId title: MessageResponse description: Response body for message-related operations. OnboardingTemplateRequest: properties: templateId: type: string title: Template Identifier description: Identifier of the system template to send. examples: - 4061e74e-f6fe-4072-a760-3aec0b64f7a6 parameters: additionalProperties: type: string maxLength: 1024 propertyNames: maxLength: 128 type: object maxProperties: 50 title: Template Parameters description: 'Values for this template''s variables, keyed by the variable `key` returned by `GET /templates/{templateId}`. Variables marked `callerMustSupply: true` are required: Bridge has no other source for them. The other variables are optional; a value sent for one (such as the Contact''s first name) replaces the per-Contact value and is used for every Contact in the conversation. Only WhatsApp provider templates accept parameters. If a required value is missing or blank, a key is not one of the template''s variables, or the template takes no parameters, the request is rejected with 422 and no conversation is created: `BRIDGE_CONVERSATION_0604` lists the missing variables in `extra.missingVariables` as `[{key, label}]`, `0605` lists the unknown keys in `extra.unknownKeys`, and `0606` names the template in `extra.templateId`. Values must also pass WhatsApp''s rules: no line breaks or tabs, no more than four consecutive spaces, the header with your value within 60 characters, a URL button''s link with your value within 2,000, and the body''s text plus your values within 1,024. Bridge refuses values it can already see break these rules with `BRIDGE_CONVERSATION_0607`, naming the template in `extra.templateId` and listing each offending value in `extra.invalidVariables` as `[{key, label, reason}]`. `reason` is the first rule the value breaks: `NEWLINE`, `TAB`, `CONSECUTIVE_SPACES`, `TOO_LONG` (header or URL button) or `BODY_TOO_LONG` (the body overflows, so every body value you sent is listed). Values Bridge fills in later, such as the Contact''s first name, also count toward the body limit, so leave room for them. At most 50 parameters per template, with keys up to 128 characters and each value up to 1,024.' examples: - delivery_date: 3 de octubre order_number: A-10492 additionalProperties: false type: object required: - templateId title: OnboardingTemplateRequest description: One entry of the onboarding override, its position in the list implying order. OpenAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Unique open custom attribute identifier. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 content: type: string title: Content description: Value of open attribute. type: object required: - customAttributeId - content title: OpenAttributeRequest description: Request body for open custom attributes operations. OutboundAgentContextRequest: properties: notes: anyOf: - type: string maxLength: 2000 - type: 'null' title: Notes description: Free-text notes for the agent, capped at 2000 characters. examples: - Lead asked about pricing tiers last week. - null mediaIds: items: type: string type: array title: Media Identifiers description: Optional preloaded-file identifiers persisted on the conversation as agent context. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: OutboundAgentContextRequest description: Notes and media stored on the conversation as agent context for the AI / human reviewer. OutboundConsentRequest: properties: status: $ref: '#/components/schemas/ConsentStatus' title: Status description: Tenant-affirmed consent state. Use GRANTED (with capturedAt) for explicit opt-in or NOT_PROVIDED when the tenant has no opt-in evidence to attest. examples: - GRANTED - NOT_PROVIDED capturedAt: anyOf: - type: string format: date-time - type: 'null' title: Captured At description: ISO8601 timestamp (with milliseconds) when consent was captured by the tenant. Required when status=GRANTED; null/omitted is accepted when status=NOT_PROVIDED. examples: - '2026-04-20T10:00:00.000Z' - null type: object required: - status title: OutboundConsentRequest description: Tenant-affirmed opt-in evidence recorded verbatim on the conversation. OutboundFollowUpRequest: properties: messageBody: type: string title: Message Body description: Plain-text body for the follow-up message. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: Optional preloaded-file identifiers to attach to the follow-up. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: OutboundFollowUpRequest description: A pre-loaded follow-up message persisted on the conversation alongside the opening template. OutboundTemplateMedia: properties: type: $ref: '#/components/schemas/HeaderFileType' title: Media Type description: Header media kind. Must match the template header type configured in Meta. examples: - IMAGE - VIDEO mediaId: anyOf: - type: string - type: 'null' title: Media Identifier description: UUID returned by /preloaded-files. Mutually exclusive with url. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f url: anyOf: - type: string - type: 'null' title: Source URL description: Public source URL fetched asynchronously via the URL file fetcher. Mutually exclusive with mediaId. examples: - null - https://cdn.example.com/promo.jpg type: object required: - type title: OutboundTemplateMedia description: 'Optional header media attached to the opening template message. Provide exactly one of ``mediaId`` (a UUID returned by ``POST /preloaded-files``) or ``url`` (a public source URL fetched asynchronously by the URL file fetcher).' ParticipantIdentifierType: type: string enum: - ID - EMAIL - PHONE title: ParticipantIdentifierType ParticipantOperationsRequest: properties: externals: anyOf: - $ref: '#/components/schemas/ExternalOperationRequest' - type: 'null' title: Externals description: External user operations, this should provided with "add" and "remove" operations. internals: anyOf: - $ref: '#/components/schemas/InternalOperationRequest' - type: 'null' title: Internals description: Internal user operations, this should provided with "add" and "remove" operations type: object title: ParticipantOperationsRequest description: Request body for participant operations when updating a conversation. PreloadedFileRequest: properties: name: type: string title: Name description: Original file name including extension. examples: - prueba.jpg fileType: $ref: '#/components/schemas/FileType' title: File Type description: Logical file type category. examples: - IMAGE - VIDEO - AUDIO - DOCUMENT contentType: anyOf: - type: string - type: 'null' title: Content Type description: MIME type of the file. examples: - image/jpeg - application/pdf - null checksumBase64: type: string title: Checksum Base64 description: Base64-encoded SHA-256 digest of the entire file. This value will be used to sign the presigned PUT and must be sent back in the header x-amz-checksum-sha256 during upload. examples: - OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= additionalProperties: false type: object required: - name - fileType - checksumBase64 title: PreloadedFileRequest description: Request for a file to be preloaded with a presigned URL. PreloadedFileResponse: properties: mediaId: type: string title: Media Identifier description: Unique media identifier. examples: - 4a2c1f7e-2f84-4a5f-bd2d-6b6b2f0c1234 presignUrl: $ref: '#/components/schemas/PresignPut' title: Presign Url description: Presigned PUT data to upload the media (url, method and headers). additionalProperties: false type: object required: - mediaId - presignUrl title: PreloadedFileResponse description: Response for a preloaded file with presigned URL for upload. PresignPut: properties: url: type: string title: Url description: Presigned PUT URL. examples: - https://s3.amazonaws.com/bucket/path/to/object method: type: string const: PUT title: Method description: HTTP method to use for the upload. default: PUT examples: - PUT headers: additionalProperties: type: string type: object title: Headers description: Headers required for the presigned PUT (e.g., Content-Type, x-amz-checksum-sha256). examples: - Content-Type: image/jpeg x-amz-checksum-sha256: OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= type: object required: - url title: PresignPut description: Presigned PUT data for uploading a media file. 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. ProviderChannel: properties: provider: $ref: '#/components/schemas/MessageProviderType' title: Provider description: Provider name of the messaging channel. examples: - WHATSAPP - HEYGIA identifier: type: string title: Identifier description: Identifier associated with this provider channel, in E.164 format without the '+' sign. type: object required: - provider - identifier title: ProviderChannel description: Provider channel associated in a workspace. ProviderChannelResponse: properties: workspaceId: type: string title: Workspace Identifier description: Unique identifier of the workspace (UUID v4). examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 providerChannels: items: $ref: '#/components/schemas/ProviderChannel' type: array title: Provider Channels description: List of provider channels (phone numbers) available for this workspace. type: object required: - workspaceId - providerChannels title: ProviderChannelResponse description: Response body for provider channels operations. ReleaseConversationBody: properties: reason: anyOf: - type: string - type: 'null' title: Reason description: Optional reason for releasing the conversation. examples: - The conversation is over - null type: object title: ReleaseConversationBody description: Body for POST release conversation. Optional reason. TemplateDiscoveryResponse: properties: id: type: string title: Id description: Unique identifier of the template. examples: - f0000040-0000-4000-8000-000000000040 name: type: string title: Name description: Name of the template, used to identify it when sending. examples: - order_shipped_promo language: type: string title: Language description: 'Language of the resolved pivot (the template''s default language), as Meta''s code: es, en, pt_BR.' examples: - es - pt_BR variables: items: $ref: '#/components/schemas/TemplateVariableResponse' type: array title: Variables description: Agnostic inventory of this template's variables. driftWarning: $ref: '#/components/schemas/TemplateDriftWarningResponse' title: Drift warning description: Diagnostic-only declaration-vs-snapshot mismatch. Never blocks a send. type: object required: - id - name - language - driftWarning title: TemplateDiscoveryResponse description: Agnostic inventory of a template's variables, for a caller that must send it without knowing Meta's model. examples: - id: f0000040-0000-4000-8000-000000000040 language: es name: order_shipped_promo variables: - callerMustSupply: false key: first_name label: Contact first name - callerMustSupply: false key: order_code label: Order code - callerMustSupply: false key: shipment_id label: Shipment ID - callerMustSupply: true key: promo_code label: Promo code TemplateDriftWarningResponse: properties: hasDrift: type: boolean title: Has drift stale: items: $ref: '#/components/schemas/TemplateVariableRef' type: array title: Stale description: Declared but no longer required by the snapshot. missingLabels: items: $ref: '#/components/schemas/TemplateVariableRef' type: array title: Missing labels description: Required by the snapshot but not yet declared. type: object required: - hasDrift title: TemplateDriftWarningResponse description: 'Diagnostic-only mismatch between the declared variables and what the Meta snapshot requires. Per the authority rule, this never affects whether a send succeeds — the snapshot alone decides that. It exists so a caller (or the console) can flag a template whose labels need refreshing after an edit made directly in WhatsApp Manager.' TemplateVariableRef: properties: key: type: string title: Key examples: - delivery_date label: type: string title: Label examples: - Delivery date type: object required: - key - label title: TemplateVariableRef description: A slot identified only by its agnostic key/label — no Meta slot address. TemplateVariableResponse: properties: key: type: string title: Key description: Agnostic identifier for this variable, stable across providers. examples: - tracking_code label: type: string title: Label description: Human-readable label for this variable. examples: - Tracking code callerMustSupply: type: boolean title: Caller must supply description: Whether the caller must supply a value for this variable when sending the template (true when the template has no declared source for it — e.g. a promo code only the caller knows; false when Bridge resolves it on its own, e.g. from the recipient's profile). examples: - true - false isCustom: type: boolean title: Is custom description: 'Whether this is a custom variable: a value only the caller knows, with a default text. The caller may send it in `parameters`; when it is left out or sent blank, `default` goes out.' default: false examples: - true - false default: anyOf: - type: string - type: 'null' title: Default description: For a custom variable, the text sent when the caller sends no value for it; null otherwise. examples: - pending - null type: object required: - key - label - callerMustSupply title: TemplateVariableResponse description: One template variable, identified by its agnostic key — no Meta slot address ever appears here. examples: - callerMustSupply: false isCustom: false key: first_name label: Contact first name - callerMustSupply: false default: pending isCustom: true key: tracking_code label: Tracking code - callerMustSupply: true isCustom: false key: promo_code label: Promo code UpdateContactBody: properties: firstName: anyOf: - type: string - type: 'null' title: First Name description: Contact's first name. examples: - John - null lastName: anyOf: - type: string - type: 'null' title: Last Name description: Contact's last name. examples: - Doe - null email: anyOf: - type: string format: email - type: 'null' title: Email description: Contact's email address. examples: - john.doe@example.com - null languageCode: anyOf: - $ref: '#/components/schemas/LanguageCode' - type: 'null' title: Language Code description: Contact's language code. examples: - EN cellphone: anyOf: - type: string - type: 'null' title: Cellphone description: Contact's cellphone number. Without a country code it is read in the workspace's country. examples: - '+14084029292' - null ownerIdentifier: anyOf: - $ref: '#/components/schemas/InternalUserIdentifierRequest' - type: 'null' title: Owner Identifier description: Identifier of the salesperson or user who owns this contact. customAttributes: $ref: '#/components/schemas/CustomAttributesBody' title: Custom Attributes description: Array of custom key-value attributes. additionalProperties: false type: object title: UpdateContactBody description: Request body for updating an existing contact. UpdateConversation: properties: name: anyOf: - type: string - type: 'null' title: Name description: Optional name/title for the conversation. examples: - Client Support - null status: anyOf: - $ref: '#/components/schemas/ConversationStatus' - type: 'null' title: Status description: Initial conversation status - 'active' for visible conversations, 'ghost' for invisible until first interaction. examples: - ACTIVE participants: anyOf: - $ref: '#/components/schemas/ParticipantOperationsRequest' - type: 'null' title: Participants description: Participants operations to add and remove from a conversation. additionalProperties: false type: object title: UpdateConversation description: Request body for updating an existing conversation. UserStatusFilter: type: string enum: - active - disabled - all title: UserStatusFilter UserType: type: string enum: - INTERNAL - EXTERNAL - BOT title: UserType 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 securitySchemes: x-api-key: type: apiKey description: Copy the API key as provided by the Bridge Console. in: header name: x-api-key