openapi: 3.1.0 info: title: Bridge API summary: Especificación de la API de Bridge para gestionar el sistema de chat. description: >- Especificación de la API REST de integraciones de Bridge para gestionar contactos, conversaciones, mensajes, archivos, atributos personalizados, canales de proveedores, plantillas, usuarios internos y Agents. Los webhooks se documentan por separado en https://docs.bridge.new/es/webhooks; este OpenAPI contiene únicamente endpoints REST. **Arquitectura multiempresa**: las operaciones sobre recursos se limitan a un workspace específico mediante workspaceId. La comprobación de estado no incluye un workspace en su ruta. 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: Servidor de producción paths: /bridge/api/health: get: tags: - Health summary: Comprobar estado description: Endpoint de comprobación de estado para verificar que la API esté en funcionamiento. operationId: health_bridge_api_health_get responses: "200": description: Respuesta satisfactoria content: application/json: schema: additionalProperties: true type: object title: Response Health Bridge Api Health Get "429": description: Demasiadas solicitudes 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: Obtener conversación por ID description: Obtiene una conversación específica por su identificador único dentro del 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único de la conversación (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único de la conversación (UUID v4). responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" patch: tags: - Conversations API summary: Actualizar conversación description: |- Actualiza los detalles de la conversación, incluidos los participantes, el estado y el nombre. Admite actualizaciones parciales: incluye solo los campos que quieras cambiar. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único de la conversación (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único de la conversación (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateConversation" description: Cuerpo de la solicitud para actualizar una conversación existente. responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/conversations: get: tags: - Conversations API summary: Consultar conversaciones con filtros flexibles description: >- Consulta conversaciones con opciones de filtrado flexibles. Permite buscar por identificadores de usuarios externos (ID, correo electrónico o teléfono) o por participantes internos, con paginación y filtrado por estado. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de conversaciones por página default: 20 title: Limit description: Número de conversaciones por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recibido en la solicitud anterior para obtener la página siguiente title: Cursor description: Cursor recibido en la solicitud anterior para obtener la página siguiente - name: status in: query required: false schema: anyOf: - type: string - type: "null" title: Status description: Estado de la conversación enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED description: Estado de la conversación - name: internalUserIdentifier in: query required: false schema: anyOf: - type: string - type: "null" description: >- Identificador del usuario interno. Si envías un número telefónico, codifica correctamente la URL de la solicitud, incluidos sus parámetros. title: Internaluseridentifier description: >- Identificador del usuario interno. Si envías un número telefónico, codifica correctamente la URL de la solicitud, incluidos sus parámetros. - 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: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ConversationListResponse" "400": description: Solicitud incorrecta 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: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" post: tags: - Conversations API summary: Crear conversación con identificación flexible de usuarios description: >- Crea una conversación con identificación flexible de usuarios. Los usuarios externos pueden identificarse por ID, correo electrónico o teléfono. Los usuarios internos solo se asignan cuando se indican explícitamente; de lo contrario, las conversaciones se asignan por turnos mediante un equipo o quedan abiertas para cualquier usuario interno disponible. Cuando no hay una línea libre y los Contacts tienen una conversación liberada con exactamente los participantes solicitados, se recupera y devuelve esa conversación, conservando su `id` e historial. No se le aplican el `name` ni el `status` de la solicitud. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateConversationRequest" description: Cuerpo de la solicitud para crear una conversación. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "400": description: Solicitud incorrecta 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: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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 PROVIDER_CHANNEL_NOT_FOUND: value: title: Provider Channel Not Found status: 409 code: BRIDGE_PROVIDER_CHANNEL_0001 EXTERNAL_USER_ALREADY_USE_THIS_CHANNEL: value: title: External User Already Use This Channel status: 409 code: BRIDGE_CONVERSATION_0105 schema: $ref: "#/components/schemas/Problem" "422": description: Contenido no procesable 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" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/release: post: tags: - Conversations API summary: Liberar conversación description: >- Libera una conversación: la marca como liberada, elimina los participantes externos y la mueve a la sección RELEASED. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único de la conversación (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único de la conversación (UUID v4). requestBody: content: application/json: schema: anyOf: - $ref: "#/components/schemas/ReleaseConversationBody" - type: "null" description: Cuerpo de POST para liberar una conversación. El motivo es opcional. title: Body responses: "204": description: Respuesta satisfactoria "400": description: Solicitud incorrecta 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" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/messages: post: tags: - Messages API summary: Crear mensaje description: >- Crea un mensaje en una conversación específica. Para un mensaje de texto o un adjunto cargado, incluye todos los campos obligatorios: `conversationId`, `messageBody` y `enableExternalBroadcast`. Adjunta los archivos cargados mediante los identificadores recibidos en `mediaIds`; consulta [Enviar un adjunto](/es/guides/send-attachments). Una respuesta satisfactoria devuelve `messageId`; no contiene un comprobante de entrega del proveedor. Consulta [Respuestas y reintentos](/es/guides/responses). 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageRequest" description: Cuerpo de la solicitud para crear un mensaje en una conversación específica. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/MessageResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/contacts/lookup: get: tags: - Contacts API summary: Obtener contacto por un identificador description: >- Obtiene un contacto específico por cualquiera de sus identificadores dentro del workspace. `type=ID` devuelve el mismo contacto que GET /contacts/{contactId}, la URL canónica de un contacto y la opción preferida cuando ya tienes su ID. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: type in: query required: true schema: $ref: "#/components/schemas/ParticipantIdentifierType" description: Tipo de identificador con el que se proporciona el valor. description: Tipo de identificador con el que se proporciona el valor. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: >- El identificador, en el formato indicado por `type`. Un `PHONE` se interpreta como el celular al escribir un contacto: si no incluye código de país, se usa el país predeterminado del workspace y se ignoran espacios y separadores. En un `EMAIL`, el dominio pasa a minúsculas, pero la parte local debe coincidir exactamente con lo enviado. title: Value description: >- El identificador, en el formato indicado por `type`. Un `PHONE` se interpreta como el celular al escribir un contacto: si no incluye código de país, se usa el país predeterminado del workspace y se ignoran espacios y separadores. En un `EMAIL`, el dominio pasa a minúsculas, pero la parte local debe coincidir exactamente con lo enviado. 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: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Contenido no procesable content: application/json: examples: INVALID_FIELD_FORMAT: value: title: Invalid Field Format status: 422 code: BRIDGE_CORE_0101 schema: $ref: "#/components/schemas/Problem" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/contacts/{contactId}: get: tags: - Contacts API summary: Obtener contacto por ID description: Obtiene un contacto específico por su identificador único dentro del 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: contactId in: path required: true schema: type: string format: uuid description: Identificador único del contacto (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Identificador único del contacto (UUID v4). responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" patch: tags: - Contacts API summary: Actualizar contacto description: Actualiza un contacto en el workspace indicado. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: contactId in: path required: true schema: type: string format: uuid description: Identificador único del contacto (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Identificador único del contacto (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateContactBody" description: Cuerpo de la solicitud para actualizar un contacto existente. responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "400": description: Solicitud incorrecta 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: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/contacts: get: tags: - Contacts API summary: Listar contactos description: >- Consulta una lista paginada de contactos del workspace. Se ordena por fecha de creación. Los filtros `ownerEmail` y `search` están obsoletos y se eliminarán; para encontrar un contacto por un identificador, usa /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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: ownerEmail in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Filtrar contactos por el correo electrónico del propietario title: Owneremail description: >- Filtra contactos por el correo electrónico del propietario. Obsoleto: se eliminará. No tiene reemplazo; filtra por `ownerId` en tu propio código. Consulta el historial de cambios. - name: search in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Buscar contactos por nombre, correo electrónico o celular example: John Doe title: Search description: >- Busca contactos por nombre, correo electrónico o celular. Obsoleto: se eliminará. Para encontrar un contacto por celular o correo electrónico, usa `GET /contacts/lookup`. Consulta el historial de cambios. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de contactos por página default: 20 title: Limit description: Número de contactos por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recibido en la solicitud anterior para obtener la página siguiente title: Cursor description: Cursor recibido en la solicitud anterior para obtener la página siguiente responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactsResponseList" "400": description: Solicitud incorrecta content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: "#/components/schemas/Problem" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" post: tags: - Contacts API summary: Crear contacto description: Crea un contacto en el workspace indicado. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateContactBody" description: Cuerpo de la solicitud para crear un contacto. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/contacts/partial: post: tags: - Contacts API summary: Crear o actualizar contacto description: Crea o actualiza un contacto usando solo el celular. Lo clasifica como NORMAL o 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePartialContactBody" description: Cuerpo de la solicitud para crear un contacto parcial. Solo cellphone es obligatorio. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/files: post: tags: - Files API summary: Crear cargas prefirmadas de archivos description: >- Carga un archivo adjunto, como un PDF, una imagen o un documento, antes de crear un mensaje. Esta operación devuelve los datos de un PUT prefirmado; los bytes del archivo se cargan por separado. Cuando la carga termine correctamente, utiliza el `mediaId` devuelto en la operación de envío. Sigue [Enviar un archivo adjunto](/es/guides/send-attachments) para los pasos de suma de comprobación, carga y mensaje. Genera URL prefirmadas para cargar archivos (Presigned PUT). Valida la extensión, contentType y los límites por tipo. La suma de comprobación es obligatoria: envía el resumen SHA-256 en checksumBase64 (Base64). La carga debe incluir la cabecera x-amz-checksum-sha256 con el mismo valor. --- Para cargar los archivos, DEBES utilizar la URL prefirmada devuelta con el método HTTP PUT. Carga el archivo exactamente en la URL indicada, sin modificaciones, tal como exige AWS S3 para un PUT con URL prefirmada. Consulta la documentación oficial de AWS S3: [Documentación de AWS S3 sobre Presigned PUT](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html). Incluye todas las cabeceras obligatorias indicadas en la respuesta, por ejemplo, 'x-amz-checksum-sha256' con el valor SHA-256 correcto. AWS rechazará la carga si no utilizas el método HTTP o las cabeceras correctos.
TipoExtensiónTipo de contenidoTamaño máximo
Imagen.jpegimage/jpeg16 MB
.jpgimage/jpeg
.pngimage/png
.webpimage/webp
GIF.gifimage/gif3 MB
.mp4video/mp4
Vídeo.avivideo/x-msvideo64 MB
.movvideo/quicktime
.mp4video/mp4
Audio.m4aaudio/mp416 MB
.mp3audio/mpeg
.oggaudio/ogg
.wavaudio/wav
Documento.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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/PreloadedFileRequest" description: Solicitud para preparar la carga de un archivo con una URL prefirmada. title: Preloaded Files responses: "201": description: Respuesta satisfactoria content: application/json: schema: type: array items: $ref: "#/components/schemas/PreloadedFileResponse" title: Response Create Preloaded Files Bridge Api V1 Workspaces Workspaceid Files Post "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/settings/attributes: get: tags: - Custom attributes API summary: Consultar atributos personalizados por workspaceId description: >- Devuelve los atributos personalizados del workspace indicado. De forma predeterminada, solo devuelve atributos **activos** (sin un `deletedAt` en el pasado). **Filtros:** - `category`: filtra por `OPEN` o `CLOSED`. Omítelo para devolver todas las categorías. - `includeArchived`: usa `true` para incluir atributos archivados (con `deletedAt` en el pasado). Predeterminado: `false`. - `isRequired`: usa `true` para devolver solo atributos obligatorios y `false` para devolver solo opcionales. Omítelo para devolver todos. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: category in: query required: false schema: anyOf: - enum: - OPEN - CLOSED type: string - type: "null" description: Filtrar por categoría de atributo. Omítelo para devolver todas las categorías. title: Category description: Filtrar por categoría de atributo. Omítelo para devolver todas las categorías. - name: includeArchived in: query required: false schema: type: boolean description: >- Con `true`, se incluyen los atributos archivados (con `deletedAt` en el pasado). El valor predeterminado es `false`, que solo devuelve atributos activos. default: false title: Includearchived description: >- Con `true`, se incluyen los atributos archivados (con `deletedAt` en el pasado). El valor predeterminado es `false`, que solo devuelve atributos activos. - name: isRequired in: query required: false schema: anyOf: - type: boolean - type: "null" description: >- Filtrar por obligatoriedad. `true` devuelve solo los obligatorios y `false` solo los opcionales. Omítelo para devolver todos. title: Isrequired description: >- Filtrar por obligatoriedad. `true` devuelve solo los obligatorios y `false` solo los opcionales. Omítelo para devolver todos. responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/CustomAttributesResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/provider-channels: get: tags: - Provider channels API summary: Obtener canales de proveedores por workspace description: >- Obtiene los canales de proveedores por identificador de workspace. Esta respuesta expone `provider` e `identifier`, similar a un número telefónico, para cada canal; no devuelve `providerChannelId`. Para las líneas de un Agent, lee `agents[].lines[].providerChannelId` en la lista de Agents. No sustituyas un ID de canal por un número telefónico. Consulta [Conceptos e identificadores](/es/guides/identifiers). 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ProviderChannelResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/provider-channels/{messageProviderType}: get: tags: - Provider channels API summary: Obtener canales por workspace y tipo de proveedor description: Obtiene los canales de proveedores por identificador de workspace y tipo de proveedor. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: messageProviderType in: path required: true schema: $ref: "#/components/schemas/MessageProviderType" description: Tipo de proveedor de mensajería (por ejemplo, WHATSAPP o HEYGIA). description: Tipo de proveedor de mensajería (por ejemplo, WHATSAPP o HEYGIA). - name: brandId in: query required: false schema: anyOf: - type: string - type: "null" description: >- Identificador opcional de marca. Si se proporciona, solo devuelve canales cuya línea corporativa pertenece a esa marca. Solo se aplica a WHATSAPP; los proveedores HEYGIA no tienen marca. title: Brandid description: >- Identificador opcional de marca. Si se proporciona, solo devuelve canales cuya línea corporativa pertenece a esa marca. Solo se aplica a WHATSAPP; los proveedores HEYGIA no tienen marca. responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/ProviderChannelResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound: post: tags: - LeadScout API summary: Iniciar conversación saliente de LeadScout con un lead conocido description: >- Inicia una conversación saliente de LeadScout con un Contact conocido. El Contact debe existir previamente. Bridge selecciona un Agent de prospección para una línea de WhatsApp apta. La plantilla se referencia mediante template.id o template.name; id tiene prioridad si se proporcionan ambos. Debe existir y estar APPROVED, y cualquier Bridge User de handoffOverride debe ser válido. Se respeta un contact.providerChannelId explícito. Sin él, la selección automática prefiere una línea libre, después una conversación liberada recuperable con este Contact y, por último, una conversación activa ocupada solo cuando forceSend=true. La disponibilidad se evalúa por Contact en cada línea, no por la ocupación global de la línea. forceSend=true reutiliza una conversación activa apta; no la ignora ni crea una nueva. Una reutilización exitosa devuelve alreadyInitiated=true y persiste la nueva plantilla y los seguimientos. Una conversación liberada recuperable se puede recuperar con cualquiera de los dos valores, conserva su ID y devuelve recovered=true. Esta opción no habilita las conversaciones bloqueadas ni las liberadas no recuperables. La ruta heredada puede reutilizar una conversación controlada por un humano u otro Agent; a diferencia del envío saliente de Agents, no exige la comprobación de control por el Agent solicitado. Una sesión abierta de LeadScout que no haya vencido sigue bloqueando una nueva solicitud saliente con 409 BRIDGE_AI_LEADSCOUT_0017; si no se puede finalizar una sesión vencida, devuelve 409 BRIDGE_AI_LEADSCOUT_0018. Las demás validaciones siguen vigentes. Los mensajes adicionales se persisten; persistirlos no demuestra su entrega ni que se espere la respuesta del lead. Una solicitud fallida puede dejar trabajo parcial, por lo que no debes tratar forceSend como idempotencia ni reintentar a ciegas un resultado incierto. Consulta [la guía completa de envío saliente](/es/guides/agent-outbound) para la matriz false/true, los indicadores de respuesta, las diferencias con el envío saliente de Agents, los errores y la transferencia. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/LeadscoutOutboundRequest" description: Cuerpo de la solicitud para iniciar una conversación saliente de LeadScout. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/LeadscoutOutboundResponse" "400": description: Solicitud incorrecta 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: No encontrado 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: Conflicto 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" "422": description: Contenido no procesable 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" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" "500": description: Error interno del servidor content: application/json: examples: CONVERSATION_OPERATION_FAILED: value: title: Conversation Operation Failed status: 500 code: BRIDGE_AI_LEADSCOUT_0015 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/leadscout/conversations/{conversationId}/handoff: post: tags: - LeadScout API summary: Solicitar transferencia manual de LeadScout a usuarios internos description: >- Solicita la transferencia manual de una conversación controlada por LeadScout a uno o más usuarios internos. La solicitud se confirma con `202 Accepted`; la asignación se procesa de forma asíncrona. La respuesta repite los destinatarios solicitados y un ID de seguimiento para correlación. La resolución de usuarios internos (por ID o EMAIL) ocurre después y no se refleja en esta respuesta. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: conversationId in: path required: true schema: type: string description: Identificador único de la conversación (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único de la conversación (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/HandoffRequest" description: Cuerpo de la solicitud de transferencia manual de LeadScout. responses: "202": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/HandoffResponse" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/templates/{templateId}: get: tags: - Templates API summary: Descubrir las variables agnósticas de una plantilla description: >- Devuelve las variables de una plantilla: `key`/`label`/`callerMustSupply`/`isCustom`/`default`, independientes de la ubicación en Meta. Nunca devuelve la dirección o el índice de una posición de Meta. `templateId` acepta el `id` o el `name` de la plantilla. Las operaciones salientes aceptan `template.id` o `template.name`, con prioridad para un id no vacío. El inicio de conversaciones utiliza `onboardingTemplates[].templateId`. Utiliza el selector que exige la operación de envío. Consulta [la receta de plantillas](/es/guides/send-template). Una variable con `callerMustSupply: true` no tiene una fuente declarada: quien llama debe incluir su `key` en `parameters` al enviar; de lo contrario, el envío falla con un 422 que identifica ese mismo `key`. Una variable con `callerMustSupply: false` la resuelve Bridge por su cuenta, por ejemplo, el nombre del destinatario, o ya tiene un valor que quien llama puede sobrescribir opcionalmente. Una variable con `isCustom: true` es un valor que solo conoce quien llama y tiene un `default`: envíala en `parameters` para usar tu propio valor, u omítela o déjala en blanco para enviar `default`. Códigos de error: - BRIDGE_CORE_0301: el workspace de la ruta no coincide con el workspace de quien llama (403) - BRIDGE_TEMPLATE_0001: no se encontró una PROVIDER_TEMPLATE para este workspace e identificador. Incluye por igual un id/name desconocido, una plantilla de otro workspace y una plantilla que no es PROVIDER_TEMPLATE (404); este endpoint nunca confirma la existencia de una plantilla fuera del workspace de quien llama 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: templateId in: path required: true schema: type: string description: "ID o nombre de la plantilla: ambos identifican la misma plantilla." examples: - order_shipped_promo - f0000040-0000-4000-8000-000000000040 title: Templateid description: "ID o nombre de la plantilla: ambos identifican la misma plantilla." responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/TemplateDiscoveryResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/users/lookup: get: tags: - Internal Users API summary: Obtener usuario interno por un identificador description: >- Obtiene un Bridge User específico por cualquiera de sus identificadores dentro del workspace. `type=ID` devuelve el mismo usuario que GET /users/{userId}, la URL canónica de un usuario interno y la opción preferida cuando ya tienes su ID. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: type in: query required: true schema: $ref: "#/components/schemas/InternalParticipantIdentifierType" description: >- Tipo de identificador con el que se proporciona el valor. El celular de un usuario interno no es una opción. description: >- Tipo de identificador con el que se proporciona el valor. El celular de un usuario interno no es una opción. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: >- El identificador, en el formato indicado por `type`. En un `EMAIL`, el dominio pasa a minúsculas, pero la parte local debe coincidir exactamente con lo enviado. title: Value description: >- El identificador, en el formato indicado por `type`. En un `EMAIL`, el dominio pasa a minúsculas, pero la parte local debe coincidir exactamente con lo enviado. 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: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/InternalUserResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Contenido no procesable content: application/json: examples: INVALID_FIELD_FORMAT: value: title: Invalid Field Format status: 422 code: BRIDGE_CORE_0101 schema: $ref: "#/components/schemas/Problem" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/users/{userId}: get: tags: - Internal Users API summary: Obtener usuario interno por ID description: Obtiene un usuario interno específico (agente humano) por su identificador único dentro del 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: userId in: path required: true schema: type: string format: uuid description: Identificador único del usuario interno (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Userid description: Identificador único del usuario interno (UUID v4). responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/InternalUserResponse" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/users: get: tags: - Internal Users API summary: Listar usuarios internos description: >- Consulta una lista paginada de usuarios internos del workspace. Se ordena por fecha de creación. Los filtros `email` y `status` están obsoletos y se eliminarán; para encontrar un usuario interno por un identificador, usa /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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: email in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Filtrar usuarios internos por correo electrónico exacto. example: john.doe@example.com title: Email description: >- Filtra usuarios internos por correo electrónico exacto. Obsoleto: se eliminará. Usa `GET /users/lookup?type=EMAIL`. Consulta el historial de cambios. - name: status in: query required: false deprecated: true schema: $ref: "#/components/schemas/UserStatusFilter" description: "Filtrar por estado: 'active' (predeterminado), 'disabled' o 'all'." default: active description: >- Filtra por estado: 'active' (predeterminado), 'disabled' o 'all'. Obsoleto: se eliminará. Lee `status` en cada fila. Consulta el historial de cambios. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de usuarios internos por página default: 20 title: Limit description: Número de usuarios internos por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recibido en una solicitud anterior para obtener la página siguiente title: Cursor description: Cursor recibido en una solicitud anterior para obtener la página siguiente responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/InternalUsersResponseList" "400": description: Solicitud incorrecta content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: "#/components/schemas/Problem" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado content: application/json: examples: WORKSPACE_NOT_FOUND: value: title: Workspace Not Found status: 404 code: BRIDGE_WORKSPACE_0001 schema: $ref: "#/components/schemas/Problem" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/agents: get: tags: - Agents API summary: Listar los Agents de un workspace description: >- Lista los Agents del workspace con su estado, disponibilidad y líneas. Incluye todos los Agents, cualquiera que sea su estado; `available` indica si pueden iniciar conversaciones. Una página puede contener menos elementos que `limit`; sigue paginando mientras `cursor` no sea 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: type in: query required: false schema: anyOf: - $ref: "#/components/schemas/AgentType" - type: "null" description: Devuelve solo Agents de este tipo. title: Type description: Devuelve solo Agents de este tipo. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de Agents por página default: 20 title: Limit description: Número de Agents por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recibido en una solicitud anterior para obtener la página siguiente title: Cursor description: Cursor recibido en una solicitud anterior para obtener la página siguiente responses: "200": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/AgentsResponseList" "400": description: Solicitud incorrecta content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_AI_AGENT_OUTBOUND_0007 schema: $ref: "#/components/schemas/Problem" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Error de validación content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 schema: $ref: "#/components/schemas/Problem" /bridge/api/v1/workspaces/{workspaceId}/agents/{agentId}/outbound: post: tags: - Agents API summary: Iniciar conversación saliente con un Contact como Agent específico description: >- Inicia una conversación saliente con un Contact conocido, atendida por el Agent indicado. Funciona con Agents LeadScout y Service. Primero se resuelve el Contact y después el Agent, que debe existir en el workspace y estar disponible (consulta `GET /agents`). La plantilla se referencia mediante `template.id` o `template.name` (id tiene prioridad si se envían ambos), debe existir y estar APPROVED, y cualquier Bridge User de `handoffOverride` debe ser válido. Si `template.media.mediaId` es desconocido, la solicitud falla con 400 `BRIDGE_AI_LEADSCOUT_0016` solo después de crear o recuperar la conversación, por lo que un reintento tras ese error puede responder de otra manera. Las reglas del cuerpo (`consent.status=GRANTED` sin `capturedAt`, o `template.media` sin exactamente uno de `mediaId` o `url`) fallan con 400 `BRIDGE_CORE_0103`. La conversación se abre en una de las líneas activas de WhatsApp del Agent, bajo su control, con la plantilla como primer mensaje. Se elige una línea en este orden: - Una línea libre. - En su defecto, una línea con una conversación liberada recuperable con este Contact. La recuperación devuelve `recovered=true` y reemplaza el contexto saliente anterior y `agentContext`. Esto ocurre incluso con `forceSend=false`. - Si ninguna línea está libre o es recuperable: `forceSend=false` (predeterminado) falla con 409 `BRIDGE_AI_LEADSCOUT_0008`; `forceSend=true` reutiliza una línea ocupada por una conversación activa con este Contact, dando preferencia a una que controle este Agent. Si la conversación elegida está controlada por otro Agent o un Bridge User, la llamada falla con 409 `BRIDGE_AI_AGENT_OUTBOUND_0006` y no se escribe nada. Libérala primero y reintenta después. Nunca se usan líneas cuya conversación esté bloqueada o se haya liberado sin recuperación, por lo que, si ninguna línea está ocupada por una conversación activa, la llamada falla con 409 `BRIDGE_AI_LEADSCOUT_0008` incluso con `forceSend=true`. `contact.providerChannelId` es una preferencia: la línea indicada se usa cuando está libre o es recuperable; de lo contrario, se aplica el mismo orden entre todas las líneas del Agent. Entre las líneas ocupadas, tiene prioridad una que controle este Agent; si no existe, se reutiliza la línea indicada (y puede fallar con 0006). La reutilización de una conversación depende del tipo de Agent: - LeadScout: si su sesión de LeadScout sigue abierta y no ha vencido, la llamada falla con 409 `BRIDGE_AI_LEADSCOUT_0017` (`extra` incluye `conversationId`, `sessionId` y `stage`). Si no se puede finalizar una sesión vencida, falla con 409 `BRIDGE_AI_LEADSCOUT_0018`. - Service Agent: se continúa una sesión de servicio abierta que no haya vencido; una sesión vencida se cierra como abandonada y se abre una nueva. Consulta [la guía completa de envío saliente](/es/guides/agent-outbound) para los requisitos, la tabla de decisión de forceSend, la recuperación, el trabajo parcial y las decisiones de reintento seguro. 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: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único del workspace (UUID v4). - name: agentId in: path required: true schema: type: string format: uuid description: Identificador único del Agent (UUID v4), según `GET /agents`. examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Agentid description: Identificador único del Agent (UUID v4), según `GET /agents`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AgentOutboundRequest" description: >- Cuerpo de la solicitud para iniciar una conversación saliente atendida por un Agent específico. responses: "201": description: Respuesta satisfactoria content: application/json: schema: $ref: "#/components/schemas/AgentOutboundResponse" "400": description: Solicitud incorrecta 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" "403": description: Acceso prohibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: No encontrado 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: Conflicto 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: Contenido no procesable 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" "429": description: Demasiadas solicitudes content: application/json: examples: WORKSPACE_BUDGET_EXHAUSTED: value: title: Too Many Requests status: 429 code: BRIDGE_RATE_LIMIT_0001 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: >- Identificador de la línea (el mismo valor que recibe `providerChannelId` en las operaciones salientes). type: object required: - providerChannelId title: AgentLine description: Línea de WhatsApp en la que responde un Agent. AgentOutboundContactRef: properties: identifier: type: string title: Identifier description: >- Identificador del Contact según identifierType: ID de Contact para ID, correo electrónico para EMAIL o teléfono en formato E.164 para PHONE. El Contact ya debe existir en el workspace. examples: - "+573001234567" identifierType: $ref: "#/components/schemas/ParticipantIdentifierType" title: Identifier Type description: Tipo de identificador. examples: - PHONE - EMAIL - ID messageProviderType: $ref: "#/components/schemas/MessageProviderType" title: Message Provider Type description: Proveedor utilizado para entregar la plantilla. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: >- Opcional. Línea preferida del Agent (el `providerChannelId` de una de sus `lines` en `GET /agents`). Si se omite, se puede usar cualquiera de sus líneas. Si se proporciona, debe ser una línea activa del Agent; de lo contrario, la solicitud falla con 422. Es una preferencia, no una garantía: si esa línea no está libre ni es recuperable, se aplica el mismo orden a todas las líneas del Agent (con `forceSend=true`, primero una ocupada que controle este Agent y luego la indicada). La respuesta no identifica la línea utilizada. examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: AgentOutboundContactRef description: Identifica el Contact al que se dirigirá la conversación saliente. AgentOutboundContext: properties: notes: anyOf: - type: string maxLength: 2000 - type: "null" title: Notes description: Notas de texto libre para el Agent, limitadas a 2000 caracteres. examples: - The Contact asked about pricing tiers last week. - null mediaIds: items: type: string type: array title: Media Identifiers description: >- Identificadores opcionales de archivos precargados guardados en la conversación como contexto para el Agent. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: AgentOutboundContext description: Notas y medios guardados en la conversación como contexto para el Agent y los Bridge Users. AgentOutboundFollowUp: properties: messageBody: type: string title: Message Body description: Cuerpo de texto plano del mensaje de seguimiento. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: >- Se acepta, pero aún no se utiliza: los seguimientos se guardan solo como texto y no se envían adjuntos. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: AgentOutboundFollowUp description: Seguimiento de texto guardado en la conversación inmediatamente después de la plantilla inicial. AgentOutboundHandoffOverride: properties: preAssignedUser: $ref: "#/components/schemas/AgentOutboundPreAssignedUser" title: Pre-assigned User description: >- Bridge User que se asignará como asesor cuando el Agent transfiera la conversación. Se valida durante la solicitud: esta se rechaza si el usuario no existe, pertenece a otro workspace o se eliminó. examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: AgentOutboundHandoffOverride description: Preasigna el Bridge User que recibe la transferencia de la conversación saliente. AgentOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Valor que identifica al Bridge User, interpretado según identifierType. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: >- Cómo resolver el identificador. ID busca por ID de Bridge User; EMAIL busca por correo electrónico. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: AgentOutboundPreAssignedUser description: Identifica al Bridge User que debe recibir la transferencia. AgentOutboundRequest: properties: contact: $ref: "#/components/schemas/AgentOutboundContactRef" title: Contact description: Contact al que se dirige esta conversación saliente. Ya debe existir en el workspace. template: $ref: "#/components/schemas/LeadscoutOutboundTemplateRef" title: Template description: Plantilla inicial que se enviará. additionalMessages: items: $ref: "#/components/schemas/AgentOutboundFollowUp" type: array maxItems: 5 title: Additional Messages description: >- Hasta cinco seguimientos de texto guardados en la conversación después de la plantilla inicial, en el orden indicado, y enviados como la plantilla. Los adjuntos (`mediaIds`) aún no se envían. agentContext: anyOf: - $ref: "#/components/schemas/AgentOutboundContext" - type: "null" title: Agent Context description: Notas y medios opcionales guardados en la conversación como contexto para el Agent. consent: anyOf: - $ref: "#/components/schemas/OutboundConsentRequest" - type: "null" title: Consent description: >- Evidencia opcional de consentimiento, declarada por la empresa, que se registra en la conversación. handoffOverride: anyOf: - $ref: "#/components/schemas/AgentOutboundHandoffOverride" - type: "null" title: Handoff Override description: >- Opcional. Preasigna un Bridge User específico como asesor para la transferencia. El Bridge User se valida antes de cualquier escritura: se rechaza la solicitud si el usuario no existe, pertenece a otro workspace o se eliminó. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- ID opcional de marca. Si se indica, solo son elegibles las líneas del Agent vinculadas a esa marca; si no hay ninguna, la solicitud falla con 404. Omítelo para considerar todas las líneas del Agent. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: "null" title: Campaign Identifier description: Referencia opcional de campaña guardada en la conversación para auditoría e informes. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: >- Controla qué ocurre cuando ninguna línea del Agent está libre o es recuperable. Siempre tiene prioridad una línea libre, seguida de una línea con una conversación liberada recuperable con este Contact, sea cual sea el valor de esta opción. Cuando ninguna existe: con false (predeterminado), la solicitud falla con 409 `BRIDGE_AI_LEADSCOUT_0008`; con true, se reutiliza una línea ocupada por una conversación activa con este Contact, dando preferencia a una que controle este Agent. Si la conversación elegida está controlada por otro Agent o por un Bridge User, la solicitud falla con 409 `BRIDGE_AI_AGENT_OUTBOUND_0006` y no se escribe nada; libérala primero y reintenta después. Nunca se usan líneas cuya conversación esté bloqueada o se haya liberado sin recuperación; por tanto, si ninguna línea está ocupada por una conversación activa, la solicitud falla con 409 `BRIDGE_AI_LEADSCOUT_0008` incluso con true. default: false examples: - false - true type: object required: - contact - template title: AgentOutboundRequest description: Cuerpo de la solicitud para iniciar una conversación saliente atendida por un Agent específico. AgentOutboundResponse: properties: conversation: $ref: "#/components/schemas/ConversationResponse" title: Conversation description: >- Conversación que ahora controla el Agent: nueva, reutilizada (`alreadyInitiated`) o recuperada (`recovered`). contact: $ref: "#/components/schemas/ContactResponse" title: Contact description: Contacto con el que se inició la conversación. templateSent: anyOf: - $ref: "#/components/schemas/AgentTemplateSent" - type: "null" title: Template Sent description: Resumen de la plantilla guardada para abrir la conversación. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Número de mensajes de seguimiento guardados en la conversación. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: >- True cuando esta solicitud satisfactoria reutilizó una conversación activa existente mediante forceSend=true. False para creación o recuperación; consulta recovered para distinguir esas rutas. Es informativo: una reutilización satisfactoria también guarda la nueva plantilla y los seguimientos, por lo que repetir la solicitud puede agregar mensajes. default: false examples: - false - true recovered: type: boolean title: Recovered description: >- True cuando se recuperó una conversación liberada que el Contact tenía en la línea, en lugar de crear otra. La recuperación reemplaza el contexto saliente anterior y `agentContext`. Las líneas recuperables se usan incluso con `forceSend=false`. default: false examples: - false - true type: object required: - conversation - contact title: AgentOutboundResponse description: Cuerpo de respuesta de un inicio saliente de Agent satisfactorio. AgentResponse: properties: id: type: string title: Agent Identifier description: Identificador único del Agent. name: type: string title: Name description: Nombre del Agent. description: anyOf: - type: string - type: "null" title: Description description: Descripción del Agent. Siempre está presente; es null cuando no tiene descripción. type: $ref: "#/components/schemas/AgentType" title: Type description: Tipo de Agent. examples: - LEADSCOUT - SERVICE_AGENT brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: Marca a la que pertenece el Agent. Siempre está presente; es null cuando no se limita a una marca. status: $ref: "#/components/schemas/AgentConfigStatus" title: Status description: Estado de configuración del Agent. examples: - DRAFT - COMPLETE available: type: boolean title: Available description: "Indica si el Agent puede iniciar conversaciones: su configuración está completa y tiene una línea." unavailableReason: anyOf: - type: string - type: "null" title: Unavailable Reason description: >- Motivo por el que el Agent no está disponible: `DRAFT` (configuración incompleta) o `NO_LINES` (sin línea activa). Siempre está presente; es null cuando está disponible. examples: - DRAFT - NO_LINES lines: items: $ref: "#/components/schemas/AgentLine" type: array title: Lines description: Líneas activas de WhatsApp en las que responde el Agent. Vacío cuando no tiene ninguna. type: object required: - id - name - type - status - available title: AgentResponse description: Agent del workspace con su estado y disponibilidad. AgentTemplateSent: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID de la plantilla enviada. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Nombre de la plantilla despachada. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: "null" title: Message Identifier description: ID de mensaje de Bridge de la plantilla. Siempre está presente; no es un `wamid` de WhatsApp. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - name title: AgentTemplateSent description: Resumen de la plantilla guardada para abrir la conversación. AgentType: type: string enum: - LEADSCOUT - SERVICE_AGENT title: AgentType description: Tipos de Agent expuestos por la API pública. AgentsResponseList: properties: agents: items: $ref: "#/components/schemas/AgentResponse" type: array title: Agents description: Lista de Agents. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor que se enviará al solicitar la página siguiente. Es null en la última página. type: object required: - agents title: AgentsResponseList description: Cuerpo de respuesta para listar los Agents de un workspace. ClosedAttribute: properties: id: type: string title: Identifier description: Identificador único de atributo cerrado examples: - 62de01f0-fd48-467c-9c35-18647c51532a value: anyOf: - type: string - type: "null" title: Value description: Valor de los atributos cerrados type: object required: - id title: ClosedAttribute description: Objeto que representa los valores de atributos cerrados. ClosedAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Identificador único del atributo personalizado cerrado. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 closedCustomAttributeIds: items: type: string type: array title: Closed Custom Attribute Identifiers description: Lista de identificadores únicos de valores de atributos cerrados. examples: - - 62de01f0-fd48-467c-9c35-18647c51532a - 6faf42bb-7d7b-44bd-9e79-5de6fd491134 type: object required: - customAttributeId - closedCustomAttributeIds title: ClosedAttributeRequest description: Cuerpo de la solicitud para operaciones de atributos personalizados cerrados. ConsentStatus: type: string enum: - GRANTED - NOT_PROVIDED title: ConsentStatus ContactResponse: properties: id: type: string title: Identifier description: Identificador único del contacto (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Identificador único del workspace al que pertenece este contacto examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 type: $ref: "#/components/schemas/ExternalUserType" title: Contact Type description: >- NORMAL cuando están presentes todos los campos obligatorios de identidad y atributos personalizados; PARTIAL en caso contrario. examples: - NORMAL - PARTIAL firstName: anyOf: - type: string - type: "null" title: First Name description: Nombre del contacto. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Apellido del contacto. examples: - Doe - null email: anyOf: - type: string format: email - type: "null" title: Email description: Correo electrónico del contacto. examples: - john.doe@example.com - null cellphone: anyOf: - type: string format: phone - type: "null" title: Cellphone description: Número de celular del contacto. examples: - "+14084029292" - null customAttributes: items: $ref: "#/components/schemas/CustomAttributeResponse" type: array title: Custom Attributes description: Lista de atributos personalizados de clave y valor. languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma del usuario externo. examples: - EN - null ownerId: anyOf: - type: string - type: "null" title: Owner Identifier description: ID del Bridge User propietario del contacto. Resuélvelo con `GET /users/{userId}`. examples: - 37673840-6259-40f9-bbe5-a7db40f8e3cf - null createdAt: type: string title: Created At description: Fecha y hora de creación del contacto. examples: - "2003-04-10T08:00:00.000Z" updatedAt: type: string title: Updated At description: Fecha y hora de la última actualización del contacto. examples: - "2003-04-10T08:00:00.000Z" type: object required: - id - workspaceId - type - createdAt - updatedAt title: ContactResponse description: Cuerpo de respuesta para operaciones con contactos. ContactsResponseList: properties: contacts: items: $ref: "#/components/schemas/ContactResponse" type: array title: Contacts description: Lista de contactos. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor que se enviará al solicitar la página siguiente. type: object required: - contacts title: ContactsResponseList description: Cuerpo de respuesta para listar contactos. ConversationListResponse: properties: conversations: items: $ref: "#/components/schemas/ConversationResponse" type: array title: Conversations description: Lista de conversaciones. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor para obtener la página siguiente de conversaciones. Es null si no hay más páginas. examples: - null - eyJ2IjoxLCJjIjp7InN0IjoxfX0 type: object required: - conversations title: ConversationListResponse description: Cuerpo de respuesta para listar conversaciones con paginación. ConversationParticipantsResponse: properties: externals: items: $ref: "#/components/schemas/ExternalParticipant" type: array title: Externals description: Lista de participantes externos. internals: items: $ref: "#/components/schemas/InternalParticipant" type: array title: Internals description: Lista de participantes internos. type: object required: - externals - internals title: ConversationParticipantsResponse description: Cuerpo de respuesta para los participantes de una conversación. ConversationResponse: properties: id: type: string title: Identifier description: Identificador único de la conversación (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Identificador único del workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 participants: $ref: "#/components/schemas/ConversationParticipantsResponse" title: Participants description: Participantes de la conversación. name: anyOf: - type: string - type: "null" title: Name description: Nombre o título opcional de la conversación. examples: - Bridge Support Team status: anyOf: - $ref: "#/components/schemas/ConversationStatus" - type: "null" title: Status description: >- Estado actual de la conversación: 'ACTIVE' para conversaciones visibles y 'GHOST' para conversaciones invisibles hasta la primera interacción. examples: - ACTIVE createdAt: type: string format: date-time title: Created At description: Fecha y hora de creación de la conversación. examples: - "2003-04-10T09:00:00.000Z" updatedAt: type: string format: date-time title: Updated At description: Fecha y hora de la última actualización de la conversación. examples: - "2003-04-10T09:00:00.000Z" type: object required: - id - workspaceId - participants - createdAt - updatedAt title: ConversationResponse description: Cuerpo de respuesta para los detalles de una conversación. ConversationStatus: type: string enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED title: ConversationStatus CreateContactBody: properties: firstName: type: string title: First Name description: Nombre del contacto. examples: - John - Alice lastName: type: string title: Last Name description: Apellido del contacto. examples: - Doe email: anyOf: - type: string format: email - type: "null" title: Email description: Correo electrónico del contacto. examples: - john.doe@example.com - null languageCode: $ref: "#/components/schemas/LanguageCode" title: Language Code description: Código de idioma del contacto. examples: - EN cellphone: type: string title: Cellphone description: >- Número de celular del contacto. Si no incluye código de país, se interpreta según el país del workspace. examples: - "+14084029292" ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador del vendedor o usuario propietario del contacto. customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto con atributos personalizados abiertos y cerrados. additionalProperties: false type: object required: - firstName - lastName - languageCode - cellphone title: CreateContactBody description: Cuerpo de la solicitud para crear un contacto. CreateConversationRequest: properties: participants: $ref: "#/components/schemas/CreateParticipantsOnConversationRequest" title: Participants description: Participantes que se agregarán a la conversación. name: anyOf: - type: string - type: "null" title: Name description: Nombre o título opcional de la conversación. examples: - Bridge Support Team - null status: $ref: "#/components/schemas/ConversationStatus" title: Status description: >- Estado inicial de la conversación: 'active' para conversaciones visibles y 'ghost' para conversaciones invisibles hasta la primera interacción. default: ACTIVE examples: - ACTIVE teamId: anyOf: - type: string format: uuid - type: "null" title: Team Identifier description: >- UUID del equipo para la asignación por turnos (opcional y mutuamente excluyente con internalParticipants). examples: - 9fd1468d-e5ca-4ba3-98d1-13017e6f3808 onboardingTemplates: items: $ref: "#/components/schemas/OnboardingTemplateRequest" type: array title: Onboarding Templates description: >- Plantillas ordenadas con las que abrir la conversación. Reemplazan la secuencia de inicio configurada en el workspace para esta conversación, en su totalidad o solo su primera plantilla, según la configuración del workspace; en el segundo caso, el resto de la secuencia configurada se envía después de las tuyas. La posición determina el orden. Omite este campo para conservar el valor predeterminado del workspace. Cada plantilla debe existir, pertenecer a tu workspace o al ámbito de la plataforma y, para plantillas de proveedor de WhatsApp, estar aprobada por Meta para la WhatsApp Business Account de la línea por la que se contacta a cada participante; de lo contrario, se rechaza la solicitud y no se crea ninguna conversación. Una plantilla cuyas variables necesiten valores que solo tú puedas proporcionar los recibe en los `parameters` de la entrada. Si una de las plantillas configuradas que se envían después de las tuyas necesita valores que solo pueda proporcionar quien llama, la solicitud se rechaza con 422 `BRIDGE_CONVERSATION_0608`, con `extra.templateId` identificando esa plantilla y `extra.origin` establecido en `WORKSPACE_CONFIGURATION`. Cambiar la solicitud no ayudará: pide a un administrador del workspace que cambie la secuencia de inicio. additionalProperties: false type: object required: - participants title: CreateConversationRequest description: Cuerpo de la solicitud para crear una conversación. CreatePartialContactBody: properties: cellphone: type: string title: Cellphone description: >- Número de celular del contacto. Si no incluye código de país, se interpreta según el país del workspace. Se utiliza para identificar al contacto durante el upsert. examples: - "+14084029292" firstName: anyOf: - type: string - type: "null" title: First Name description: Nombre del contacto. Obligatorio para la clasificación NORMAL. examples: - Maria - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Apellido del contacto. Obligatorio para la clasificación NORMAL. examples: - Lopez - null email: anyOf: - type: string format: email - type: "null" title: Email description: Correo electrónico del contacto. examples: - maria@acme.com - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma del contacto. Obligatorio para la clasificación NORMAL. examples: - EN - null ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador del vendedor o usuario propietario del contacto. examples: - identifier: jane@acme.com identifierType: EMAIL - null customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto con atributos personalizados abiertos y cerrados. examples: - closedAttributes: [] openAttributes: [] additionalProperties: false type: object required: - cellphone title: CreatePartialContactBody description: Cuerpo de la solicitud para crear un contacto parcial. Solo cellphone es obligatorio. CreateParticipantsOnConversationRequest: properties: externals: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Externals description: Lista de identificadores de usuarios externos. internals: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Internals description: Lista de identificadores de usuarios internos (opcional y mutuamente excluyente con teamId). type: object title: CreateParticipantsOnConversationRequest description: Cuerpo de la solicitud de participantes al crear una conversación. CustomAttributeResponse: properties: key: type: string title: Key description: Clave o nombre del atributo values: items: type: string type: array title: Values description: Valor del atributo type: object required: - key title: CustomAttributeResponse description: Cuerpo de respuesta para atributos personalizados en operaciones con contactos. CustomAttributes: properties: id: type: string title: Identifier description: Identificador único del atributo personalizado. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 category: type: string enum: - OPEN - CLOSED title: Category description: Categoría del atributo personalizado. examples: - OPEN - CLOSED isRequired: type: boolean title: Is Required description: Define si el atributo personalizado es obligatorio. examples: - true - false keyName: type: string title: Key Name description: Nombre del atributo personalizado. closedAttributesValues: anyOf: - items: $ref: "#/components/schemas/ClosedAttribute" type: array - type: "null" title: Closed Attributes Values description: Lista de valores del atributo cerrado. type: type: string enum: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT title: Type description: Tipo de los valores de los atributos personalizados. examples: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT deletedAt: anyOf: - type: string - type: "null" title: Deleted At description: Fecha y hora de eliminación lógica. Null indica que el atributo está activo. type: object required: - id - category - isRequired - keyName - type title: CustomAttributes description: Objeto que representa el atributo personalizado. CustomAttributesBody: properties: openAttributes: anyOf: - items: $ref: "#/components/schemas/OpenAttributeRequest" type: array - type: "null" title: Open Attributes description: Lista de atributos abiertos. closedAttributes: anyOf: - items: $ref: "#/components/schemas/ClosedAttributeRequest" type: array - type: "null" title: Closed Attributes description: Lista de atributos cerrados. type: object title: CustomAttributesBody description: Cuerpo de la solicitud para operaciones de atributos personalizados. CustomAttributesResponse: properties: customAttributes: items: $ref: "#/components/schemas/CustomAttributes" type: array title: Custom Attributes description: Lista de objetos de atributos personalizados con sus valores. type: object required: - customAttributes title: CustomAttributesResponse description: Cuerpo de respuesta para operaciones de atributos personalizados. ExternalOperationRequest: properties: add: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Add description: Participantes externos que se agregarán. remove: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Remove description: Participantes externos que se eliminarán. type: object title: ExternalOperationRequest description: Operaciones sobre participantes externos de una conversación. ExternalParticipant: properties: identifier: type: string title: Identifier description: Valor del identificador del participante. examples: - ef7ee722-5f95-415a-9a98-81eeae178b11 identifierType: type: string enum: - ID - EMAIL - PHONE title: Identifier Type description: Tipo de identificador de participantes externos (ID, EMAIL o PHONE). examples: - EMAIL - PHONE - ID role: $ref: "#/components/schemas/UserType" title: Role description: Rol del participante en la conversación. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Fecha y hora en que el participante se unió a la conversación. examples: - "2004-04-10T09:00:00.000Z" lastSeenAt: anyOf: - type: string format: date-time - type: "null" title: Last Seen At description: Fecha y hora de la última actividad observada del participante. examples: - null - "2004-04-10T09:00:00.000Z" type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Objeto que representa al participante externo de la conversación. ExternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: Valor del identificador del usuario. examples: - john.doe@example.com - "+13802098869" - 37673840-6259-40f9-bbe5-a7db40f8e3cf identifierType: type: string enum: - ID - EMAIL - PHONE title: Identifier Type description: Tipo de identificador de usuarios externos (ID, EMAIL o PHONE). examples: - EMAIL - PHONE - ID messageProviderType: anyOf: - $ref: "#/components/schemas/MessageProviderType" - type: "null" title: Message Provider Type description: Tipo de proveedor de mensajería de la conversación. examples: - WHATSAPP - null providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: ID del canal del proveedor que usará Bridge para comunicarse con el usuario. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- Marca propietaria de la línea corporativa utilizada para contactar al usuario. Cuando el workspace tiene al menos una línea con marca, la selección automática de líneas se limita a esta marca y la solicitud debe incluir brandId o providerChannelId; se rechaza si no incluye ninguno. Se ignora cuando el workspace no tiene líneas con marca. type: object required: - identifier - identifierType title: ExternalUserIdentifierRequest description: Cuerpo para identificar a un usuario externo en Bridge. 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 o correo electrónico del usuario interno, según identifierType. examples: - u-123 - ana@acme.com identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Estrategia de búsqueda del usuario interno. Solo se admiten ID y EMAIL. examples: - ID - EMAIL additionalProperties: false type: object required: - identifier - identifierType title: HandoffAssignee description: Usuario interno al que se asignará la conversación durante una transferencia. HandoffRequest: properties: assignees: items: $ref: "#/components/schemas/HandoffAssignee" type: array minItems: 1 title: Assignees description: Usuarios internos que recibirán la transferencia de la conversación. Se requiere al menos uno. handoffMessages: items: type: string type: array title: Handoff Messages description: Cuerpos de mensajes opcionales publicados como parte de la transferencia. includeAiLeadSummary: type: boolean title: Include AI Lead Summary description: Con true, el mensaje de transferencia debe incluir un resumen del lead generado por IA. default: false additionalProperties: false type: object required: - assignees title: HandoffRequest description: Cuerpo de la solicitud de transferencia manual de LeadScout. HandoffResponse: properties: trackingId: type: string title: Tracking Identifier description: ID de correlación generado para esta solicitud de transferencia. conversationId: type: string title: Conversation Identifier description: Conversación a la que se dirige la transferencia. status: type: string title: Status description: Estado de aceptación de la solicitud de transferencia. examples: - ACCEPTED assignees: items: $ref: "#/components/schemas/HandoffAssignee" type: array title: Assignees description: Repite los destinatarios recibidos en la solicitud. type: object required: - trackingId - conversationId - status - assignees title: HandoffResponse description: Cuerpo de respuesta que confirma la aceptación de la solicitud de transferencia. HeaderFileType: type: string enum: - IMAGE - VIDEO - GIF title: HeaderFileType InternalOperationRequest: properties: add: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Add description: Participantes internos que se agregarán. remove: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Remove description: Participantes internos que se eliminarán type: object title: InternalOperationRequest description: Operaciones sobre participantes internos de una conversación. InternalParticipant: properties: identifier: type: string title: Identifier description: Valor del identificador del participante. examples: - ef7ee722-5f95-415a-9a98-81eeae178b11 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Tipo de identificador de participantes internos (ID o EMAIL). examples: - EMAIL - ID role: $ref: "#/components/schemas/UserType" title: Role description: Rol del participante en la conversación. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Fecha y hora en que el participante se unió a la conversación. examples: - "2004-04-10T09:00:00.000Z" lastSeenAt: anyOf: - type: string format: date-time - type: "null" title: Last Seen At description: Fecha y hora de la última actividad observada del participante. examples: - null - "2004-04-10T09:00:00.000Z" type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Objeto que representa al participante interno de la conversación. InternalParticipantIdentifierType: type: string enum: - ID - EMAIL title: InternalParticipantIdentifierType InternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: Valor del identificador del usuario. examples: - john.doe@example.com - "+13802098869" - 37673840-6259-40f9-bbe5-a7db40f8e3cf identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Tipo de identificador de usuarios internos (ID o EMAIL). examples: - EMAIL - ID type: object required: - identifier - identifierType title: InternalUserIdentifierRequest description: Cuerpo para identificar a un usuario interno en Bridge. InternalUserResponse: properties: id: type: string title: Identifier description: Identificador único del usuario interno (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 firstName: anyOf: - type: string - type: "null" title: First Name description: Nombre del usuario interno. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Apellido del usuario interno. examples: - Doe - null email: anyOf: - type: string - type: "null" title: Email description: Correo electrónico del usuario interno. examples: - john.doe@example.com - null cellphone: anyOf: - type: string - type: "null" title: Cellphone description: Número de celular del usuario interno. examples: - "+14084029292" - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma del usuario interno. examples: - EN - null status: type: string enum: - active - disabled title: Status description: "'active' cuando el usuario interno está activo; 'disabled' cuando se eliminó al usuario." examples: - active - disabled createdAt: type: string title: Created At description: Fecha y hora de creación del usuario interno. examples: - "2003-04-10T08:00:00.000Z" updatedAt: type: string title: Updated At description: Fecha y hora de la última actualización del usuario interno. examples: - "2003-04-10T08:00:00.000Z" type: object required: - id - status - createdAt - updatedAt title: InternalUserResponse description: Cuerpo de respuesta para operaciones de lectura de usuarios internos (agentes humanos). InternalUsersResponseList: properties: users: items: $ref: "#/components/schemas/InternalUserResponse" type: array title: Users description: Lista de usuarios internos. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor que se enviará al solicitar la página siguiente. type: object required: - users title: InternalUsersResponseList description: Cuerpo de respuesta para listar usuarios internos. 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: >- Identificador del Contact según identifierType: ID de Contact para ID, correo electrónico para EMAIL o teléfono en formato E.164 para PHONE. El Contact ya debe existir en el workspace. examples: - "+573001234567" identifierType: $ref: "#/components/schemas/ParticipantIdentifierType" title: Identifier Type description: Tipo de identificador. examples: - PHONE - EMAIL - ID messageProviderType: $ref: "#/components/schemas/MessageProviderType" title: Message Provider Type description: Proveedor utilizado para entregar la plantilla. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: >- ID opcional de línea explícita de WhatsApp. Si se proporciona, se usa esa línea, que debe pertenecer al workspace y resolver a un Agent de prospección. Si se omite, las líneas elegibles se seleccionan automáticamente: primero las libres, después las liberadas recuperables y, solo con forceSend=true, las ocupadas. Si se indica brandId, se limitan los candidatos a esa marca. El ID de línea no es un número telefónico. Consulta [identificadores](/es/guides/identifiers) y [selección saliente](/es/guides/agent-outbound). examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: LeadscoutOutboundContactRef description: Identifica al lead al que se dirigirá la conversación saliente. LeadscoutOutboundHandoffOverride: properties: preAssignedUser: $ref: "#/components/schemas/LeadscoutOutboundPreAssignedUser" title: Pre-assigned User description: >- Usuario interno que se asignará como asesor cuando la IA transfiera la conversación. Se valida durante la solicitud: si el usuario no existe, está inactivo o pertenece a otro workspace, se rechaza antes de crear una conversación. examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: LeadscoutOutboundHandoffOverride description: Reemplaza la asignación predeterminada del asesor de la conversación saliente. LeadscoutOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Valor que identifica al usuario interno, interpretado según identifier_type. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: >- Cómo resolver el identificador. ID busca por ID de usuario interno; EMAIL busca por correo electrónico. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: LeadscoutOutboundPreAssignedUser description: Identifica al usuario interno que debe recibir la transferencia. LeadscoutOutboundRequest: properties: contact: $ref: "#/components/schemas/LeadscoutOutboundContactRef" title: Contact description: Lead al que se dirige esta conversación saliente. Ya debe existir en el workspace. template: $ref: "#/components/schemas/LeadscoutOutboundTemplateRef" title: Template description: Plantilla inicial que se enviará. additionalMessages: items: $ref: "#/components/schemas/OutboundFollowUpRequest" type: array maxItems: 5 title: Additional Messages description: >- Hasta cinco mensajes de seguimiento guardados en la conversación en el orden de la solicitud. La persistencia no confirma la entrega. No asumas que estos mensajes esperan la respuesta del lead; consulta la guía de outbound para considerar entrega y reintentos. agentContext: anyOf: - $ref: "#/components/schemas/OutboundAgentContextRequest" - type: "null" title: Agent Context description: Notas y medios opcionales guardados en la conversación como contexto para el agente. consent: anyOf: - $ref: "#/components/schemas/OutboundConsentRequest" - type: "null" title: Consent description: >- Evidencia opcional de consentimiento, declarada por la empresa, que se registra en la conversación. handoffOverride: anyOf: - $ref: "#/components/schemas/LeadscoutOutboundHandoffOverride" - type: "null" title: Handoff Override description: >- Opción para preasignar un usuario interno específico como asesor de la transferencia. Se valida durante la solicitud; si falla, se cancela la creación de la conversación. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- ID opcional de marca. Si se proporciona, solo son elegibles los canales vinculados a ella. Omítelo para considerar todos los canales del workspace. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: "null" title: Campaign Identifier description: Referencia opcional de campaña guardada en la conversación para auditoría e informes. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: >- Controla la reutilización de una conversación activa existente con este Contact en la línea elegida. Con false (predeterminado), una línea ocupada seleccionada explícitamente devuelve 409 BRIDGE_AI_LEADSCOUT_0007; la selección automática con solo líneas ocupadas devuelve 409 BRIDGE_AI_LEADSCOUT_0008. Con true, se reutiliza una conversación ocupada apta en lugar de crear una nueva, y una reutilización exitosa establece alreadyInitiated=true. La selección automática prefiere una línea libre, después una conversación liberada recuperable y, por último, una conversación ocupada cuando true. La recuperación es posible con cualquiera de los dos valores y devuelve recovered=true. La ruta heredada de LeadScout puede reutilizar una conversación controlada por un humano; no aplica la comprobación de control del envío saliente de Agents. Esta opción no omite las conversaciones bloqueadas/no recuperables, las comprobaciones de sesión ni otras validaciones y no es una clave de idempotencia. Consulta [Envío saliente de Agents y forceSend](/es/guides/agent-outbound). default: false examples: - false - true type: object required: - contact - template title: LeadscoutOutboundRequest description: Cuerpo de la solicitud para iniciar una conversación saliente de LeadScout. LeadscoutOutboundResponse: properties: conversation: $ref: "#/components/schemas/ConversationResponse" title: Conversation description: >- Conversación utilizada para esta solicitud saliente: nueva, reutilizada (alreadyInitiated=true) o recuperada (recovered=true). Una conversación reutilizada conserva su ID; la reutilización legacy, por sí sola, no implica que haya cambiado su controlador. contact: $ref: "#/components/schemas/ContactResponse" title: Contact description: Contacto con el que se inició la conversación. templateSent: anyOf: - $ref: "#/components/schemas/LeadscoutTemplateSent" - type: "null" title: Template Sent description: Resumen de la plantilla despachada. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Número de mensajes de seguimiento guardados en la conversación. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: >- True cuando esta solicitud satisfactoria reutilizó una conversación activa existente mediante forceSend=true. False para creación o recuperación; consulta recovered para distinguir esas rutas. Es informativo: una reutilización satisfactoria también guarda la nueva plantilla y los seguimientos, por lo que repetir la solicitud puede agregar mensajes. default: false examples: - false - true recovered: type: boolean title: Recovered description: >- True cuando esta solicitud recuperó una conversación liberada que el contacto tenía en el canal elegido, en lugar de crear otra. default: false examples: - false - true type: object required: - conversation - contact title: LeadscoutOutboundResponse description: Cuerpo de respuesta de un inicio saliente de LeadScout satisfactorio. LeadscoutOutboundTemplateRef: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID de la plantilla registrada (de GET /templates). Si se envían id y name, se usa id. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f - null name: anyOf: - type: string - type: "null" title: Template Name description: >- Nombre de la plantilla registrada y aprobada por Meta que se enviará. Obligatorio si no se envía id; se ignora si se envía id. examples: - leadscout_outbound_fb_v1 - null orderedParams: items: type: string type: array title: Ordered Parameters description: >- Valores proporcionados por el cliente para los slots de parámetros de la plantilla con origen CALLER, en orden de posición. examples: - - Maria - ACME parameters: additionalProperties: type: string type: object title: Parameters description: >- Valores proporcionados por el cliente e indexados por la clave de variable de la plantilla (consulta GET /templates/{id} para obtener las claves), tanto para el cuerpo como para los botones. Prefiere esta opción a orderedParams si la plantilla tiene un botón dinámico. Se rechaza con 422 una clave desconocida o que se superponga con un slot ya cubierto por orderedParams. examples: - recipient_first_name: Maria tracking_code: TRK123 media: anyOf: - $ref: "#/components/schemas/OutboundTemplateMedia" - type: "null" title: Header Media description: >- Medio opcional de encabezado (imagen o video) que se adjuntará al mensaje de plantilla. Acepta un mediaId precargado o una url pública. type: object title: LeadscoutOutboundTemplateRef description: Referencia la plantilla aprobada por Meta que abrirá la conversación. LeadscoutTemplateSent: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID de la plantilla enviada. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Nombre de la plantilla despachada. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: "null" title: Message Identifier description: >- wamid de Meta de la plantilla despachada. Es null en el flujo satisfactorio hasta que el proceso de envío devuelva el wamid a la API de entrada. examples: - null - wamid.HBgM... type: object required: - name title: LeadscoutTemplateSent description: Resumen de la plantilla despachada para abrir la conversación. 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: Identificador de la conversación. examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 messageBody: type: string title: Message Body description: Cuerpo del mensaje. examples: - Hello, welcome to Bridge! replyToMessageId: anyOf: - type: string - type: "null" title: Reply To Message Identifier description: Identificador del mensaje al que se responde. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 - null enableExternalBroadcast: type: boolean title: Enable External Broadcast description: >- Controla si un mensaje aceptado es elegible para entrega externa. Con false, el mensaje se crea, pero se omite el broadcast externo. Con true, entra en el flujo normal de entrega externa cuando las reglas de la conversación y del destinatario lo permiten. Una respuesta de creación satisfactoria y messageId no son comprobantes de entrega. Este indicador no concede visibilidad ni omite permisos. Tampoco desactiva las plantillas de onboarding iniciadas por una solicitud separada de creación de conversación. examples: - true - false mediaIds: items: type: string type: array title: Media Identifiers description: Lista de IDs de medios asociados al mensaje. examples: - - a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6 type: object required: - conversationId - messageBody - enableExternalBroadcast title: MessageRequest description: Cuerpo de la solicitud para crear un mensaje en una conversación específica. MessageResponse: properties: messagingProduct: type: string title: Messaging Product description: Nombre del producto. default: bridge examples: - bridge messageId: type: string title: Message Identifier description: Identificador único del mensaje como cadena UUID. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 type: object required: - messageId title: MessageResponse description: Cuerpo de respuesta para operaciones con mensajes. OnboardingTemplateRequest: properties: templateId: type: string title: Template Identifier description: Identificador de la plantilla del sistema que se enviará. examples: - 4061e74e-f6fe-4072-a760-3aec0b64f7a6 parameters: additionalProperties: type: string maxLength: 1024 propertyNames: maxLength: 128 type: object maxProperties: 50 title: Template Parameters description: >- Valores de las variables de esta plantilla, indexados por el `key` de la variable devuelto por `GET /templates/{templateId}`. Las variables marcadas con `callerMustSupply: true` son obligatorias: Bridge no tiene otra fuente para ellas. Las demás son opcionales; un valor enviado para una de ellas, como el nombre del Contact, reemplaza el valor por Contact y se utiliza para todos los Contacts de la conversación. Solo las plantillas de proveedor de WhatsApp aceptan parámetros. Si falta un valor obligatorio o está en blanco, una clave no corresponde a ninguna variable de la plantilla o la plantilla no admite parámetros, la solicitud se rechaza con 422 y no se crea ninguna conversación: `BRIDGE_CONVERSATION_0604` enumera las variables que faltan en `extra.missingVariables` como `[{key, label}]`, `0605` enumera las claves desconocidas en `extra.unknownKeys` y `0606` identifica la plantilla en `extra.templateId`. Los valores también deben cumplir las reglas de WhatsApp: sin saltos de línea ni tabulaciones, no más de cuatro espacios consecutivos, el encabezado con tu valor dentro de 60 caracteres, el enlace de un botón URL con tu valor dentro de 2.000 y el texto del cuerpo más tus valores dentro de 1.024. Bridge rechaza los valores que puede detectar que incumplen estas reglas con `BRIDGE_CONVERSATION_0607`, identificando la plantilla en `extra.templateId` y enumerando cada valor inválido en `extra.invalidVariables` como `[{key, label, reason}]`. `reason` es la primera regla que incumple el valor: `NEWLINE`, `TAB`, `CONSECUTIVE_SPACES`, `TOO_LONG` (encabezado o botón URL) o `BODY_TOO_LONG` (el cuerpo supera el límite, por lo que se enumeran todos los valores del cuerpo que enviaste). Los valores que Bridge rellena después, como el nombre del Contact, también cuentan para el límite del cuerpo, así que deja espacio para ellos. Como máximo, 50 parámetros por plantilla, con claves de hasta 128 caracteres y cada valor de hasta 1.024. examples: - delivery_date: 3 de octubre order_number: A-10492 additionalProperties: false type: object required: - templateId title: OnboardingTemplateRequest description: Entrada del reemplazo de onboarding; su posición en la lista determina el orden. OpenAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Identificador único del atributo personalizado abierto. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 content: type: string title: Content description: Valor del atributo abierto. type: object required: - customAttributeId - content title: OpenAttributeRequest description: Cuerpo de la solicitud para operaciones de atributos personalizados abiertos. OutboundAgentContextRequest: properties: notes: anyOf: - type: string maxLength: 2000 - type: "null" title: Notes description: Notas de texto libre para el agente, limitadas a 2000 caracteres. examples: - Lead asked about pricing tiers last week. - null mediaIds: items: type: string type: array title: Media Identifiers description: >- Identificadores opcionales de archivos precargados guardados en la conversación como contexto del agente. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: OutboundAgentContextRequest description: >- Notas y medios guardados en la conversación como contexto del agente para la revisión por IA o una persona. OutboundConsentRequest: properties: status: $ref: "#/components/schemas/ConsentStatus" title: Status description: >- Estado de consentimiento declarado por la empresa. Usa GRANTED (con capturedAt) para consentimiento explícito o NOT_PROVIDED si la empresa no tiene evidencia que declarar. examples: - GRANTED - NOT_PROVIDED capturedAt: anyOf: - type: string format: date-time - type: "null" title: Captured At description: >- Fecha y hora ISO8601 (con milisegundos) en que la empresa obtuvo el consentimiento. Obligatorio con status=GRANTED; se acepta null u omitido con status=NOT_PROVIDED. examples: - "2026-04-20T10:00:00.000Z" - null type: object required: - status title: OutboundConsentRequest description: >- Evidencia de consentimiento declarada por la empresa y registrada sin modificaciones en la conversación. OutboundFollowUpRequest: properties: messageBody: type: string title: Message Body description: Cuerpo de texto plano del mensaje de seguimiento. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: >- El esquema de solicitud lo acepta, pero el flujo saliente compartido actual guarda los seguimientos solo como texto y no adjunta estos IDs de medios. Para medios de la plantilla inicial, usa template.media; para un mensaje de adjunto separado, sigue el flujo de adjuntos de Message. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: OutboundFollowUpRequest description: Mensaje de seguimiento precargado que se guarda en la conversación junto a la plantilla inicial. OutboundTemplateMedia: properties: type: $ref: "#/components/schemas/HeaderFileType" title: Media Type description: Tipo de medio del encabezado. Debe coincidir con el configurado para la plantilla en Meta. examples: - IMAGE - VIDEO mediaId: anyOf: - type: string - type: "null" title: Media Identifier description: >- UUID devuelto por POST /bridge/api/v1/workspaces/{workspaceId}/files. Mutuamente excluyente con url. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f url: anyOf: - type: string - type: "null" title: Source URL description: >- URL pública de origen que obtiene de forma asíncrona el servicio de descarga de archivos por URL. Mutuamente excluyente con mediaId. examples: - null - https://cdn.example.com/promo.jpg type: object required: - type title: OutboundTemplateMedia description: >- Medio opcional de encabezado adjunto al mensaje de plantilla inicial. Proporciona exactamente uno: ``mediaId`` (UUID devuelto por ``POST /bridge/api/v1/workspaces/{workspaceId}/files``) o ``url`` (URL pública de origen obtenida de forma asíncrona por el servicio de descarga por URL). ParticipantIdentifierType: type: string enum: - ID - EMAIL - PHONE title: ParticipantIdentifierType ParticipantOperationsRequest: properties: externals: anyOf: - $ref: "#/components/schemas/ExternalOperationRequest" - type: "null" title: Externals description: >- Operaciones sobre usuarios externos; deben proporcionarse mediante las operaciones "add" y "remove". internals: anyOf: - $ref: "#/components/schemas/InternalOperationRequest" - type: "null" title: Internals description: >- Operaciones sobre usuarios internos; deben proporcionarse mediante las operaciones "add" y "remove". type: object title: ParticipantOperationsRequest description: Cuerpo de la solicitud de operaciones sobre participantes al actualizar una conversación. PreloadedFileRequest: properties: name: type: string title: Name description: Nombre original del archivo, incluida la extensión. examples: - prueba.jpg fileType: $ref: "#/components/schemas/FileType" title: File Type description: Categoría lógica del tipo de archivo. examples: - IMAGE - VIDEO - AUDIO - DOCUMENT contentType: anyOf: - type: string - type: "null" title: Content Type description: Tipo MIME del archivo. examples: - image/jpeg - application/pdf - null checksumBase64: type: string title: Checksum Base64 description: >- Resumen SHA-256 del archivo completo, codificado en Base64. Se utiliza para firmar el PUT prefirmado y debe enviarse de nuevo en el encabezado x-amz-checksum-sha256 durante la carga. examples: - OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= additionalProperties: false type: object required: - name - fileType - checksumBase64 title: PreloadedFileRequest description: Solicitud para preparar la carga de un archivo con una URL prefirmada. PreloadedFileResponse: properties: mediaId: type: string title: Media Identifier description: Identificador único del medio. examples: - 4a2c1f7e-2f84-4a5f-bd2d-6b6b2f0c1234 presignUrl: $ref: "#/components/schemas/PresignPut" title: Presign Url description: Datos del PUT prefirmado para cargar el medio (URL, método y encabezados). additionalProperties: false type: object required: - mediaId - presignUrl title: PreloadedFileResponse description: Respuesta para un archivo precargado con URL prefirmada para su carga. PresignPut: properties: url: type: string title: Url description: URL de PUT prefirmado. examples: - https://s3.amazonaws.com/bucket/path/to/object method: type: string const: PUT title: Method description: Método HTTP que se usará para la carga. default: PUT examples: - PUT headers: additionalProperties: type: string type: object title: Headers description: >- Encabezados obligatorios para el PUT prefirmado (por ejemplo, Content-Type y x-amz-checksum-sha256). examples: - Content-Type: image/jpeg x-amz-checksum-sha256: OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= type: object required: - url title: PresignPut description: Datos del PUT prefirmado para cargar un archivo de medios. Problem: properties: title: type: string title: Title description: Resumen breve del tipo de problema. status: type: integer title: Status description: Código de estado HTTP generado por el servidor de origen para esta instancia del problema. detail: anyOf: - type: string - type: "null" title: Detail description: Explicación específica de esta instancia del problema. instance: anyOf: - type: string - type: "null" title: Instance description: Referencia URI que identifica esta instancia del problema. traceId: anyOf: - type: string - type: "null" title: Traceid description: ID de seguimiento para depuración. code: anyOf: - type: string - type: "null" title: Code description: Código para identificar el error; consulta la página de códigos de error para más detalles. errors: anyOf: - items: additionalProperties: true type: object type: array - type: "null" title: Errors description: Lista de detalles de errores. extra: anyOf: - additionalProperties: true type: object - type: "null" title: Extra description: Información adicional sobre el problema. type: object required: - title - status title: Problem description: Objeto que representa el cuerpo de una respuesta Problem. ProviderChannel: properties: provider: $ref: "#/components/schemas/MessageProviderType" title: Provider description: Nombre del proveedor del canal de mensajería. examples: - WHATSAPP - HEYGIA identifier: type: string title: Identifier description: Identificador asociado a este canal del proveedor, en formato E.164 sin el signo '+'. type: object required: - provider - identifier title: ProviderChannel description: Canal de proveedor asociado a un workspace. ProviderChannelResponse: properties: workspaceId: type: string title: Workspace Identifier description: Identificador único del workspace (UUID v4). examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 providerChannels: items: $ref: "#/components/schemas/ProviderChannel" type: array title: Provider Channels description: Lista de canales de proveedores (números telefónicos) disponibles para este workspace. type: object required: - workspaceId - providerChannels title: ProviderChannelResponse description: Cuerpo de respuesta para operaciones con canales de proveedores. ReleaseConversationBody: properties: reason: anyOf: - type: string - type: "null" title: Reason description: Motivo opcional para liberar la conversación. examples: - The conversation is over - null type: object title: ReleaseConversationBody description: Cuerpo de POST para liberar una conversación. El motivo es opcional. TemplateDiscoveryResponse: properties: id: type: string title: Id description: Identificador único de la plantilla. examples: - f0000040-0000-4000-8000-000000000040 name: type: string title: Name description: Nombre de la plantilla, utilizado para identificarla al enviarla. examples: - order_shipped_promo language: type: string title: Language description: >- Idioma del pivot resuelto (idioma predeterminado de la plantilla), como código de Meta: es, en, pt_BR. examples: - es - pt_BR variables: items: $ref: "#/components/schemas/TemplateVariableResponse" type: array title: Variables description: Inventario agnóstico de las variables de esta plantilla. driftWarning: $ref: "#/components/schemas/TemplateDriftWarningResponse" title: Drift warning description: Diferencia entre declaración y snapshot, solo para diagnóstico. Nunca bloquea un envío. type: object required: - id - name - language - driftWarning title: TemplateDiscoveryResponse description: >- Inventario agnóstico de las variables de una plantilla para un cliente que debe enviarla sin conocer el modelo de Meta. examples: - id: f0000040-0000-4000-8000-000000000040 language: es name: order_shipped_promo driftWarning: hasDrift: false stale: [] missingLabels: [] 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: Declarado, pero ya no requerido por el snapshot. missingLabels: items: $ref: "#/components/schemas/TemplateVariableRef" type: array title: Missing labels description: Requerido por el snapshot, pero aún no declarado. type: object required: - hasDrift title: TemplateDriftWarningResponse description: >- Diferencia, solo para diagnóstico, entre las variables declaradas y lo que requiere el snapshot de Meta. Según la regla de autoridad, esto nunca afecta el éxito de un envío: lo determina únicamente el snapshot. Permite que el cliente o la consola identifique una plantilla cuyas etiquetas necesitan actualizarse tras una edición realizada directamente en 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: Slot identificado solo por su clave y etiqueta agnósticas, sin dirección de slot de Meta. TemplateVariableResponse: properties: key: type: string title: Key description: Identificador agnóstico de esta variable, estable entre proveedores. examples: - tracking_code label: type: string title: Label description: Etiqueta legible de esta variable. examples: - Tracking code callerMustSupply: type: boolean title: Caller must supply description: >- Indica si el cliente debe proporcionar un valor para esta variable al enviar la plantilla: true si la plantilla no tiene un origen declarado para ese valor (por ejemplo, un código promocional que solo conoce el cliente) y false si Bridge lo resuelve por su cuenta (por ejemplo, desde el perfil del destinatario). examples: - true - false isCustom: type: boolean title: Is custom description: >- Indica si es una variable personalizada: un valor que solo conoce el cliente y que tiene un texto predeterminado. El cliente puede enviarlo en `parameters`; si se omite o se envía vacío, se utiliza `default`. default: false examples: - true - false default: anyOf: - type: string - type: "null" title: Default description: "Para una variable personalizada, el texto que se envía cuando quien llama no proporciona un valor; en los demás casos, null." examples: - pending - null type: object required: - key - label - callerMustSupply title: TemplateVariableResponse description: >- Variable de plantilla identificada por su clave agnóstica; aquí nunca aparece una dirección de slot de Meta. 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: Nombre del contacto. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Apellido del contacto. examples: - Doe - null email: anyOf: - type: string format: email - type: "null" title: Email description: Correo electrónico del contacto. examples: - john.doe@example.com - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma del contacto. examples: - EN cellphone: anyOf: - type: string - type: "null" title: Cellphone description: >- Número de celular del contacto. Si no incluye código de país, se interpreta según el país del workspace. examples: - "+14084029292" - null ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador del vendedor o usuario propietario del contacto. customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto con las listas openAttributes y closedAttributes. additionalProperties: false type: object title: UpdateContactBody description: Cuerpo de la solicitud para actualizar un contacto existente. UpdateConversation: properties: name: anyOf: - type: string - type: "null" title: Name description: Nombre o título opcional de la conversación. examples: - Client Support - null status: anyOf: - $ref: "#/components/schemas/ConversationStatus" - type: "null" title: Status description: >- Estado inicial de la conversación: 'active' para conversaciones visibles y 'ghost' para conversaciones invisibles hasta la primera interacción. examples: - ACTIVE participants: anyOf: - $ref: "#/components/schemas/ParticipantOperationsRequest" - type: "null" title: Participants description: Operaciones para agregar y eliminar participantes de una conversación. additionalProperties: false type: object title: UpdateConversation description: Cuerpo de la solicitud para actualizar una conversación existente. 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