openapi: 3.1.0 info: title: Bridge API summary: Especificação da API do Bridge para gerenciar o sistema de chat. description: >- Especificação da API REST de integrações do Bridge para gerenciar contatos, conversas, mensagens, arquivos, atributos personalizados, canais de provedores, modelos, usuários internos e Agents. Os webhooks são documentados separadamente em https://docs.bridge.new/pt-br/webhooks; este OpenAPI contém apenas endpoints REST. **Arquitetura multiempresa**: as operações sobre recursos são limitadas a um workspace específico por workspaceId. A verificação de integridade não inclui um workspace no caminho. 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 produção paths: /bridge/api/health: get: tags: - Health summary: Verificar integridade description: Endpoint de verificação de integridade para confirmar que a API está em funcionamento. operationId: health_bridge_api_health_get responses: "200": description: Resposta bem-sucedida content: application/json: schema: additionalProperties: true type: object title: Response Health Bridge Api Health Get "429": description: Muitas solicitações 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: Obter conversa por ID description: Obtém uma conversa específica pelo seu identificador único no 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único da conversa (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único da conversa (UUID v4). responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Atualizar conversa description: |- Atualiza os detalhes da conversa, incluindo participantes, status e nome. Aceita atualizações parciais: inclua apenas os campos que deseja alterar. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único da conversa (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único da conversa (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateConversation" description: Corpo da solicitação para atualizar uma conversa existente. responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 conversas com filtros flexíveis description: >- Consulta conversas com opções flexíveis de filtragem. Permite buscar por identificadores de usuários externos (ID, e-mail ou telefone) ou por participantes internos, com paginação e filtro por status. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de conversas por página default: 20 title: Limit description: Número de conversas por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recebido na solicitação anterior para obter a próxima página title: Cursor description: Cursor recebido na solicitação anterior para obter a próxima página - name: status in: query required: false schema: anyOf: - type: string - type: "null" title: Status description: Status da conversa enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED description: Status da conversa - name: internalUserIdentifier in: query required: false schema: anyOf: - type: string - type: "null" description: >- Identificador do usuário interno. Ao enviar um número de telefone, codifique corretamente a URL da solicitação, incluindo seus parâmetros. title: Internaluseridentifier description: >- Identificador do usuário interno. Ao enviar um número de telefone, codifique corretamente a URL da solicitação, incluindo seus 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: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ConversationListResponse" "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Criar conversa com identificação flexível de usuários description: >- Cria uma conversa com identificação flexível de usuários. Os usuários externos podem ser identificados por ID, e-mail ou telefone. Usuários internos só são atribuídos quando informados explicitamente; caso contrário, as conversas são distribuídas em rodízio por uma equipe ou ficam abertas para qualquer usuário interno disponível. Quando não há uma linha livre e os Contacts têm uma conversa liberada com exatamente os participantes solicitados, essa conversa é recuperada e retornada, mantendo seu `id` e histórico. O `name` e o `status` da solicitação não são aplicados a ela. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateConversationRequest" description: Corpo da solicitação para criar uma conversa. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ConversationResponse" "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Conteúdo não processável 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: Muitas solicitações 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 conversa description: >- Libera uma conversa: marca-a como liberada, remove os participantes externos e move-a para a seção 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: conversationId in: path required: true schema: type: string format: uuid description: Identificador único da conversa (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único da conversa (UUID v4). requestBody: content: application/json: schema: anyOf: - $ref: "#/components/schemas/ReleaseConversationBody" - type: "null" description: Corpo do POST para liberar uma conversa. O motivo é opcional. title: Body responses: "204": description: Resposta bem-sucedida "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Criar mensagem description: >- Cria uma mensagem em uma conversa específica. Para uma mensagem de texto ou um anexo enviado, inclua todos os campos obrigatórios: `conversationId`, `messageBody` e `enableExternalBroadcast`. Anexe os arquivos enviados usando os identificadores retornados em `mediaIds`; consulte [Enviar um anexo](/pt-br/guides/send-attachments). Uma resposta bem-sucedida retorna `messageId`; não contém uma confirmação de entrega do provedor. Consulte [Respostas e novas tentativas](/pt-br/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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageRequest" description: Corpo da solicitação para criar uma mensagem em uma conversa específica. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/MessageResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Obter contato por um identificador description: >- Obtém um contato específico por qualquer um de seus identificadores no workspace. `type=ID` retorna o mesmo contato que GET /contacts/{contactId}, a URL canônica de um contato e a opção preferida quando você já tem seu 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: type in: query required: true schema: $ref: "#/components/schemas/ParticipantIdentifierType" description: Tipo de identificador usado para informar o valor. description: Tipo de identificador usado para informar o valor. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: >- O identificador no formato indicado por `type`. Um `PHONE` é interpretado como o celular ao gravar um contato: sem código de país, usa-se o país padrão do workspace, ignorando espaços e separadores. Em um `EMAIL`, o domínio é convertido para minúsculas, mas a parte local deve corresponder exatamente ao valor enviado. title: Value description: >- O identificador no formato indicado por `type`. Um `PHONE` é interpretado como o celular ao gravar um contato: sem código de país, usa-se o país padrão do workspace, ignorando espaços e separadores. Em um `EMAIL`, o domínio é convertido para minúsculas, mas a parte local deve corresponder exatamente ao valor 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: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conteúdo não processável 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: Muitas solicitações 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: Obter contato por ID description: Obtém um contato específico pelo seu identificador único no 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: contactId in: path required: true schema: type: string format: uuid description: Identificador único do contato (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Identificador único do contato (UUID v4). responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Atualizar contato description: Atualiza um contato no workspace informado. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: contactId in: path required: true schema: type: string format: uuid description: Identificador único do contato (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Contactid description: Identificador único do contato (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateContactBody" description: Corpo da solicitação para atualizar um contato existente. responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 contatos description: >- Consulta uma lista paginada de contatos do workspace. A lista é ordenada por data de criação. Os filtros `ownerEmail` e `search` estão obsoletos e serão removidos; para encontrar um contato por um identificador, use /contacts/lookup. operationId: get_contacts_bridge_api_v1_workspaces__workspaceId__contacts_get security: - x-api-key: [] parameters: - name: workspaceId in: path required: true schema: type: string format: uuid description: Identificador único do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: ownerEmail in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Filtrar contatos pelo e-mail do proprietário title: Owneremail description: >- Filtra contatos pelo e-mail do proprietário. Obsoleto: será removido. Não há substituto; filtre por `ownerId` no seu próprio código. Consulte o histórico de alterações. - name: search in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Buscar contatos por nome, e-mail ou celular example: John Doe title: Search description: >- Busca contatos por nome, e-mail ou celular. Obsoleto: será removido. Para encontrar um contato por celular ou e-mail, use `GET /contacts/lookup`. Consulte o histórico de alterações. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de contatos por página default: 20 title: Limit description: Número de contatos por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recebido na solicitação anterior para obter a próxima página title: Cursor description: Cursor recebido na solicitação anterior para obter a próxima página responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactsResponseList" "400": description: Solicitação inválida content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: "#/components/schemas/Problem" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Criar contato description: Cria um contato no workspace informado. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateContactBody" description: Corpo da solicitação para criar um contato. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Criar ou atualizar contato description: Cria ou atualiza um contato usando apenas o celular. Classifica-o como NORMAL ou 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePartialContactBody" description: Corpo da solicitação para criar um contato parcial. Apenas cellphone é obrigatório. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ContactResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Criar uploads pré-assinados de arquivos description: >- Carregue um anexo, como um PDF, uma imagem ou um documento, antes de criar uma mensagem. Esta operação retorna os dados de um PUT pré-assinado; os bytes do arquivo são enviados separadamente. Após o upload ser concluído, use o `mediaId` retornado na operação de envio. Siga [Enviar um anexo](/pt-br/guides/send-attachments) para as etapas de checksum, upload e mensagem. Gera URLs pré-assinadas para upload de arquivos (Presigned PUT). Valida a extensão, contentType e os limites por tipo. O checksum é obrigatório: envie o resumo SHA-256 em checksumBase64 (Base64). O upload deve incluir o cabeçalho x-amz-checksum-sha256 com o mesmo valor. --- Para fazer upload dos arquivos, você DEVE usar a URL pré-assinada retornada com o método HTTP PUT. Envie o arquivo exatamente para a URL indicada, sem modificações, conforme exigido pelo AWS S3 para PUT com URL pré-assinada. Consulte a documentação oficial do AWS S3: [Documentação do AWS S3 sobre Presigned PUT](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html). Inclua todos os cabeçalhos obrigatórios indicados na resposta, por exemplo, 'x-amz-checksum-sha256' com o valor SHA-256 correto. A AWS rejeitará o upload se você não usar o método HTTP ou os cabeçalhos corretos.
TipoExtensãoTipo de conteúdoTamanho máximo
Imagem.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
Áudio.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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/PreloadedFileRequest" description: Solicitação para preparar o upload de um arquivo com uma URL pré-assinada. title: Preloaded Files responses: "201": description: Resposta bem-sucedida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: >- Retorna os atributos personalizados do workspace informado. Por padrão, retorna apenas atributos **ativos** (sem um `deletedAt` no passado). **Filtros:** - `category`: filtra por `OPEN` ou `CLOSED`. Omita para retornar todas as categorias. - `includeArchived`: use `true` para incluir atributos arquivados (com `deletedAt` no passado). Padrão: `false`. - `isRequired`: use `true` para retornar apenas atributos obrigatórios e `false` para retornar apenas opcionais. Omita para retornar 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: category in: query required: false schema: anyOf: - enum: - OPEN - CLOSED type: string - type: "null" description: Filtrar pela categoria do atributo. Omita para retornar todas as categorias. title: Category description: Filtrar pela categoria do atributo. Omita para retornar todas as categorias. - name: includeArchived in: query required: false schema: type: boolean description: >- Com `true`, os atributos arquivados (com `deletedAt` no passado) são incluídos. O padrão é `false`, que retorna apenas atributos ativos. default: false title: Includearchived description: >- Com `true`, os atributos arquivados (com `deletedAt` no passado) são incluídos. O padrão é `false`, que retorna apenas atributos ativos. - name: isRequired in: query required: false schema: anyOf: - type: boolean - type: "null" description: >- Filtrar pela obrigatoriedade. `true` retorna apenas os obrigatórios e `false` apenas os opcionais. Omita para retornar todos. title: Isrequired description: >- Filtrar pela obrigatoriedade. `true` retorna apenas os obrigatórios e `false` apenas os opcionais. Omita para retornar todos. responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/CustomAttributesResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Obter canais de provedores por workspace description: >- Obtém os canais de provedores pelo identificador do workspace. Esta resposta expõe `provider` e `identifier`, semelhante a um número de telefone, para cada canal; não retorna `providerChannelId`. Para as linhas de um Agent, leia `agents[].lines[].providerChannelId` na lista de Agents. Não substitua um ID de canal por um número de telefone. Consulte [Conceitos e identificadores](/pt-br/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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ProviderChannelResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Obter canais por workspace e tipo de provedor description: Obtém os canais de provedores pelo identificador do workspace e tipo de provedor. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: messageProviderType in: path required: true schema: $ref: "#/components/schemas/MessageProviderType" description: Tipo de provedor de mensagens (por exemplo, WHATSAPP ou HEYGIA). description: Tipo de provedor de mensagens (por exemplo, WHATSAPP ou HEYGIA). - name: brandId in: query required: false schema: anyOf: - type: string - type: "null" description: >- Identificador opcional de marca. Quando informado, retorna apenas canais cuja linha corporativa pertence à marca. Aplica-se apenas a WHATSAPP; provedores HEYGIA não têm marca. title: Brandid description: >- Identificador opcional de marca. Quando informado, retorna apenas canais cuja linha corporativa pertence à marca. Aplica-se apenas a WHATSAPP; provedores HEYGIA não têm marca. responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/ProviderChannelResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 conversa de saída do LeadScout com um lead conhecido description: >- Inicia uma conversa de saída do LeadScout com um Contact conhecido. O Contact já deve existir. A Bridge seleciona um Agent de prospecção para uma linha de WhatsApp elegível. O template é referenciado por template.id ou template.name; id tem precedência quando ambos são informados. Ele deve existir e estar APPROVED, e qualquer Bridge User de handoffOverride deve ser válido. Um contact.providerChannelId explícito é respeitado. Sem ele, a seleção automática prefere uma linha livre, depois uma conversa liberada recuperável com este Contact e, por último, uma conversa ativa ocupada somente quando forceSend=true. A disponibilidade é avaliada por Contact em cada linha, não pela ocupação global da linha. forceSend=true reutiliza uma conversa ativa elegível; não a ignora nem cria uma nova. Uma reutilização bem-sucedida retorna alreadyInitiated=true e persiste o novo template e os acompanhamentos. Uma conversa liberada recuperável pode ser recuperada com qualquer um dos valores, mantém seu ID e retorna recovered=true. Esta opção não torna utilizáveis as conversas bloqueadas nem as liberadas não recuperáveis. A rota legada pode reutilizar uma conversa controlada por um humano ou outro Agent; ao contrário da saída de Agents, ela não exige a verificação de controle pelo Agent solicitado. Uma sessão aberta do LeadScout ainda não expirada continua bloqueando uma nova solicitação de saída com 409 BRIDGE_AI_LEADSCOUT_0017; a impossibilidade de finalizar uma sessão expirada retorna 409 BRIDGE_AI_LEADSCOUT_0018. As outras validações continuam valendo. As mensagens adicionais são persistidas; a persistência não comprova a entrega nem uma espera pela resposta do lead. Uma solicitação com falha pode deixar trabalho parcial, portanto não trate forceSend como idempotência nem repita às cegas uma solicitação com resultado incerto. Consulte [o guia completo de saída](/pt-br/guides/agent-outbound) para a matriz false/true, os indicadores de resposta, as diferenças em relação à saída de Agents, os erros e a transferência. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/LeadscoutOutboundRequest" description: Corpo da solicitação para iniciar uma conversa de saída do LeadScout. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/LeadscoutOutboundResponse" "400": description: Solicitação inválida 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: Não 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: Conflito 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: Conteúdo não processável 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: Muitas solicitações 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: Erro interno do 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 transferência manual do LeadScout para usuários internos description: >- Solicita a transferência manual de uma conversa controlada pelo LeadScout para um ou mais usuários internos. A solicitação é confirmada com `202 Accepted`; a atribuição é processada de forma assíncrona. A resposta repete os destinatários solicitados e um ID de rastreamento para correlação. A resolução de usuários internos (por ID ou EMAIL) ocorre depois e não é refletida nesta resposta. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: conversationId in: path required: true schema: type: string description: Identificador único da conversa (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Conversationid description: Identificador único da conversa (UUID v4). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/HandoffRequest" description: Corpo da solicitação de transferência manual do LeadScout. responses: "202": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/HandoffResponse" "422": description: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Descobrir as variáveis agnósticas de um modelo description: >- Retorna as variáveis de um template: `key`/`label`/`callerMustSupply`/`isCustom`/`default`, independentes da posição na Meta. Nunca retorna o endereço ou índice de uma posição da Meta. `templateId` aceita o `id` ou o `name` do template. As operações de saída aceitam `template.id` ou `template.name`, com precedência para um id não vazio. A abertura de conversas usa `onboardingTemplates[].templateId`. Use o seletor exigido pela operação de envio. Consulte [a receita de templates](/pt-br/guides/send-template). Uma variável com `callerMustSupply: true` não tem uma fonte declarada: quem chama deve incluir sua `key` em `parameters` ao enviar; caso contrário, o envio falha com um 422 que identifica a mesma `key`. Uma variável com `callerMustSupply: false` é resolvida pela própria Bridge, por exemplo, o primeiro nome do destinatário, ou já tem um valor que quem chama pode substituir opcionalmente. Uma variável com `isCustom: true` é um valor conhecido apenas por quem chama e tem um `default`: envie-a em `parameters` para usar seu próprio valor, ou omita-a ou deixe-a em branco para enviar `default`. Códigos de erro: - BRIDGE_CORE_0301: o workspace na rota não corresponde ao workspace de quem chama (403) - BRIDGE_TEMPLATE_0001: nenhuma PROVIDER_TEMPLATE foi encontrada para este workspace e identificador. Abrange igualmente um id/name desconhecido, um template de outro workspace e um template que não é PROVIDER_TEMPLATE (404); este endpoint nunca confirma a existência de um template fora do workspace de quem chama 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: templateId in: path required: true schema: type: string description: "ID ou nome do modelo: ambos identificam o mesmo modelo." examples: - order_shipped_promo - f0000040-0000-4000-8000-000000000040 title: Templateid description: "ID ou nome do modelo: ambos identificam o mesmo modelo." responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/TemplateDiscoveryResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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: Obter usuário interno por um identificador description: >- Obtém um Bridge User específico por qualquer um de seus identificadores no workspace. `type=ID` retorna o mesmo usuário que GET /users/{userId}, a URL canônica de um usuário interno e a opção preferida quando você já tem seu 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: type in: query required: true schema: $ref: "#/components/schemas/InternalParticipantIdentifierType" description: >- Tipo de identificador usado para informar o valor. O celular de um usuário interno não é uma opção. description: >- Tipo de identificador usado para informar o valor. O celular de um usuário interno não é uma opção. - name: value in: query required: true schema: type: string minLength: 1 maxLength: 320 description: >- O identificador no formato indicado por `type`. Em um `EMAIL`, o domínio é convertido para minúsculas, mas a parte local deve corresponder exatamente ao valor enviado. title: Value description: >- O identificador no formato indicado por `type`. Em um `EMAIL`, o domínio é convertido para minúsculas, mas a parte local deve corresponder exatamente ao valor 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: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/InternalUserResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conteúdo não processável 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: Muitas solicitações 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: Obter usuário interno por ID description: Obtém um usuário interno específico (agente humano) pelo seu identificador único no 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: userId in: path required: true schema: type: string format: uuid description: Identificador único do usuário interno (UUID v4). examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Userid description: Identificador único do usuário interno (UUID v4). responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/InternalUserResponse" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 usuários internos description: >- Consulta uma lista paginada de usuários internos do workspace. A lista é ordenada por data de criação. Os filtros `email` e `status` estão obsoletos e serão removidos; para encontrar um usuário interno por um identificador, use /users/lookup. operationId: get_internal_users_bridge_api_v1_workspaces__workspaceId__users_get security: - x-api-key: [] parameters: - name: workspaceId in: path required: true schema: type: string format: uuid description: Identificador único do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: email in: query required: false deprecated: true schema: anyOf: - type: string - type: "null" description: Filtrar usuários internos pelo e-mail exato. example: john.doe@example.com title: Email description: >- Filtra usuários internos pelo e-mail exato. Obsoleto: será removido. Use `GET /users/lookup?type=EMAIL`. Consulte o histórico de alterações. - name: status in: query required: false deprecated: true schema: $ref: "#/components/schemas/UserStatusFilter" description: "Filtrar por status: 'active' (padrão), 'disabled' ou 'all'." default: active description: >- Filtra por status: 'active' (padrão), 'disabled' ou 'all'. Obsoleto: será removido. Leia `status` em cada linha. Consulte o histórico de alterações. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Número de usuários internos por página default: 20 title: Limit description: Número de usuários internos por página - name: cursor in: query required: false schema: anyOf: - type: string - type: "null" description: Cursor recebido em uma solicitação anterior para obter a próxima página title: Cursor description: Cursor recebido em uma solicitação anterior para obter a próxima página responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/InternalUsersResponseList" "400": description: Solicitação inválida content: application/json: examples: INVALID_CURSOR: value: title: Invalid Cursor status: 400 code: BRIDGE_CORE_0104 schema: $ref: "#/components/schemas/Problem" "403": description: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 os Agents de um workspace description: >- Lista os Agents do workspace com seu status, disponibilidade e linhas. Inclui todos os Agents, independentemente do status; `available` indica se podem iniciar conversas. Uma página pode conter menos itens que `limit`; continue a paginação enquanto `cursor` não for 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: type in: query required: false schema: anyOf: - $ref: "#/components/schemas/AgentType" - type: "null" description: Retorna apenas Agents deste tipo. title: Type description: Retorna apenas Agents deste 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 recebido em uma solicitação anterior para obter a próxima página title: Cursor description: Cursor recebido em uma solicitação anterior para obter a próxima página responses: "200": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/AgentsResponseList" "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "422": description: Erro de validação content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" "429": description: Muitas solicitações 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 conversa de saída com um Contact como Agent específico description: >- Inicia uma conversa de saída com um Contact conhecido, atendida pelo Agent indicado. Funciona com Agents LeadScout e Service. Primeiro é resolvido o Contact e depois o Agent, que deve existir no workspace e estar disponível (consulte `GET /agents`). O template é referenciado por `template.id` ou `template.name` (id tem precedência quando ambos são enviados), deve existir e estar APPROVED, e qualquer Bridge User de `handoffOverride` deve ser válido. Se `template.media.mediaId` for desconhecido, a solicitação falha com 400 `BRIDGE_AI_LEADSCOUT_0016` somente depois de a conversa ser criada ou recuperada, portanto uma nova tentativa após esse erro pode responder de forma diferente. As regras do corpo (`consent.status=GRANTED` sem `capturedAt`, ou `template.media` sem exatamente um de `mediaId` ou `url`) falham com 400 `BRIDGE_CORE_0103`. A conversa é aberta em uma das linhas ativas de WhatsApp do Agent, sob seu controle, com o template como primeira mensagem. A linha é escolhida nesta ordem: - Uma linha livre. - Caso contrário, uma linha com uma conversa liberada recuperável com este Contact. A recuperação retorna `recovered=true` e substitui o contexto de saída anterior e `agentContext`. Isso acontece mesmo com `forceSend=false`. - Se nenhuma linha estiver livre ou for recuperável: `forceSend=false` (padrão) falha com 409 `BRIDGE_AI_LEADSCOUT_0008`; `forceSend=true` reutiliza uma linha ocupada por uma conversa ativa com este Contact, dando preferência a uma controlada por este Agent. Se a conversa escolhida for controlada por outro Agent ou por um Bridge User, a chamada falha com 409 `BRIDGE_AI_AGENT_OUTBOUND_0006` e nada é gravado. Libere-a primeiro e tente novamente. Linhas cuja conversa está bloqueada ou foi liberada sem recuperação nunca são usadas; assim, se nenhuma linha estiver ocupada por uma conversa ativa, a chamada falha com 409 `BRIDGE_AI_LEADSCOUT_0008` mesmo com `forceSend=true`. `contact.providerChannelId` é uma preferência: a linha indicada é usada quando está livre ou é recuperável; caso contrário, a mesma ordem é aplicada entre todas as linhas do Agent. Entre as linhas ocupadas, uma controlada por este Agent tem prioridade; se nenhuma for, a linha indicada é reutilizada (e pode falhar com 0006). A reutilização de uma conversa depende do tipo de Agent: - LeadScout: se sua sessão do LeadScout ainda estiver aberta e não expirada, a chamada falha com 409 `BRIDGE_AI_LEADSCOUT_0017` (`extra` inclui `conversationId`, `sessionId` e `stage`). Se uma sessão expirada não puder ser finalizada, falha com 409 `BRIDGE_AI_LEADSCOUT_0018`. - Service Agent: uma sessão de serviço aberta e não expirada continua; uma sessão expirada é encerrada como abandonada e uma nova é aberta. Consulte [o guia completo de saída](/pt-br/guides/agent-outbound) para os pré-requisitos, a tabela de decisão de forceSend, a recuperação, o trabalho parcial e as decisões seguras de nova tentativa. 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 do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 title: Workspaceid description: Identificador único do workspace (UUID v4). - name: agentId in: path required: true schema: type: string format: uuid description: Identificador único do Agent (UUID v4), conforme `GET /agents`. examples: - 4e362e2b-67b2-4a7e-a9df-e9ecf9141be8 title: Agentid description: Identificador único do Agent (UUID v4), conforme `GET /agents`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AgentOutboundRequest" description: Corpo da solicitação para iniciar uma conversa de saída atendida por um Agent específico. responses: "201": description: Resposta bem-sucedida content: application/json: schema: $ref: "#/components/schemas/AgentOutboundResponse" "400": description: Solicitação inválida 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: Acesso proibido content: application/json: examples: FORBIDDEN: value: title: Forbidden status: 403 code: BRIDGE_CORE_0301 schema: $ref: "#/components/schemas/Problem" "404": description: Não 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: Conflito 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: Conteúdo não processável 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: Muitas solicitações 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 da linha (o mesmo valor recebido por `providerChannelId` nas operações de saída). type: object required: - providerChannelId title: AgentLine description: Linha de WhatsApp na qual um Agent responde. AgentOutboundContactRef: properties: identifier: type: string title: Identifier description: >- Identificador do Contact conforme identifierType: ID do Contact para ID, e-mail para EMAIL ou telefone em formato E.164 para PHONE. O Contact já deve existir no 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: Provedor usado para entregar o modelo. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: >- Opcional. Linha preferida do Agent (o `providerChannelId` de uma de suas `lines` em `GET /agents`). Se omitida, qualquer uma de suas linhas pode ser usada. Se informada, deve ser uma linha ativa do Agent; caso contrário, a solicitação falha com 422. É uma preferência, não uma garantia: se a linha não estiver livre nem for recuperável, a mesma ordem se aplica a todas as linhas do Agent (com `forceSend=true`, primeiro uma ocupada controlada por este Agent e depois a indicada). A resposta não identifica a linha utilizada. examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: AgentOutboundContactRef description: Identifica o Contact ao qual a conversa de saída será direcionada. AgentOutboundContext: properties: notes: anyOf: - type: string maxLength: 2000 - type: "null" title: Notes description: Notas em texto livre para o 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 opcionais de arquivos pré-carregados armazenados na conversa como contexto para o Agent. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: AgentOutboundContext description: Notas e mídias armazenadas na conversa como contexto para o Agent e os Bridge Users. AgentOutboundFollowUp: properties: messageBody: type: string title: Message Body description: Corpo em texto simples da mensagem de acompanhamento. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: >- Aceito, mas ainda não utilizado: os acompanhamentos são armazenados apenas como texto e os anexos não são enviados. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: AgentOutboundFollowUp description: Acompanhamento de texto armazenado na conversa logo após o modelo inicial. AgentOutboundHandoffOverride: properties: preAssignedUser: $ref: "#/components/schemas/AgentOutboundPreAssignedUser" title: Pre-assigned User description: >- Bridge User a ser atribuído como consultor quando o Agent transferir a conversa. Validado durante a solicitação: ela é rejeitada se o usuário não existir, pertencer a outro workspace ou tiver sido excluído. examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: AgentOutboundHandoffOverride description: Pré-atribui o Bridge User que recebe a transferência da conversa de saída. AgentOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Valor que identifica o Bridge User, interpretado conforme identifierType. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Como resolver o identificador. ID busca pelo ID do Bridge User; EMAIL busca pelo e-mail. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: AgentOutboundPreAssignedUser description: Identifica o Bridge User que deve receber a transferência. AgentOutboundRequest: properties: contact: $ref: "#/components/schemas/AgentOutboundContactRef" title: Contact description: Contact ao qual esta conversa de saída é direcionada. Já deve existir no workspace. template: $ref: "#/components/schemas/LeadscoutOutboundTemplateRef" title: Template description: Modelo inicial a ser enviado. additionalMessages: items: $ref: "#/components/schemas/AgentOutboundFollowUp" type: array maxItems: 5 title: Additional Messages description: >- Até cinco acompanhamentos de texto armazenados na conversa após o modelo inicial, na ordem informada, e enviados como o modelo. Os anexos (`mediaIds`) ainda não são enviados. agentContext: anyOf: - $ref: "#/components/schemas/AgentOutboundContext" - type: "null" title: Agent Context description: Notas e mídias opcionais armazenadas na conversa como contexto para o Agent. consent: anyOf: - $ref: "#/components/schemas/OutboundConsentRequest" - type: "null" title: Consent description: Evidência opcional de consentimento, declarada pela empresa, registrada na conversa. handoffOverride: anyOf: - $ref: "#/components/schemas/AgentOutboundHandoffOverride" - type: "null" title: Handoff Override description: >- Opcional. Pré-atribui um Bridge User específico como consultor para a transferência. O Bridge User é validado antes de qualquer gravação: a solicitação é rejeitada se o usuário não existir, pertencer a outro workspace ou tiver sido excluído. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- ID opcional da marca. Quando informado, apenas as linhas do Agent vinculadas à marca são elegíveis; se não houver nenhuma, a solicitação falha com 404. Omita para considerar todas as linhas do Agent. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: "null" title: Campaign Identifier description: Referência opcional de campanha armazenada na conversa para auditoria e relatórios. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: >- Controla o que acontece quando nenhuma linha do Agent está livre ou é recuperável. Uma linha livre sempre tem prioridade, seguida de uma linha com uma conversa liberada recuperável com este Contact, qualquer que seja o valor desta opção. Quando nenhuma existe: com false (padrão), a solicitação falha com 409 `BRIDGE_AI_LEADSCOUT_0008`; com true, uma linha ocupada por uma conversa ativa com este Contact é reutilizada, dando preferência a uma controlada por este Agent. Se a conversa escolhida for controlada por outro Agent ou por um Bridge User, a solicitação falha com 409 `BRIDGE_AI_AGENT_OUTBOUND_0006` e nada é gravado; libere-a primeiro e tente novamente. Linhas cuja conversa está bloqueada ou foi liberada sem recuperação nunca são usadas; portanto, se nenhuma linha estiver ocupada por uma conversa ativa, a solicitação falha com 409 `BRIDGE_AI_LEADSCOUT_0008` mesmo com true. default: false examples: - false - true type: object required: - contact - template title: AgentOutboundRequest description: Corpo da solicitação para iniciar uma conversa de saída atendida por um Agent específico. AgentOutboundResponse: properties: conversation: $ref: "#/components/schemas/ConversationResponse" title: Conversation description: >- Conversa agora controlada pelo Agent: nova, reutilizada (`alreadyInitiated`) ou recuperada (`recovered`). contact: $ref: "#/components/schemas/ContactResponse" title: Contact description: Contato com o qual a conversa foi iniciada. templateSent: anyOf: - $ref: "#/components/schemas/AgentTemplateSent" - type: "null" title: Template Sent description: Resumo do modelo armazenado para abrir a conversa. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Número de mensagens de acompanhamento armazenadas na conversa. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: >- True quando esta solicitação bem-sucedida reutilizou uma conversa ativa existente por forceSend=true. False para criação ou recuperação; consulte recovered para distinguir esses caminhos. É informativo: uma reutilização bem-sucedida também armazena o novo modelo e os acompanhamentos, portanto repetir a solicitação pode adicionar mensagens. default: false examples: - false - true recovered: type: boolean title: Recovered description: >- True quando uma conversa liberada que o Contact tinha na linha foi recuperada em vez de criar outra. A recuperação substitui o contexto de saída anterior e `agentContext`. Linhas recuperáveis são usadas mesmo com `forceSend=false`. default: false examples: - false - true type: object required: - conversation - contact title: AgentOutboundResponse description: Corpo da resposta de uma iniciação de saída bem-sucedida do Agent. AgentResponse: properties: id: type: string title: Agent Identifier description: Identificador único do Agent. name: type: string title: Name description: Nome do Agent. description: anyOf: - type: string - type: "null" title: Description description: Descrição do Agent. Sempre presente; null quando não há descrição. 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 à qual o Agent pertence. Sempre presente; null quando não está limitado a uma marca. status: $ref: "#/components/schemas/AgentConfigStatus" title: Status description: Status de configuração do Agent. examples: - DRAFT - COMPLETE available: type: boolean title: Available description: "Indica se o Agent pode iniciar conversas: sua configuração está completa e ele tem uma linha." unavailableReason: anyOf: - type: string - type: "null" title: Unavailable Reason description: >- Motivo pelo qual o Agent não está disponível: `DRAFT` (configuração incompleta) ou `NO_LINES` (sem linha ativa). Sempre presente; null quando está disponível. examples: - DRAFT - NO_LINES lines: items: $ref: "#/components/schemas/AgentLine" type: array title: Lines description: Linhas ativas de WhatsApp nas quais o Agent responde. Vazio quando não há nenhuma. type: object required: - id - name - type - status - available title: AgentResponse description: Agent do workspace com seu status e disponibilidade. AgentTemplateSent: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID do modelo enviado. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Nome do modelo despachado. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: "null" title: Message Identifier description: ID da mensagem do Bridge referente ao modelo. Sempre presente; não é um `wamid` do WhatsApp. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - name title: AgentTemplateSent description: Resumo do modelo armazenado para abrir a conversa. AgentType: type: string enum: - LEADSCOUT - SERVICE_AGENT title: AgentType description: Tipos de Agent expostos pela 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 a ser enviado ao solicitar a próxima página. É null na última página. type: object required: - agents title: AgentsResponseList description: Corpo da resposta para listar os Agents de um workspace. ClosedAttribute: properties: id: type: string title: Identifier description: Identificador único do atributo fechado examples: - 62de01f0-fd48-467c-9c35-18647c51532a value: anyOf: - type: string - type: "null" title: Value description: Valor dos atributos fechados type: object required: - id title: ClosedAttribute description: Objeto que representa os valores de atributos fechados. ClosedAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Identificador único do atributo personalizado fechado. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 closedCustomAttributeIds: items: type: string type: array title: Closed Custom Attribute Identifiers description: Lista de identificadores únicos dos valores de atributos fechados. examples: - - 62de01f0-fd48-467c-9c35-18647c51532a - 6faf42bb-7d7b-44bd-9e79-5de6fd491134 type: object required: - customAttributeId - closedCustomAttributeIds title: ClosedAttributeRequest description: Corpo da solicitação para operações de atributos personalizados fechados. ConsentStatus: type: string enum: - GRANTED - NOT_PROVIDED title: ConsentStatus ContactResponse: properties: id: type: string title: Identifier description: Identificador único do contato (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Identificador único do workspace ao qual este contato pertence examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 type: $ref: "#/components/schemas/ExternalUserType" title: Contact Type description: >- NORMAL quando todos os campos obrigatórios de identidade e atributos personalizados estão presentes; PARTIAL caso contrário. examples: - NORMAL - PARTIAL firstName: anyOf: - type: string - type: "null" title: First Name description: Nome do contato. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Sobrenome do contato. examples: - Doe - null email: anyOf: - type: string format: email - type: "null" title: Email description: E-mail do contato. examples: - john.doe@example.com - null cellphone: anyOf: - type: string format: phone - type: "null" title: Cellphone description: Número de celular do contato. examples: - "+14084029292" - null customAttributes: items: $ref: "#/components/schemas/CustomAttributeResponse" type: array title: Custom Attributes description: Lista de atributos personalizados de chave e valor. languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma do usuário externo. examples: - EN - null ownerId: anyOf: - type: string - type: "null" title: Owner Identifier description: ID do Bridge User proprietário do contato. Resolva-o com `GET /users/{userId}`. examples: - 37673840-6259-40f9-bbe5-a7db40f8e3cf - null createdAt: type: string title: Created At description: Data e hora de criação do contato. examples: - "2003-04-10T08:00:00.000Z" updatedAt: type: string title: Updated At description: Data e hora da última atualização do contato. examples: - "2003-04-10T08:00:00.000Z" type: object required: - id - workspaceId - type - createdAt - updatedAt title: ContactResponse description: Corpo da resposta para operações com contatos. ContactsResponseList: properties: contacts: items: $ref: "#/components/schemas/ContactResponse" type: array title: Contacts description: Lista de contatos. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor a ser enviado ao solicitar a próxima página. type: object required: - contacts title: ContactsResponseList description: Corpo da resposta para listar contatos. ConversationListResponse: properties: conversations: items: $ref: "#/components/schemas/ConversationResponse" type: array title: Conversations description: Lista de conversas. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor para obter a próxima página de conversas. É null quando não há mais páginas. examples: - null - eyJ2IjoxLCJjIjp7InN0IjoxfX0 type: object required: - conversations title: ConversationListResponse description: Corpo da resposta para listar conversas com paginação. 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: Corpo da resposta para os participantes de uma conversa. ConversationResponse: properties: id: type: string title: Identifier description: Identificador único da conversa (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 workspaceId: type: string title: Workspace Identifier description: Identificador único do workspace (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 participants: $ref: "#/components/schemas/ConversationParticipantsResponse" title: Participants description: Participantes da conversa. name: anyOf: - type: string - type: "null" title: Name description: Nome ou título opcional da conversa. examples: - Bridge Support Team status: anyOf: - $ref: "#/components/schemas/ConversationStatus" - type: "null" title: Status description: >- Status atual da conversa: 'ACTIVE' para conversas visíveis e 'GHOST' para conversas invisíveis até a primeira interação. examples: - ACTIVE createdAt: type: string format: date-time title: Created At description: Data e hora de criação da conversa. examples: - "2003-04-10T09:00:00.000Z" updatedAt: type: string format: date-time title: Updated At description: Data e hora da última atualização da conversa. examples: - "2003-04-10T09:00:00.000Z" type: object required: - id - workspaceId - participants - createdAt - updatedAt title: ConversationResponse description: Corpo da resposta para os detalhes de uma conversa. ConversationStatus: type: string enum: - ACTIVE - GHOST - RELEASED - NOT_ASSIGNED_TO_HUMAN - BLOCKED title: ConversationStatus CreateContactBody: properties: firstName: type: string title: First Name description: Nome do contato. examples: - John - Alice lastName: type: string title: Last Name description: Sobrenome do contato. examples: - Doe email: anyOf: - type: string format: email - type: "null" title: Email description: E-mail do contato. examples: - john.doe@example.com - null languageCode: $ref: "#/components/schemas/LanguageCode" title: Language Code description: Código de idioma do contato. examples: - EN cellphone: type: string title: Cellphone description: Número de celular do contato. Sem código de país, é interpretado conforme o país do workspace. examples: - "+14084029292" ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador do vendedor ou usuário proprietário do contato. customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto com atributos personalizados abertos e fechados. additionalProperties: false type: object required: - firstName - lastName - languageCode - cellphone title: CreateContactBody description: Corpo da solicitação para criar um contato. CreateConversationRequest: properties: participants: $ref: "#/components/schemas/CreateParticipantsOnConversationRequest" title: Participants description: Participantes a adicionar à conversa. name: anyOf: - type: string - type: "null" title: Name description: Nome ou título opcional da conversa. examples: - Bridge Support Team - null status: $ref: "#/components/schemas/ConversationStatus" title: Status description: >- Status inicial da conversa: 'active' para conversas visíveis e 'ghost' para conversas invisíveis até a primeira interação. default: ACTIVE examples: - ACTIVE teamId: anyOf: - type: string format: uuid - type: "null" title: Team Identifier description: >- UUID da equipe para distribuição em rodízio (opcional e mutuamente exclusivo com internalParticipants). examples: - 9fd1468d-e5ca-4ba3-98d1-13017e6f3808 onboardingTemplates: items: $ref: "#/components/schemas/OnboardingTemplateRequest" type: array title: Onboarding Templates description: >- Templates ordenados para abrir a conversa. Eles substituem a sequência de abertura configurada no workspace para esta conversa, por inteiro ou apenas seu primeiro template, conforme a configuração do workspace; no segundo caso, o restante da sequência configurada ainda é enviado depois dos seus. A posição determina a ordem. Omita para manter o padrão do workspace. Cada template deve existir, pertencer ao seu workspace ou ao escopo da plataforma e, para templates de provedor do WhatsApp, estar aprovado pela Meta para a WhatsApp Business Account da linha pela qual cada participante é contatado; caso contrário, a solicitação é rejeitada e nenhuma conversa é criada. Um template cujas variáveis precisem de valores que só você pode fornecer os recebe em `parameters` da entrada. Se um dos templates configurados enviados depois dos seus precisar de valores que só quem chama pode fornecer, a solicitação é rejeitada com 422 `BRIDGE_CONVERSATION_0608`, com `extra.templateId` identificando esse template e `extra.origin` definido como `WORKSPACE_CONFIGURATION`. Alterar a solicitação não ajudará: peça a um administrador do workspace que altere a sequência de abertura. additionalProperties: false type: object required: - participants title: CreateConversationRequest description: Corpo da solicitação para criar uma conversa. CreatePartialContactBody: properties: cellphone: type: string title: Cellphone description: >- Número de celular do contato. Sem código de país, é interpretado conforme o país do workspace. Usado para identificar o contato durante o upsert. examples: - "+14084029292" firstName: anyOf: - type: string - type: "null" title: First Name description: Nome do contato. Obrigatório para a classificação NORMAL. examples: - Maria - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Sobrenome do contato. Obrigatório para a classificação NORMAL. examples: - Lopez - null email: anyOf: - type: string format: email - type: "null" title: Email description: E-mail do contato. examples: - maria@acme.com - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma do contato. Obrigatório para a classificação NORMAL. examples: - EN - null ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador do vendedor ou usuário proprietário do contato. examples: - identifier: jane@acme.com identifierType: EMAIL - null customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto com atributos personalizados abertos e fechados. examples: - closedAttributes: [] openAttributes: [] additionalProperties: false type: object required: - cellphone title: CreatePartialContactBody description: Corpo da solicitação para criar um contato parcial. Apenas cellphone é obrigatório. CreateParticipantsOnConversationRequest: properties: externals: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Externals description: Lista de identificadores de usuários externos. internals: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Internals description: Lista de identificadores de usuários internos (opcional e mutuamente exclusiva com teamId). type: object title: CreateParticipantsOnConversationRequest description: Corpo da solicitação de participantes ao criar uma conversa. CustomAttributeResponse: properties: key: type: string title: Key description: Chave ou nome do atributo values: items: type: string type: array title: Values description: Valor do atributo type: object required: - key title: CustomAttributeResponse description: Corpo da resposta para atributos personalizados em operações com contatos. CustomAttributes: properties: id: type: string title: Identifier description: Identificador único do atributo personalizado. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 category: type: string enum: - OPEN - CLOSED title: Category description: Categoria do atributo personalizado. examples: - OPEN - CLOSED isRequired: type: boolean title: Is Required description: Define se o atributo personalizado é obrigatório. examples: - true - false keyName: type: string title: Key Name description: Nome do atributo personalizado. closedAttributesValues: anyOf: - items: $ref: "#/components/schemas/ClosedAttribute" type: array - type: "null" title: Closed Attributes Values description: Lista de valores do atributo fechado. type: type: string enum: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT title: Type description: Tipo dos valores dos atributos personalizados. examples: - TEXT - NUMBER - DATE - SELECT - MULTI_SELECT deletedAt: anyOf: - type: string - type: "null" title: Deleted At description: Data e hora da exclusão lógica. Null indica que o atributo está ativo. type: object required: - id - category - isRequired - keyName - type title: CustomAttributes description: Objeto que representa o atributo personalizado. CustomAttributesBody: properties: openAttributes: anyOf: - items: $ref: "#/components/schemas/OpenAttributeRequest" type: array - type: "null" title: Open Attributes description: Lista de atributos abertos. closedAttributes: anyOf: - items: $ref: "#/components/schemas/ClosedAttributeRequest" type: array - type: "null" title: Closed Attributes description: Lista de atributos fechados. type: object title: CustomAttributesBody description: Corpo da solicitação para operações de atributos personalizados. CustomAttributesResponse: properties: customAttributes: items: $ref: "#/components/schemas/CustomAttributes" type: array title: Custom Attributes description: Lista de objetos de atributos personalizados com seus valores. type: object required: - customAttributes title: CustomAttributesResponse description: Corpo da resposta para operações de atributos personalizados. ExternalOperationRequest: properties: add: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Add description: Participantes externos a adicionar. remove: items: $ref: "#/components/schemas/ExternalUserIdentifierRequest" type: array title: Remove description: Participantes externos a remover. type: object title: ExternalOperationRequest description: Operações sobre participantes externos de uma conversa. ExternalParticipant: properties: identifier: type: string title: Identifier description: Valor do identificador do 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 ou PHONE). examples: - EMAIL - PHONE - ID role: $ref: "#/components/schemas/UserType" title: Role description: Papel do participante na conversa. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Data e hora em que o participante entrou na conversa. examples: - "2004-04-10T09:00:00.000Z" lastSeenAt: anyOf: - type: string format: date-time - type: "null" title: Last Seen At description: Data e hora da última atividade observada do participante. examples: - null - "2004-04-10T09:00:00.000Z" type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Objeto que representa o participante externo da conversa. ExternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: Valor do identificador do usuário. 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 usuários externos (ID, EMAIL ou PHONE). examples: - EMAIL - PHONE - ID messageProviderType: anyOf: - $ref: "#/components/schemas/MessageProviderType" - type: "null" title: Message Provider Type description: Tipo de provedor de mensagens da conversa. examples: - WHATSAPP - null providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: ID do canal do provedor usado pelo Bridge para se comunicar com o usuário. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- Marca proprietária da linha corporativa usada para contatar o usuário. Quando o workspace tem pelo menos uma linha com marca, a seleção automática de linhas é limitada a essa marca e a solicitação deve incluir brandId ou providerChannelId; a ausência de ambos é rejeitada. Ignorado quando o workspace não tem linhas com marca. type: object required: - identifier - identifierType title: ExternalUserIdentifierRequest description: Corpo para identificar um usuário externo no 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 ou e-mail do usuário interno, conforme identifierType. examples: - u-123 - ana@acme.com identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Estratégia de busca do usuário interno. Apenas ID e EMAIL são aceitos. examples: - ID - EMAIL additionalProperties: false type: object required: - identifier - identifierType title: HandoffAssignee description: Usuário interno ao qual a conversa será atribuída durante uma transferência. HandoffRequest: properties: assignees: items: $ref: "#/components/schemas/HandoffAssignee" type: array minItems: 1 title: Assignees description: Usuários internos que receberão a transferência da conversa. Pelo menos um é obrigatório. handoffMessages: items: type: string type: array title: Handoff Messages description: Corpos de mensagens opcionais publicados como parte da transferência. includeAiLeadSummary: type: boolean title: Include AI Lead Summary description: Com true, a mensagem de transferência deve incluir um resumo do lead gerado por IA. default: false additionalProperties: false type: object required: - assignees title: HandoffRequest description: Corpo da solicitação de transferência manual do LeadScout. HandoffResponse: properties: trackingId: type: string title: Tracking Identifier description: ID de correlação gerado para esta solicitação de transferência. conversationId: type: string title: Conversation Identifier description: Conversa à qual a transferência é direcionada. status: type: string title: Status description: Status de aceitação da solicitação de transferência. examples: - ACCEPTED assignees: items: $ref: "#/components/schemas/HandoffAssignee" type: array title: Assignees description: Repete os destinatários recebidos na solicitação. type: object required: - trackingId - conversationId - status - assignees title: HandoffResponse description: Corpo da resposta que confirma a aceitação da solicitação de transferência. HeaderFileType: type: string enum: - IMAGE - VIDEO - GIF title: HeaderFileType InternalOperationRequest: properties: add: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Add description: Participantes internos a adicionar. remove: items: $ref: "#/components/schemas/InternalUserIdentifierRequest" type: array title: Remove description: Participantes internos a remover type: object title: InternalOperationRequest description: Operações sobre participantes internos de uma conversa. InternalParticipant: properties: identifier: type: string title: Identifier description: Valor do identificador do participante. examples: - ef7ee722-5f95-415a-9a98-81eeae178b11 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Tipo de identificador de participantes internos (ID ou EMAIL). examples: - EMAIL - ID role: $ref: "#/components/schemas/UserType" title: Role description: Papel do participante na conversa. examples: - EXTERNAL - INTERNAL joinedAt: type: string format: date-time title: Joined At description: Data e hora em que o participante entrou na conversa. examples: - "2004-04-10T09:00:00.000Z" lastSeenAt: anyOf: - type: string format: date-time - type: "null" title: Last Seen At description: Data e hora da última atividade observada do participante. examples: - null - "2004-04-10T09:00:00.000Z" type: object required: - identifier - identifierType - role - joinedAt title: Participant description: Objeto que representa o participante interno da conversa. InternalParticipantIdentifierType: type: string enum: - ID - EMAIL title: InternalParticipantIdentifierType InternalUserIdentifierRequest: properties: identifier: type: string title: Identifier description: Valor do identificador do usuário. examples: - john.doe@example.com - "+13802098869" - 37673840-6259-40f9-bbe5-a7db40f8e3cf identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Tipo de identificador de usuários internos (ID ou EMAIL). examples: - EMAIL - ID type: object required: - identifier - identifierType title: InternalUserIdentifierRequest description: Corpo para identificar um usuário interno no Bridge. InternalUserResponse: properties: id: type: string title: Identifier description: Identificador único do usuário interno (UUID v4). examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 firstName: anyOf: - type: string - type: "null" title: First Name description: Nome do usuário interno. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Sobrenome do usuário interno. examples: - Doe - null email: anyOf: - type: string - type: "null" title: Email description: E-mail do usuário interno. examples: - john.doe@example.com - null cellphone: anyOf: - type: string - type: "null" title: Cellphone description: Número de celular do usuário interno. examples: - "+14084029292" - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma do usuário interno. examples: - EN - null status: type: string enum: - active - disabled title: Status description: "'active' quando o usuário interno está ativo; 'disabled' quando o usuário foi removido." examples: - active - disabled createdAt: type: string title: Created At description: Data e hora de criação do usuário interno. examples: - "2003-04-10T08:00:00.000Z" updatedAt: type: string title: Updated At description: Data e hora da última atualização do usuário interno. examples: - "2003-04-10T08:00:00.000Z" type: object required: - id - status - createdAt - updatedAt title: InternalUserResponse description: Corpo da resposta para operações de leitura de usuários internos (agentes humanos). InternalUsersResponseList: properties: users: items: $ref: "#/components/schemas/InternalUserResponse" type: array title: Users description: Lista de usuários internos. cursor: anyOf: - type: string - type: "null" title: Cursor description: Cursor a ser enviado ao solicitar a próxima página. type: object required: - users title: InternalUsersResponseList description: Corpo da resposta para listar usuários 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 do Contact conforme identifierType: ID do Contact para ID, e-mail para EMAIL ou telefone em formato E.164 para PHONE. O Contact já deve existir no 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: Provedor usado para entregar o modelo. examples: - WHATSAPP providerChannelId: anyOf: - type: string - type: "null" title: Provider Channel Identifier description: >- ID opcional de linha explícita de WhatsApp. Quando informado, essa linha é usada, deve pertencer ao workspace e resolver para um Agent de prospecção. Se omitido, as linhas elegíveis são selecionadas automaticamente: primeiro livres, depois liberadas recuperáveis e, apenas com forceSend=true, ocupadas. Quando informado, brandId limita os candidatos à marca. O ID da linha não é um número de telefone. Consulte [identificadores](/pt-br/guides/identifiers) e [seleção de saída](/pt-br/guides/agent-outbound). examples: - c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c - null type: object required: - identifier - identifierType - messageProviderType title: LeadscoutOutboundContactRef description: Identifica o lead ao qual a conversa de saída será direcionada. LeadscoutOutboundHandoffOverride: properties: preAssignedUser: $ref: "#/components/schemas/LeadscoutOutboundPreAssignedUser" title: Pre-assigned User description: >- Usuário interno a ser atribuído como consultor quando a IA transferir a conversa. Validado durante a solicitação: se o usuário não existir, estiver inativo ou pertencer a outro workspace, a solicitação será rejeitada antes de criar uma conversa. examples: - identifier: advisor@acme.com identifierType: EMAIL additionalProperties: false type: object required: - preAssignedUser title: LeadscoutOutboundHandoffOverride description: Substitui a atribuição padrão do consultor da conversa de saída. LeadscoutOutboundPreAssignedUser: properties: identifier: type: string title: Identifier description: Valor que identifica o usuário interno, interpretado conforme identifier_type. examples: - advisor@acme.com - usr_01HZ2K3J4M5N6P7Q8R9S0T1UV2 identifierType: $ref: "#/components/schemas/InternalParticipantIdentifierType" title: Identifier Type description: Como resolver o identificador. ID busca pelo ID do usuário interno; EMAIL busca pelo e-mail. examples: - EMAIL - ID additionalProperties: false type: object required: - identifier - identifierType title: LeadscoutOutboundPreAssignedUser description: Identifica o usuário interno que deve receber a transferência. LeadscoutOutboundRequest: properties: contact: $ref: "#/components/schemas/LeadscoutOutboundContactRef" title: Contact description: Lead ao qual esta conversa de saída é direcionada. Já deve existir no workspace. template: $ref: "#/components/schemas/LeadscoutOutboundTemplateRef" title: Template description: Modelo inicial a ser enviado. additionalMessages: items: $ref: "#/components/schemas/OutboundFollowUpRequest" type: array maxItems: 5 title: Additional Messages description: >- Até cinco mensagens de acompanhamento armazenadas na conversa na ordem da solicitação. A persistência não confirma a entrega. Não presuma que essas mensagens aguardam a resposta do lead; consulte o guia de saída para considerações sobre entrega e novas tentativas. agentContext: anyOf: - $ref: "#/components/schemas/OutboundAgentContextRequest" - type: "null" title: Agent Context description: Notas e mídias opcionais armazenadas na conversa como contexto para o agente. consent: anyOf: - $ref: "#/components/schemas/OutboundConsentRequest" - type: "null" title: Consent description: Evidência opcional de consentimento, declarada pela empresa, registrada na conversa. handoffOverride: anyOf: - $ref: "#/components/schemas/LeadscoutOutboundHandoffOverride" - type: "null" title: Handoff Override description: >- Opção para pré-atribuir um usuário interno específico como consultor da transferência. Validada durante a solicitação; em caso de falha, a criação da conversa é cancelada. brandId: anyOf: - type: string - type: "null" title: Brand Identifier description: >- ID opcional da marca. Quando informado, apenas os canais vinculados a ela são elegíveis. Omita para considerar todos os canais do workspace. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f campaignId: anyOf: - type: string - type: "null" title: Campaign Identifier description: Referência opcional de campanha armazenada na conversa para auditoria e relatórios. examples: - null - spring_promo_2026 forceSend: type: boolean title: Force Send description: >- Controla a reutilização de uma conversa ativa existente com este Contact na linha escolhida. Com false (padrão), uma linha ocupada selecionada explicitamente retorna 409 BRIDGE_AI_LEADSCOUT_0007; a seleção automática com apenas linhas ocupadas retorna 409 BRIDGE_AI_LEADSCOUT_0008. Com true, uma conversa ocupada elegível é reutilizada em vez de criar uma nova, e uma reutilização bem-sucedida define alreadyInitiated=true. A seleção automática prefere uma linha livre, depois uma conversa liberada recuperável e, por último, uma conversa ocupada quando true. A recuperação é possível com qualquer um dos valores e retorna recovered=true. A rota legada do LeadScout pode reutilizar uma conversa controlada por um humano; ela não aplica a verificação de controle da saída de Agents. Esta opção não ignora conversas bloqueadas/não recuperáveis, verificações de sessão ou outras validações e não é uma chave de idempotência. Consulte [Saída de Agents e forceSend](/pt-br/guides/agent-outbound). default: false examples: - false - true type: object required: - contact - template title: LeadscoutOutboundRequest description: Corpo da solicitação para iniciar uma conversa de saída do LeadScout. LeadscoutOutboundResponse: properties: conversation: $ref: "#/components/schemas/ConversationResponse" title: Conversation description: >- Conversa usada para esta solicitação de saída: nova, reutilizada (alreadyInitiated=true) ou recuperada (recovered=true). Uma conversa reutilizada mantém seu ID; a reutilização legacy, por si só, não implica mudança de controlador. contact: $ref: "#/components/schemas/ContactResponse" title: Contact description: Contato com o qual a conversa foi iniciada. templateSent: anyOf: - $ref: "#/components/schemas/LeadscoutTemplateSent" - type: "null" title: Template Sent description: Resumo do modelo despachado. additionalMessagesPersisted: type: integer title: Additional Messages Persisted description: Número de mensagens de acompanhamento armazenadas na conversa. default: 0 examples: - 0 - 3 alreadyInitiated: type: boolean title: Already Initiated description: >- True quando esta solicitação bem-sucedida reutilizou uma conversa ativa existente por forceSend=true. False para criação ou recuperação; consulte recovered para distinguir esses caminhos. É informativo: uma reutilização bem-sucedida também armazena o novo modelo e os acompanhamentos, portanto repetir a solicitação pode adicionar mensagens. default: false examples: - false - true recovered: type: boolean title: Recovered description: >- True quando esta solicitação recuperou uma conversa liberada que o contato tinha no canal escolhido, em vez de criar outra. default: false examples: - false - true type: object required: - conversation - contact title: LeadscoutOutboundResponse description: Corpo da resposta de uma iniciação de saída bem-sucedida do LeadScout. LeadscoutOutboundTemplateRef: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID do modelo registrado (de GET /templates). Se id e name forem enviados, usa-se id. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f - null name: anyOf: - type: string - type: "null" title: Template Name description: >- Nome do modelo registrado e aprovado pela Meta a ser enviado. Obrigatório quando id não é enviado; ignorado quando id é enviado. examples: - leadscout_outbound_fb_v1 - null orderedParams: items: type: string type: array title: Ordered Parameters description: >- Valores fornecidos pelo cliente para os slots de parâmetros do modelo com origem CALLER, em ordem de posição. examples: - - Maria - ACME parameters: additionalProperties: type: string type: object title: Parameters description: >- Valores fornecidos pelo cliente e indexados pela chave de variável do modelo (consulte GET /templates/{id} para obter as chaves), tanto para o corpo como para os botões. Prefira esta opção a orderedParams se o modelo tiver um botão dinâmico. Uma chave desconhecida ou que se sobreponha a um slot já coberto por orderedParams é rejeitada com 422. examples: - recipient_first_name: Maria tracking_code: TRK123 media: anyOf: - $ref: "#/components/schemas/OutboundTemplateMedia" - type: "null" title: Header Media description: >- Mídia opcional de cabeçalho (imagem ou vídeo) a anexar à mensagem do modelo. Aceita um mediaId pré-carregado ou uma url pública. type: object title: LeadscoutOutboundTemplateRef description: Referencia o modelo aprovado pela Meta que abrirá a conversa. LeadscoutTemplateSent: properties: id: anyOf: - type: string - type: "null" title: Template Identifier description: ID do modelo enviado. examples: - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f name: type: string title: Template Name description: Nome do modelo despachado. examples: - leadscout_outbound_fb_v1 messageId: anyOf: - type: string - type: "null" title: Message Identifier description: >- wamid da Meta do modelo despachado. É null no fluxo bem-sucedido até que o processo de envio retorne o wamid à API de entrada. examples: - null - wamid.HBgM... type: object required: - name title: LeadscoutTemplateSent description: Resumo do modelo despachado para abrir a conversa. 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 da conversa. examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 messageBody: type: string title: Message Body description: Corpo da mensagem. examples: - Hello, welcome to Bridge! replyToMessageId: anyOf: - type: string - type: "null" title: Reply To Message Identifier description: Identificador da mensagem à qual se está respondendo. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 - null enableExternalBroadcast: type: boolean title: Enable External Broadcast description: >- Controla se uma mensagem aceita é elegível para entrega externa. Com false, a mensagem é criada, mas o broadcast externo é ignorado. Com true, entra no fluxo normal de entrega externa quando as regras da conversa e do destinatário permitem. Uma resposta de criação bem-sucedida e messageId não são confirmações de entrega. Este indicador não concede visibilidade nem ignora permissões. Também não desativa os modelos de onboarding iniciados por uma solicitação separada de criação de conversa. examples: - true - false mediaIds: items: type: string type: array title: Media Identifiers description: Lista de IDs de mídia associados à mensagem. examples: - - a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6 type: object required: - conversationId - messageBody - enableExternalBroadcast title: MessageRequest description: Corpo da solicitação para criar uma mensagem em uma conversa específica. MessageResponse: properties: messagingProduct: type: string title: Messaging Product description: Nome do produto. default: bridge examples: - bridge messageId: type: string title: Message Identifier description: Identificador único da mensagem como string UUID. examples: - b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234 type: object required: - messageId title: MessageResponse description: Corpo da resposta para operações com mensagens. OnboardingTemplateRequest: properties: templateId: type: string title: Template Identifier description: Identificador do modelo do sistema a ser enviado. examples: - 4061e74e-f6fe-4072-a760-3aec0b64f7a6 parameters: additionalProperties: type: string maxLength: 1024 propertyNames: maxLength: 128 type: object maxProperties: 50 title: Template Parameters description: >- Valores das variáveis deste template, indexados pela `key` da variável retornada por `GET /templates/{templateId}`. As variáveis marcadas com `callerMustSupply: true` são obrigatórias: a Bridge não tem outra fonte para elas. As demais são opcionais; um valor enviado para uma delas, como o primeiro nome do Contact, substitui o valor por Contact e é usado para todos os Contacts da conversa. Somente templates de provedor do WhatsApp aceitam parâmetros. Se um valor obrigatório estiver ausente ou em branco, uma chave não corresponder a nenhuma variável do template ou o template não aceitar parâmetros, a solicitação é rejeitada com 422 e nenhuma conversa é criada: `BRIDGE_CONVERSATION_0604` lista as variáveis ausentes em `extra.missingVariables` como `[{key, label}]`, `0605` lista as chaves desconhecidas em `extra.unknownKeys` e `0606` identifica o template em `extra.templateId`. Os valores também devem cumprir as regras do WhatsApp: sem quebras de linha ou tabulações, no máximo quatro espaços consecutivos, o cabeçalho com seu valor dentro de 60 caracteres, o link de um botão de URL com seu valor dentro de 2.000 e o texto do corpo mais seus valores dentro de 1.024. A Bridge recusa os valores que já consegue identificar como inválidos com `BRIDGE_CONVERSATION_0607`, identificando o template em `extra.templateId` e listando cada valor inválido em `extra.invalidVariables` como `[{key, label, reason}]`. `reason` é a primeira regra violada pelo valor: `NEWLINE`, `TAB`, `CONSECUTIVE_SPACES`, `TOO_LONG` (cabeçalho ou botão de URL) ou `BODY_TOO_LONG` (o corpo excede o limite, portanto todos os valores de corpo enviados são listados). Os valores preenchidos depois pela Bridge, como o primeiro nome do Contact, também contam para o limite do corpo; por isso, reserve espaço para eles. No máximo, 50 parâmetros por template, com chaves de até 128 caracteres e cada valor de até 1.024. examples: - delivery_date: 3 de octubre order_number: A-10492 additionalProperties: false type: object required: - templateId title: OnboardingTemplateRequest description: Entrada da substituição de onboarding; sua posição na lista determina a ordem. OpenAttributeRequest: properties: customAttributeId: type: string title: Custom Attribute Identifier description: Identificador único do atributo personalizado aberto. examples: - 651c97c1-b31d-466f-825c-fe77b39e7ae6 content: type: string title: Content description: Valor do atributo aberto. type: object required: - customAttributeId - content title: OpenAttributeRequest description: Corpo da solicitação para operações de atributos personalizados abertos. OutboundAgentContextRequest: properties: notes: anyOf: - type: string maxLength: 2000 - type: "null" title: Notes description: Notas em texto livre para o 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 opcionais de arquivos pré-carregados armazenados na conversa como contexto do agente. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object title: OutboundAgentContextRequest description: Notas e mídias armazenadas na conversa como contexto do agente para revisão por IA ou uma pessoa. OutboundConsentRequest: properties: status: $ref: "#/components/schemas/ConsentStatus" title: Status description: >- Estado de consentimento declarado pela empresa. Use GRANTED (com capturedAt) para consentimento explícito ou NOT_PROVIDED quando a empresa não tiver evidências a declarar. examples: - GRANTED - NOT_PROVIDED capturedAt: anyOf: - type: string format: date-time - type: "null" title: Captured At description: >- Data e hora ISO8601 (com milissegundos) em que a empresa obteve o consentimento. Obrigatório com status=GRANTED; null ou omissão são aceitos com status=NOT_PROVIDED. examples: - "2026-04-20T10:00:00.000Z" - null type: object required: - status title: OutboundConsentRequest description: Evidência de consentimento declarada pela empresa e registrada sem modificações na conversa. OutboundFollowUpRequest: properties: messageBody: type: string title: Message Body description: Corpo em texto simples da mensagem de acompanhamento. examples: - Just confirming we're still on for tomorrow at 10am. mediaIds: items: type: string type: array title: Media Identifiers description: >- O esquema da solicitação aceita o campo, mas o fluxo de saída compartilhado atual armazena os acompanhamentos apenas como texto e não anexa estes IDs de mídia. Para mídia do modelo inicial, use template.media; para uma mensagem de anexo separada, siga o fluxo de anexos de Message. examples: - [] - - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f type: object required: - messageBody title: OutboundFollowUpRequest description: Mensagem de acompanhamento pré-carregada armazenada na conversa junto ao modelo inicial. OutboundTemplateMedia: properties: type: $ref: "#/components/schemas/HeaderFileType" title: Media Type description: Tipo de mídia do cabeçalho. Deve corresponder ao tipo configurado para o modelo na Meta. examples: - IMAGE - VIDEO mediaId: anyOf: - type: string - type: "null" title: Media Identifier description: >- UUID retornado por POST /bridge/api/v1/workspaces/{workspaceId}/files. Mutuamente exclusivo com url. examples: - null - 7e1d2c3b-4a5f-6e7d-8c9b-0a1b2c3d4e5f url: anyOf: - type: string - type: "null" title: Source URL description: >- URL pública de origem obtida de forma assíncrona pelo serviço de download de arquivos por URL. Mutuamente exclusiva com mediaId. examples: - null - https://cdn.example.com/promo.jpg type: object required: - type title: OutboundTemplateMedia description: >- Mídia opcional de cabeçalho anexada à mensagem do modelo inicial. Forneça exatamente um: ``mediaId`` (UUID retornado por ``POST /bridge/api/v1/workspaces/{workspaceId}/files``) ou ``url`` (URL pública de origem obtida de forma assíncrona pelo serviço de download por URL). ParticipantIdentifierType: type: string enum: - ID - EMAIL - PHONE title: ParticipantIdentifierType ParticipantOperationsRequest: properties: externals: anyOf: - $ref: "#/components/schemas/ExternalOperationRequest" - type: "null" title: Externals description: Operações sobre usuários externos; devem ser informadas pelas operações "add" e "remove". internals: anyOf: - $ref: "#/components/schemas/InternalOperationRequest" - type: "null" title: Internals description: Operações sobre usuários internos; devem ser informadas pelas operações "add" e "remove". type: object title: ParticipantOperationsRequest description: Corpo da solicitação de operações sobre participantes ao atualizar uma conversa. PreloadedFileRequest: properties: name: type: string title: Name description: Nome original do arquivo, incluindo a extensão. examples: - prueba.jpg fileType: $ref: "#/components/schemas/FileType" title: File Type description: Categoria lógica do tipo de arquivo. examples: - IMAGE - VIDEO - AUDIO - DOCUMENT contentType: anyOf: - type: string - type: "null" title: Content Type description: Tipo MIME do arquivo. examples: - image/jpeg - application/pdf - null checksumBase64: type: string title: Checksum Base64 description: >- Resumo SHA-256 do arquivo completo, codificado em Base64. Usado para assinar o PUT pré-assinado e deve ser reenviado no cabeçalho x-amz-checksum-sha256 durante o upload. examples: - OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= additionalProperties: false type: object required: - name - fileType - checksumBase64 title: PreloadedFileRequest description: Solicitação para preparar o upload de um arquivo com uma URL pré-assinada. PreloadedFileResponse: properties: mediaId: type: string title: Media Identifier description: Identificador único da mídia. examples: - 4a2c1f7e-2f84-4a5f-bd2d-6b6b2f0c1234 presignUrl: $ref: "#/components/schemas/PresignPut" title: Presign Url description: Dados do PUT pré-assinado para enviar a mídia (URL, método e cabeçalhos). additionalProperties: false type: object required: - mediaId - presignUrl title: PreloadedFileResponse description: Resposta para um arquivo pré-carregado com URL pré-assinada para upload. PresignPut: properties: url: type: string title: Url description: URL de PUT pré-assinado. examples: - https://s3.amazonaws.com/bucket/path/to/object method: type: string const: PUT title: Method description: Método HTTP a usar no upload. default: PUT examples: - PUT headers: additionalProperties: type: string type: object title: Headers description: >- Cabeçalhos obrigatórios para o PUT pré-assinado (por exemplo, Content-Type e x-amz-checksum-sha256). examples: - Content-Type: image/jpeg x-amz-checksum-sha256: OaZ+I0yqf3u3u5w8h0Y2v4e7W9vHh3zbn2mA2m1yPVo= type: object required: - url title: PresignPut description: Dados do PUT pré-assinado para enviar um arquivo de mídia. Problem: properties: title: type: string title: Title description: Resumo breve do tipo de problema. status: type: integer title: Status description: Código de status HTTP gerado pelo servidor de origem para esta ocorrência do problema. detail: anyOf: - type: string - type: "null" title: Detail description: Explicação específica desta ocorrência do problema. instance: anyOf: - type: string - type: "null" title: Instance description: Referência URI que identifica esta ocorrência do problema. traceId: anyOf: - type: string - type: "null" title: Traceid description: ID de rastreamento para depuração. code: anyOf: - type: string - type: "null" title: Code description: Código para identificar o erro; consulte a página de códigos de erro para mais detalhes. errors: anyOf: - items: additionalProperties: true type: object type: array - type: "null" title: Errors description: Lista de detalhes dos erros. extra: anyOf: - additionalProperties: true type: object - type: "null" title: Extra description: Informações adicionais sobre o problema. type: object required: - title - status title: Problem description: Objeto que representa o corpo de uma resposta Problem. ProviderChannel: properties: provider: $ref: "#/components/schemas/MessageProviderType" title: Provider description: Nome do provedor do canal de mensagens. examples: - WHATSAPP - HEYGIA identifier: type: string title: Identifier description: Identificador associado a este canal do provedor, em formato E.164 sem o sinal '+'. type: object required: - provider - identifier title: ProviderChannel description: Canal de provedor associado a um workspace. ProviderChannelResponse: properties: workspaceId: type: string title: Workspace Identifier description: Identificador único do workspace (UUID v4). examples: - 92b2d4f3-81e1-4b61-a7ec-6f4ff3b58be5 providerChannels: items: $ref: "#/components/schemas/ProviderChannel" type: array title: Provider Channels description: Lista de canais de provedores (números de telefone) disponíveis para este workspace. type: object required: - workspaceId - providerChannels title: ProviderChannelResponse description: Corpo da resposta para operações com canais de provedores. ReleaseConversationBody: properties: reason: anyOf: - type: string - type: "null" title: Reason description: Motivo opcional para liberar a conversa. examples: - The conversation is over - null type: object title: ReleaseConversationBody description: Corpo do POST para liberar uma conversa. O motivo é opcional. TemplateDiscoveryResponse: properties: id: type: string title: Id description: Identificador único do modelo. examples: - f0000040-0000-4000-8000-000000000040 name: type: string title: Name description: Nome do modelo, usado para identificá-lo no envio. examples: - order_shipped_promo language: type: string title: Language description: "Idioma do pivot resolvido (idioma padrão do modelo), como código da Meta: es, en, pt_BR." examples: - es - pt_BR variables: items: $ref: "#/components/schemas/TemplateVariableResponse" type: array title: Variables description: Inventário agnóstico das variáveis deste modelo. driftWarning: $ref: "#/components/schemas/TemplateDriftWarningResponse" title: Drift warning description: Diferença entre declaração e snapshot, apenas para diagnóstico. Nunca bloqueia um envio. type: object required: - id - name - language - driftWarning title: TemplateDiscoveryResponse description: >- Inventário agnóstico das variáveis de um modelo para um cliente que deve enviá-lo sem conhecer o modelo da 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, mas não mais exigido pelo snapshot. missingLabels: items: $ref: "#/components/schemas/TemplateVariableRef" type: array title: Missing labels description: Exigido pelo snapshot, mas ainda não declarado. type: object required: - hasDrift title: TemplateDriftWarningResponse description: >- Diferença, apenas para diagnóstico, entre as variáveis declaradas e o que o snapshot da Meta exige. Conforme a regra de autoridade, isso nunca afeta o sucesso de um envio: apenas o snapshot determina o resultado. Permite que o cliente ou o console identifique um modelo cujos rótulos precisam ser atualizados após uma edição feita diretamente no 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 apenas por sua chave e rótulo agnósticos, sem endereço de slot da Meta. TemplateVariableResponse: properties: key: type: string title: Key description: Identificador agnóstico desta variável, estável entre provedores. examples: - tracking_code label: type: string title: Label description: Rótulo legível desta variável. examples: - Tracking code callerMustSupply: type: boolean title: Caller must supply description: >- Indica se o cliente deve fornecer um valor para esta variável ao enviar o modelo: true quando o modelo não tem uma origem declarada para o valor (por exemplo, um código promocional conhecido apenas pelo cliente) e false quando o Bridge o resolve por conta própria (por exemplo, a partir do perfil do destinatário). examples: - true - false isCustom: type: boolean title: Is custom description: >- Indica se é uma variável personalizada: um valor conhecido apenas pelo cliente e que tem um texto padrão. O cliente pode enviá-lo em `parameters`; quando omitido ou enviado em branco, usa-se `default`. default: false examples: - true - false default: anyOf: - type: string - type: "null" title: Default description: "Para uma variável personalizada, o texto enviado quando quem chama não fornece um valor; nos demais casos, null." examples: - pending - null type: object required: - key - label - callerMustSupply title: TemplateVariableResponse description: >- Variável de modelo identificada por sua chave agnóstica; um endereço de slot da Meta nunca aparece aqui. 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: Nome do contato. examples: - John - null lastName: anyOf: - type: string - type: "null" title: Last Name description: Sobrenome do contato. examples: - Doe - null email: anyOf: - type: string format: email - type: "null" title: Email description: E-mail do contato. examples: - john.doe@example.com - null languageCode: anyOf: - $ref: "#/components/schemas/LanguageCode" - type: "null" title: Language Code description: Código de idioma do contato. examples: - EN cellphone: anyOf: - type: string - type: "null" title: Cellphone description: Número de celular do contato. Sem código de país, é interpretado conforme o país do workspace. examples: - "+14084029292" - null ownerIdentifier: anyOf: - $ref: "#/components/schemas/InternalUserIdentifierRequest" - type: "null" title: Owner Identifier description: Identificador do vendedor ou usuário proprietário do contato. customAttributes: $ref: "#/components/schemas/CustomAttributesBody" title: Custom Attributes description: Objeto com as listas openAttributes e closedAttributes. additionalProperties: false type: object title: UpdateContactBody description: Corpo da solicitação para atualizar um contato existente. UpdateConversation: properties: name: anyOf: - type: string - type: "null" title: Name description: Nome ou título opcional da conversa. examples: - Client Support - null status: anyOf: - $ref: "#/components/schemas/ConversationStatus" - type: "null" title: Status description: >- Status inicial da conversa: 'active' para conversas visíveis e 'ghost' para conversas invisíveis até a primeira interação. examples: - ACTIVE participants: anyOf: - $ref: "#/components/schemas/ParticipantOperationsRequest" - type: "null" title: Participants description: Operações para adicionar e remover participantes de uma conversa. additionalProperties: false type: object title: UpdateConversation description: Corpo da solicitação para atualizar uma conversa 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