openapi: 3.1.0 info: title: Relya API — Rotas da instância version: 1.0.0 description: Contrato público das 131 rotas autenticadas pelo token da instância. Consulte x-relya-runtime-capabilities e x-relya-runtime-status antes de integrar. Limite padrão de 60 requisições por minuto por credencial; ao exceder, a API responde 429 com os campos limit e retryAfterSeconds. Os erros seguem o schema Error, com os campos error (legível) e code (estável para automação). x-relya-coverage-scope: instance_token_contract_current_runtime x-relya-runtime-capabilities: version: 2026-07-18 documentedRoutes: 131 scope: current_runtime warning: O catálogo público mostra somente rotas autenticadas pelo token da instância. A execução ainda depende de sessão conectada, permissões e serviços externos. integration: label: Integração atual releaseStage: available documentedRoutes: 131 availableToday: 109 blockedToday: 2 outsideCurrentGuard: 2 experimentalOrUnsupported: 18 note: A matriz informa o comportamento do ambiente publicado sem expor componentes internos da plataforma. Rotas não disponíveis falham antes de simular sucesso ou criar efeito parcial. servers: - url: https://relya.com.br components: securitySchemes: InstanceToken: type: apiKey in: header name: token schemas: Error: type: object properties: error: type: string description: Mensagem legível do erro. code: type: string description: "Código estável para tratamento programático (ex.: INSTANCE_NOT_CONNECTED)." retry_safe: type: boolean description: Indica se uma nova operação pode ser criada sem risco conhecido de duplicidade. Quando falso, consulte ou repita somente a mesma chave e o mesmo corpo. error_source: type: string description: "Origem do erro (ex.: relya_runtime)." status: type: string description: Status da instância, quando aplicável. retryAfterSeconds: type: integer description: Segundos sugeridos para nova tentativa (respostas 429). MessageDeliveryOutcome: type: object required: - state - code - retrySafe - observedAt properties: state: type: string enum: - indeterminate - resolved code: type: string enum: - DELIVERY_OUTCOME_INDETERMINATE retrySafe: type: boolean description: "Permanece falso: nunca crie uma segunda operação para resolver uma entrega incerta." observedAt: type: string format: date-time operationId: type: string evidence: type: object additionalProperties: false properties: clientMessageId: type: string providerMessageId: type: string providerTimestamp: type: string idempotencyStatus: type: string enum: - stored - replayed resolvedAt: type: string format: date-time resolution: type: string enum: - Sent - Delivered - Read - Failed resolvedBy: type: string enum: - provider_message - provider_receipt Message: type: object required: - id - status properties: id: type: string description: Identidade estável da mensagem na Relya. providerMessageId: type: string chatid: type: string status: type: string enum: - Queued - Processing - Sent - Delivered - Read - Failed - Canceled track_id: type: string delivery_state: type: string enum: - indeterminate - resolved description: Só aparece quando existiu incerteza no transporte. code: type: string enum: - DELIVERY_OUTCOME_INDETERMINATE retry_safe: type: boolean delivery_outcome: $ref: "#/components/schemas/MessageDeliveryOutcome" historicalMessageAvailable: type: boolean idempotencyExpiresAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time MessageFindResponse: type: object required: - messages - total - simulated properties: messages: type: array items: $ref: "#/components/schemas/Message" total: type: integer minimum: 0 simulated: type: boolean paths: /message/delete: post: tags: - Ações na mensagem e Buscar operationId: deleteMessage summary: Apagar Mensagem Para Todos description: 'Apaga uma mensagem para todos os participantes da conversa. ### Funcionalidades: - Apaga mensagens em conversas individuais ou grupos - Funciona com mensagens enviadas pelo usuário ou recebidas - Atualiza o status no banco de dados - Envia webhook de atualização **Notas Técnicas**: 1. O ID da mensagem pode ser fornecido em dois formatos: - ID completo (contém ":"): usado diretamente - ID curto: concatenado com o owner para busca 2. Gera evento webhook do tipo "messages_update" 3. Atualiza o status da mensagem para "Deleted" 4. Para newsletters/canais, use `POST /newsletter/messages/delete`' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID da mensagem a ser apagada required: - id responses: "200": description: Resposta da operação content: application/json: schema: type: object properties: response: type: string example: message_deleted id: type: string providerMessageId: type: string example: response: message_deleted id: 3EB0C767D82B0A3B providerMessageId: BAE5F1A2C3D4E5F6 "400": description: Payload inválido ou ID de chat/sender inválido content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Token não fornecido content: application/json: schema: type: object properties: error: type: string example: Unauthorized "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem não encontrada content: application/json: schema: type: object properties: error: type: string example: message not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou sessão não iniciada content: application/json: schema: type: object properties: error: type: string example: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/download: post: tags: - Ações na mensagem e Buscar operationId: downloadMessage summary: Baixar arquivo de uma mensagem description: 'Baixa o arquivo associado a uma mensagem de mídia (imagem, vídeo, áudio, documento ou sticker). ## Parâmetros - **id** (string, obrigatório): ID da mensagem - **return_base64** (boolean, default: false): Retorna arquivo em base64 - **generate_mp3** (boolean, default: true): Para áudios, define formato de retorno - `true`: Retorna MP3 - `false`: Retorna OGG - **return_link** (boolean, default: true): Retorna URL pública do arquivo - **transcribe** (boolean, default: false): Transcreve áudios para texto - **openai_apikey** (string, opcional): Chave OpenAI para transcrição - Se não informada, usa a chave salva na instância - Se informada, atualiza e salva na instância para próximas chamadas - **download_quoted** (boolean, default: false): Baixa mídia da mensagem citada - Útil para baixar conteúdo original de status do WhatsApp - Quando uma mensagem é resposta a um status, permite baixar a mídia do status original - **Contextualização**: Ao baixar a mídia citada, você identifica o contexto da conversa - Exemplo: Se alguém responde a uma promoção, baixando a mídia você saberá que a pergunta é sobre aquela promoção específica ## Exemplos ### Baixar áudio como MP3: ```json { "id": "7EB0F01D7244B421048F0706368376E0", "generate_mp3": true } ``` ### Transcrever áudio: ```json { "id": "7EB0F01D7244B421048F0706368376E0", "transcribe": true } ``` ### Apenas base64 (sem salvar): ```json { "id": "7EB0F01D7244B421048F0706368376E0", "return_base64": true, "return_link": false } ``` ### Baixar mídia de status (mensagem citada): ```json { "id": "7EB0F01D7244B421048F0706368376E0", "download_quoted": true } ``` *Útil quando o cliente responde a uma promoção/status - você baixa a mídia original para entender sobre qual produto/oferta ele está perguntando.* ## Resposta ```json { "fileURL": "https://api.exemplo.com/files/arquivo.mp3", "mimetype": "audio/mpeg", "base64Data": "UklGRkj...", "transcription": "Texto transcrito" } ``` **Nota**: - Por padrão, se não definido o contrário: 1. áudios são retornados como MP3. 2. E todos os pedidos de download são retornados com URL pública. - Transcrição requer chave OpenAI válida. A chave pode ser configurada uma vez na instância e será reutilizada automaticamente. - Retenção de mídia: mantemos as mídias no nosso storage por 2 dias. Após 2 dias, elas são removidas na limpeza automática e o link retornado deixa de ficar disponível. Para voltar a disponibilizar a mídia, é necessário refazer o download pelo endpoint. Se o cliente solicitar novamente, a mídia será baixada do CDN da Meta, o que pode aumentar o tempo de resposta. Enquanto estiver no nosso storage, a resposta tende a ser mais rápida.' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID da mensagem contendo o arquivo example: 7EB0F01D7244B421048F0706368376E0 return_base64: type: boolean description: Se verdadeiro, retorna o conteúdo em base64 default: false generate_mp3: type: boolean description: Para áudios, define formato de retorno (true=MP3, false=OGG) default: true return_link: type: boolean description: Salva e retorna URL pública do arquivo default: true transcribe: type: boolean description: Se verdadeiro, transcreve áudios para texto default: false openai_apikey: type: string description: Chave da API OpenAI para transcrição (opcional) example: sk-... download_quoted: type: boolean description: Se verdadeiro, baixa mídia da mensagem citada ao invés da mensagem principal default: false required: - id responses: "200": description: Successful file download content: application/json: schema: type: object properties: fileURL: type: string description: URL pública para acessar o arquivo (se return_link=true) example: https://api.exemplo.com/files/arquivo.mp3 mimetype: type: string description: Tipo MIME do arquivo example: audio/mpeg base64Data: type: string description: Conteúdo do arquivo em base64 (se return_base64=true) example: UklGRkj... transcription: type: string description: Texto transcrito do áudio (se transcribe=true) example: Texto transcrito required: - mimetype "400": description: Bad Request content: application/json: schema: type: object properties: error: type: string example: Unsupported media type or no media found in message "401": description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: Invalid token "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Not Found content: application/json: schema: type: object properties: error: type: string examples: - Message not found - No quoted message found in this message "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Internal Server Error content: application/json: schema: type: object properties: error: type: string example: Failed to download media x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/edit: post: tags: - Ações na mensagem e Buscar operationId: editMessage summary: Edita uma mensagem enviada description: "Edita o conteúdo de uma mensagem já enviada usando a funcionalidade nativa do WhatsApp. O endpoint realiza: - Busca a mensagem original no banco de dados usando o ID fornecido - Edita o conteúdo da mensagem para o novo texto no WhatsApp - Gera um novo ID para a mensagem editada - Retorna objeto de mensagem completo seguindo o padrão da API - Dispara eventos SSE/Webhook automaticamente **Importante**: - Só é possível editar mensagens enviadas pela própria instância - A mensagem deve existir no banco de dados - O ID pode ser fornecido no formato completo (owner:messageid) ou apenas messageid - A mensagem deve estar dentro do prazo permitido pelo WhatsApp para edição - Para newsletters/canais, use `POST /newsletter/messages/edit`" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - id - text properties: id: type: string description: ID único da mensagem que será editada (formato owner:messageid ou apenas messageid) example: 3A12345678901234567890123456789012 text: type: string description: Novo conteúdo de texto da mensagem example: Texto editado da mensagem responses: "200": description: Resposta da operação content: application/json: schema: type: object properties: response: type: string example: message_edited id: type: string providerMessageId: type: string text: type: string example: response: message_edited id: 3EB0C767D82B0A3B providerMessageId: BAE5F1A2C3D4E5F6 text: Texto corrigido "400": description: Dados inválidos na requisição content: application/json: schema: type: object properties: error: type: string example: Invalid payload "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem não encontrada content: application/json: schema: type: object properties: error: type: string example: Message not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Error fetching message from database x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/find: post: tags: - Ações na mensagem e Buscar operationId: findMessages summary: Buscar mensagens e consultar uma operação exata description: "Busca no histórico persistido da instância. Para uma operação exata, use `id`, `messageid`, `messageId`, `providerMessageId`, `track_id` ou `trackId`. Também aceita `chatid`/`chatId` e `query`/`text`. Quando a linha detalhada já expirou, uma busca exata ainda pode retornar o último estado conhecido pelo índice idempotente, com `historicalMessageAvailable: false` e `idempotencyExpiresAt`. Se `status` for `Failed` e `delivery_state` for `indeterminate`, não crie outra chave. Respeite `retry_safe: false`, consulte a mesma operação ou repita exatamente a mesma chave e o mesmo corpo." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID estável da mensagem ou ID do provedor messageid: type: string description: Alias para busca exata pelo ID estável messageId: type: string description: Alias camelCase para busca exata providerMessageId: type: string description: ID devolvido pelo transporte chatid: type: string description: ID exato do chat example: 5511999999999@s.whatsapp.net chatId: type: string description: Alias camelCase do chat track_id: type: string description: Chave idempotente da ação de negócio trackId: type: string description: Alias camelCase da chave idempotente query: type: string description: Texto livre procurado na mensagem ou remetente text: type: string description: Alias de query limit: type: integer description: Número máximo de mensagens a retornar (padrão 50, máximo 200) minimum: 1 maximum: 200 default: 50 example: 20 example: messageid: msg_relya_123 responses: "200": description: Mensagens encontradas. Uma busca exata pode vir do índice idempotente após o histórico detalhado expirar. content: application/json: schema: $ref: "#/components/schemas/MessageFindResponse" "400": description: Parametros invalidos "401": description: Token invalido ou expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/history-sync: post: tags: - Ações na mensagem e Buscar operationId: requestHistorySync summary: Solicitar histórico sob demanda de um chat description: "Solicita ao WhatsApp um sync sob demanda de mensagens antigas de um chat ou tenta recuperar uma mensagem exata já conhecida localmente. Modos suportados: - `history` (padrão): busca histórico para trás a partir de uma mensagem âncora - `exact`: tenta recarregar a mensagem exata informada em `messageid` Regras: - envie `number` - `mode` é opcional; quando omitido, assume `history` - em `mode=history`, `count` é opcional e limitado a 100 - em `mode=history`, `messageid` é opcional; quando informado, a API usa essa mensagem como referência para buscar mensagens mais antigas do chat - em `mode=exact`, `messageid` é obrigatório e `count` não é necessário Observação: - **Importante:** a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano - em `mode=history`, `messageid` define a mensagem de referência para carregar histórico anterior - em `mode=history`, esse campo não serve para buscar essa mensagem específica - em `mode=history`, o histórico é buscado para trás a partir da mensagem de referência informada - se você quiser recuperar apenas uma mensagem específica `X` via histórico, informe como `messageid` a mensagem logo depois de `X` e use `count=1` - se `messageid` não for informado em `mode=history`, a API usa a mensagem mais antiga conhecida localmente desse chat como referência para buscar histórico anterior - em `mode=exact`, a API tenta um rerequest da mensagem exata informada em `messageid` - **`mode=exact` está em teste** e funciona melhor quando a mensagem já existe no histórico local da instância - as mensagens retornam depois via webhook/SSE em eventos do tipo `history` e também ficam disponíveis em `/message/find`" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number properties: mode: type: string enum: - history - exact default: history description: > Define o comportamento da operação. - `history`: busca mensagens mais antigas a partir de uma âncora - `exact`: tenta recuperar a mensagem exata informada em `messageid` example: history messageid: type: string description: > Em `mode=history`, ID da mensagem de referência usada para buscar mensagens mais antigas do chat. Em `mode=exact`, ID exato da mensagem que deve ser recarregada. example: 3EB01234567890ABCDEF number: type: string description: JID completo do chat. Mantido obrigatório em todos os modos para simplificar o contrato público e restringir a busca ao chat esperado. example: 5511999999999@s.whatsapp.net count: type: integer minimum: 1 maximum: 100 description: Quantidade desejada de mensagens no sync em `mode=history`. Em `mode=exact`, este campo é ignorado. example: 20 example: number: 5511999999999@s.whatsapp.net mode: exact messageid: 3EB01234567890ABCDEF responses: "200": description: Solicitação enviada com sucesso content: application/json: schema: type: object properties: success: type: boolean example: true mode: type: string example: history message: type: string example: History sync request sent. Messages will be received as history sync events. details: type: object additionalProperties: true description: Metadados adicionais da operação example: success: true mode: history message: History sync request sent. Messages will be received as history sync events. "400": description: Payload inválido, modo inválido ou âncora insuficiente content: application/json: schema: type: object properties: error: type: string example: number is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem exata não encontrada no histórico local content: application/json: schema: type: object properties: error: type: string example: messageid not found in local history for chat; use mode=history to fetch older messages first "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao solicitar o history sync ou o rerequest exato content: application/json: schema: type: object properties: error: type: string example: "Failed to request history: connection closed" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/markread: post: tags: - Ações na mensagem e Buscar operationId: markMessageRead summary: Marcar mensagens como lidas description: 'Marca uma ou mais mensagens como lidas. Este endpoint permite: 1. Marcar múltiplas mensagens como lidas de uma vez 2. Atualizar o status de leitura no WhatsApp 3. Sincronizar o status de leitura entre dispositivos Exemplo de requisição básica: ```json { "id": [ "62AD1AD844E518180227BF68DA7ED710", "ECB9DE48EB41F77BFA8491BFA8D6EF9B" ] } ``` Exemplo de resposta: ```json { "success": true, "message": "Messages marked as read", "markedMessages": [ { "id": "62AD1AD844E518180227BF68DA7ED710", "timestamp": 1672531200000 }, { "id": "ECB9DE48EB41F77BFA8491BFA8D6EF9B", "timestamp": 1672531300000 } ] } ``` Parâmetros disponíveis: - id: Lista de IDs das mensagens a serem marcadas como lidas Erros comuns: - 401: Token inválido ou expirado - 400: Lista de IDs vazia ou inválida - 404: Uma ou mais mensagens não encontradas - 500: Erro ao marcar mensagens como lidas' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: array description: Lista de IDs das mensagens a serem marcadas como lidas items: type: string example: - 62AD1AD844E518180227BF68DA7ED710 - ECB9DE48EB41F77BFA8491BFA8D6EF9B required: - id responses: "200": description: Messages successfully marked as read content: application/json: schema: type: object properties: results: type: array items: type: object properties: message_id: type: string description: ID of the message that was processed status: type: string enum: - success - error description: Status of the mark as read operation error: type: string description: Error message if status is error example: - message_id: 62AD1AD844E518180227BF68DA7ED710 status: success - message_id: ECB9DE48EB41F77BFA8491BFA8D6EF9B status: error error: Message not found "400": description: Invalid request payload or missing required fields content: application/json: schema: type: object properties: error: type: string example: Missing Id in Payload "401": description: Unauthorized - invalid or missing token "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Server error while processing the request x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/pin: post: tags: - Ações na mensagem e Buscar operationId: pinMessage summary: Fixa ou desafixa uma mensagem description: "Fixa ou desafixa uma mensagem específica usando a funcionalidade nativa do WhatsApp. O endpoint realiza: - Busca a mensagem original no banco de dados usando o ID fornecido - Envia a ação de fixar ou desafixar a mensagem no WhatsApp - Funciona em conversas individuais e grupos - Gera um novo ID para o evento de pin/unpin - Retorna objeto de mensagem completo seguindo o padrão da API - Dispara eventos SSE/Webhook automaticamente **Importante**: - O ID pode ser fornecido no formato completo (`owner:messageid`) ou apenas `messageid` - Em conversas `1:1`, a ação é suportada normalmente - Em grupos, a permissão depende da configuração do WhatsApp do grupo (`apenas admins` ou `qualquer membro`) - O backend não valida localmente se a instância é admin do grupo; a decisão final é do WhatsApp - Newsletters/canais não são suportados neste endpoint - Se `pin` não for enviado, o valor padrão é `true` - Ao fixar mensagem, `duration` aceita dias (`1`, `7` ou `30`) - Se `duration` não for enviado ou vier com qualquer outro valor, o backend usa `30` dias - Ao desafixar (`pin: false`), `duration` é ignorado" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: ID único da mensagem alvo (formato `owner:messageid` ou apenas `messageid`) example: 3A12345678901234567890123456789012 pin: type: boolean default: true description: Define se a mensagem deve ser fixada (`true`) ou desafixada (`false`) example: true duration: type: integer default: 30 description: "Duração do pin em dias. Valores aceitos: `1`, `7` ou `30`. Qualquer outro valor cai para `30`." example: 7 example: id: 3A12345678901234567890123456789012 pin: true duration: 7 responses: "200": description: Ação de fixar/desafixar mensagem enviada com sucesso content: application/json: schema: type: object properties: id: type: string description: ID único da mensagem gerada para o evento de pin/unpin example: 5511999999999:3A12345678901234567890123456789012 messageid: type: string description: ID da mensagem do evento no WhatsApp example: 3A12345678901234567890123456789012 chatid: type: string description: Chat onde a ação ocorreu example: 120363123456789012@g.us sender: type: string description: JID do remetente da ação example: 5511999999999@s.whatsapp.net senderName: type: string description: Nome do perfil da instância example: Minha Instância isGroup: type: boolean description: Indica se o chat é um grupo example: true fromMe: type: boolean description: Indica se a ação foi enviada pela própria instância example: true content: type: object description: Payload interno de `PinInChatMessage` messageType: type: string description: Tipo da mensagem retornada example: PinInChatMessage source: type: string description: Origem estimada da mensagem example: web messageTimestamp: type: integer description: Timestamp da mensagem em milissegundos example: 1704067200000 status: type: string description: Status atual da ação example: Pending text: type: string description: Texto amigável derivado da ação example: Mensagem fixada quoted: type: string description: ID da mensagem citada, quando aplicável example: "" edited: type: string description: ID da mensagem editada, quando aplicável example: "" reaction: type: string description: Emoji de reação, quando aplicável example: "" convertOptions: type: string description: Opções convertidas para mensagens interativas, quando aplicável example: "" owner: type: string description: Proprietário da instância example: "5511999999999" targetMessageID: type: string description: ID da mensagem alvo que foi fixada ou desafixada example: 3EB0538DA65A59F6D8A251 pinned: type: boolean description: Estado final solicitado para a mensagem alvo example: true "400": description: Dados inválidos na requisição ou operação não suportada content: application/json: schema: type: object properties: error: type: string example: message pinning is not supported for newsletters "401": description: Sem sessão ativa ou token inválido content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem não encontrada content: application/json: schema: type: object properties: error: type: string example: Message not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou erro retornado pelo WhatsApp content: application/json: schema: type: object properties: error: type: string example: "error pinning message: ..." x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/react: post: tags: - Ações na mensagem e Buscar operationId: reactToMessage summary: Enviar reação a uma mensagem description: 'Envia uma reação (emoji) a uma mensagem específica. Este endpoint permite: 1. Adicionar ou remover reações em mensagens 2. Usar qualquer emoji Unicode válido 3. Reagir a mensagens em chats individuais ou grupos 4. Remover reações existentes 5. Verificar o status da reação enviada Tipos de reações suportados: - Qualquer emoji Unicode válido (👍, ❤️, 😂, etc) - String vazia para remover reação Exemplo de requisição básica: ```json { "number": "5511999999999@s.whatsapp.net", "text": "👍", "id": "3EB0538DA65A59F6D8A251" } ``` Exemplo de requisição para remover reação: ```json { "number": "5511999999999@s.whatsapp.net", "text": "", "id": "3EB0538DA65A59F6D8A251" } ``` Exemplo de resposta: ```json { "success": true, "message": "Reaction sent", "reaction": { "id": "3EB0538DA65A59F6D8A251", "emoji": "👍", "timestamp": 1672531200000, "status": "sent" } } ``` Exemplo de resposta ao remover reação: ```json { "success": true, "message": "Reaction removed", "reaction": { "id": "3EB0538DA65A59F6D8A251", "emoji": null, "timestamp": 1672531200000, "status": "removed" } } ``` Parâmetros disponíveis: - number: Número do chat no formato internacional (ex: 5511999999999@s.whatsapp.net) - text: Emoji Unicode da reação (ou string vazia para remover reação) - id: ID da mensagem que receberá a reação Erros comuns: - 401: Token inválido ou expirado - 400: Número inválido ou emoji não suportado - 404: Mensagem não encontrada - 500: Erro ao enviar reação Limitações: - Só é possível reagir a mensagens enviadas por outros usuários - Não é possível reagir a mensagens antigas (mais de 7 dias) - O mesmo usuário só pode ter uma reação ativa por mensagem' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: Número do chat no formato internacional example: 5511999999999@s.whatsapp.net text: type: string description: Emoji Unicode da reação (ou string vazia para remover reação) example: 👍 id: type: string description: ID da mensagem que receberá a reação example: 3EB0538DA65A59F6D8A251 required: - number - text - id responses: "200": description: Reação enviada com sucesso content: application/json: schema: type: object properties: id: type: string description: ID único da mensagem de reação example: owner:generated_message_id messageid: type: string description: ID gerado para a mensagem de reação example: generated_message_id content: type: object description: Detalhes da reação messageTimestamp: type: number description: Timestamp da mensagem em milissegundos example: 1672531200000 messageType: type: string description: Tipo da mensagem example: reaction status: type: string description: Status atual da mensagem example: Pending owner: type: string description: Proprietário da instância example: instance_owner "400": description: Erro nos dados da requisição content: application/json: schema: type: object properties: error: type: string example: Missing Id in Payload "401": description: Não autorizado content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem não encontrada content: application/json: schema: type: object properties: error: type: string example: Message not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Error sending message x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/block: post: tags: - Bloqueios operationId: blockChat summary: Bloqueia ou desbloqueia contato do WhatsApp description: Bloqueia ou desbloqueia um contato do WhatsApp. Contatos bloqueados não podem enviar mensagens para a instância e a instância não pode enviar mensagens para eles. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: Número do WhatsApp no formato internacional (ex. 5511999999999) example: "5511999999999" block: type: boolean description: True para bloquear, False para desbloquear example: true required: - number - block responses: "200": description: Operação realizada com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação example: Blocked successfully blockList: type: array description: Lista atualizada de contatos bloqueados items: type: string example: - 5511999999999@s.whatsapp.net - 5511888888888@s.whatsapp.net "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Não autorizado - token inválido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Contato não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro do servidor ao processar a requisição x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/blocklist: get: tags: - Bloqueios operationId: getBlocklist summary: Lista contatos bloqueados description: Retorna a lista completa de contatos que foram bloqueados pela instância. Esta lista é atualizada em tempo real conforme contatos são bloqueados/desbloqueados. security: - InstanceToken: [] parameters: [] responses: "200": description: Lista de contatos bloqueados recuperada com sucesso content: application/json: schema: type: object properties: blockList: type: array items: type: string description: JIDs dos contatos bloqueados no formato "número@s.whatsapp.net" example: - 5511999999999@s.whatsapp.net - 5511888888888@s.whatsapp.net "401": description: Token inválido ou não fornecido "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou instância não conectada x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /business/catalog/delete: post: tags: - Business operationId: post__business_catalog_delete summary: Deletar um produto do catálogo description: Deleta um produto específico do catálogo. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: O ID do produto. required: - id responses: "200": description: Produto deletado com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de sucesso. example: Deleted product "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao deletar o produto content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /business/catalog/hide: post: tags: - Business operationId: post__business_catalog_hide summary: Ocultar um produto do catálogo description: Oculta um produto específico do catálogo. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: O ID do produto. required: - id responses: "200": description: Produto ocultado com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de sucesso. example: Product hidden "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao ocultar o produto content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /business/catalog/info: post: tags: - Business operationId: post__business_catalog_info summary: Obter informações de um produto do catálogo description: Retorna as informações de um produto específico do catálogo. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: jid: type: string description: JID do catálogo a consultar example: 5511999999999@s.whatsapp.net id: type: string description: O ID do produto. required: - jid - id responses: "200": description: Informações do produto recuperadas com sucesso content: application/json: schema: type: object properties: response: type: object description: Informações do produto properties: id: type: string name: type: string description: type: string price: type: string currency: type: string "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload ou JID example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar as informações do produto content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /business/catalog/list: post: tags: - Business operationId: getCatalog summary: Listar os produtos do catálogo description: "Lista uma página de produtos do catálogo de um perfil comercial no WhatsApp. Observações: - envie apenas `jid` para buscar a primeira página - a paginação pública usa o campo `after` - copie exatamente o valor retornado em `response.Paging.After` e envie na próxima chamada - o valor de `after` é um token opaco: não tente decodificar ou modificar - a integração atual retorna até 10 produtos por chamada - o retorno espelha as structs atuais da camada de integração, então os campos de `response` usam nomes em maiúsculas (`Products`, `Paging`, etc.)" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: jid: type: string description: JID do catálogo a consultar example: 5511999999999@s.whatsapp.net after: type: string description: Token da próxima página. Use exatamente o valor retornado em `response.Paging.After`. example: Q1VSU09SX1BST1hJTUFfUEFHSU5B required: - jid example: jid: 5511999999999@s.whatsapp.net responses: "200": description: Produtos do catálogo recuperados com sucesso content: application/json: schema: type: object properties: response: type: object description: Página atual do catálogo retornada pelo WhatsApp. properties: JID: type: object description: JID do catálogo consultado, serializado pela struct atual do backend. properties: User: type: string example: "5511999999999" RawAgent: type: integer example: 0 Device: type: integer example: 0 Integrator: type: integer example: 0 Server: type: string example: s.whatsapp.net CartEnabled: type: boolean description: Indica se o carrinho do catálogo está habilitado. example: false Source: type: string description: Origem do catálogo retornada pelo WhatsApp. example: "" Products: type: array description: Lista de produtos da página atual. items: type: object properties: ID: type: string example: "1234567890" Name: type: string example: Produto Exemplo Description: type: string example: Descrição do produto Price: type: object nullable: true properties: Amount: type: string example: "1990" Currency: type: string example: BRL SalePrice: type: string example: "" RetailerID: type: string example: sku-123 Url: type: string example: https://exemplo.com/produto Availability: type: string example: in stock IsHidden: type: boolean example: false StatusInfo: type: object properties: Status: type: string example: active CanAppeal: type: boolean example: false MaxAvailable: type: integer example: 10 ImageFetchStatus: type: string example: success Images: type: array items: type: object properties: ID: type: string example: img-1 OriginalDimensions: type: object properties: Height: type: integer example: 720 Width: type: integer example: 720 RequestImageUrl: type: string example: https://mmg.whatsapp.net/v/t62.7118-24/... OriginalImageUrl: type: string example: https://lookaside.whatsapp.net/... Paging: type: object description: Cursores de paginação retornados pelo WhatsApp. properties: Before: type: string example: "" After: type: string example: Q1VSU09SX1BST1hJTUFfUEFHSU5B example: response: JID: User: "5511999999999" RawAgent: 0 Device: 0 Integrator: 0 Server: s.whatsapp.net CartEnabled: false Source: "" Products: - ID: "1234567890" Name: Produto Exemplo Description: Descrição do produto Price: Amount: "1990" Currency: BRL SalePrice: "" RetailerID: sku-123 Url: https://exemplo.com/produto Availability: in stock IsHidden: false StatusInfo: Status: active CanAppeal: false MaxAvailable: 10 ImageFetchStatus: success Images: - ID: img-1 OriginalDimensions: Height: 720 Width: 720 RequestImageUrl: https://mmg.whatsapp.net/v/t62.7118-24/... OriginalImageUrl: https://lookaside.whatsapp.net/... Paging: Before: "" After: Q1VSU09SX1BST1hJTUFfUEFHSU5B "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload ou JID example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar os produtos do catálogo content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /business/catalog/show: post: tags: - Business operationId: post__business_catalog_show summary: Mostrar um produto do catálogo description: Mostra um produto específico do catálogo. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: O ID do produto. required: - id responses: "200": description: Produto mostrado com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de sucesso. example: Product shown "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao mostrar o produto content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /business/get/categories: get: tags: - Business operationId: get__business_get_categories summary: Obter as categorias de negócios description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Retorna a categoria observada no perfil da empresa; o transporte atual não expõe o catálogo mestre completo. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] responses: "200": description: Categorias de negócios recuperadas com sucesso content: application/json: schema: type: object properties: response: type: array description: Lista de categorias de negócios items: type: object properties: id: type: string localized_display_name: type: string "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar as categorias de negócios content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Retorna a categoria observada no perfil da empresa; o transporte atual não expõe o catálogo mestre completo. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /business/get/profile: post: tags: - Business operationId: post__business_get_profile summary: Obter o perfil comercial description: Retorna o perfil comercial da conta do WhatsApp Business atualmente conectada. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: jid: type: string description: JID do perfil comercial a consultar example: 5511999999999@s.whatsapp.net responses: "200": description: Perfil comercial recuperado com sucesso content: application/json: schema: type: object properties: response: type: object description: Dados do perfil comercial properties: tag: type: string description: A tag do perfil comercial. description: type: string description: A descrição do perfil comercial. address: type: string description: O endereço do perfil comercial. email: type: string description: O email do perfil comercial. websites: type: array items: type: string description: Os websites do perfil comercial. categories: type: array items: type: object properties: id: type: string localized_display_name: type: string description: As categorias do perfil comercial. "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação do payload ou do JID example: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar o perfil comercial content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /business/update/profile: post: tags: - Business operationId: post__business_update_profile summary: Atualizar o perfil comercial description: Atualiza os dados do perfil comercial da conta do WhatsApp Business atualmente conectada. Todos os campos são opcionais; apenas os enviados serão atualizados. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: description: type: string description: Nova descrição do perfil comercial. example: Loja de eletrônicos e acessórios address: type: string description: Novo endereço do perfil comercial. example: Rua das Flores, 123 - Centro email: type: string description: Novo email do perfil comercial. example: contato@empresa.com example: description: Loja de eletrônicos e acessórios address: Rua das Flores, 123 - Centro email: contato@empresa.com responses: "200": description: Todos os campos enviados foram atualizados content: application/json: schema: type: object properties: response: type: object description: Resultado por campo updated: type: integer description: Total de campos atualizados example: 3 failed: type: integer description: Total de campos que falharam example: 0 example: response: description: status: updated address: status: updated email: status: updated updated: 3 failed: 0 "207": description: Sucesso parcial — ao menos um campo falhou content: application/json: schema: type: object properties: response: type: object description: Resultado por campo updated: type: integer example: 1 failed: type: integer example: 1 example: response: description: status: updated address: status: error error: upstream unavailable updated: 1 failed: 1 "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de validação example: error: invalid payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Mensagem de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Falha total — nenhum campo foi atualizado content: application/json: schema: type: object properties: response: type: object description: Resultado por campo updated: type: integer example: 0 failed: type: integer example: 3 x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /call/make: post: tags: - Chamadas operationId: makeCall summary: Iniciar chamada de voz description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Cria um link real de chamada e declara que não iniciou uma ligação direta. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: "Número do contato no formato internacional (ex: 5511999999999)" example: "5511999999999" call_duration: type: integer description: Duração da chamada em segundos (opcional). Após esse tempo a chamada é encerrada automaticamente. example: 15 required: - number responses: "200": description: Chamada iniciada com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação example: Call successful "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Descrição do erro example: error: missing number in payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Descrição do erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string description: Descrição do erro interno example: "error making call: network timeout" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Cria um link real de chamada e declara que não iniciou uma ligação direta. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /call/reject: post: tags: - Chamadas operationId: rejectCall summary: Rejeitar chamada recebida description: 'Rejeita uma chamada recebida do WhatsApp. O body pode ser enviado vazio `{}`. Os campos `number` e `id` são opcionais e podem ser usados para especificar uma chamada específica. Exemplo de requisição (recomendado): ```json {} ``` Exemplo de requisição com campos opcionais: ```json { "number": "5511999999999", "id": "ABEiGmo8oqkAcAKrBYQAAAAA_1" } ``` Exemplo de resposta: ```json { "response": "Call rejected" } ``` Erros comuns: - 401: Token inválido ou expirado - 400: Número inválido - 500: Erro ao rejeitar chamada' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object example: {} properties: number: type: string description: "(Opcional) Número do contato no formato internacional (ex: 5511999999999)" id: type: string description: (Opcional) ID único da chamada a ser rejeitada responses: "200": description: Chamada rejeitada com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação example: Call rejected "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Descrição do erro examples: - invalid number "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Descrição do erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string description: Descrição do erro interno example: "error rejecting call: timeout" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/archive: post: tags: - Chats operationId: archiveChat summary: Arquivar/desarquivar chat description: Altera o estado de arquivamento de um chat do WhatsApp. - Quando arquivado, o chat é movido para a seção de arquivados no WhatsApp - A ação é sincronizada entre todos os dispositivos conectados - Não afeta as mensagens ou o conteúdo do chat security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number - archive properties: number: type: string description: Número do telefone (formato E.164) ou ID do grupo example: "5511999999999" archive: type: boolean description: true para arquivar, false para desarquivar example: true responses: "200": description: Chat arquivado/desarquivado com sucesso content: application/json: schema: type: object properties: response: type: string example: Chat updated successfully "400": description: Dados da requisição inválidos content: application/json: schema: type: object properties: error: type: string example: Invalid phone number format "401": description: Token de autenticação ausente ou inválido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro ao executar a operação content: application/json: schema: type: object properties: error: type: string example: Error archiving chat x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/delete: post: tags: - Chats operationId: deleteChat summary: Deleta chat description: "Deleta ou limpa um chat e/ou suas mensagens do WhatsApp e/ou banco de dados. Você pode escolher: - Deletar o chat do WhatsApp - Limpar a conversa no WhatsApp - Deletar o chat do banco de dados - Deletar apenas as mensagens do banco de dados - Qualquer combinação das opções acima Observação: - Se clearChatWhatsApp e deleteChatWhatsApp forem true, o clear tem prioridade." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: | Número do chat no formato internacional. Para grupos use o ID completo do grupo. example: "5511999999999" deleteChatDB: type: boolean description: Se true, deleta o chat do banco de dados default: false example: true deleteMessagesDB: type: boolean description: Se true, deleta todas as mensagens do chat do banco de dados default: false example: true deleteChatWhatsApp: type: boolean description: > Se true, deleta o chat do WhatsApp. Para grupos, esta operação não é permitida e o chat será apenas limpo. default: false example: true clearChatWhatsApp: type: boolean description: > Se true, limpa a conversa do chat no WhatsApp (sem sair do chat). Funciona para grupos e conversas individuais. default: false example: true required: - number responses: "200": description: Operação realizada com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de sucesso example: Chat deletion process completed actions: type: array description: Lista de ações realizadas items: type: string example: - Chat deleted from WhatsApp - Chat deleted from database - "Messages associated with chat deleted from database: 42" errors: type: array description: Lista de erros ocorridos, se houver items: type: string example: - "Error deleting chat from WhatsApp: connection timeout" "400": description: Erro nos parâmetros da requisição content: application/json: schema: type: object properties: error: type: string example: Missing number in payload "401": description: Token inválido ou não fornecido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/ephemeral: post: tags: - Chats operationId: updateChatEphemeral summary: Configurar mensagens temporárias em chat privado description: "Define o temporizador de mensagens temporárias (disappearing messages) de um chat privado. Valores aceitos para a duração: - `0` ou `off` para desativar - `1d` - `7d` - `90d` Observações: - este endpoint é apenas para chats privados - se o identificador informado for de grupo, a API retorna erro orientando usar `/group/ephemeral` - a resposta também atualiza o `wa_ephemeralExpiration` do chat no cache local" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number - duration properties: number: type: string description: Identificador do chat privado example: 5511999999999@s.whatsapp.net duration: oneOf: - type: string - type: integer description: Duração desejada para mensagens temporárias example: 7d example: number: 5511999999999@s.whatsapp.net duration: 7d responses: "200": description: Temporizador atualizado com sucesso content: application/json: schema: type: object properties: response: type: string example: Ephemeral timer updated successfully chat: type: object description: Estrutura descrita pelo exemplo desta operação. ephemeral: type: object properties: enabled: type: boolean example: true seconds: type: integer format: int64 example: 604800 label: type: string example: 7d example: response: Ephemeral timer updated successfully chat: wa_chatid: 5511999999999@s.whatsapp.net wa_ephemeralExpiration: 604800 wa_isGroup: false ephemeral: enabled: true seconds: 604800 label: 7d "400": description: Payload inválido, chat inválido ou duração não suportada content: application/json: schema: type: object properties: error: type: string example: "invalid duration. Allowed values: 0, off, 1d, 7d, 90d" "401": description: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar o temporizador content: application/json: schema: type: object properties: error: type: string example: "Error updating chat ephemeral timer: connection closed" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/find: post: tags: - Chats operationId: findChats summary: Busca chats com filtros description: "Busca chats com diversos filtros e ordenação. Suporta filtros em todos os campos do chat, paginação e ordenação customizada. Operadores de filtro: - `~` : LIKE (contém) - `!~` : NOT LIKE (não contém) - `!=` : diferente - `>=` : maior ou igual - `>` : maior que - `<=` : menor ou igual - `<` : menor que - Sem operador: LIKE (contém)" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: operator: type: string enum: - AND - OR default: AND description: Operador lógico entre os filtros sort: type: string description: Campo para ordenação (+/-campo). Ex -wa_lastMsgTimestamp limit: type: integer description: Quantidade máxima de resultados a retornar default: 20 offset: type: integer description: Número de registros a pular (para paginação) default: 0 wa_fastid: type: string wa_chatid: type: string wa_archived: type: boolean wa_contactName: type: string wa_name: type: string name: type: string wa_isBlocked: type: boolean wa_isGroup: type: boolean wa_isGroup_admin: type: boolean wa_isGroup_announce: type: boolean wa_isGroup_member: type: boolean wa_isPinned: type: boolean wa_label: type: string description: ID da label aplicada ao chat. Use o valor retornado por `/labels`, não o nome da etiqueta. wa_notes: type: string lead_tags: type: string lead_isTicketOpen: type: boolean lead_assignedAttendant_id: type: string lead_status: type: string example: operator: AND sort: -wa_lastMsgTimestamp limit: 50 offset: 0 wa_isGroup: true lead_status: ~novo wa_label: "10" wa_notes: ~vip responses: "200": description: Lista de chats encontrados content: application/json: schema: type: object properties: chats: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. totalChatsStats: type: object description: Contadores totais de chats pagination: type: object properties: totalRecords: type: integer description: Total de registros encontrados limit: type: integer description: Limite aplicado na busca offset: type: integer description: Offset usado para recuperar os resultados "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/mute: post: tags: - Chats operationId: muteChat summary: Silenciar chat description: "Silencia notificações de um chat por um período específico. As opções de silenciamento são: * 0 - Remove o silenciamento * 8 - Silencia por 8 horas * 168 - Silencia por 1 semana (168 horas) * -1 - Silencia permanentemente" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number - muteEndTime properties: number: type: string description: ID do chat no formato 123456789@s.whatsapp.net ou 123456789-123456@g.us example: 5511999999999@s.whatsapp.net muteEndTime: type: integer description: | Duração do silenciamento: * 0 = Remove silenciamento * 8 = Silencia por 8 horas * 168 = Silencia por 1 semana * -1 = Silencia permanentemente enum: - 0 - 8 - 168 - -1 example: 8 responses: "200": description: Chat silenciado com sucesso content: application/json: schema: type: object properties: response: type: string example: Chat mute settings updated successfully "400": description: Duração inválida ou formato de número incorreto "401": description: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/notes: post: tags: - Chats operationId: getChatNotes summary: Consultar notas internas do chat description: "Retorna `wa_notes` de um chat usando apenas os dados já persistidos localmente. Casos de uso: - ler a anotação local já persistida no chat - consultar notas mesmo durante reconexão da sessão do WhatsApp Regras: - envie `number` - `/chat/notes/refresh` relê o estado persistido da Relya; não promete sincronização remota" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: JID completo do chat example: 5511999999999@s.whatsapp.net example: number: 5511999999999@s.whatsapp.net responses: "200": description: Nota do chat retornada com sucesso content: application/json: schema: type: object properties: chat: type: object description: Estrutura descrita pelo exemplo desta operação. wa_notes: type: string description: Conteúdo atual da nota do chat example: Cliente prefere contato no período da tarde source: type: string description: Origem usada para compor a resposta enum: - local example: local example: chat: wa_fastid: admin:5511999999999 wa_chatid: 5511999999999@s.whatsapp.net wa_notes: Cliente prefere contato no período da tarde wa_notes: Cliente prefere contato no período da tarde source: local "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: number is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado content: application/json: schema: type: object properties: error: type: string example: chat not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar a nota local content: application/json: schema: type: object properties: error: type: string example: failed to load chat notes from local database x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/notes/edit: post: tags: - Chats operationId: editChatNotes summary: Editar notas internas persistidas do chat description: "Atualiza a nota interna da Relya por instância e chat. Não declara alteração no app state do WhatsApp. Regras: - envie `number` - envie `notes` como campo principal - envie string vazia para limpar a nota do chat" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: JID completo do chat example: 5511999999999@s.whatsapp.net notes: type: string description: Conteúdo da nota a persistir no chat example: Cliente prefere contato no período da tarde example: number: 5511999999999@s.whatsapp.net notes: Cliente prefere contato no período da tarde responses: "200": description: Nota atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Chat notes updated chat: type: object description: Estrutura descrita pelo exemplo desta operação. wa_notes: type: string description: Conteúdo atual da nota após a atualização example: Cliente prefere contato no período da tarde source: type: string description: Origem da atualização enum: - api example: api "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: notes is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado content: application/json: schema: type: object properties: error: type: string example: chat not found "409": description: A edição não pode ser executada porque o history sync inicial ainda está em andamento content: application/json: schema: type: object properties: error: type: string example: history sync still in progress, try again in a moment "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar a nota content: application/json: schema: type: object properties: error: type: string example: "error editing chat notes: client is not connected" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/notes/refresh: post: tags: - Chats operationId: refreshChatNotes summary: Reler notas internas persistidas do chat description: Relê a nota interna persistida na Relya e responde com `source:relya_local` no driver WhatsApp. O campo `force` é aceito por compatibilidade, mas não transforma esta leitura em sincronização do WhatsApp. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: JID completo do chat example: 5511999999999@s.whatsapp.net force: type: boolean description: | Tente primeiro com `false`. Use `true` apenas quando a recarga padrão não funcionar bem, pois esse modo faz uma nova leitura mais completa das notas. default: false example: false example: number: 5511999999999@s.whatsapp.net responses: "200": description: Nota do chat recarregada com sucesso content: application/json: schema: type: object properties: chat: type: object description: Estrutura descrita pelo exemplo desta operação. wa_notes: type: string description: Conteúdo atual da nota do chat example: Cliente prefere contato no período da tarde source: type: string description: Origem usada para compor a resposta enum: - appstate_reload example: appstate_reload "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: number is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado após o reload content: application/json: schema: type: object properties: error: type: string example: chat not found "409": description: O reload não pode ser executado porque o history sync inicial ainda está em andamento content: application/json: schema: type: object properties: error: type: string example: history sync still in progress, try again in a moment "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao recarregar a nota content: application/json: schema: type: object properties: error: type: string example: "failed to fetch regular_low app state: connection closed" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/pin: post: tags: - Chats operationId: pinChat summary: Fixar/desafixar chat description: Fixa ou desafixa um chat no topo da lista de conversas. Chats fixados permanecem no topo mesmo quando novas mensagens são recebidas em outros chats. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: > Número do chat no formato internacional completo (ex: "5511999999999") ou ID do grupo (ex: "123456789-123456@g.us") example: "5511999999999" pin: type: boolean description: > Define se o chat deve ser fixado (true) ou desafixado (false) example: true required: - number - pin responses: "200": description: Chat fixado/desafixado com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação example: Chat pinned "400": description: Erro na requisição content: application/json: schema: type: object properties: error: type: string description: Descrição do erro example: Could not parse phone "401": description: Não autorizado content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro de autenticação example: Invalid token "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/read: post: tags: - Chats operationId: markChatRead summary: Marcar chat como lido/não lido description: "Atualiza o status de leitura de um chat no WhatsApp. Quando um chat é marcado como lido: - O contador de mensagens não lidas é zerado - O indicador visual de mensagens não lidas é removido - O remetente recebe confirmação de leitura (se ativado) Quando marcado como não lido: - O chat aparece como pendente de leitura - Não afeta as confirmações de leitura já enviadas" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number - read properties: number: type: string description: > Identificador do chat no formato: - Para usuários: [número]@s.whatsapp.net (ex: 5511999999999@s.whatsapp.net) - Para grupos: [id-grupo]@g.us (ex: 123456789-987654321@g.us) example: 5511999999999@s.whatsapp.net read: type: boolean description: | - true: marca o chat como lido - false: marca o chat como não lido responses: "200": description: Status de leitura atualizado com sucesso content: application/json: schema: type: object properties: response: type: string example: Chat read status updated successfully "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de autenticação ausente ou inválido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro ao atualizar status de leitura x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/check: post: tags: - Contatos operationId: checkChat summary: Verificar Números no WhatsApp description: "Verifica se números fornecidos estão registrados no WhatsApp e retorna informações detalhadas. ### Funcionalidades: - Verifica múltiplos números simultaneamente - Suporta números individuais e IDs de grupo - Retorna nome verificado quando disponível - Identifica grupos e comunidades - Verifica subgrupos de comunidades **Comportamento específico**: - Para números individuais: - Verifica registro no WhatsApp - Retorna nome verificado se disponível - Normaliza formato do número - Para grupos: - Verifica existência - Retorna nome do grupo - Retorna id do grupo de anúncios se buscado por id de comunidade" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: numbers: type: array items: type: string description: Lista de números ou IDs de grupo para verificar example: - "5511999999999" - 123456789@g.us responses: "200": description: Resultado da verificação content: application/json: schema: type: array items: type: object properties: query: type: string description: Número/ID original consultado jid: type: string description: JID do WhatsApp lid: type: string description: LID do WhatsApp isInWhatsapp: type: boolean description: Indica se está no WhatsApp verifiedName: type: string description: Nome verificado se disponível groupName: type: string description: Nome do grupo se aplicável error: type: string description: Mensagem de erro se houver "400": description: Payload inválido ou sem números content: application/json: schema: type: object properties: error: type: string example: Missing numbers in payload "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No active session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: WhatsApp client is not connected x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/details: post: tags: - Contatos operationId: getChatDetails summary: Obter Detalhes Completos description: "Retorna informações **completas** sobre um contato ou chat, incluindo **todos os campos disponíveis** do modelo Chat. ### Funcionalidades: - **Retorna chat completo**: Todos os campos do modelo Chat (mais de 60 campos) - **Busca informações para contatos individuais e grupos** - **URLs de imagem em dois tamanhos**: preview (menor) ou full (original) - **Combina informações de diferentes fontes**: WhatsApp, contatos salvos, leads - **Atualiza automaticamente dados desatualizados** no banco ### Campos Retornados: - **Informações básicas**: id, wa_fastid, wa_chatid, owner, name, phone - **Dados do WhatsApp**: wa_name, wa_contactName, wa_archived, wa_isBlocked, etc. - **Dados de lead/CRM**: lead_name, lead_email, lead_status, lead_field01-20, etc. - **Informações de grupo**: wa_isGroup, wa_isGroup_admin, wa_isGroup_announce, etc. - **Chatbot**: chatbot_summary, chatbot_lastTrigger_id, chatbot_disableUntil, etc. - **Configurações**: wa_muteEndTime, wa_isPinned, wa_unreadCount, etc. **Comportamento**: - Para contatos individuais: - Busca nome verificado do WhatsApp - Verifica nome salvo nos contatos - Formata número internacional - Calcula grupos em comum - Para grupos: - Busca nome do grupo - Verifica status de comunidade" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: Número do telefone ou ID do grupo example: "5511999999999" preview: type: boolean description: > Controla o tamanho da imagem de perfil retornada: - `true`: Retorna imagem em tamanho preview (menor, otimizada para listagens) - `false` (padrão): Retorna imagem em tamanho full (resolução original, maior qualidade) default: false required: - number responses: "200": description: Informações completas do chat retornadas com sucesso content: application/json: schema: allOf: - type: object description: Estrutura descrita pelo exemplo desta operação. - type: object properties: common_groups: type: string description: "Grupos em comum separados por vírgula, formato: nome_grupo(id_grupo)" example: Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us) imagePreview: type: string description: URL da imagem de perfil em tamanho preview (menor) - apenas se preview=true image: type: string description: URL da imagem de perfil em tamanho full (resolução original) - apenas se preview=false example: id: r1a2b3c4d5e6f7 wa_fastid: admin:5511999999999 wa_chatid: 5511999999999@s.whatsapp.net wa_name: João Silva name: João Silva phone: +55 11 99999-9999 owner: admin wa_archived: false wa_isBlocked: false wa_isGroup: false lead_name: João lead_fullName: João Silva lead_email: joao@exemplo.com lead_status: ativo wa_contactName: João Silva common_groups: Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us) image: https://pps.whatsapp.net/v/t61.24694-24/12345_image.jpg "400": description: Payload inválido ou número inválido content: application/json: schema: type: object properties: error: type: string example: Invalid request payload "401": description: Token não fornecido content: application/json: schema: type: object properties: error: type: string example: Unauthorized "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou sessão não iniciada content: application/json: schema: type: object properties: error: type: string example: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /contact/add: post: tags: - Contatos operationId: addContact summary: Adiciona um contato à agenda description: "Adiciona um novo contato à agenda do celular. O endpoint realiza: - Adiciona o contato à agenda usando o WhatsApp - Usa o campo 'name' tanto para o nome completo quanto para o primeiro nome - Salva as informações do contato na agenda do WhatsApp - Retorna informações do contato adicionado" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number - name properties: number: type: string description: > Número de telefone no formato internacional com código do país obrigatório. Para Brasil, deve começar com 55. Aceita variações com/sem símbolo +, com/sem parênteses, com/sem hífen e com/sem espaços. Também aceita formato JID do WhatsApp (@s.whatsapp.net). Não aceita contatos comerciais (@lid) nem grupos (@g.us). examples: - +55 (21) 99999-9999 - +55 21 99999-9999 - +55 21 999999999 - "+5521999999999" - "5521999999999" - 5521999999999@s.whatsapp.net name: type: string description: Nome completo do contato (será usado como primeiro nome e nome completo) example: João Silva responses: "200": description: Contato adicionado com sucesso content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Contato adicionado com sucesso contact: type: object properties: jid: type: string description: "ID único do contato no WhatsApp (formato: número@s.whatsapp.net)" example: 5511999999999@s.whatsapp.net name: type: string description: Nome completo do contato example: João Silva phone: type: string description: Número de telefone example: "5511999999999" "400": description: Dados inválidos na requisição content: application/json: schema: type: object properties: error: type: string example: Número inválido "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Erro ao adicionar contato x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /contact/remove: post: tags: - Contatos operationId: removeContact summary: Remove um contato da agenda description: "Remove um contato da agenda do celular. O endpoint realiza: - Remove o contato da agenda usando o WhatsApp AppState - Atualiza a lista de contatos sincronizada - Retorna confirmação da remoção" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - number properties: number: type: string description: > Número de telefone no formato internacional com código do país obrigatório. Para Brasil, deve começar com 55. Aceita variações com/sem símbolo +, com/sem parênteses, com/sem hífen e com/sem espaços. Também aceita formato JID do WhatsApp (@s.whatsapp.net). Não aceita contatos comerciais (@lid) nem grupos (@g.us). examples: - +55 (21) 99999-9999 - +55 21 99999-9999 - +55 21 999999999 - "+5521999999999" - "5521999999999" - 5521999999999@s.whatsapp.net responses: "200": description: Contato removido com sucesso content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Contato removido com sucesso removed_contact: type: object properties: jid: type: string description: "ID único do contato no WhatsApp (formato: número@s.whatsapp.net)" example: 5511999999999@s.whatsapp.net phone: type: string description: Número de telefone removido example: "5511999999999" "400": description: Dados inválidos na requisição content: application/json: schema: type: object properties: error: type: string example: Número inválido "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Contato não encontrado content: application/json: schema: type: object properties: error: type: string example: Contato não encontrado na agenda "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Erro ao remover contato x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /contacts: get: tags: - Contatos operationId: checkContacts summary: Retorna lista de contatos do WhatsApp description: "Retorna a lista de contatos do WhatsApp conforme o filtro informado em `contactScope`. O endpoint realiza: - Busca todos os contatos armazenados - Filtra para contatos da agenda, fora da agenda ou todos - Usa `address_book` como padrao quando `contactScope` nao for informado - Retorna dados formatados incluindo JID e informações de nome" security: - InstanceToken: [] parameters: - in: query name: contactScope required: false schema: type: string enum: - address_book - outside_address_book - all default: address_book description: Define se a busca retorna apenas contatos da agenda, apenas fora da agenda ou todos os contatos conhecidos. responses: "200": description: Lista de contatos retornada com sucesso content: application/json: schema: type: array items: type: object properties: jid: type: string description: "ID único do contato no WhatsApp (formato: número@s.whatsapp.net)" example: 5511999999999@s.whatsapp.net contact_name: type: string description: Nome completo do contato example: Contato Exemplo contact_FirstName: type: string description: Primeiro nome do contato example: Contato example: jid: 5511999999999@s.whatsapp.net contact_name: Contato Exemplo contact_FirstName: Contato "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Internal server error x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /contacts/list: post: tags: - Contatos operationId: listContacts summary: Listar todos os contatos com paginacao description: Retorna uma lista paginada de contatos da conta do WhatsApp atualmente conectada. Use este endpoint (POST) para controlar `limit` e `offset` via corpo da requisicao. O campo `contactScope` permite escolher entre contatos da agenda, fora da agenda ou todos os contatos conhecidos. A rota GET `/contacts` continua disponivel para quem prefere a lista completa sem paginacao. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: limit: type: integer description: Quantidade maxima de resultados por pagina (padrao 100, maximo 1000) default: 100 offset: type: integer description: Deslocamento base zero para paginacao default: 0 contactScope: type: string description: Define se a busca retorna apenas contatos da agenda, apenas fora da agenda ou todos os contatos conhecidos. enum: - address_book - outside_address_book - all default: address_book responses: "200": description: Lista de contatos recuperada com sucesso content: application/json: schema: type: object properties: contacts: type: array items: type: object properties: jid: type: string description: "ID unico do contato no WhatsApp (formato: numero@s.whatsapp.net)" example: 5511999999999@s.whatsapp.net contact_name: type: string description: Nome completo do contato (quando salvo) example: Joao Silva contact_FirstName: type: string description: Primeiro nome do contato example: Joao totalDeviceContacts: type: integer description: Total bruto de contatos no dispositivo pagination: type: object properties: totalRecords: type: integer description: Total de contatos apos filtragem limit: type: integer description: Limite aplicado na pagina atual offset: type: integer description: Offset efetivamente usado na pagina atual "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token nao fornecido ou invalido content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar contatos content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /chat/editLead: post: tags: - CRM operationId: editLead summary: Edita informações de lead description: Atualiza as informações de lead associadas a um chat. Permite modificar status do ticket, atribuição de atendente, posição no kanban, tags e outros campos customizados. As alterações são refletidas imediatamente no banco de dados e disparam eventos webhook/SSE para manter a aplicação sincronizada. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: | Identificador do chat. Pode ser: - wa_chatid (ex: "5511999999999@s.whatsapp.net") - wa_fastid (ex: "5511888888888:5511999999999") example: 5511999999999@s.whatsapp.net chatbot_disableUntil: type: integer format: int64 description: > Timestamp UTC até quando o chatbot deve ficar desativado para este chat. Use 0 para reativar imediatamente. example: 1735686000 lead_isTicketOpen: type: boolean description: | Status do ticket associado ao lead. - true: Ticket está aberto/em atendimento - false: Ticket está fechado/resolvido example: true lead_assignedAttendant_id: type: string description: | ID do atendente atribuído ao lead. Use string vazia ("") para remover a atribuição. example: att_123456 lead_kanbanOrder: type: integer format: int64 description: | Posição do card no quadro kanban. Valores maiores aparecem primeiro. example: 1000 lead_tags: type: array items: type: string description: | Lista de tags associadas ao lead. Tags inexistentes são criadas automaticamente. Envie array vazio ([]) para remover todas as tags. example: - vip - suporte - prioridade-alta lead_name: type: string description: Nome principal do lead example: João Silva lead_fullName: type: string description: Nome completo do lead example: João Silva Pereira lead_email: type: string format: email description: Email do lead example: joao@exemplo.com lead_personalid: type: string description: | Documento de identificação (CPF/CNPJ) Apenas números ou formatado example: 123.456.789-00 lead_status: type: string description: Status do lead no funil de vendas example: qualificado lead_notes: type: string description: Anotações sobre o lead example: Cliente interessado em plano premium lead_field01: type: string description: Campo personalizado 1 lead_field02: type: string description: Campo personalizado 2 lead_field03: type: string description: Campo personalizado 3 lead_field04: type: string description: Campo personalizado 4 lead_field05: type: string description: Campo personalizado 5 lead_field06: type: string description: Campo personalizado 6 lead_field07: type: string description: Campo personalizado 7 lead_field08: type: string description: Campo personalizado 8 lead_field09: type: string description: Campo personalizado 9 lead_field10: type: string description: Campo personalizado 10 lead_field11: type: string description: Campo personalizado 11 lead_field12: type: string description: Campo personalizado 12 lead_field13: type: string description: Campo personalizado 13 lead_field14: type: string description: Campo personalizado 14 lead_field15: type: string description: Campo personalizado 15 lead_field16: type: string description: Campo personalizado 16 lead_field17: type: string description: Campo personalizado 17 lead_field18: type: string description: Campo personalizado 18 lead_field19: type: string description: Campo personalizado 19 lead_field20: type: string description: Campo personalizado 20 responses: "200": description: Lead atualizado com sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. example: wa_fastid: 5511888888888:5511999999999 wa_chatid: 5511999999999@s.whatsapp.net lead_name: João Silva lead_status: qualificado lead_tags: - vip - suporte lead_isTicketOpen: true lead_assignedAttendant_id: att_123456 "400": description: Payload inválido "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/updateFieldsMap: post: tags: - CRM operationId: updateFieldsMap summary: Atualizar campos personalizados de leads description: 'Atualiza os campos personalizados (custom fields) de uma instância. Permite configurar até 20 campos personalizados para armazenamento de informações adicionais sobre leads. Cada campo pode armazenar até 255 caracteres e aceita qualquer tipo de dado. Campos disponíveis: - lead_field01 a lead_field20 Exemplo de uso: 1. Armazenar informações adicionais sobre leads 2. Criar campos personalizados para integração com outros sistemas 3. Armazenar tags ou categorias personalizadas 4. Manter histórico de interações com o lead Exemplo de requisição: ```json { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone", "lead_field04": "cidade", "lead_field05": "estado", "lead_field06": "idade", "lead_field07": "interesses", "lead_field08": "origem", "lead_field09": "status", "lead_field10": "valor", "lead_field11": "observacoes", "lead_field12": "ultima_interacao", "lead_field13": "proximo_contato", "lead_field14": "vendedor", "lead_field15": "produto_interesse", "lead_field16": "fonte_captacao", "lead_field17": "score", "lead_field18": "tags", "lead_field19": "historico", "lead_field20": "custom" } ``` Exemplo de resposta: ```json { "success": true, "message": "Custom fields updated successfully", "instance": { "id": "r183e2ef9597845", "name": "minha-instancia", "fieldsMap": { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone", "lead_field04": "cidade", "lead_field05": "estado", "lead_field06": "idade", "lead_field07": "interesses", "lead_field08": "origem", "lead_field09": "status", "lead_field10": "valor", "lead_field11": "observacoes", "lead_field12": "ultima_interacao", "lead_field13": "proximo_contato", "lead_field14": "vendedor", "lead_field15": "produto_interesse", "lead_field16": "fonte_captacao", "lead_field17": "score", "lead_field18": "tags", "lead_field19": "historico", "lead_field20": "custom" } } } ``` Erros comuns: - 400: Campos inválidos ou payload mal formatado - 401: Token inválido ou expirado - 404: Instância não encontrada - 500: Erro ao atualizar campos no banco de dados Restrições: - Cada campo pode ter no máximo 255 caracteres - Campos vazios serão mantidos com seus valores atuais - Apenas os campos enviados serão atualizados' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: lead_field01: type: string description: Campo personalizado 01 maxLength: 255 lead_field02: type: string description: Campo personalizado 02 maxLength: 255 lead_field03: type: string description: Campo personalizado 03 maxLength: 255 lead_field04: type: string description: Campo personalizado 04 maxLength: 255 lead_field05: type: string description: Campo personalizado 05 maxLength: 255 lead_field06: type: string description: Campo personalizado 06 maxLength: 255 lead_field07: type: string description: Campo personalizado 07 maxLength: 255 lead_field08: type: string description: Campo personalizado 08 maxLength: 255 lead_field09: type: string description: Campo personalizado 09 maxLength: 255 lead_field10: type: string description: Campo personalizado 10 maxLength: 255 lead_field11: type: string description: Campo personalizado 11 maxLength: 255 lead_field12: type: string description: Campo personalizado 12 maxLength: 255 lead_field13: type: string description: Campo personalizado 13 maxLength: 255 lead_field14: type: string description: Campo personalizado 14 maxLength: 255 lead_field15: type: string description: Campo personalizado 15 maxLength: 255 lead_field16: type: string description: Campo personalizado 16 maxLength: 255 lead_field17: type: string description: Campo personalizado 17 maxLength: 255 lead_field18: type: string description: Campo personalizado 18 maxLength: 255 lead_field19: type: string description: Campo personalizado 19 maxLength: 255 lead_field20: type: string description: Campo personalizado 20 maxLength: 255 responses: "200": description: Sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido/expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Instância não encontrada "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/presence: post: tags: - Enviar Mensagem operationId: sendPresence summary: Enviar atualização de presença description: Envia uma atualização imediata de presença. Na integração atual, composing, recording, paused, available e unavailable são aceitos; delay e repetição temporizada não são simulados e retornam 422. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: "Número do destinatário no formato internacional (ex: 5511999999999)" example: "5511999999999" presence: type: string description: Tipo de presença a ser enviada enum: - composing - recording - paused example: composing delay: type: integer description: > Duração em milissegundos que a presença ficará ativa (máximo 5 minutos = 300000ms). Se não informado ou valor maior que 5 minutos, usa o limite padrão de 5 minutos. A presença é reenviada a cada 10 segundos durante este período. maximum: 300000 example: 30000 required: - number - presence responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Ação executada na conexão real do número. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. x-relya-runtime-options: preserved: - number - track_id - track_source - async=true - presence=composing|recording|paused|available|unavailable rejectedWhenRequested: - delay - forward=true note: A atualizacao e imediata. Repeticao por tempo e encaminhamento nao sao simulados. /send/carousel: post: tags: - Enviar Mensagem operationId: sendCarousel summary: Enviar carrossel de mídia com botões description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Carrossel vira resumo textual unico para nao multiplicar envios O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" text: type: string description: Texto principal da mensagem example: Nossos Produtos em Destaque carousel: type: array description: Array de cartões do carrossel items: type: object properties: text: type: string description: Texto do cartão example: |- Smartphone XYZ O mais avançado smartphone da linha image: type: string description: URL da imagem (opcional) example: https://exemplo.com/produto1.jpg video: type: string description: URL do vídeo (alternativa à imagem) example: https://exemplo.com/produto1.mp4 document: type: string description: URL do documento (alternativa à imagem) example: https://exemplo.com/catalogo.pdf filename: type: string description: Nome do arquivo para documentos example: Catalogo.pdf buttons: type: array description: Array de botões do cartão items: type: object properties: id: type: string description: ID do botão example: buy_xyz text: type: string description: Texto exibido no botão example: Comprar Agora type: type: string description: > Tipo do botão: * REPLY - O id será enviado como resposta ao chat * URL - O id deve ser a URL completa que será aberta * COPY - O id será o texto copiado para área de transferência * CALL - O id deve ser o número de telefone para a chamada enum: - REPLY - URL - CALL - COPY example: REPLY required: - text - buttons delay: type: integer description: Atraso em milissegundos antes do envio example: 1000 readchat: type: boolean description: Marca conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 forward: type: boolean description: Marca a mensagem como encaminhada no WhatsApp example: false async: type: boolean description: Se true, envia a mensagem de forma assíncrona via fila interna example: false track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 required: - number - text - carousel responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Carrossel vira resumo textual unico para nao multiplicar envios x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /send/contact: post: tags: - Enviar Mensagem operationId: sendContact summary: Enviar cartão de contato (vCard) description: Envia vCard. Na integração atual, um nome e um telefone são preservados; múltiplos telefones, organização, e-mail e URL retornam 422 antes da fila. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" fullName: type: string description: Nome completo do contato example: João Silva phoneNumber: type: string description: Números de telefone (separados por vírgula) example: 5511999999999,5511888888888 organization: type: string description: Nome da organização/empresa example: Empresa XYZ email: type: string description: Endereço de email example: joao@empresa.com url: type: string description: URL pessoal ou da empresa example: https://empresa.com/joao replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 readchat: type: boolean description: Marca conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true delay: type: integer description: Atraso em milissegundos antes do envio, durante o atraso apacerá 'Digitando...' example: 1000 forward: type: boolean description: Marca a mensagem como encaminhada no WhatsApp example: true track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 async: type: boolean description: Se true, envia a mensagem de forma assíncrona via fila interna example: false required: - number - fullName - phoneNumber responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Ação executada na conexão real do número. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. x-relya-runtime-options: preserved: - number - track_id - track_source - async=true - name|fullName - um phoneNumber|phone|contact|numberContact rejectedWhenRequested: - delay - readchat=true - readmessages=true - async=false - replyid - mentions - forward=true - multiplos telefones - organization - email - url note: Um vCard com nome e um telefone e preservado. Campos adicionais ou multiplos telefones retornam 422 antes da fila. /send/location: post: tags: - Enviar Mensagem operationId: sendLocation summary: Enviar localização geográfica description: Envia coordenadas geográficas. Na integração atual, latitude e longitude são preservadas; nome e endereço retornam 422 antes da fila. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" name: type: string description: Nome do local example: MASP address: type: string description: Endereço do local example: Av. Paulista, 1578 - Bela Vista, São Paulo - SP latitude: type: number description: Latitude (-90 a 90) example: -23.5616 longitude: type: number description: Longitude (-180 a 180) example: -46.6562 replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 readchat: type: boolean description: Marca conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true delay: type: integer description: Atraso em milissegundos antes do envio, durante o atraso apacerá 'Digitando...' example: 1000 forward: type: boolean description: Marca a mensagem como encaminhada no WhatsApp example: true track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 async: type: boolean description: Se true, envia a mensagem de forma assíncrona via fila interna example: false required: - number - latitude - longitude responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Ação executada na conexão real do número. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. x-relya-runtime-options: preserved: - number - track_id - track_source - async=true - latitude|lat - longitude|lng|long rejectedWhenRequested: - delay - readchat=true - readmessages=true - async=false - replyid - mentions - forward=true - name - address note: Coordenadas sao preservadas. Nome, endereco e opcoes comuns sem representacao no engine falham antes da fila. /send/location-button: post: tags: - Enviar Mensagem operationId: sendLocationButton summary: Solicitar localização do usuário description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Solicitacao vira instrucao textual para compartilhar localizacao O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" text: type: string description: Texto da mensagem que será exibida example: Por favor, compartilhe sua localização delay: type: integer description: Atraso em milissegundos antes do envio example: 0 readchat: type: boolean description: Se deve marcar a conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 async: type: boolean description: Se true, envia a mensagem de forma assíncrona via fila interna example: false track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 required: - number - text responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Solicitacao vira instrucao textual para compartilhar localizacao x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /send/media: post: tags: - Enviar Mensagem operationId: sendMedia summary: Enviar mídia (imagem, vídeo, áudio ou documento) description: Envia imagem, video, audio, voz, documento ou sticker por URL, data URI ou base64. O contrato por driver informa modos preservados; opcoes sem representacao fiel retornam 422 sem criar item na fila. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object required: - number - type - file properties: number: type: string description: Número com DDI, somente dígitos example: "5511999999999" type: type: string enum: - image - video - videoplay - ptv - audio - ptt - myaudio - document - sticker example: audio file: type: string description: URL HTTPS, data URI ou base64 example: https://seusite.com/audio.mp3 fileName: type: string description: Nome exibido para documentos docName: type: string description: Nome do documento (tem prioridade sobre fileName) viewOnce: type: boolean description: true envia imagem ou vídeo como visualização única caption: type: string description: Legenda de imagem, vídeo ou documento mimetype: type: string description: "Ex.: audio/mpeg, audio/ogg, image/jpeg" ptt: type: boolean description: true envia áudio como mensagem de voz track_id: type: string description: Chave de idempotência da ação example: audio-123 example: number: "5511999999999" type: image file: https://exemplo.com/foto.jpg responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "413": description: Arquivo de mídia acima do limite de 16 MB. content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Envio real de imagem, vídeo, áudio, voz, documento ou figurinha, por URL, data URI ou base64. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. x-relya-runtime-options: preserved: - number - track_id - track_source - async=true - type=image|video|videoplay|audio|ptt|myaudio|document|sticker - file|url|media - text|caption - docName|fileName - mimetype - ptt - viewOnce para image|video|audio - gifPlayback para video rejectedWhenRequested: - delay - readchat=true - readmessages=true - async=false - replyid - mentions - forward=true - thumbnail - compress=true - type=ptv|videonote - viewOnce para document|sticker - caption para audio|sticker note: Midia, legenda e nome de documento suportados sao preservados. Modos que o engine nao consegue representar retornam 422 sem criar item na fila. /send/menu: post: tags: - Enviar Mensagem operationId: sendMenu summary: Enviar menu interativo (botões, carrosel, lista ou enquete) description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Menus viram lista textual ou enquete nativa quando possivel O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" type: type: string description: Tipo do menu (button, list, poll, carousel) enum: - button - list - poll - carousel example: list text: type: string description: Texto principal (aceita placeholders) example: "Escolha uma opção:" footerText: type: string description: Texto do rodapé (opcional) example: Menu de serviços listButton: type: string description: Texto do botão principal example: Ver opções selectableCount: type: integer description: Número máximo de opções selecionáveis (para enquetes) example: 1 choices: type: array description: Lista de opções. Use [Título] para seções em listas items: type: string example: - "[Eletrônicos]" - Smartphones|phones|Últimos lançamentos - Notebooks|notes|Modelos 2024 - "[Acessórios]" - Fones|fones|Bluetooth e com fio - Capas|cases|Proteção para seu device imageButton: type: string description: "URL da imagem para botões (recomendado para type: button)" example: https://exemplo.com/imagem-botao.jpg replyid: type: string description: ID da mensagem para responder example: 3EB0538DA65A59F6D8A251 mentions: type: string description: Números para mencionar (separados por vírgula) example: 5511999999999,5511888888888 readchat: type: boolean description: Marca conversa como lida após envio example: true readmessages: type: boolean description: Marca últimas mensagens recebidas como lidas example: true delay: type: integer description: Atraso em milissegundos antes do envio, durante o atraso apacerá 'Digitando...' example: 1000 track_source: type: string description: Origem do rastreamento da mensagem example: chatwoot track_id: type: string description: ID para rastreamento da mensagem (aceita valores duplicados) example: msg_123456789 async: type: boolean description: Se true, envia a mensagem de forma assíncrona via fila interna example: false required: - number - type - text - choices responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Menus viram lista textual ou enquete nativa quando possivel x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /send/pix-button: post: tags: - Enviar Mensagem operationId: sendPixButton summary: Enviar botão PIX description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: PIX vira mensagem textual com a chave informada O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" pixType: type: string description: "Tipo da chave PIX. Valores aceitos: CPF, CNPJ, PHONE, EMAIL ou EVP" example: EVP pixKey: type: string description: Valor da chave PIX (CPF/CNPJ/telefone/email/EVP) example: 123e4567-e89b-12d3-a456-426614174000 pixName: type: string description: Nome exibido como recebedor do PIX (padrão "Pix" se vazio) example: Loja Exemplo async: type: boolean description: Enfileira o envio para processamento assíncrono delay: type: integer description: Atraso em milissegundos antes do envio (exibe "digitando..." no WhatsApp) readchat: type: boolean description: Marca o chat como lido após enviar a mensagem readmessages: type: boolean description: Marca mensagens recentes como lidas após o envio replyid: type: string description: ID da mensagem que será respondida mentions: type: string description: Lista de números mencionados separados por vírgula track_source: type: string description: "Origem de rastreamento (ex.: chatwoot, crm-interno)" track_id: type: string description: Identificador de rastreamento (aceita valores duplicados) required: - number - pixType - pixKey example: number: "5511999999999" pixType: EVP pixKey: 123e4567-e89b-12d3-a456-426614174000 pixName: Loja Exemplo responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: PIX vira mensagem textual com a chave informada x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /send/request-payment: post: tags: - Enviar Mensagem operationId: sendRequestPayment summary: Solicitar pagamento description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Envia uma cobrança legível em uma mensagem com referências HTTP(S) e declara que não é um pedido de pagamento nativo. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: number: type: string description: ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). example: "5511999999999" title: type: string description: Título que aparece no cabeçalho do fluxo example: Detalhes do pedido text: type: string description: Mensagem exibida no corpo do fluxo example: "Pedido #123 pronto para pagamento" footer: type: string description: Texto do rodapé da mensagem example: Loja Exemplo itemName: type: string description: Nome do item principal listado no fluxo example: Assinatura Plano Ouro invoiceNumber: type: string description: Identificador ou número da fatura example: PED-123 amount: description: Valor da cobrança em BRL. Aceita número JSON ou string decimal/BR estrita, como `199.90`, `199,90` e `R$ 1.234,50`. Notação científica, hexadecimal, binária e formatos ambíguos como `1.234` são rejeitados. O valor normalizado precisa resultar em pelo menos R$ 0,01. oneOf: - type: number format: double minimum: 0.01 maximum: 100000000 - type: string pattern: ^\s*(?:R\$\s*)?(?:\d+(?:[.,]\d{1,2})?|\d{1,3}(?:\.\d{3})+,\d{1,2})\s*$ example: 199.9 pixKey: type: string description: Chave PIX estático (CPF/CNPJ/telefone/email/EVP) example: 123e4567-e89b-12d3-a456-426614174000 pixType: type: string description: Tipo da chave PIX (`CPF`, `CNPJ`, `PHONE`, `EMAIL`, `EVP`). Padrão `EVP` example: EVP pixName: type: string description: Nome do recebedor exibido no fluxo (padrão usa o nome do perfil da instância) example: Loja Exemplo paymentLink: type: string format: uri description: URL HTTP(S) externa para checkout, com host e sem usuário ou senha embutidos example: https://pagamentos.exemplo.com/checkout/abc fileUrl: type: string format: uri description: URL HTTP(S) do documento, enviada como referência legível; não é anunciada como anexo nativo. example: https://cdn.exemplo.com/boleto-123.pdf fileName: type: string description: Metadado opcional de compatibilidade. O fallback textual não anexa o arquivo nem exibe `fileName`; ele preserva a referência completa de `fileUrl`. example: boleto-123.pdf boletoCode: type: string description: Linha digitável do boleto (habilita o método boleto automaticamente) example: 34191.79001 01043.510047 91020.150008 5 91070026000 replyid: type: string description: ID da mensagem que será respondida mentions: type: string description: Números mencionados separados por vírgula delay: type: integer description: Atraso em milissegundos antes do envio (exibe "digitando..." no WhatsApp) readchat: type: boolean description: Marca o chat como lido após enviar a mensagem readmessages: type: boolean description: Marca mensagens recentes como lidas após o envio async: type: boolean description: Enfileira o envio para processamento assíncrono track_source: type: string description: "Origem de rastreamento (ex.: chatwoot, crm-interno)" track_id: type: string description: Chave idempotente. Repetir a mesma chave com o mesmo payload reutiliza o envio original; conteúdo diferente retorna 409. required: - number - amount example: number: "5511999999999" amount: 199.9 text: "Pedido #123 pronto para pagamento" pixKey: 123e4567-e89b-12d3-a456-426614174000 pixType: EVP responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Envia uma cobrança legível em uma mensagem com referências HTTP(S) e declara que não é um pedido de pagamento nativo. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /send/status: post: tags: - Enviar Mensagem operationId: sendStatus summary: Enviar status (stories) description: Publica texto, imagem, vídeo ou áudio no Status do WhatsApp. Destinatários explícitos são validados em lote, JIDs LID são resolvidos quando o cache da sessão conhece o número e max_recipients limita a audiência. Sem recipients, usa os contatos sincronizados da instância. Cores 1 a 19 e as fontes documentadas são aplicadas pelo transporte. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: type: type: string enum: - text - image - video - audio - myaudio - ptt description: Tipo do status. example: text text: type: string description: Texto principal ou legenda. example: Novidades chegando! background_color: type: integer minimum: 1 maximum: 19 description: Índice da cor de fundo para status em texto. example: 7 font: type: integer enum: - 0 - 1 - 2 - 6 - 7 - 8 - 9 - 10 description: Fonte aceita para `type=text`. example: 1 file: type: string description: URL ou base64 do arquivo de mídia. example: https://example.com/video.mp4 thumbnail: type: string description: Campo aceito no payload; o backend gera thumbnail automaticamente quando necessário. example: https://example.com/thumb.jpg mimetype: type: string description: MIME type do arquivo, quando necessário. example: video/mp4 recipients: type: array description: Lista explícita de destinatários. Aceita números em formato WhatsApp, JIDs `@s.whatsapp.net` e JIDs `@lid`. O backend valida item a item, descarta os inválidos com motivo no `debug` e envia para o subconjunto válido restante. Entradas `@lid` dependem de resolução local para PN. items: type: string example: - "5511999999999" - 5511888888888@s.whatsapp.net max_recipients: type: integer minimum: 0 description: Limita o envio a um subconjunto determinístico da audiência. Quando `recipients` for informado, funciona como cap de segurança sobre a lista explícita já validada. example: 100 required: - type responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Ação executada na conexão real do número. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /send/text: post: tags: - Enviar Mensagem operationId: sendText summary: Enviar mensagem de texto description: Envia texto pela fila persistente. Na integração atual, texto simples e rastreamento são preservados; preview, resposta, menções, encaminhamento, delay por requisição e marcação de leitura retornam 422 antes da fila. Consulte x-relya-runtime-options. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object required: - number - text properties: number: type: string description: Número com DDI, somente dígitos example: "5511999999999" text: type: string example: Olá! Esta é uma mensagem de teste. track_id: type: string description: Chave de idempotência da ação example: pedido-123 example: number: "5511999999999" text: Olá! Como posso ajudar? responses: "200": description: "Replay idempotente: o envio original já concluído foi reutilizado sem nova chamada ao transporte" content: application/json: schema: $ref: "#/components/schemas/Message" "202": description: Mensagem aceita e adicionada à fila persistente content: application/json: schema: $ref: "#/components/schemas/Message" "400": description: Destinatário, formato ou conteúdo inválido "401": description: Credencial ausente ou inválida "402": description: Assinatura ou período de teste sem acesso "409": description: Instância desconectada ou chave de idempotência em conflito "422": description: Opção não suportada pela integração foi recusada antes da fila; nada foi enviado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido "502": description: O resultado remoto pode ser indeterminado. Não crie outra chave; consulte a mesma mensagem ou repita a mesma chave e o mesmo corpo. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Ação executada na conexão real do número. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. x-relya-runtime-options: preserved: - number - track_id - track_source - async=true - text - linkPreview=false rejectedWhenRequested: - delay - readchat=true - readmessages=true - async=false - replyid - mentions - forward=true - linkPreview=true - linkPreviewTitle - linkPreviewDescription - linkPreviewImage - linkPreviewLarge=true - placeholders note: Texto simples e rastreamento sao preservados. Preview, resposta, mencoes, encaminhamento e marcacao de leitura falham antes da fila. /chat/labels: post: tags: - Etiquetas operationId: setChatLabels summary: Gerencia labels de um chat description: "Atualiza as labels associadas a um chat específico. Este endpoint oferece três modos de operação: 1. **Definir todas as labels** (labelids): Define o conjunto completo de labels para o chat, substituindo labels existentes 2. **Adicionar uma label** (add_labelid): Adiciona uma única label ao chat sem afetar as existentes 3. **Remover uma label** (remove_labelid): Remove uma única label do chat sem afetar as outras **Importante**: Use apenas um dos três parâmetros por requisição. Labels inexistentes serão rejeitadas. As labels devem ser fornecidas no formato id ou labelid encontradas na função get labels." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: number: type: string description: Número do chat ou grupo example: "5511999999999" labelids: type: array items: type: string description: Lista de IDs das labels a serem aplicadas ao chat (define todas as labels) example: - "10" - "20" add_labelid: type: string description: ID da label a ser adicionada ao chat example: "10" remove_labelid: type: string description: ID da label a ser removida do chat example: "20" required: - number oneOf: - required: - labelids - required: - add_labelid - required: - remove_labelid example: number: "5511999999999" labelids: - "10" - "20" - "30" responses: "200": description: Labels atualizadas com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação editions: type: array items: type: string description: Lista de operações realizadas (apenas para operação labelids) example: response: Labels updated successfully editions: - Added label 10 to chat - Added label 20 to chat - Removed label 5 from chat "400": description: Erro na requisição content: application/json: schema: type: object properties: error: type: string example: "Use only one operation: labelids, add_labelid, or remove_labelid" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Chat não encontrado content: application/json: schema: type: object properties: error: type: string example: Chat not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /label/edit: post: tags: - Etiquetas operationId: editLabel summary: Criar, editar ou deletar etiqueta description: 'Cria, edita ou deleta uma etiqueta da instância. Regras de uso: - Para editar uma etiqueta existente, envie o `labelid` real da etiqueta. - Para criar uma nova etiqueta, envie `labelid: "new"` com `delete: false`. O backend irá gerar o próximo `labelid` numérico disponível para a instância. - Para deletar uma etiqueta existente, envie o `labelid` real com `delete: true`. Observações: - A resposta de sucesso retorna `"Label created"` para criação e `"Label edited"` para edição. - Para descobrir o `labelid` final criado, consulte `GET /labels` após a operação ou consuma o webhook/evento de labels da instância.' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: labelid: type: string description: > ID da etiqueta. Use o ID real para editar/deletar uma etiqueta existente. Use `"new"` para criar uma nova etiqueta quando `delete` for `false`. example: "25" name: type: string description: Novo nome da etiqueta example: responder editado color: type: integer description: Código numérico da nova cor (0-19) minimum: 0 maximum: 19 example: 2 delete: type: boolean description: Indica se a etiqueta deve ser deletada example: false required: - labelid example: labelid: new name: responder editado color: 2 delete: false responses: "200": description: Operação concluída com sucesso content: application/json: schema: type: object properties: response: type: string enum: - Label created - Label edited example: Label edited example: response: Label created "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou sessão inválida content: application/json: schema: type: object properties: error: type: string example: error editing label x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /labels: get: tags: - Etiquetas operationId: listLabels summary: Buscar todas as etiquetas description: Retorna a lista completa de etiquetas da instância. security: - InstanceToken: [] parameters: [] responses: "200": description: Lista de etiquetas retornada com sucesso content: application/json: schema: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to fetch labels from database x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /labels/refresh: post: tags: - Etiquetas operationId: refreshLabels summary: Iniciar recarga de etiquetas do WhatsApp description: "Inicia uma nova leitura das etiquetas no WhatsApp em background. A resposta confirma apenas que a recarga foi iniciada ou que já existe uma recarga em andamento. Para obter a lista atualizada, consulte `GET /labels` depois. Efeitos no backend: - a recarga também processa associações de etiquetas sincronizadas do WhatsApp - chats existentes podem ter o campo `wa_label` atualizado com as etiquetas corretas - quando uma associação de etiqueta muda após a sincronização do histórico, o webhook `chat_labels` pode ser enviado com os dados completos do chat Uso recomendado: - tente primeiro com `force=false` - se isso não trouxer as etiquetas corretamente, tente `force=true` - use `force=true` apenas como tentativa de correção, porque ele faz uma recarga mais pesada" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: force: type: boolean default: false description: > Tente primeiro com `false`. Use `true` apenas quando a recarga padrão não funcionar bem, pois esse modo faz uma nova leitura mais completa das etiquetas. example: false responses: "202": description: Recarga de etiquetas aceita para processamento em background content: application/json: schema: type: object required: - success - status - message - force - fullSync properties: success: type: boolean example: true status: type: string enum: - started - in_progress example: started message: type: string example: Label refresh started. Use GET /labels to fetch the refreshed list. force: type: boolean example: false fullSync: type: boolean example: false "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A recarga não pôde ser executada porque a sincronização do histórico ainda está em andamento content: application/json: schema: type: object properties: error: type: string example: history sync still in progress, try again in a moment "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: failed to reload labels from WhatsApp x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /community/create: post: tags: - Grupos e Comunidades operationId: createCommunity summary: Criar uma comunidade description: Cria uma nova comunidade no WhatsApp. Uma comunidade é uma estrutura que permite agrupar múltiplos grupos relacionados sob uma única administração. A comunidade criada inicialmente terá apenas o grupo principal (announcements), e grupos adicionais podem ser vinculados posteriormente usando o endpoint `/community/updategroups`. **Observações importantes:** - O número que cria a comunidade torna-se automaticamente o administrador - A comunidade terá um grupo principal de anúncios criado automaticamente security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Nome da comunidade minLength: 1 maxLength: 25 example: Comunidade do Bairro required: - name responses: "200": description: Comunidade criada com sucesso content: application/json: schema: type: object properties: group: type: object description: Estrutura descrita pelo exemplo desta operação. failed: type: array description: Lista de JIDs que falharam ao serem adicionados items: type: string format: jid "400": description: Erro na requisição content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Token inválido ou não fornecido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Sem permissão para criar comunidades "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de criação de comunidades atingido "500": description: Erro interno do servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /community/editgroups: post: tags: - Grupos e Comunidades operationId: editCommunityGroups summary: Gerenciar grupos em uma comunidade description: "Adiciona ou remove grupos de uma comunidade do WhatsApp. Apenas administradores da comunidade podem executar estas operações. O lote aceita no máximo 10 grupos e usa uma única chave de idempotência, mas a aplicação no WhatsApp é sequencial e não atômica. Em uma falha parcial, a resposta preserva os grupos concluídos e o grupo em que a execução parou. ## Funcionalidades - Adicionar múltiplos grupos simultaneamente a uma comunidade - Remover grupos de uma comunidade existente - Suporta operações em lote ## Limitações - Os grupos devem existir previamente - A comunidade deve existir e o usuário deve ser administrador - Grupos já vinculados não podem ser adicionados novamente - Grupos não vinculados não podem ser removidos ## Ações Disponíveis - `add`: Adiciona os grupos especificados à comunidade - `remove`: Remove os grupos especificados da comunidade" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - community - action - groupjids properties: community: type: string description: JID (identificador único) da comunidade example: 120363153742561022@g.us action: type: string enum: - add - remove description: | Tipo de operação a ser realizada: * add - Adiciona grupos à comunidade * remove - Remove grupos da comunidade groupjids: type: array items: type: string pattern: ^[0-9]+@g.us$ minItems: 1 maxItems: 10 description: Lista de JIDs dos grupos para adicionar ou remover example: - 120363324255083289@g.us - 120363308883996631@g.us responses: "200": description: Operação realizada com sucesso content: application/json: schema: type: object properties: message: type: string example: community updated success: type: array items: type: string description: Lista de JIDs dos grupos processados com sucesso failed: type: array items: type: string description: Lista de JIDs dos grupos que falharam no processamento "400": description: Requisição inválida "401": description: Não autorizado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador da comunidade "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/create: post: tags: - Grupos e Comunidades operationId: createGroup summary: Criar um novo grupo description: "Cria um novo grupo no WhatsApp com participantes iniciais. ### Detalhes - Requer autenticação via token da instância - Os números devem ser fornecidos sem formatação (apenas dígitos) ### Limitações - Mínimo de 1 participante além do criador ### Comportamento - Retorna informações detalhadas do grupo criado - Inclui lista de participantes adicionados com sucesso/falha" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Nome do grupo minLength: 1 maxLength: 25 example: Relya grupo participants: type: array description: Lista de números de telefone dos participantes iniciais items: type: string description: Número de telefone sem formatação minItems: 1 maxItems: 50 example: - "5521987905995" - "5511912345678" required: - name - participants example: name: Meu Novo Grupo participants: - "5521987905995" responses: "200": description: Grupo criado com sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: Erro de payload inválido content: application/json: schema: type: object properties: error: type: string example: Could not parse phone "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to create group x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/ephemeral: post: tags: - Grupos e Comunidades operationId: updateGroupEphemeral summary: Configurar mensagens temporárias em grupo description: "Define o temporizador de mensagens temporárias (disappearing messages) de um grupo. Valores aceitos para a duração: - `0` ou `off` para desativar - `1d` - `7d` - `90d` Observações: - este endpoint é apenas para grupos - requer privilégios de administrador do grupo - se o identificador informado não for de grupo, a API retorna erro orientando usar `/chat/ephemeral` - após sucesso, a resposta devolve o chat atualizado e o snapshot mais recente do grupo no cache local" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - groupjid - duration properties: groupjid: type: string description: JID do grupo no formato xxxxx@g.us example: 120363339858396166@g.us duration: oneOf: - type: string - type: integer description: Duração desejada para mensagens temporárias example: 1d example: groupjid: 120363339858396166@g.us duration: 1d responses: "200": description: Temporizador atualizado com sucesso content: application/json: schema: type: object properties: response: type: string example: Ephemeral timer updated successfully chat: type: object description: Estrutura descrita pelo exemplo desta operação. ephemeral: type: object properties: enabled: type: boolean example: true seconds: type: integer format: int64 example: 86400 label: type: string example: 1d group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisou ser recarregado no cache local example: false example: response: Ephemeral timer updated successfully chat: wa_chatid: 120363339858396166@g.us wa_ephemeralExpiration: 86400 wa_isGroup: true ephemeral: enabled: true seconds: 86400 label: 1d group: JID: 120363339858396166@g.us IsEphemeral: true DisappearingTimer: 86400 needs_refresh: false "400": description: Payload inválido, grupo inválido ou duração não suportada content: application/json: schema: type: object properties: error: type: string example: "invalid duration. Allowed values: 0, off, 1d, 7d, 90d" "401": description: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo content: application/json: schema: type: object properties: error: type: string example: user is not an admin of this group "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar o temporizador content: application/json: schema: type: object properties: error: type: string example: "Error updating chat ephemeral timer: connection closed" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/info: post: tags: - Grupos e Comunidades operationId: getGroupInfo summary: Obter informações detalhadas de um grupo description: "Recupera informações completas de um grupo do WhatsApp, incluindo: - Detalhes do grupo - Participantes - Configurações - Link de convite (opcional)" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo (JID) example: 120363153742561022@g.us getInviteLink: type: boolean description: Recuperar link de convite do grupo default: false example: true getRequestsParticipants: type: boolean description: Recuperar lista de solicitações pendentes de participação default: false example: false force: type: boolean description: Forçar atualização, ignorando cache default: false example: false required: - groupjid responses: "200": description: Informações do grupo obtidas com sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. example: JID: 120363153742561022@g.us Name: Relya Community Participants: - JID: 5521987654321@s.whatsapp.net IsAdmin: true IsLocked: false IsAnnounce: false "400": description: Código de convite inválido ou mal formatado content: application/json: schema: type: object properties: error: type: string example: Invalid invite code "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Grupo não encontrado ou link de convite expirado content: application/json: schema: type: object properties: error: type: string example: Group invite link is invalid or has expired "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve group information x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/inviteInfo: post: tags: - Grupos e Comunidades operationId: getGroupInviteInfo summary: Obter informações de um grupo pelo código de convite description: "Retorna informações detalhadas de um grupo usando um código de convite ou URL completo do WhatsApp. Esta rota permite: - Recuperar informações básicas sobre um grupo antes de entrar - Validar um link de convite - Obter detalhes como nome do grupo, número de participantes e restrições de entrada" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: invitecode: type: string description: | Código de convite ou URL completo do grupo. Pode ser um código curto ou a URL completa do WhatsApp. examples: - IYnl5Zg9bUcJD32rJrDzO7 - https://chat.whatsapp.com/IYnl5Zg9bUcJD32rJrDzO7 required: - invitecode responses: "200": description: Informações do grupo obtidas com sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. example: JID: 120363153742561022@g.us Name: Relya Community Participants: - JID: 5521987654321@s.whatsapp.net IsAdmin: true IsLocked: false IsAnnounce: false "400": description: Código de convite inválido ou mal formatado content: application/json: schema: type: object properties: error: type: string example: Invalid invite code "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Grupo não encontrado ou link de convite expirado content: application/json: schema: type: object properties: error: type: string example: Group invite link is invalid or has expired "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve group information x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/join: post: tags: - Grupos e Comunidades operationId: joinGroup summary: Entrar em um grupo usando código de convite description: "Permite entrar em um grupo do WhatsApp usando um código de convite ou URL completo. Características: - Suporta código de convite ou URL completo - Valida o código antes de tentar entrar no grupo - Retorna informações básicas do grupo após entrada bem-sucedida - Trata possíveis erros como convite inválido ou expirado" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - invitecode properties: invitecode: type: string description: > Código de convite ou URL completo do grupo. Formatos aceitos: - Código completo: "IYnl5Zg9bUcJD32rJrDzO7" - URL completa: "https://chat.whatsapp.com/IYnl5Zg9bUcJD32rJrDzO7" example: https://chat.whatsapp.com/IYnl5Zg9bUcJD32rJrDzO7 minLength: 10 maxLength: 50 responses: "200": description: Entrada no grupo realizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group join successful group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: Código de convite inválido content: application/json: schema: type: object properties: error: type: string example: Invalid invite code "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário já está no grupo ou não tem permissão para entrar content: application/json: schema: type: object properties: error: type: string example: Unable to join group "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Error processing group invite x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/leave: post: tags: - Grupos e Comunidades operationId: leaveGroup summary: Sair de um grupo description: "Remove o usuário atual de um grupo específico do WhatsApp. Requisitos: - O usuário deve estar conectado a uma instância válida - O usuário deve ser um membro do grupo Comportamentos: - Se o usuário for o último administrador, o grupo será dissolvido - Se o usuário for um membro comum, será removido do grupo" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: | Identificador único do grupo (JID) - Formato: número@g.us - Exemplo válido: 120363324255083289@g.us example: 120363324255083289@g.us pattern: ^\d+@g\.us$ required: - groupjid responses: "200": description: Saída do grupo realizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group leave successful "400": description: Erro de payload inválido content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou falha na conexão content: application/json: schema: type: object properties: error: type: string example: error leaving group x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/list: get: tags: - Grupos e Comunidades operationId: listGroups summary: Listar todos os grupos description: "Retorna uma lista com todos os grupos disponíveis para a conta do WhatsApp atualmente conectada. Recursos adicionais: - Suporta atualização forçada do cache de grupos - Recupera informações detalhadas de grupos conectados" security: - InstanceToken: [] parameters: - name: force in: query schema: type: boolean default: false description: > Se definido como `true`, força a atualização do cache de grupos. Útil para garantir que as informações mais recentes sejam recuperadas. Comportamentos: - `false` (padrão): Usa informações em cache - `true`: Busca dados atualizados diretamente do WhatsApp required: false - name: noparticipants in: query schema: type: boolean default: false description: > Se definido como `true`, retorna a lista de grupos sem incluir os participantes. Útil para otimizar a resposta quando não há necessidade dos dados dos participantes. Comportamentos: - `false` (padrão): Retorna grupos com lista completa de participantes - `true`: Retorna grupos sem incluir os participantes required: false responses: "200": description: Lista de grupos recuperada com sucesso content: application/json: schema: type: object properties: groups: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. description: Lista detalhada de grupos "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar grupos content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. post: tags: - Grupos e Comunidades operationId: refreshGroups summary: Listar todos os grupos com filtros e paginacao description: Retorna uma lista com todos os grupos disponiveis para a conta do WhatsApp atualmente conectada, com opcoes de filtros e paginacao via corpo (POST). A rota GET continua para quem prefere a listagem direta sem paginacao. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: limit: type: integer description: Quantidade maxima de resultados por pagina (padrao 50, maximo 1000) default: 50 offset: type: integer description: Deslocamento base zero default: 0 search: type: string description: Texto para filtrar grupos por nome/JID force: type: boolean default: false description: > Se definido como `true`, forca a atualizacao do cache de grupos. Util para garantir que as informacoes mais recentes sejam recuperadas. noParticipants: type: boolean default: false description: > Se definido como `true`, retorna a lista de grupos sem incluir os participantes. Util para otimizar a resposta quando nao ha necessidade dos dados dos participantes. responses: "200": description: Lista de grupos recuperada com sucesso content: application/json: schema: type: object properties: groups: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. description: Lista detalhada de grupos pagination: type: object properties: totalRecords: type: integer description: Total de grupos encontrados limit: type: integer description: Limite aplicado na pagina atual offset: type: integer description: Offset efetivamente usado na pagina atual "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar grupos content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/resetInviteCode: post: tags: - Grupos e Comunidades operationId: resetGroupInviteCode summary: Resetar código de convite do grupo description: "Gera um novo código de convite para o grupo, invalidando o código de convite anterior. Somente administradores do grupo podem realizar esta ação. Principais características: - Invalida o link de convite antigo - Cria um novo link único - Retorna as informações atualizadas do grupo" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo (JID) example: 120363308883996631@g.us required: - groupjid responses: "200": description: Código de convite resetado com sucesso content: application/json: schema: type: object properties: InviteLink: type: string description: Novo link de convite gerado example: https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: Erro de validação content: application/json: schema: type: object properties: error: type: string example: Could not parse Group JID "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário sem permissão content: application/json: schema: type: object properties: error: type: string example: User is not an admin of this group "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to reset group invite link x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateAnnounce: post: tags: - Grupos e Comunidades operationId: updateGroupAnnounce summary: Configurar permissões de envio de mensagens no grupo description: "Define as permissões de envio de mensagens no grupo, permitindo restringir o envio apenas para administradores. Quando ativado (announce=true): - Apenas administradores podem enviar mensagens - Outros participantes podem apenas ler - Útil para anúncios importantes ou controle de spam Quando desativado (announce=false): - Todos os participantes podem enviar mensagens - Configuração padrão para grupos normais Requer que o usuário seja administrador do grupo para fazer alterações." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo no formato xxxx@g.us example: 120363339858396166@g.us announce: type: boolean description: Controla quem pode enviar mensagens no grupo example: true required: - groupjid - announce responses: "200": description: Configuração atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group announce enabled successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de autenticação ausente ou inválido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "404": description: Grupo não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou falha na API do WhatsApp x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateDescription: post: tags: - Grupos e Comunidades operationId: updateGroupDescription summary: Atualizar descrição do grupo description: Altera a descrição (tópico) do grupo WhatsApp especificado. Requer que o usuário seja administrador do grupo. A descrição aparece na tela de informações do grupo e pode ser visualizada por todos os participantes. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - groupjid - description properties: groupjid: type: string description: JID (ID) do grupo no formato xxxxx@g.us example: 120363339858396166@g.us pattern: ^[0-9]+@g\.us$ description: type: string description: Nova descrição/tópico do grupo example: Grupo oficial de suporte maxLength: 512 responses: "200": description: Descrição atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group description updated successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "404": description: Grupo não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "413": description: Descrição excede o limite máximo permitido "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateImage: post: tags: - Grupos e Comunidades operationId: updateGroupImage summary: Atualizar imagem do grupo description: 'Altera a imagem do grupo especificado. A imagem pode ser enviada como URL ou como string base64. Requisitos da imagem: - Formato: JPEG - Resolução máxima: 640x640 pixels - Imagens maiores ou diferente de JPEG não são aceitas pelo WhatsApp Para remover a imagem atual, envie "remove" ou "delete" no campo image.' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: JID do grupo example: 120363308883996631@g.us image: type: string description: > URL da imagem, string base64 ou "remove"/"delete" para remover. A imagem deve estar em formato JPEG e ter resolução máxima de 640x640. examples: - https://example.com/image.jpg - data:image/jpeg;base64,/9j/4AAQSkZJRg... - remove required: - groupjid - image responses: "200": description: Imagem atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group image updated successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: Erro nos parâmetros da requisição "401": description: Token inválido ou expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "413": description: Imagem muito grande "415": description: Formato de imagem inválido "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateJoinApproval: post: tags: - Grupos e Comunidades operationId: updateGroupJoinApproval summary: Configurar aprovação para entrada no grupo description: "Define se novos participantes precisam ser aprovados antes de entrar no grupo. No objeto retornado em `group` e também em `/group/info`, esse estado aparece no campo `IsJoinApprovalRequired`. Quando ativado (`IsJoinApprovalRequired=true`): - Novas entradas passam por aprovação de administrador - Solicitações pendentes podem ser listadas em `/group/info` Quando desativado (`IsJoinApprovalRequired=false`): - Entradas por link/convite não exigem aprovação adicional Requer que o usuário seja administrador do grupo." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo no formato xxxx@g.us example: 120363339858396166@g.us IsJoinApprovalRequired: type: boolean description: Define se a entrada no grupo exige aprovação; reflete no campo `IsJoinApprovalRequired` example: true required: - groupjid - IsJoinApprovalRequired responses: "200": description: Configuração atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group join approval enabled successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false example: response: Group join approval enabled successfully group: JID: 120363339858396166@g.us IsJoinApprovalRequired: true needs_refresh: false "400": description: Payload inválido ou campo IsJoinApprovalRequired ausente/inválido content: application/json: schema: type: object properties: error: type: string example: IsJoinApprovalRequired is required "401": description: Token de autenticação ausente ou inválido "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "404": description: Grupo não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou falha na API do WhatsApp x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateLocked: post: tags: - Grupos e Comunidades operationId: updateGroupLocked summary: Configurar permissão de edição do grupo description: "Define se apenas administradores podem editar as informações do grupo. Quando bloqueado (locked=true), apenas administradores podem alterar nome, descrição, imagem e outras configurações do grupo. Quando desbloqueado (locked=false), qualquer participante pode editar as informações. Importante: - Requer que o usuário seja administrador do grupo - Afeta edições de nome, descrição, imagem e outras informações do grupo - Não controla permissões de adição de membros" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo (JID) example: 120363308883996631@g.us locked: type: boolean description: | Define permissões de edição: - true = apenas admins podem editar infos do grupo - false = qualquer participante pode editar infos do grupo example: true required: - groupjid - locked responses: "200": description: Operação realizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group lock status changed successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "404": description: Grupo não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateMemberAddMode: post: tags: - Grupos e Comunidades operationId: updateGroupMemberAddMode summary: Configurar quem pode adicionar novos membros ao grupo description: "Define quem tem permissão para adicionar novos participantes diretamente ao grupo. No objeto retornado em `group` e também em `/group/info`, esse estado aparece no campo `MemberAddMode`. Valores aceitos em `MemberAddMode`: - `admin_add`: apenas administradores podem adicionar membros - `all_member_add`: qualquer participante pode adicionar membros Requer que o usuário seja administrador do grupo." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: Identificador único do grupo no formato xxxx@g.us example: 120363339858396166@g.us MemberAddMode: type: string enum: - admin_add - all_member_add description: Define quem pode adicionar novos membros ao grupo; reflete no campo `MemberAddMode` example: admin_add required: - groupjid - MemberAddMode responses: "200": description: Configuração atualizada com sucesso content: application/json: schema: type: object properties: response: type: string example: Group member add mode set to admin_add successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false example: response: Group member add mode set to admin_add successfully group: JID: 120363339858396166@g.us MemberAddMode: admin_add needs_refresh: false "400": description: Valor inválido para MemberAddMode "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "404": description: Grupo não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ou falha na API do WhatsApp x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateName: post: tags: - Grupos e Comunidades operationId: updateGroupName summary: Atualizar nome do grupo description: Altera o nome de um grupo do WhatsApp. Apenas administradores do grupo podem realizar esta operação. O nome do grupo deve seguir as diretrizes do WhatsApp e ter entre 1 e 25 caracteres. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - groupjid - name properties: groupjid: type: string description: Identificador único do grupo no formato JID example: 120363339858396166@g.us name: type: string description: Novo nome para o grupo example: Grupo de Suporte minLength: 1 maxLength: 25 responses: "200": description: Nome do grupo atualizado com sucesso content: application/json: schema: type: object properties: response: type: string example: Group name updated successfully group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: Erro de validação na requisição content: application/json: schema: type: object properties: error: type: string example: Invalid payload "401": description: Token de autenticação ausente ou inválido content: application/json: schema: type: object properties: error: type: string example: Unauthorized "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo content: application/json: schema: type: object properties: error: type: string example: User is not an admin of this group "404": description: Grupo não encontrado content: application/json: schema: type: object properties: error: type: string example: Group not found "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to update group name x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /group/updateParticipants: post: tags: - Grupos e Comunidades operationId: updateGroupParticipants summary: Gerenciar participantes do grupo description: "Gerencia participantes do grupo através de diferentes ações: - Adicionar ou remover participantes - Promover ou rebaixar administradores - Aprovar ou rejeitar solicitações pendentes Requer que o usuário seja administrador do grupo para executar as ações." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupjid: type: string description: JID (identificador) do grupo example: 120363308883996631@g.us action: type: string description: | Ação a ser executada: - add: Adicionar participantes ao grupo - remove: Remover participantes do grupo - promote: Promover participantes a administradores - demote: Remover privilégios de administrador - approve: Aprovar solicitações pendentes de entrada - reject: Rejeitar solicitações pendentes de entrada enum: - add - remove - promote - demote - approve - reject example: promote participants: type: array items: type: string description: > Lista de números de telefone ou JIDs dos participantes. Para números de telefone, use formato internacional sem '+' ou espaços. example: - "5521987654321" - "5511999887766" required: - groupjid - action - participants responses: "200": description: Sucesso na operação content: application/json: schema: type: object properties: groupUpdated: type: array items: type: object properties: JID: type: string description: JID do participante Error: type: integer description: Código de erro (0 para sucesso) description: Status da operação para cada participante group: type: object description: Estrutura descrita pelo exemplo desta operação. needs_refresh: type: boolean description: Indica se o grupo precisa ser atualizado no cache local example: false "400": description: Erro nos parâmetros da requisição "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Usuário não é administrador do grupo "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada ao driver real de grupos e comunidades. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance: delete: tags: - Instância operationId: deleteInstance summary: Deletar instância description: Remove a instância do sistema. security: - InstanceToken: [] parameters: [] responses: "200": description: Instância deletada com sucesso content: application/json: schema: type: object properties: response: type: string example: Instance Deleted info: type: string example: O dispositivo foi desconectado com sucesso e a instância foi removida do banco de dados. "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Falha na autenticação content: application/json: schema: type: object properties: error: type: string example: Não autorizado - Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Instância não encontrada content: application/json: schema: type: object properties: error: type: string example: Instância não encontrada "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Falha ao deletar instância x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/connect: post: tags: - Instância operationId: connectInstance summary: Conectar instância ao WhatsApp description: 'Inicia o processo de conexão de uma instância ao WhatsApp. Este endpoint: 1. Requer o token de autenticação da instância 2. Recebe o número de telefone associado à conta WhatsApp 3. Gera um QR code caso não passe o campo `phone` 4. Ou Gera código de pareamento se passar o o campo `phone` 5. Atualiza o status da instância para "connecting" O processo de conexão permanece pendente até que: - O QR code seja escaneado no WhatsApp do celular, ou - O código de pareamento seja usado no WhatsApp - Timeout de 2 minutos para QRCode seja atingido ou 5 minutos para o código de pareamento Use o endpoint /instance/status para monitorar o progresso da conexão. Estados possíveis da instância: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado - `hibernated`: Sessão pausada, com credenciais preservadas para reconexão Sincronização e armazenamento de mensagens: - Todas as mensagens recebidas da Meta durante a sincronização da conexão (leitura do QR code) são enviadas no evento `history` do webhook. - As mensagens dos últimos 7 dias são armazenadas no banco de dados e ficam acessíveis pelos endpoints: `POST /message/find` e `POST /chat/find`. - Depois que a instância conecta, todas as mensagens enviadas ou recebidas são armazenadas no banco de dados. - Mensagens mais antigas do que 7 dias são excluídas durante a madrugada. Proxy regional: - No momento, o proxy regional público está disponível para Brasil (`br`). - Use `GET /proxy-managed/cities?country=br` para listar cidades brasileiras. - Envie `proxy_managed_city` com o `value` retornado pela cidade. - Quando a cidade retornar `state`, envie também `proxy_managed_state` com esse valor. - O backend valida a combinação de país, estado e cidade antes de salvar.' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: phone: type: string description: "Número de telefone no formato internacional (ex: 5511999999999). Se informado, gera código de pareamento. Se omitido, gera QR code." example: "5511999999999" pattern: ^\d{10,15}$ browser: type: string description: Browser usado no ciclo de autenticação/conexão. `auto` preserva um perfil válido já salvo ou escolhe Safari, Firefox ou Edge para novas conexões. enum: - auto - safari - firefox - edge - chrome default: auto example: auto systemName: type: string description: Sistema/nome exibido no celular em aparelhos conectados. Ajuda a identificar a instância no WhatsApp; para maior estabilidade, recomendamos deixar em branco e usar o valor padrão do navegador escolhido. example: Minha Empresa proxy_managed_country: type: string description: País desejado para o proxy regional, em ISO alpha-2 minúsculo. No momento, use `br`. example: br pattern: ^[a-z]{2}$ proxy_managed_state: type: string description: Estado/subdivisão da cidade escolhida. Quando o país/cidade exigir desambiguação, use o campo `state` retornado por `GET /proxy-managed/cities?country=br`. example: sp proxy_managed_city: type: string description: Cidade escolhida para o proxy regional. Use sempre o campo `value` retornado por `GET /proxy-managed/cities`. example: campinas example: browser: auto systemName: Minha Empresa proxy_managed_country: br proxy_managed_state: sp proxy_managed_city: campinas responses: "200": description: Sucesso content: application/json: schema: type: object properties: connected: type: boolean description: Estado atual da conexão example: false loggedIn: type: boolean description: Estado do login example: false jid: type: - object - "null" description: ID do WhatsApp (quando logado) example: null instance: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido/expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Instância não encontrada "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de conexões simultâneas atingido "500": description: Erro interno "503": description: Capacidade de conexão temporariamente indisponível x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/disconnect: post: tags: - Instância operationId: disconnectInstance summary: Desconectar instância description: "Desconecta a conta do WhatsApp atualmente conectada, encerrando a sessão atual. Esta operação: - Encerra a conexão ativa - Requer novo QR code para reconectar Diferenças entre desconectar e hibernar: - Desconectar: Encerra completamente a sessão, exigindo novo login - Hibernar: Mantém a sessão ativa, apenas pausa a conexão Use este endpoint para: 1. Encerrar completamente uma sessão 2. Forçar uma nova autenticação 3. Limpar credenciais da sessão atual 4. Reiniciar o processo de conexão Estados possíveis após desconectar: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de reconexão (após usar /instance/connect)" security: - InstanceToken: [] parameters: [] responses: "200": description: Sucesso content: application/json: schema: type: object properties: instance: type: object description: Estrutura descrita pelo exemplo desta operação. response: type: string example: Disconnected info: type: string example: The device has been successfully disconnected from WhatsApp. A new QR code will be required for the next connection. "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido/expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Instância não encontrada "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/presence: post: tags: - Instância operationId: updateInstancePresence summary: Atualizar status de presença da instância description: 'Atualiza o status de presença global da conta do WhatsApp atualmente conectada. Este endpoint permite: 1. Definir se a conta aparece como disponível ("online") ou indisponível 2. Controlar o status de presença para todos os contatos 3. Salvar o estado atual da presença para a conta conectada Tipos de presença suportados: - available: Marca a conta como disponível/online - unavailable: Marca a conta como indisponível/offline **Atenção**: - O status de presença pode ser temporariamente alterado para "available" (online) em algumas situações internas da API, e com isso o visto por último também pode ser atualizado. - Caso isso for um problema, considere alterar suas configurações de privacidade no WhatsApp para não mostrar o visto por último e/ou quem pode ver seu status "online". **⚠️ Importante - Limitação do Presence "unavailable"**: - **Quando a API é o único dispositivo ativo**: Confirmações de entrega/leitura (ticks cinzas/azuis) não são enviadas nem recebidas - **Impacto**: Eventos `message_update` com status de entrega podem não ser recebidos - **Solução**: Se precisar das confirmações, mantenha WhatsApp Web ou aplicativo móvel ativo ou use presence "available" Exemplo de requisição: ```json { "presence": "available" } ``` Exemplo de resposta: ```json { "response": "Presence updated successfully" } ``` Erros comuns: - 401: Token inválido ou expirado - 400: Valor de presença inválido - 500: Erro ao atualizar presença' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: presence: type: string description: Status de presença da conta atualmente conectada enum: - available - unavailable example: available required: - presence responses: "200": description: Presença atualizada com sucesso content: application/json: schema: type: object properties: response: type: string description: Mensagem de confirmação example: Presence updated successfully "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string description: Descrição do erro examples: - Invalid payload - Invalid presence value, use available or unavailable "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string description: Descrição do erro de autenticação example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string description: Descrição do erro interno example: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/privacy: get: tags: - Instância operationId: getInstancePrivacy summary: Buscar configurações de privacidade description: 'Busca as configurações de privacidade atuais da conta do WhatsApp atualmente conectada. **Importante - Diferença entre Status e Broadcast:** - **Status**: Refere-se ao recado personalizado que aparece embaixo do nome do usuário (ex: "Disponível", "Ocupado", texto personalizado) - **Broadcast**: Refere-se ao envio de "stories/reels" (fotos/vídeos temporários) **Limitação**: As configurações de privacidade do broadcast (stories/reels) não estão disponíveis para alteração via API. Retorna todas as configurações de privacidade como quem pode: - Adicionar aos grupos - Ver visto por último - Ver status (recado embaixo do nome) - Ver foto de perfil - Receber confirmação de leitura - Ver status online - Fazer chamadas' security: - InstanceToken: [] parameters: [] responses: "200": description: Configurações de privacidade obtidas com sucesso content: application/json: schema: type: object properties: groupadd: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode adicionar aos grupos. Valores - all, contacts, contact_blacklist, none example: contacts last: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver visto por último. Valores - all, contacts, contact_blacklist, none example: contacts status: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver status (recado embaixo do nome). Valores - all, contacts, contact_blacklist, none example: contacts profile: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver foto de perfil. Valores - all, contacts, contact_blacklist, none example: contacts readreceipts: type: string enum: - all - none description: Confirmação de leitura. Valores - all, none example: all online: type: string enum: - all - match_last_seen description: Quem pode ver status online. Valores - all, match_last_seen example: all calladd: type: string enum: - all - known description: Quem pode fazer chamadas. Valores - all, known example: all example: groupadd: contacts last: contacts status: contacts profile: contacts readreceipts: all online: all calladd: all "401": description: Token de autenticação inválido content: application/json: schema: type: object properties: error: type: string example: client not found "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. post: tags: - Instância operationId: setPrivacySetting summary: Alterar configurações de privacidade description: 'Altera uma ou múltiplas configurações de privacidade da conta do WhatsApp atualmente conectada de forma otimizada. **Importante - Diferença entre Status e Broadcast:** - **Status**: Refere-se ao recado personalizado que aparece embaixo do nome do usuário (ex: "Disponível", "Ocupado", texto personalizado) - **Broadcast**: Refere-se ao envio de "stories/reels" (fotos/vídeos temporários) **Limitação**: As configurações de privacidade do broadcast (stories/reels) não estão disponíveis para alteração via API. **Características:** - ✅ **Eficiência**: Altera apenas configurações que realmente mudaram - ✅ **Flexibilidade**: Pode alterar uma ou múltiplas configurações na mesma requisição - ✅ **Feedback completo**: Retorna todas as configurações atualizadas **Formato de entrada:** ```json { "groupadd": "contacts", "last": "none", "status": "contacts" } ``` **Tipos de privacidade disponíveis:** - `groupadd`: Quem pode adicionar aos grupos - `last`: Quem pode ver visto por último - `status`: Quem pode ver status (recado embaixo do nome) - `profile`: Quem pode ver foto de perfil - `readreceipts`: Confirmação de leitura - `online`: Quem pode ver status online - `calladd`: Quem pode fazer chamadas **Valores possíveis:** - `all`: Todos - `contacts`: Apenas contatos - `contact_blacklist`: Contatos exceto bloqueados - `none`: Ninguém - `match_last_seen`: Corresponder ao visto por último (apenas para online) - `known`: Números conhecidos (apenas para calladd)' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: groupadd: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode adicionar aos grupos. Valores - all, contacts, contact_blacklist, none last: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver visto por último. Valores - all, contacts, contact_blacklist, none status: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver status (recado embaixo do nome). Valores - all, contacts, contact_blacklist, none profile: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver foto de perfil. Valores - all, contacts, contact_blacklist, none readreceipts: type: string enum: - all - none description: Confirmação de leitura. Valores - all, none online: type: string enum: - all - match_last_seen description: Quem pode ver status online. Valores - all, match_last_seen calladd: type: string enum: - all - known description: Quem pode fazer chamadas. Valores - all, known minProperties: 1 additionalProperties: false example: groupadd: contacts responses: "200": description: Configuração de privacidade alterada com sucesso content: application/json: schema: type: object properties: groupadd: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode adicionar aos grupos. Valores - all, contacts, contact_blacklist, none last: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver visto por último. Valores - all, contacts, contact_blacklist, none status: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver status (recado embaixo do nome). Valores - all, contacts, contact_blacklist, none profile: type: string enum: - all - contacts - contact_blacklist - none description: Quem pode ver foto de perfil. Valores - all, contacts, contact_blacklist, none readreceipts: type: string enum: - all - none description: Confirmação de leitura. Valores - all, none online: type: string enum: - all - match_last_seen description: Quem pode ver status online. Valores - all, match_last_seen calladd: type: string enum: - all - known description: Quem pode fazer chamadas. Valores - all, known example: groupadd: contacts last: contacts status: contacts profile: contacts readreceipts: all online: all calladd: all "400": description: Dados de entrada inválidos content: application/json: schema: type: object properties: error: type: string example: error: 'No valid privacy settings found. Use format: {"groupadd": "contacts", "last": "none"}' "401": description: Token de autenticação inválido content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: error: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/reset: post: tags: - Instância operationId: resetInstance summary: Reiniciar runtime da instância description: "Solicita um reset controlado do runtime da instância atual. Este endpoint é útil quando a sessão ficou presa, o envio não está progredindo ou a instância precisa forçar uma tentativa de recuperação sem apagar o registro da instância. Comportamentos possíveis: - inicia um novo reset quando a instância está apta - informa que um reset já está em andamento - informa que existe cooldown ativo entre resets - retorna erro quando a sessão não pode ser recuperada ou quando a política de reconexão bloqueia a operação A resposta sempre informa: - `instanceId`: ID da instância autenticada - `resetting`: se há reset em andamento no momento - `queuedRecoveryAttempted`: se houve tentativa de recuperação da fila interna" security: - InstanceToken: [] parameters: [] responses: "200": description: Reset aceito, já em andamento ou em cooldown content: application/json: schema: type: object properties: response: type: string example: Instance reset started resetting: type: boolean example: true instanceId: type: string example: r183e2ef9597845 queuedRecoveryAttempted: type: boolean example: true example: response: Instance reset started resetting: true instanceId: r183e2ef9597845 queuedRecoveryAttempted: true "400": description: Payload JSON inválido content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Token inválido, ausente ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Reset bloqueado pela política de reconexão content: application/json: schema: type: object properties: error: type: string resetting: type: boolean example: false instanceId: type: string queuedRecoveryAttempted: type: boolean "409": description: Sessão atual não é reconectável por reset content: application/json: schema: type: object properties: error: type: string resetting: type: boolean example: false instanceId: type: string queuedRecoveryAttempted: type: boolean "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao solicitar o reset content: application/json: schema: type: object properties: error: type: string example: server not available resetting: type: boolean example: false instanceId: type: string queuedRecoveryAttempted: type: boolean x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/status: get: tags: - Instância operationId: getInstanceStatus summary: Verificar status da instância description: "Retorna o status atual de uma instância, incluindo: - Estado da conexão (disconnected, connecting, connected, hibernated) - QR code atualizado (se em processo de conexão) - Código de pareamento (se disponível) - Informações da última desconexão - Detalhes completos da instância Este endpoint é particularmente útil para: 1. Monitorar o progresso da conexão 2. Obter QR codes atualizados durante o processo de conexão 3. Verificar o estado atual da instância 4. Identificar problemas de conexão Estados possíveis: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão (aguardando QR code ou código de pareamento) - `connected`: Conectado e autenticado com sucesso - `hibernated`: Sessão pausada, com credenciais preservadas para reconexão" security: - InstanceToken: [] parameters: [] responses: "200": description: Sucesso content: application/json: schema: type: object properties: instance: type: object description: Estrutura descrita pelo exemplo desta operação. status: type: object properties: connected: type: boolean description: Indica se está conectado ao WhatsApp loggedIn: type: boolean description: Indica se está autenticado no WhatsApp jid: type: - object - "null" description: ID do WhatsApp quando conectado example: instance: id: r183e2ef9597845 name: minha-instancia status: connected profileName: Meu WhatsApp currentTime: 2024-01-25T12:00:00.000Z status: connected: true loggedIn: true jid: user: "5511999999999" agent: 0 device: 0 server: s.whatsapp.net "401": description: Token inválido/expirado content: application/json: schema: type: object properties: error: type: string example: instance info not found "404": description: Instância não encontrada "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/updateInstanceName: post: tags: - Instância operationId: updateInstanceName summary: Atualizar nome da instância description: Atualiza o nome de uma instância WhatsApp existente. O nome não precisa ser único. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Novo nome para a instância example: Minha Nova Instância 2024!@# required: - name responses: "200": description: Sucesso content: application/json: schema: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido/expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Instância não encontrada "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/wa_messages_limits: get: tags: - Instância operationId: getWAMessageLimits summary: Consultar limites atuais de novas conversas no WhatsApp description: "Consulta o estado atual de limitação do WhatsApp para a conta atualmente conectada. Este endpoint é útil para: - diagnosticar erros de envio com `provider_code: 463` - verificar se o WhatsApp indica que a conta atualmente conectada pode iniciar novas conversas - exibir informações de suporte antes de campanhas ou envios de alto volume A resposta consolida duas fontes internas do WhatsApp: - `new_chat_message_capping`: limite de mensagens para iniciar novas conversas - `reachout_timelock`: restrição temporária para iniciar novas conversas Observações: - este endpoint depende de sessão ativa e conectada - se o WhatsApp não retornar os dados esperados, a resposta pode marcar os blocos como indisponíveis via `available: false` e `lookup_error` - `message` descreve o estado atual da conta atualmente conectada - `provider_message` detalha o motivo reportado pelo WhatsApp quando houver restrição ativa" security: - InstanceToken: [] parameters: [] responses: "200": description: Diagnóstico atual dos limites de novas conversas da conta atualmente conectada content: application/json: schema: type: object properties: provider: type: string example: whatsapp reachable: type: boolean description: Indica se ao menos uma das consultas ao WhatsApp retornou dados úteis example: true can_send_new_messages: type: - boolean - "null" description: > Indica se o WhatsApp sinaliza que a conta atualmente conectada pode iniciar novas conversas. Pode ser `null` quando não foi possível concluir o diagnóstico. example: false error_key: type: string description: Chave de erro derivada do diagnóstico atual example: WHATSAPP_REACHOUT_TIMELOCK message: type: string description: Mensagem técnica principal em inglês example: WhatsApp indicates that the currently connected account is under a temporary restriction for starting new conversations. This is not an internal API error. message_ptbr: type: string description: Mensagem principal traduzida para pt-BR example: O WhatsApp indica que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas. Isso não é um erro interno da API. provider_message: type: string description: Motivo detalhado reportado pelo WhatsApp em inglês example: WhatsApp reported that the currently connected account is under a temporary restriction for starting new conversations, usually related to sending volume or quality. provider_message_ptbr: type: string description: Motivo detalhado reportado pelo WhatsApp em pt-BR example: O WhatsApp informou que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas, normalmente relacionada a volume ou qualidade de envios. diagnostics_endpoint: type: string example: /instance/wa_messages_limits new_chat_message_capping: type: object properties: available: type: boolean example: true status: type: string example: CAPPED used_quota: type: integer example: 10 total_quota: type: integer example: 10 cycle_start: type: string format: date-time cycle_end: type: string format: date-time server_sent_at: type: string format: date-time ote_status: type: string example: EXHAUSTED mv_status: type: string example: ACTIVE lookup_error: type: string reachout_timelock: type: object properties: available: type: boolean example: true active: type: boolean example: true until: type: string format: date-time enforcement_type: type: string example: BIZ_QUALITY lookup_error: type: string example: provider: whatsapp reachable: true can_send_new_messages: false error_key: WHATSAPP_REACHOUT_TIMELOCK message: WhatsApp indicates that the currently connected account is under a temporary restriction for starting new conversations. This is not an internal API error. message_ptbr: O WhatsApp indica que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas. Isso não é um erro interno da API. provider_message: WhatsApp reported that the currently connected account is under a temporary restriction for starting new conversations, usually related to sending volume or quality. provider_message_ptbr: O WhatsApp informou que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas, normalmente relacionada a volume ou qualidade de envios. diagnostics_endpoint: /instance/wa_messages_limits new_chat_message_capping: available: true status: CAPPED used_quota: 10 total_quota: 10 cycle_end: 2026-04-30T23:59:59Z ote_status: EXHAUSTED mv_status: ACTIVE reachout_timelock: available: true active: true until: 2026-04-07T12:00:00Z enforcement_type: BIZ_QUALITY "401": description: Token inválido ou ausente content: application/json: schema: type: object properties: error: type: string example: invalid token "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar os limites content: application/json: schema: type: object properties: error: type: string example: No session x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /chatwoot/config: get: tags: - Integração Chatwoot operationId: getChatwootConfig summary: Obter configuração do Chatwoot description: "Retorna a configuração atual da integração com Chatwoot para a instância. ### Funcionalidades: - Retorna todas as configurações do Chatwoot incluindo credenciais - Mostra status de habilitação da integração - Útil para verificar configurações atuais antes de fazer alterações" security: - InstanceToken: [] parameters: [] responses: "200": description: Configuração obtida com sucesso content: application/json: schema: type: object properties: chatwoot_enabled: type: boolean description: Se a integração com Chatwoot está habilitada example: true chatwoot_url: type: string description: URL base da instância Chatwoot example: https://app.chatwoot.com chatwoot_account_id: type: integer format: int64 description: ID da conta no Chatwoot example: 1 chatwoot_inbox_id: type: integer format: int64 description: ID da inbox no Chatwoot example: 5 chatwoot_access_token: type: string description: Token de acesso da API Chatwoot example: pXXGHHHyJPYHYgWHJHYHgJjj chatwoot_ignore_groups: type: boolean description: Se deve ignorar mensagens de grupos na sincronização example: false chatwoot_sign_messages: type: boolean description: Se deve assinar mensagens enviadas para o WhatsApp example: true chatwoot_create_new_conversation: type: boolean description: Sempre criar nova conversa ao invés de reutilizar conversas existentes example: false "401": description: Token inválido/expirado "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Configuração persistida e webhook ligado à fila de envio da instância. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. put: tags: - Integração Chatwoot operationId: updateChatwootConfig summary: Atualizar configuração do Chatwoot description: 'Atualiza a configuração da integração com Chatwoot para a instância. ### Funcionalidades: - Configura todos os parâmetros da integração Chatwoot - Reinicializa automaticamente o cliente Chatwoot quando habilitado - Retorna URL do webhook para configurar no Chatwoot - Sincronização bidirecional de mensagens novas entre WhatsApp e Chatwoot - Sincronização automática de contatos (nome e telefone) - Atualização automática LID → PN (Local ID para Phone Number) - Sistema de nomes inteligentes com til (~) ### Configuração no Chatwoot: 1. Após configurar via API, use a URL retornada no webhook settings da inbox no Chatwoot 2. Configure como webhook URL na sua inbox do Chatwoot 3. A integração ficará ativa e sincronizará mensagens e contatos automaticamente ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: São atualizados automaticamente quando o contato modifica seu nome no WhatsApp - **Nomes específicos**: Para definir um nome fixo, remova o til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" será atualizado automaticamente, "João Silva" (sem til) permanecerá fixo - **Atualização LID→PN**: Contatos migram automaticamente de Local ID para Phone Number quando disponível - **Sem duplicação**: Durante a migração LID→PN, não haverá duplicação de conversas - **Respostas nativas**: Todas as respostas dos agentes aparecem nativamente no Chatwoot ### 🚧 AVISO IMPORTANTE - INTEGRAÇÃO BETA: - **Fase Beta**: Esta integração está em fase de desenvolvimento e testes - **Uso por conta e risco**: O usuário assume total responsabilidade pelo uso - **Recomendação**: Teste em ambiente não-produtivo antes de usar em produção - **Suporte limitado**: Funcionalidades podem mudar sem aviso prévio ### ⚠️ Limitações Conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: enabled: type: boolean description: Habilitar/desabilitar integração com Chatwoot example: true url: type: string description: URL base da instância Chatwoot (sem barra final) example: https://app.chatwoot.com access_token: type: string description: Token de acesso da API Chatwoot (obtido em Profile Settings > Access Token) example: pXXGHHHyJPYHYgWHJHYHgJjj account_id: type: integer format: int64 description: ID da conta no Chatwoot (visível na URL da conta) example: 1 inbox_id: type: integer format: int64 description: ID da inbox no Chatwoot (obtido nas configurações da inbox) example: 5 ignore_groups: type: boolean description: Ignorar mensagens de grupos do WhatsApp na sincronização example: false sign_messages: type: boolean description: Assinar mensagens enviadas para WhatsApp com identificação do agente example: true create_new_conversation: type: boolean description: Sempre criar nova conversa ao invés de reutilizar conversas existentes example: false required: - enabled - url - access_token - account_id - inbox_id responses: "200": description: Configuração atualizada com sucesso content: application/json: schema: type: object properties: message: type: string description: Mensagem de confirmação example: "Chatwoot config updated successfully, put this URL in Chatwoot inbox webhook settings:" chatwoot_inbox_webhook_url: type: string description: URL do webhook para configurar na inbox do Chatwoot example: https://sua-api.com/chatwoot/webhook/inst_abc123 "400": description: Dados inválidos no body da requisição "401": description: Token inválido/expirado "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao salvar configuração x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Configuração persistida e webhook ligado à fila de envio da instância. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/updateDelaySettings: post: tags: - Mensagem Async operationId: updateDelaySettings summary: Configurar delay entre mensagens async description: 'Configura o intervalo de tempo entre mensagens diretas enviadas com `async=true`. ### Detalhes - Configuração aplicada apenas à fila interna de mensagens async - Afeta mensagens enviadas pelos endpoints de envio com `async=true` - Não afeta campanhas do sender (`/sender/*`) - Delay mínimo (msg_delay_min): 0 ou mais segundos (0 = sem delay) - Delay máximo (msg_delay_max): se menor que min, será ajustado para o mesmo valor de min - Sistema ajusta automaticamente valores negativos para 0 ### Exemplo ```json { "msg_delay_min": 0, "msg_delay_max": 2 } ```' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: msg_delay_min: type: integer format: int64 minimum: 0 description: Delay mínimo em segundos (0 = sem delay) example: 0 msg_delay_max: type: integer format: int64 minimum: 0 description: Delay máximo em segundos example: 2 required: - msg_delay_min - msg_delay_max responses: "200": description: Sucesso content: application/json: schema: type: object properties: instance: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: Invalid request payload "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to update delay settings x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /message/async: get: tags: - Mensagem Async operationId: getAsyncQueueStatus summary: Consultar fila async de envio direto description: "Retorna um resumo simples da fila de envio `async=true` da instância atual autenticada. Este endpoint cobre apenas a fila interna de envio direto assíncrono. Ele **não** representa: - campanhas de envio em massa do sender (`/sender/*`) A resposta padrão foi pensada para clientes: - `status`: visão resumida da fila (`idle`, `queued`, `processing`, `waiting_connection`, `resetting`) - `pending`: quantidade total estimada de mensagens pendentes - `processingNow`: indica se o worker está ocupando um job neste momento - `acceptingNewMessages`: indica se a fila aceita novos envios async - `sessionReady`: indica se a sessão WhatsApp está pronta para envio - `resetting`: indica se a fila está pausada por reset/clear" security: - InstanceToken: [] parameters: [] responses: "200": description: Resumo da fila async content: application/json: schema: type: object properties: response: type: string example: Async queue status instanceId: type: string description: ID da instância queue: type: object properties: status: type: string description: Estado resumido da fila example: waiting_connection pending: type: integer format: int64 description: Quantidade total estimada de mensagens pendentes example: 3 processingNow: type: boolean description: Indica se há um job ativo no worker agora example: true acceptingNewMessages: type: boolean description: Indica se a fila aceita novos envios async example: true sessionReady: type: boolean description: Indica se a sessão WhatsApp está pronta para envio example: false resetting: type: boolean description: Indica se a fila async está pausada por reset/clear example: false "401": description: Token inválido ou ausente "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar a fila async content: application/json: schema: type: object properties: error: type: string instanceId: type: string x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. delete: tags: - Mensagem Async operationId: clearAsyncQueue summary: Limpar fila async de envio direto description: "Cancela toda a fila de envio `async=true` da instância e marca as mensagens pendentes como `Canceled`. Este endpoint atua apenas na fila interna de envio direto assíncrono. Ele **não** afeta: - campanhas do sender (`/sender/*`) - mensagens já enviadas com sucesso - mensagens em massa agendadas O fluxo executado é: 1. pausa o worker interno da fila async 2. drena jobs pendentes em memória e overflow 3. marca backlog persistido em `Queued` como `Canceled` 4. libera a fila para novos envios async Use este endpoint quando houver backlog preso, fila acumulada ou quando você quiser abortar todos os envios assíncronos ainda não concluídos." security: - InstanceToken: [] parameters: [] responses: "200": description: Fila async limpa com sucesso content: application/json: schema: type: object properties: response: type: string example: Async queue cleared instanceId: type: string description: ID da instância stats: type: object properties: trackedJobsCleared: type: integer description: Quantidade de IDs rastreados removidos da fila em memória example: 3 bufferedJobsMarkedCanceled: type: integer description: Jobs em memória marcados como `Canceled` example: 2 drainedChannelJobs: type: integer description: Jobs removidos do canal principal da fila example: 1 clearedOverflowJobs: type: integer description: Jobs removidos do backlog de overflow example: 1 persistedQueuedCanceled: type: integer format: int64 description: Mensagens persistidas em `Queued` que foram atualizadas para `Canceled` example: 5 "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A fila não pôde ser limpa porque a instância está em reset ou havia envio em progresso que não drenou a tempo content: application/json: schema: type: object properties: error: type: string example: async queue did not drain before reset instanceId: type: string stats: type: object additionalProperties: true "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao limpar a fila async content: application/json: schema: type: object properties: error: type: string instanceId: type: string stats: type: object additionalProperties: true x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Consulta estado persistido ou dados reais da operação. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/advanced: post: tags: - Mensagem em massa operationId: sendAdvancedCampaign summary: Criar envio em massa avançado description: Cria um novo envio em massa com configurações avançadas, permitindo definir múltiplos destinatários e mensagens com delays personalizados. security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object properties: delayMin: type: integer description: Delay mínimo entre mensagens (segundos) minimum: 0 example: 3 delayMax: type: integer description: Delay máximo entre mensagens (segundos) minimum: 0 example: 6 info: type: string description: Descrição ou informação sobre o envio em massa example: Campanha de lançamento scheduled_for: type: integer description: Timestamp em milissegundos (date unix) ou minutos a partir de agora para agendamento example: 1 messages: type: array description: Lista de mensagens a serem enviadas items: type: object required: - number - type properties: number: type: string description: ID do chat ou número do destinatário. example: "5511999999999" type: type: string enum: - text - image - document - audio - ptt - myaudio - sticker - video - videoplay - contact - location - poll - list - button - carousel description: | Tipo da mensagem: - text: Mensagem de texto - image: Imagem - document: Documento/arquivo - audio: Áudio - ptt: Mensagem de voz - myaudio: Áudio (opção alternativa) - sticker: Figurinha - video: Vídeo - videoplay: Vídeo com autoplay/loop no WhatsApp - contact: Contato - location: Localização - poll: Enquete - list: Lista de opções - button: Botões interativos - carousel: Carrossel de cartões com imagens e botões text: type: string description: Texto da mensagem (quando type é "text") ou legenda para mídia file: type: string description: URL da mídia (quando type é image, video, audio, document, etc) docName: type: string description: Nome do arquivo (quando type é document) linkPreview: type: boolean description: Se deve gerar preview de links (quando type é text). O preview será gerado automaticamente a partir da URL contida no texto. linkPreviewTitle: type: string description: Título personalizado para o preview do link (opcional) linkPreviewDescription: type: string description: Descrição personalizada para o preview do link (opcional) linkPreviewImage: type: string description: URL ou dados base64 da imagem para o preview do link (opcional) linkPreviewLarge: type: boolean description: Se deve usar preview grande ou pequeno (opcional, padrão false) fullName: type: string description: Nome completo (quando type é contact) phoneNumber: type: string description: Número do telefone (quando type é contact) organization: type: string description: Organização (quando type é contact) email: type: string description: Email (quando type é contact) url: type: string description: URL (quando type é contact) latitude: type: number description: Latitude (quando type é location) longitude: type: number description: Longitude (quando type é location) name: type: string description: Nome do local (quando type é location) address: type: string description: Endereço (quando type é location) footerText: type: string description: Texto do rodapé (quando type é list, button, poll ou carousel) buttonText: type: string description: Texto do botão (quando type é list, button, poll ou carousel) listButton: type: string description: Texto do botão da lista (quando type é list) selectableCount: type: integer description: Quantidade de opções selecionáveis (quando type é poll) choices: type: array items: type: string description: Lista de opções (quando type é list, button, poll ou carousel). Para carousel, use formato específico com [texto], {imagem} e botões imageButton: type: string description: URL da imagem para o botão (quando type é button) required: - messages example: delayMin: 3 delayMax: 6 info: teste avançado scheduled_for: 1 messages: - number: "5511999999999" type: text text: First message - number: "5511999999999" type: button text: |- Promoção Especial! Confira nossas ofertas incríveis footerText: Válido até 31/12/2024 imageButton: https://exemplo.com/banner-promocao.jpg choices: - Ver Ofertas|https://loja.exemplo.com/ofertas - Falar com Vendedor|reply:vendedor - Copiar Cupom|copy:PROMO2024 - number: "5511999999999" type: list text: "Escolha sua categoria preferida:" listButton: Ver Categorias choices: - "[Eletrônicos]" - Smartphones|eletronicos_smartphones - Notebooks|eletronicos_notebooks - "[Roupas]" - Camisetas|roupas_camisetas - Sapatos|roupas_sapatos - number: "5511999999999" type: document file: https://example.com/doc.pdf docName: Documento.pdf - number: "5511999999999" type: carousel text: Conheça nossos produtos choices: - |- [Smartphone XYZ O mais avançado smartphone da linha] - "{https://exemplo.com/produto1.jpg}" - Copiar Código|copy:PROD123 - Ver no Site|https://exemplo.com/xyz - |- [Notebook ABC O notebook ideal para profissionais] - "{https://exemplo.com/produto2.jpg}" - Copiar Código|copy:NOTE456 - Comprar Online|https://exemplo.com/abc responses: "200": description: Mensagens adicionadas à fila com sucesso content: application/json: schema: type: object properties: folder_id: type: string description: ID da pasta/lote criado count: type: integer description: Total de mensagens adicionadas à fila status: type: string description: Status da operação example: queued "400": description: Erro nos parâmetros da requisição content: application/json: schema: type: object properties: error: type: string description: Descrição do erro example: Formato de número inválido "401": description: Não autorizado - token inválido ou ausente content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro example: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string description: Detalhes do erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/clearall: delete: tags: - Mensagem em massa operationId: clearAllCampaigns summary: Limpar toda fila de mensagens description: Remove todas as mensagens da fila de envio em massa, incluindo mensagens pendentes e já enviadas. Esta é uma operação irreversível. security: - InstanceToken: [] parameters: [] responses: "200": description: Fila de mensagens limpa com sucesso content: application/json: schema: type: object properties: status: type: string description: Status da operação example: processed messages_deleted: type: integer description: Quantidade de mensagens deletadas example: 150 folders_deleted: type: integer description: Quantidade de pastas deletadas example: 3 "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Não autorizado - token inválido ou ausente content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro example: Token inválido ou ausente "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string description: Detalhes do erro interno x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/cleardone: post: tags: - Mensagem em massa operationId: clearDoneCampaigns summary: Limpar mensagens enviadas description: Inicia processo de limpeza de mensagens antigas em lote que já foram enviadas com sucesso. Por padrão, remove mensagens mais antigas que 7 dias. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: hours: type: integer description: Quantidade de horas para manter mensagens. Mensagens mais antigas que esse valor serão removidas. example: 168 default: 168 responses: "200": description: Limpeza iniciada com sucesso content: application/json: schema: type: object properties: status: type: string description: Status da operação example: cleanup started "400": description: "Requisição inválida: corpo, número ou parâmetro ausente ou incorreto." content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/edit: post: tags: - Mensagem em massa operationId: editCampaign summary: Controlar campanha de envio em massa description: 'Permite controlar campanhas de envio de mensagens em massa através de diferentes ações: ## Ações Disponíveis: **🛑 stop** - Pausar campanha - Pausa uma campanha ativa ou agendada - Altera o status para "paused" - Use quando quiser interromper temporariamente o envio - Mensagens já enviadas não são afetadas **▶️ continue** - Continuar campanha - Retoma uma campanha pausada - Altera o status para "scheduled" - Use para continuar o envio após pausar uma campanha - Não funciona em campanhas já concluídas ("done") **🗑️ delete** - Deletar campanha - Remove completamente a campanha - Deleta apenas mensagens NÃO ENVIADAS (status "scheduled") - Mensagens já enviadas são preservadas no histórico - Operação é executada de forma assíncrona ## Status de Campanhas: - **scheduled**: Agendada para envio - **sending**: Enviando mensagens - **paused**: Pausada pelo usuário - **done**: Concluída (não pode ser alterada) - **deleting**: Sendo deletada (operação em andamento)' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: folder_id: type: string description: Identificador único da campanha de envio example: folder_123 action: type: string enum: - stop - continue - delete description: > Ação a ser executada na campanha: - **stop**: Pausa a campanha (muda para status "paused") - **continue**: Retoma campanha pausada (muda para status "scheduled") - **delete**: Remove campanha e mensagens não enviadas (assíncrono) example: stop required: - folder_id - action responses: "200": description: Ação realizada com sucesso content: application/json: schema: oneOf: - type: object title: Resposta para ação 'stop' properties: status: type: string enum: - paused description: Status da campanha após pausar example: paused - type: object title: Resposta para ação 'continue' properties: status: type: string enum: - scheduled description: Status da campanha após retomar example: scheduled message: type: string description: Mensagem de confirmação example: Folder resumed successfully - type: object title: Resposta para ação 'delete' properties: status: type: string enum: - deleting description: Status indicando que a deleção foi iniciada example: deleting message: type: string description: Mensagem informando que a deleção é assíncrona example: Folder deletion has been initiated "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: folder_id is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/listfolders: get: tags: - Mensagem em massa operationId: listCampaignFolders summary: Listar campanhas de envio description: Retorna as campanhas de envio em massa da instância atual, ordenadas das mais recentes para as mais antigas. Se a instância não possuir owner associado, a API retorna uma lista vazia. security: - InstanceToken: [] parameters: - in: query name: status schema: type: string enum: - Active - Archived description: > Filtro de status desejado. O backend atual retorna todas as pastas do owner e pode ignorar esse parâmetro dependendo da implementação da fila. required: false responses: "200": description: Lista de campanhas retornada com sucesso content: application/json: schema: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: "Failed to fetch batches: database error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/listmessages: post: tags: - Mensagem em massa operationId: listCampaignMessages summary: Listar mensagens de uma campanha description: Retorna a lista de mensagens de uma campanha específica, com opções de filtro por status e paginação security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: folder_id: type: string description: ID da campanha a ser consultada messageStatus: type: string enum: - Scheduled - Sent - Failed description: Status das mensagens para filtrar limit: type: integer minimum: 1 maximum: 1000 default: 1000 description: Quantidade maxima de itens por pagina offset: type: integer minimum: 0 default: 0 description: Deslocamento base zero para paginacao required: - folder_id responses: "200": description: Lista de mensagens retornada com sucesso content: application/json: schema: type: object properties: messages: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. pagination: type: object properties: totalRecords: type: integer description: Total de mensagens encontradas limit: type: integer description: Limite aplicado na pagina atual offset: type: integer description: Offset efetivamente usado na pagina atual "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: folder_id is required "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to fetch messages x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sender/simple: post: tags: - Mensagem em massa operationId: sendSimpleCampaign summary: Criar nova campanha (Simples) description: Cria uma nova campanha de envio com configurações básicas security: - InstanceToken: [] parameters: - in: header name: Idempotency-Key required: true description: Chave única obrigatória da ação. Em resultado incerto, reutilize exatamente a mesma chave e o mesmo corpo. schema: type: string maxLength: 200 requestBody: content: application/json: schema: type: object required: - numbers - type - delayMin - delayMax - scheduled_for properties: numbers: type: array description: Lista de números para envio items: type: string example: - 5511999999999@s.whatsapp.net type: type: string description: Tipo da mensagem enum: - text - image - video - videoplay - audio - document - contact - location - list - button - poll - carousel folder: type: string description: Nome da campanha de envio example: Campanha Janeiro delayMin: type: integer description: Delay mínimo entre mensagens em segundos minimum: 1 example: 10 delayMax: type: integer description: Delay máximo entre mensagens em segundos minimum: 1 example: 30 scheduled_for: type: integer description: Timestamp em milissegundos ou minutos a partir de agora para agendamento example: 1706198400000 info: type: string description: Informações adicionais sobre a campanha delay: type: integer description: Delay fixo entre mensagens (opcional) mentions: type: string description: Menções na mensagem em formato JSON text: type: string description: Texto da mensagem linkPreview: type: boolean description: Habilitar preview de links em mensagens de texto. O preview será gerado automaticamente a partir da URL contida no texto. linkPreviewTitle: type: string description: Título personalizado para o preview do link (opcional) linkPreviewDescription: type: string description: Descrição personalizada para o preview do link (opcional) linkPreviewImage: type: string description: URL ou dados base64 da imagem para o preview do link (opcional) linkPreviewLarge: type: boolean description: Se deve usar preview grande ou pequeno (opcional, padrão false) file: type: string description: URL da mídia ou arquivo (quando type é image, video, audio, document, etc.) docName: type: string description: Nome do arquivo (quando type é document) fullName: type: string description: Nome completo (quando type é contact) phoneNumber: type: string description: Número do telefone (quando type é contact) organization: type: string description: Organização (quando type é contact) email: type: string description: Email (quando type é contact) url: type: string description: URL (quando type é contact) latitude: type: number description: Latitude (quando type é location) longitude: type: number description: Longitude (quando type é location) name: type: string description: Nome do local (quando type é location) address: type: string description: Endereço (quando type é location) footerText: type: string description: Texto do rodapé (quando type é list, button, poll ou carousel) buttonText: type: string description: Texto do botão (quando type é list, button, poll ou carousel) listButton: type: string description: Texto do botão da lista (quando type é list) selectableCount: type: integer description: Quantidade de opções selecionáveis (quando type é poll) choices: type: array items: type: string description: Lista de opções (quando type é list, button, poll ou carousel). Para carousel, use formato específico com [texto], {imagem} e botões imageButton: type: string description: URL da imagem para o botão (quando type é button) responses: "200": description: campanha criada com sucesso content: application/json: schema: type: object properties: folder_id: type: string description: ID único da campanha criada count: type: integer description: Quantidade de mensagens agendadas status: type: string description: Status da operação example: queued "400": description: Erro nos parâmetros da requisição content: application/json: schema: type: object properties: error: type: string "401": description: Erro de autenticação content: application/json: schema: type: object properties: error: type: string "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: Conflito - campanha já existe content: application/json: schema: type: object properties: error: type: string "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Campanha executada pela fila persistente, com controle de estado e idempotência. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/admin/accept: post: tags: - Newsletters e Canais operationId: acceptNewsletterAdminInvite summary: Aceitar convite de admin do canal description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Convite aceito com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao aceitar convite de admin content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/admin/invite: post: tags: - Newsletters e Canais operationId: inviteNewsletterAdmin summary: Convidar admin do canal description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - phone properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter phone: type: string example: "5511999999999" responses: "200": description: Convite enviado com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: phone is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao convidar admin content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/admin/remove: post: tags: - Newsletters e Canais operationId: removeNewsletterAdmin summary: Remover admin do canal description: Remove um administrador do canal usando o telefone dele. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - phone properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter phone: type: string example: "5511999999999" responses: "200": description: Admin removido com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: phone is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao remover admin content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/admin/revoke: post: tags: - Newsletters e Canais operationId: revokeNewsletterAdminInvite summary: Revogar convite de admin do canal description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - phone properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter phone: type: string example: "5511999999999" responses: "200": description: Convite revogado com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: phone is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao revogar convite content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Fluxo administrativo persistente e auditável; a resposta declara quando não existe confirmação administrativa nativa. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/create: post: tags: - Newsletters e Canais operationId: createNewsletter summary: Criar canal description: "Cria um novo canal/newsletter no WhatsApp. Observações: - `name` é obrigatório - `picture` é opcional - `picture` aceita URL HTTP/HTTPS, base64 puro ou data URI - imagens acima de 1 MB são rejeitadas" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - name properties: name: type: string example: Canal de Promoções description: type: string example: Ofertas e novidades da loja picture: type: string description: URL, base64 puro ou data URI da imagem do canal. example: https://example.com/newsletter.png responses: "200": description: Canal criado com sucesso content: application/json: schema: type: object properties: response: type: object description: Metadata do canal retornada pelo WhatsApp. additionalProperties: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: name is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao criar o canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/delete: post: tags: - Newsletters e Canais operationId: deleteNewsletter summary: Deletar canal description: Remove/deleta um canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Canal deletado com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao deletar o canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/description: post: tags: - Newsletters e Canais operationId: updateNewsletterDescription summary: Atualizar descrição do canal description: Atualiza a descrição do canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter description: type: string example: Atualizações, ofertas e novidades responses: "200": description: Descrição atualizada com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido ou ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar a descrição do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/follow: post: tags: - Newsletters e Canais operationId: followNewsletter summary: Seguir canal description: Segue um canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Canal seguido com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao seguir canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/info: post: tags: - Newsletters e Canais operationId: getNewsletterInfo summary: Buscar informações de um canal description: Busca os detalhes de um canal/newsletter pelo `id` numérico ou pelo `jid`. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. example: "120363123456789012" jid: type: string description: JID completo do canal. example: 120363123456789012@newsletter responses: "200": description: Informações do canal recuperadas com sucesso content: application/json: schema: type: object properties: response: type: object additionalProperties: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar o canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/link: post: tags: - Newsletters e Canais operationId: getNewsletterInfoWithInvite summary: Buscar canal por link-chave de convite description: Busca as informações de um canal a partir da chave de convite. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - key properties: key: type: string description: Chave do convite do canal. example: AbCdEfGhIjKlMn responses: "200": description: Informações do canal recuperadas com sucesso content: application/json: schema: type: object properties: response: type: object additionalProperties: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: key is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar o convite content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/list: get: tags: - Newsletters e Canais operationId: listNewsletters summary: Listar canais inscritos description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Lista o índice persistente de canais conhecidos pela instância; não promete enumeração completa da conta. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] responses: "200": description: Lista de canais recuperada com sucesso content: application/json: schema: type: object properties: response: type: array items: type: object additionalProperties: true "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao listar canais content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Lista o índice persistente de canais conhecidos pela instância; não promete enumeração completa da conta. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/messages: post: tags: - Newsletters e Canais operationId: getNewsletterMessages summary: Buscar mensagens de um canal description: "Busca diretamente no WhatsApp os posts/mensagens de um canal (newsletter). Esta rota não depende de mensagens salvas localmente e é útil para: - carregar o histórico recente de posts de um canal - paginar mensagens anteriores usando `beforeid` - consumir conteúdo de newsletters sem persistência em banco Identificação do canal: - envie `id` com o identificador numérico do canal; o backend converte para `@newsletter` - ou envie `jid` completo no formato `1234567890@newsletter` Observações: - `count` controla quantos posts retornar - use preferencialmente `beforeid` - `beforeid` pagina para trás a partir de um `serverid` - o retorno vem no campo `response`" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. example: "120363123456789012" jid: type: string description: JID completo do canal. example: 120363123456789012@newsletter count: type: integer minimum: 1 description: Quantidade de mensagens/posts a buscar. example: 20 beforeid: type: integer minimum: 1 description: | Retorna mensagens anteriores ao `serverid` informado. Use para paginação retroativa. example: 12345 example: id: "120363123456789012" count: 20 responses: "200": description: Mensagens do canal recuperadas com sucesso content: application/json: schema: type: object properties: response: type: array description: Lista de mensagens/posts do canal retornados diretamente pelo WhatsApp. items: type: object properties: serverid: type: integer description: Identificador sequencial do post no canal. example: 12345 messageid: type: string description: ID lógico da mensagem. example: 3EB0B4302B3A8A52F7A1 type: type: string description: Tipo da mensagem do canal. example: text timestamp: type: string format: date-time description: Momento em que o post foi publicado. viewsCount: type: integer description: Quantidade de visualizações conhecida no momento da consulta. example: 1200 reactionCounts: type: object additionalProperties: type: integer description: Mapa de emoji para quantidade de reações. example: 👍: 22 🔥: 7 message: type: object description: Conteúdo bruto da mensagem retornado pelo WhatsApp quando disponível. additionalProperties: true example: response: - messageid: 3EB0B4302B3A8A52F7A1 serverid: 12345 type: text timestamp: 2026-03-24T18:20:00Z viewsCount: 1200 reactionCounts: 👍: 22 🔥: 7 message: conversation: Post do canal "400": description: Payload inválido ou ID/JID do canal inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar mensagens do canal no WhatsApp content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/messages/delete: post: tags: - Newsletters e Canais operationId: deleteNewsletterMessage summary: Deletar mensagem recente de um canal description: "Apaga um post recente de newsletter diretamente no WhatsApp. Esta rota: - nao depende de mensagens salvas localmente - revoga o post no canal usando o WhatsApp - aceita localizar o post por `messageid` ou `serverid` Observações: - use `jid` ou `id` para identificar o canal - envie ao menos um entre `messageid` e `serverid` - `count` e `maxpages` controlam a janela de busca no canal" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. example: "120363123456789012" jid: type: string description: JID completo do canal. example: 120363123456789012@newsletter messageid: type: string description: ID lógico da mensagem no canal. example: 3EB0B4302B3A8A52F7A1 serverid: type: integer minimum: 1 description: Identificador sequencial do post no canal. example: 12345 count: type: integer minimum: 1 description: Quantidade de mensagens buscadas por página ao localizar o post. example: 100 maxpages: type: integer minimum: 1 description: Quantidade máxima de páginas buscadas ao localizar o post. example: 5 example: jid: 120363123456789012@newsletter messageid: 3EB0B4302B3A8A52F7A1 responses: "200": description: Mensagem do canal deletada com sucesso content: application/json: schema: type: object properties: response: type: object properties: jid: type: string example: 120363123456789012@newsletter targetmessageid: type: string description: ID lógico do post deletado. example: 3EB0B4302B3A8A52F7A1 targetserverid: type: integer description: Identificador sequencial do post deletado. example: 12345 messageid: type: string description: ID da operação de deleção enviada ao WhatsApp. example: 3EB01234567890ABCDEF serverid: type: integer description: Server id retornado pela operação de deleção. example: 12346 "400": description: Payload inválido ou canal inválido content: application/json: schema: type: object properties: error: type: string example: messageid or serverid is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem do canal não encontrada na janela recente consultada content: application/json: schema: type: object properties: error: type: string example: newsletter message not found in recent history "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar ou deletar a mensagem do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: blocked available: false reason: Rota bloqueada nesta conexão para impedir sucesso aparente sem efeito confirmado. /newsletter/messages/edit: post: tags: - Newsletters e Canais operationId: editNewsletterMessage summary: Editar mensagem recente de um canal description: "Edita o conteúdo de um post recente de newsletter diretamente no WhatsApp. Esta rota: - nao depende de mensagens salvas localmente - busca a mensagem recente do canal via WhatsApp - localiza o post por `messageid` ou `serverid` - edita apenas tipos suportados (`text`, `image`, `video`, `document`) Observações: - use `jid` ou `id` para identificar o canal - envie ao menos um entre `messageid` e `serverid` - envie `text` com o novo conteúdo/legenda - `count` e `maxpages` controlam a janela de busca no canal" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - text properties: id: type: string description: ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. example: "120363123456789012" jid: type: string description: JID completo do canal. example: 120363123456789012@newsletter messageid: type: string description: ID lógico da mensagem no canal. example: 3EB0B4302B3A8A52F7A1 serverid: type: integer minimum: 1 description: Identificador sequencial do post no canal. example: 12345 text: type: string description: Novo texto ou nova legenda do post. example: Post atualizado count: type: integer minimum: 1 description: Quantidade de mensagens buscadas por página ao localizar o post. example: 100 maxpages: type: integer minimum: 1 description: Quantidade máxima de páginas buscadas ao localizar o post. example: 5 example: jid: 120363123456789012@newsletter messageid: 3EB0B4302B3A8A52F7A1 text: Post atualizado responses: "200": description: Mensagem do canal editada com sucesso content: application/json: schema: type: object properties: response: type: object properties: jid: type: string example: 120363123456789012@newsletter targetmessageid: type: string description: ID lógico do post editado. example: 3EB0B4302B3A8A52F7A1 targetserverid: type: integer description: Identificador sequencial do post editado. example: 12345 messageid: type: string description: ID da operação de edição enviada ao WhatsApp. example: 3EB01234567890ABCDEF serverid: type: integer description: Server id retornado pela operação de edição. example: 12346 "400": description: Payload inválido, mensagem não editável, mensagem alvo não identificada ou canal inválido content: application/json: schema: type: object properties: error: type: string example: text is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Mensagem do canal não encontrada na janela recente consultada content: application/json: schema: type: object properties: error: type: string example: newsletter message not found in recent history "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar ou editar a mensagem do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: blocked available: false reason: Rota bloqueada nesta conexão para impedir sucesso aparente sem efeito confirmado. /newsletter/mute: post: tags: - Newsletters e Canais operationId: muteNewsletter summary: Silenciar canal description: Ativa o mute de um canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Canal silenciado com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao silenciar canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/name: post: tags: - Newsletters e Canais operationId: updateNewsletterName summary: Atualizar nome do canal description: Atualiza o nome do canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - name properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter name: type: string example: Canal de Promoções VIP responses: "200": description: Nome atualizado com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: name is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar o nome do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/owner/transfer: post: tags: - Newsletters e Canais operationId: transferNewsletterOwnership summary: Transferir dono do canal description: "Transfere a propriedade do canal para outro telefone. Observações: - `phone` é obrigatório - `quitAdmin=true` remove o dono anterior da posição de admin após a transferência" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - phone properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter phone: type: string example: "5511999999999" quitAdmin: type: boolean example: false responses: "200": description: Transferência solicitada com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: phone is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao transferir ownership do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/picture: post: tags: - Newsletters e Canais operationId: updateNewsletterPicture summary: Atualizar foto do canal description: "Atualiza a imagem do canal/newsletter. Observações: - `picture` aceita URL HTTP/HTTPS, base64 puro ou data URI - imagens acima de 1 MB são rejeitadas" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - picture properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter picture: type: string example: https://example.com/newsletter.png responses: "200": description: Foto do canal atualizada com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: empty image source "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar a foto do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /newsletter/reaction: post: tags: - Newsletters e Canais operationId: reactNewsletterMessage summary: Reagir a um post do canal description: "Envia, altera ou remove uma reação de um post do canal. Observações: - `serverid` identifica o post alvo - `reaction` define o emoji - envie `reaction` vazio para remover a reação - `reactionmessageid` é opcional; se omitido, o WhatsApp gera o ID da reação" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter serverid: type: integer example: 12345 reaction: type: string example: 🔥 reactionmessageid: type: string example: 3EB0AABBCCDD responses: "200": description: Reação aplicada com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido ou faltando `serverid` content: application/json: schema: type: object properties: error: type: string example: serverid is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao reagir ao post content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/search: post: tags: - Newsletters e Canais operationId: searchNewsletterDirectory summary: Pesquisar canais públicos description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Pesquisa o índice persistente de canais conhecidos; não se apresenta como busca no diretório público do WhatsApp. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: limit: type: integer example: 20 view: type: string example: RECOMMENDED countryCodes: type: array items: type: string example: - BR searchText: type: string example: promo after: type: string example: YXJyYXljb25uZWN0aW9uOjE5 responses: "200": description: Pesquisa executada com sucesso content: application/json: schema: type: object properties: response: type: object properties: after: type: string nullable: true example: YXJyYXljb25uZWN0aW9uOjIw data: type: array items: type: object additionalProperties: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: invalid payload "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao pesquisar canais content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Pesquisa o índice persistente de canais conhecidos; não se apresenta como busca no diretório público do WhatsApp. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/settings: post: tags: - Newsletters e Canais operationId: updateNewsletterSettings summary: Atualizar configurações do canal description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Persiste a política de reações da Relya porque o transporte atual não expõe esse ajuste. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - reactionCodes properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter reactionCodes: type: string example: basic responses: "200": description: Configurações atualizadas com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido content: application/json: schema: type: object properties: error: type: string example: invalid reactionCodes "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao atualizar configurações do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Persiste a política de reações da Relya porque o transporte atual não expõe esse ajuste. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/subscribe: post: tags: - Newsletters e Canais operationId: subscribeNewsletterLiveUpdates summary: Assinar live updates temporários de um canal description: "Assina temporariamente os live updates internos do WhatsApp para um canal. Observação: - esta rota retorna apenas a duração da assinatura temporária - isso não cria um novo evento de webhook" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Assinatura criada com sucesso content: application/json: schema: type: object properties: response: type: string description: Duração retornada pelo WhatsApp. example: 5m0s "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao assinar updates content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/unfollow: post: tags: - Newsletters e Canais operationId: unfollowNewsletter summary: Deixar de seguir canal description: Deixa de seguir um canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Canal removido dos seguidos com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao deixar de seguir canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/unmute: post: tags: - Newsletters e Canais operationId: unmuteNewsletter summary: Remover mute do canal description: Remove o mute de um canal/newsletter. security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter responses: "200": description: Mute removido com sucesso content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: ID/JID inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao remover mute do canal content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/updates: post: tags: - Newsletters e Canais operationId: getNewsletterMessageUpdates summary: Buscar updates de mensagens de um canal description: "Consulta diretamente no WhatsApp os updates de posts já existentes de um canal. Esta rota é diferente de `/newsletter/messages`: - `/newsletter/messages` retorna o conteúdo dos posts - `/newsletter/updates` retorna mudanças posteriores nos posts, especialmente métricas Esta rota também não é um evento de webhook: - não existe webhook `newsletter_messages_update` - para views e reactions de canais, consulte `/newsletter/updates` sob demanda Casos de uso: - atualizar contadores de `views` de posts já carregados - atualizar `reactionCounts` de posts do canal - consultar sob demanda os mesmos tipos de métricas que chegam nos live updates internos do WhatsApp Observações: - use preferencialmente `afterid` - `afterid` filtra updates depois de um `serverid` - `since` filtra pelo momento do update - `since` aceita timestamp em segundos ou milissegundos - o retorno vem no campo `response`" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string description: ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. example: "120363123456789012" jid: type: string description: JID completo do canal. example: 120363123456789012@newsletter count: type: integer minimum: 1 description: Quantidade máxima de updates retornados. example: 50 afterid: type: integer minimum: 1 description: Retorna apenas updates posteriores ao `serverid` informado. example: 12345 since: type: integer description: > Timestamp de corte. - Se maior que `1000000000000`, é interpretado como milissegundos. - Caso contrário, é interpretado como segundos. example: 1710000000 example: id: "120363123456789012" count: 50 afterid: 12345 responses: "200": description: Updates de mensagens do canal recuperados com sucesso content: application/json: schema: type: object properties: response: type: array description: Lista de updates de mensagens do canal. items: type: object properties: serverid: type: integer description: Identificador do post no canal. example: 12345 messageid: type: string description: ID lógico da mensagem. example: 3EB0B4302B3A8A52F7A1 type: type: string description: Tipo da mensagem do canal. example: text timestamp: type: string format: date-time description: Momento associado ao update retornado. viewsCount: type: integer description: Quantidade atualizada de visualizações. example: 1540 reactionCounts: type: object additionalProperties: type: integer description: Mapa atualizado de emoji para quantidade de reações. example: 👍: 35 🔥: 11 message: type: object description: | Conteúdo bruto da mensagem, quando presente. Em muitos live updates esse campo pode vir ausente. additionalProperties: true example: response: - messageid: 3EB0B4302B3A8A52F7A1 serverid: 12345 type: text timestamp: 2026-03-24T19:00:00Z viewsCount: 1540 reactionCounts: 👍: 35 🔥: 11 "400": description: Payload inválido ou ID/JID do canal inválido content: application/json: schema: type: object properties: error: type: string example: invalid newsletter id "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao consultar updates do canal no WhatsApp content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Operação ligada à capacidade nativa de canais do transporte conectado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /newsletter/viewed: post: tags: - Newsletters e Canais operationId: markNewsletterViewed summary: Marcar posts do canal como visualizados description: "⚠️ Operação adaptada: elementos interativos (botões, listas, carrossel) e pagamentos nativos são entregues como texto ou enquete neste transporte, não como componente nativo do WhatsApp. Adaptação funcional e declarada da Relya: Registra de forma persistente as mensagens vistas e confirma pelo transporte quando houver suporte. O schema mantém os campos de entrada compatíveis e a resposta informa o modo realmente executado." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: id: type: string example: "120363123456789012" jid: type: string example: 120363123456789012@newsletter serverids: type: array items: type: integer example: - 12345 - 12346 responses: "200": description: Posts marcados como visualizados content: application/json: schema: type: object properties: response: type: boolean example: true "400": description: Payload inválido ou faltando `serverids` content: application/json: schema: type: object properties: error: type: string example: serverids is required "401": description: Instância não autenticada ou cliente não encontrado content: application/json: schema: type: object properties: error: type: string example: client not found "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno ao marcar visualização content: application/json: schema: type: object properties: error: type: string example: connection closed x-relya-status: adapted x-relya-status-label: Adaptada x-relya-note: Registra de forma persistente as mensagens vistas e confirma pelo transporte quando houver suporte. x-relya-runtime-status: status: adapted available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /profile/image: post: tags: - Perfil operationId: updateProfileImage summary: Altera a imagem do perfil do WhatsApp description: "Altera a imagem de perfil da conta do WhatsApp atualmente conectada. O endpoint realiza: - Atualiza a imagem do perfil usando - Processa a imagem (URL, base64 ou comando de remoção) - Sincroniza a mudança com o servidor do WhatsApp - Retorna confirmação da alteração **Importante**: - A conta do WhatsApp deve estar conectada - A imagem será visível para todos os contatos - A imagem deve estar em formato JPEG e tamanho 640x640 pixels" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - image properties: image: type: string description: | Imagem do perfil. Pode ser: - URL da imagem (http/https) - String base64 da imagem - "remove" ou "delete" para remover a imagem atual example: https://picsum.photos/640/640.jpg oneOf: - description: URL da imagem example: https://picsum.photos/640/640.jpg - description: Imagem em base64 example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k= - description: Comando para remover imagem example: remove responses: "200": description: Imagem do perfil alterada com sucesso content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Imagem do perfil alterada com sucesso profile: type: object properties: image_updated: type: boolean description: Indica se a imagem foi atualizada example: true image_removed: type: boolean description: Indica se a imagem foi removida example: false updated_at: type: integer description: Timestamp da alteração (Unix timestamp) example: 1704067200 "400": description: Dados inválidos na requisição content: application/json: schema: type: object properties: error: type: string example: Formato de imagem inválido ou URL inacessível "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Ação não permitida content: application/json: schema: type: object properties: error: type: string example: Limite de alterações excedido ou conta com restrições "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "413": description: Imagem muito grande content: application/json: schema: type: object properties: error: type: string example: Imagem muito grande, tamanho máximo permitido excedido "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Erro ao alterar imagem do perfil x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: unsupported available: false reason: Sem implementação estável nesta conexão; a chamada falha explicitamente e nunca simula sucesso. /profile/name: post: tags: - Perfil operationId: updateProfileName summary: Altera o nome do perfil do WhatsApp description: "Altera o nome de exibição do perfil da conta do WhatsApp atualmente conectada. O endpoint realiza: - Atualiza o nome do perfil usando o WhatsApp AppState - Sincroniza a mudança com o servidor do WhatsApp - Retorna confirmação da alteração **Importante**: - A conta do WhatsApp deve estar conectada - O nome será visível para todos os contatos - Pode haver um limite de alterações por período (conforme WhatsApp)" security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: Novo nome do perfil do WhatsApp example: Minha Empresa - Atendimento maxLength: 25 responses: "200": description: Nome do perfil alterado com sucesso content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Nome do perfil alterado com sucesso profile: type: object properties: name: type: string description: Novo nome do perfil example: Minha Empresa - Atendimento updated_at: type: integer description: Timestamp da alteração (Unix timestamp) example: 1704067200 "400": description: Dados inválidos na requisição content: application/json: schema: type: object properties: error: type: string example: Nome muito longo ou inválido "401": description: Sem sessão ativa content: application/json: schema: type: object properties: error: type: string example: No session "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: Ação não permitida content: application/json: schema: type: object properties: error: type: string example: Limite de alterações excedido ou conta com restrições "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Erro ao alterar nome do perfil x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Possui implementação concreta no runtime da Relya. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /instance/proxy: get: tags: - Proxy operationId: getProxyConfig summary: Obter configuração de proxy da instância description: 'A Relya distingue a intenção persistida do cliente (`mode`) do transporte efetivo em runtime (`effective_mode`). Isso evita degradar silenciosamente para conexão direta quando a instância foi configurada para usar proxy. `mode` sempre será: - `custom`: o cliente escolheu um proxy próprio; - `internal`: a instância deve usar o pool interno ou a rota interna; ou - `none`: o cliente confirmou explicitamente que aceita conexão direta. `effective_mode` mostra o que está sendo usado no momento: - `custom` - `internal` - `direct` `effective_detail` qualifica o transporte efetivo: - `managed_pool`: proxy interno gerenciado pela plataforma; - `internal_route`: rota interna dedicada do ambiente, sem uma `proxy_url` própria; - `relay`: túnel relay do cliente; - campo omitido: sem detalhe adicional. Quando um proxy customizado falha, a plataforma pode seguir uma cadeia de contingência: 1. `proxy_fallback` explícito, se configurado com outra URL; 2. proxy interno; 3. conexão direta como último recurso, quando a política permitir. Em qualquer fallback, a intenção persistida continua sendo `mode=custom`. O cliente deve olhar `effective_mode`, `effective_detail` e `fallback.active` para entender o estado runtime. Como ler cada campo da resposta: - `mode`: intenção salva na instância. É o que o cliente pediu para usar. - `effective_mode`: transporte realmente em uso agora. Pode divergir de `mode` durante fallback. - `effective_detail`: detalhe extra do transporte efetivo. Use para distinguir pool interno, rota interna ou relay. Quando não há detalhe adicional, o campo é omitido. - `fallback.active`: `true` quando a instância está operando fora da rota principal configurada. - `fallback.reason`: motivo interno resumido do fallback atual. Serve para diagnóstico e pode mudar conforme a causa. - `fallback.since`: timestamp Unix em milissegundos desde quando o fallback atual começou. - `proxy_url`: proxy persistido na instância, sempre mascarado. Se `mode=custom`, continua mostrando o proxy do cliente mesmo quando a sessão caiu em fallback. - `proxy_fallback`: política persistida de contingência para `mode=custom`. Pode ser `internal`, `never` ou outra URL de proxy. - `managed`: campo legado. Fica `true` quando a infraestrutura interna da plataforma está envolvida no transporte atual ou pretendido. - `last_test_at`: timestamp Unix em milissegundos do último teste ou da última falha persistida para esse proxy. - `last_test_error`: último erro persistido para diagnóstico. String vazia significa ausência de erro salvo. - `validation_error`: atalho booleano para `last_test_error != ""`. Leitura rápida dos cenários mais comuns: - `mode=custom` + `effective_mode=custom`: o proxy do cliente está sendo usado normalmente. - `mode=custom` + `effective_mode=internal`: o proxy do cliente falhou e a sessão está operando no fallback interno. - `mode=custom` + `effective_mode=direct`: o proxy do cliente falhou e a sessão caiu para conexão direta como último recurso. - `mode=internal` + `effective_detail=managed_pool`: a instância está usando um proxy do pool interno. - `mode=internal` + `effective_detail=internal_route`: a instância está usando uma rota interna dedicada, sem `proxy_url` própria. - `mode=none` + `effective_mode=direct`: conexão direta assumida explicitamente. Combinações que não devem aparecer numa resposta válida: - `mode=none` com `effective_mode=custom` ou `internal` - `effective_detail=managed_pool` com `effective_mode=custom` - `effective_detail=relay` com `effective_mode=internal` ou `direct`' security: - InstanceToken: [] parameters: [] responses: "200": description: Configuração de proxy recuperada com sucesso content: application/json: schema: type: object example: mode: custom effective_mode: internal effective_detail: managed_pool fallback: active: true reason: custom_failed_internal:dial tcp timeout since: 1760000000000 proxy_url: http://***:***@cliente-proxy.example:8080 proxy_fallback: internal managed: true last_test_at: 1760000000000 last_test_error: dial tcp timeout validation_error: true properties: mode: type: string enum: - custom - internal - none description: Intenção persistida do cliente. Representa o modo salvo na instância, não necessariamente o transporte em uso agora. example: custom effective_mode: type: string enum: - custom - internal - direct description: Transporte efetivo em runtime. É o valor principal para entender por onde a sessão está saindo neste momento. example: internal effective_detail: type: string enum: - managed_pool - internal_route - relay description: | Detalhe opcional do transporte atual. `managed_pool` = proxy interno gerenciado. `internal_route` = rota interna dedicada do ambiente. `relay` = túnel relay do cliente. Quando não há detalhe adicional, o campo é omitido. example: managed_pool fallback: type: object description: Estado do fallback runtime. Só fica ativo quando a instância precisou sair da rota principal configurada. properties: active: type: boolean description: Indica se a instância está operando em fallback neste momento. example: true reason: type: string description: Motivo interno resumido do fallback atual, útil para observabilidade e suporte. example: custom_failed_internal:dial tcp timeout since: type: integer description: Timestamp Unix em milissegundos desde quando o fallback atual está ativo. example: 1760000000000 proxy_url: type: string description: URL mascarada do proxy persistido. Em fallback de proxy custom, continua mostrando a URL do cliente; não troca para o proxy efetivo de contingência. example: http://***:***@cliente-proxy.example:8080 proxy_fallback: type: string description: > Política de contingência persistida para `mode=custom`. Valores aceitos: - `internal` - `never` - uma URL de proxy HTTP/HTTPS/SOCKS para contingência explícita example: internal managed: type: boolean description: Campo legado indicando participação da infraestrutura interna. Pode ficar `true` tanto em `mode=internal` quanto em fallback interno de `mode=custom`. example: true last_test_at: type: integer description: Timestamp Unix em milissegundos do último teste ou da última falha persistida. example: 1760000000000 last_test_error: type: string description: Último erro persistido para diagnóstico. String vazia significa ausência de erro salvo. example: dial tcp timeout validation_error: type: boolean description: Indica se `last_test_error` está preenchido. example: true example: mode: custom effective_mode: custom fallback: active: false reason: "" since: 0 proxy_url: http://***:***@cliente-proxy.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: "" validation_error: false "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string example: Unauthorized "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao recuperar a configuração content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Configuração validada e aplicada ao transporte por adaptador dedicado. x-relya-runtime-status: status: outside_guard available: false reason: Rota fora do guard de seguranca deste release; a chamada falha antes de alterar estado. post: tags: - Proxy operationId: updateProxyConfig summary: Configurar ou alterar o proxy description: "Define explicitamente um dos três estados aceitos: - `mode=custom`: usa um proxy próprio informado em `proxy_url`; - `mode=internal`: usa a infraestrutura interna; ou - `mode=none`: conexão direta, permitida apenas com `confirm_no_proxy=true`. Importante: `POST /instance/proxy` confirma que a configuração foi salva, não que o proxy já foi comprovado em uso. A validação operacional principal acontece no próximo ciclo real de conexão da instância. Em termos práticos: - `200 OK` aqui = configuração persistida com sucesso; - falhas reais de conectividade podem aparecer depois; e - para observar o estado real, consulte `GET /instance/proxy` e leia: - `effective_mode` - `effective_detail` - `fallback.active` - `last_test_error` - `validation_error` Quando `mode=custom`, você também pode definir a contingência via `proxy_fallback`: - `internal`: tenta a infraestrutura interna e, se ainda assim falhar, pode usar direto como último recurso; - `never`: não usa contingência; ou - uma URL de proxy de contingência controlada pelo próprio cliente. Quando `mode=internal`, `rotate_now: true` troca imediatamente o proxy interno persistido. Se houver mais de uma origem interna disponível, a plataforma escolhe outra origem sem expor o fornecedor. Se houver apenas uma origem, troca apenas o proxy/IP dentro dessa origem. Protocolos aceitos em URLs de proxy customizado: - `http://usuario:senha@host:porta` - `https://usuario:senha@host:porta` - `socks5://usuario:senha@host:porta` - `socks5h://usuario:senha@host:porta` O esquema `socks://` genérico não é aceito. Para proxies SOCKS, use `socks5://` ou `socks5h://`." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object properties: mode: type: string enum: - custom - internal - none description: Campo canônico para definir a estratégia de proxy. proxy_url: type: string description: > Obrigatório quando `mode=custom`. Protocolos aceitos: `http://`, `https://`, `socks5://` e `socks5h://`. O esquema `socks://` genérico não é suportado; use `socks5://` ou `socks5h://`. example: http://usuario:senha@ip:porta proxy_fallback: type: string description: > Política de contingência para `mode=custom`. Aceita `internal`, `never` ou uma URL de proxy de contingência usando `http://`, `https://`, `socks5://` ou `socks5h://`. confirm_no_proxy: type: boolean description: Obrigatório quando `mode=none`. rotate_now: type: boolean description: Quando `true` com `mode=internal`, troca imediatamente o proxy interno persistido sem expor o fornecedor usado. default: false example: mode: custom proxy_url: http://usuario:senha@proxy-do-cliente.example:8080 proxy_fallback: internal responses: "200": description: Proxy configurado com sucesso content: application/json: schema: type: object example: details: Proxy configurado proxy: mode: custom effective_mode: custom fallback: active: false reason: "" since: 0 proxy_url: http://***:***@proxy-do-cliente.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: "" validation_error: false restart_requested: true properties: details: type: string example: Proxy configurado proxy: type: object properties: mode: type: string enum: - custom - internal - none description: Intenção persistida do cliente após a gravação. effective_mode: type: string enum: - custom - internal - direct description: Transporte efetivo no momento da resposta. effective_detail: type: string enum: - managed_pool - internal_route - relay description: Detalhe complementar do transporte efetivo. Quando não há detalhe adicional, o campo é omitido. fallback: type: object description: Estado do fallback runtime. properties: active: type: boolean description: Indica se a instância está operando em fallback neste momento. reason: type: string description: Motivo interno resumido do fallback atual. since: type: integer description: Timestamp Unix em milissegundos desde quando o fallback atual está ativo. proxy_url: type: string description: URL mascarada do proxy persistido. proxy_fallback: type: string description: Política de contingência persistida para `mode=custom`. managed: type: boolean description: Campo legado ligado ao uso da infraestrutura interna. last_test_at: type: integer description: Timestamp do último teste/erro persistido. last_test_error: type: string description: Último erro persistido para diagnóstico. validation_error: type: boolean description: Indica se `last_test_error` está preenchido. restart_requested: type: boolean description: Indica se uma reinicialização da conexão foi solicitada para aplicar o proxy. rotated: type: boolean description: Presente como `true` quando `rotate_now` troca o proxy interno com sucesso. example: details: Proxy configurado proxy: mode: custom effective_mode: custom fallback: active: false reason: "" since: 0 proxy_url: http://***:***@proxy-do-cliente.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: "" validation_error: false restart_requested: true "400": description: Payload inválido ou falha na validação do proxy content: application/json: schema: type: object properties: error: type: string example: confirm_no_proxy é obrigatório para desabilitar proxy "401": description: Token inválido ou expirado content: application/json: schema: type: object properties: error: type: string example: Unauthorized "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: Não há proxy alternativo disponível para rotação interna content: application/json: schema: type: object properties: error: type: string example: "nao foi possivel rotacionar proxy interno: nenhum proxy alternativo disponível para rotação" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor ao configurar o proxy content: application/json: schema: type: object properties: error: type: string description: Mensagem detalhando o erro encontrado x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Configuração validada e aplicada ao transporte por adaptador dedicado. x-relya-runtime-status: status: outside_guard available: false reason: Rota fora do guard de seguranca deste release; a chamada falha antes de alterar estado. /proxy-managed/cities: get: tags: - Proxy operationId: listRegionCities summary: Proxy Interno - Listar cidades disponíveis description: "Retorna a lista de cidades disponíveis para uso nos campos `proxy_managed_country`, `proxy_managed_state` e `proxy_managed_city` do endpoint `POST /instance/connect`. O backend consulta o catálogo disponível e aplica um cache interno de 24 horas. Se o catálogo de cidades não estiver disponível, o endpoint retorna erro. - Autenticação: requer `token` válido de qualquer instância (ou credencial administrativa via instância). - Query `country` (opcional): ISO alpha-2 minúsculo. Default `br`. - Query `state` (opcional): UF/subdivisão minúscula, como `sp`. - Query `search` (opcional): filtro parcial por nome/slug, insensível a acento/caixa. Como escolher a cidade: 1. Use `br` em `proxy_managed_country`. 2. Chame `GET /proxy-managed/cities?country=br` para obter as cidades brasileiras. 3. Quando a cidade retornar `state`, envie também esse valor em `proxy_managed_state`. 4. Quando o usuário escolher uma cidade, envie em `/instance/connect`: - `proxy_managed_country`: o país escolhido, ex. `br` - `proxy_managed_state`: o `state` retornado pela cidade, ex. `sp`, quando disponível - `proxy_managed_city`: sempre o `cities[].value` Se `state` não vier na cidade selecionada, envie apenas `proxy_managed_country` e `proxy_managed_city`. O backend valida a combinação e retorna erro se faltar algum dado necessário. Exemplo de requisição: ``` GET /proxy-managed/cities?country=br&state=sp&search=camp ```" security: - InstanceToken: [] parameters: - in: query name: country required: false schema: type: string pattern: ^[a-z]{2}$ default: br description: ISO alpha-2 (minúsculo). Default `br`. - in: query name: state required: false schema: type: string pattern: ^[a-z0-9-]{1,16}$ description: Filtra por UF/subdivisão quando o catálogo traz `state`. Para Brasil, use valores como `sp`, `rj`, `mg`. - in: query name: search required: false schema: type: string description: Filtro parcial por nome/slug (insensível a acento/caixa). responses: "200": description: Lista de cidades disponíveis content: application/json: schema: type: object properties: country: type: string example: br state: type: string description: Retornado apenas quando a query `state` foi informada. example: sp cities: type: array items: type: object properties: value: type: string description: Slug aceito em `proxy_managed_city`. example: saopaulo label: type: string description: Nome apresentável da cidade. example: São Paulo state: type: string description: Código ISO 3166-2 da subdivisão/estado quando disponível. example: sp state_label: type: string description: Nome apresentável do estado/subdivisão quando disponível. example: São Paulo raw_city: type: string description: Campo técnico para diagnóstico. Não envie este campo no `/instance/connect`; use `value`. example: sao_paulo example: country: br state: sp cities: - value: campinas label: Campinas state: sp state_label: São Paulo raw_city: campinas - value: saopaulo label: São Paulo state: sp state_label: São Paulo raw_city: sao_paulo "400": description: country inválido (não é ISO alpha-2) "401": description: Token inválido/ausente "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno "503": description: Provider indisponível ou catálogo de cidades inacessível x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Configuração validada e aplicada ao transporte por adaptador dedicado. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /quickreply/edit: post: tags: - Respostas Rápidas operationId: editQuickReply summary: Criar, atualizar ou excluir resposta rápida description: "Gerencia templates de respostas rápidas para agilizar o atendimento. Por padrão, cria respostas rápidas locais. Para criar/sincronizar uma resposta rápida no WhatsApp Business, envie `onWhatsApp: true`. - Para criar: não inclua o campo `id` - Para atualizar: inclua o `id` existente - Para excluir: defina `delete: true` e inclua o `id` Observação: respostas rápidas sincronizadas com o WhatsApp suportam apenas `type: text`. Não é possível converter uma resposta rápida local existente em resposta do WhatsApp; para criar no WhatsApp, envie `onWhatsApp: true` sem `id`." security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object required: - shortCut - type properties: id: type: string description: Necessário para atualizações/exclusões, omitir para criação example: rb9da9c03637452 delete: type: boolean description: Definir como true para excluir o template default: false onWhatsApp: type: boolean description: Quando true, cria/sincroniza a resposta rápida no WhatsApp Business via app state. Disponível apenas para type=text. default: false shortCut: type: string description: Atalho para acesso rápido ao template example: saudacao1 type: type: string enum: - text - audio - myaudio - ptt - document - video - image description: Tipo da mensagem text: type: string description: Obrigatório para mensagens do tipo texto example: Olá! Como posso ajudar hoje? file: type: string description: URL ou Base64 para tipos de mídia example: https://exemplo.com/arquivo.pdf docName: type: string description: Nome do arquivo opcional para tipo documento example: apresentacao.pdf example: shortCut: saudacao type: text text: Olá! Como posso ajudar? responses: "200": description: Operação concluída com sucesso content: application/json: schema: type: object properties: message: type: string example: Operação concluída com sucesso quickReplies: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: Requisição inválida (erro de validação) "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: Template não encontrado "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro no servidor ou falha ao sincronizar com WhatsApp x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Resposta rápida persistida e sincronizada com o driver da instância. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /quickreply/showall: get: tags: - Respostas Rápidas operationId: listQuickReplies summary: Listar todas as respostas rápidas description: Retorna todas as respostas rápidas cadastradas para a instância autenticada security: - InstanceToken: [] parameters: [] responses: "200": description: Lista de respostas rápidas content: application/json: schema: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro no servidor x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Resposta rápida persistida e sincronizada com o driver da instância. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /sse: get: tags: - Webhooks e SSE operationId: subscribeSSE summary: Server-Sent Events (SSE) description: "Receber eventos em tempo real via Server-Sent Events (SSE) ### Funcionalidades Principais: - Configuração de URL para recebimento de eventos - Seleção granular de tipos de eventos - Filtragem avançada de mensagens - Parâmetros adicionais na URL - Gerenciamento múltiplo de webhooks **Eventos Disponíveis**: - `connection`: Alterações no estado da conexão - `history`: Recebimento de histórico de mensagens - `messages`: Novas mensagens recebidas - `messages_update`: Atualizações em mensagens existentes - `call`: Eventos de chamadas VoIP - `contacts`: Atualizações na agenda de contatos - `presence`: Alterações no status de presença - `groups`: Modificações em grupos - `labels`: Gerenciamento de etiquetas - `chats`: Eventos de conversas - `chat_labels`: Alterações em etiquetas de conversas - `blocks`: Bloqueios/desbloqueios Estabelece uma conexão persistente para receber eventos em tempo real. Este endpoint: 1. Requer autenticação via token 2. Mantém uma conexão HTTP aberta com o cliente 3. Envia eventos conforme ocorrem no servidor 4. Suporta diferentes tipos de eventos Quando `events` é informado, somente os eventos selecionados são enviados. Aliases nativos são normalizados para os nomes públicos e um nome desconhecido retorna HTTP 400 antes de abrir o stream. Exemplo de uso: ```javascript const response = await fetch('/sse?events=chats,messages', { headers: { token: 'SEU_TOKEN' } }); const reader = response.body .pipeThrough(new TextDecoderStream()) .getReader(); while (true) { const { value, done } = await reader.read(); if (done) break; console.log('Eventos SSE:', value); } ``` Estrutura de um evento: ```json { \"type\": \"message\", \"data\": { \"id\": \"3EB0538DA65A59F6D8A251\", \"from\": \"5511999999999@s.whatsapp.net\", \"to\": \"5511888888888@s.whatsapp.net\", \"text\": \"Olá!\", \"timestamp\": 1672531200000 } } ```" security: - InstanceToken: [] parameters: - name: token in: header schema: type: string required: true description: Token de autenticação da instância. Em produção, token na query string é bloqueado para não vazar em logs. example: "{{token}}" - name: events in: query schema: type: string required: true description: | Tipos de eventos a serem recebidos. Suporta dois formatos: - Separados por vírgula: `?events=chats,messages` - Parâmetros repetidos: `?events=chats&events=messages` example: chats,messages - name: excludeMessages in: query schema: type: string required: false description: > Tipos de mensagens a serem excluídas do evento `messages`. Suporta dois formatos: - Separados por vírgula: `?excludeMessages=poll,reaction` - Parâmetros repetidos: `?excludeMessages=poll&excludeMessages=reaction` example: poll,reaction responses: "200": description: Resposta da operação "401": description: Token de instância ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Entrega eventos reais da instância e do processamento de mensagens. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /webhook: get: tags: - Webhooks e SSE operationId: getWebhook summary: Ver Webhook da Instância description: 'Retorna a configuração atual do webhook da instância, incluindo: - URL configurada - Eventos ativos - Filtros aplicados - Configurações adicionais Exemplo de resposta: ```json [ { "id": "123e4567-e89b-12d3-a456-426614174000", "enabled": true, "url": "https://example.com/webhook", "events": ["messages", "messages_update"], "excludeMessages": ["wasSentByApi", "isGroupNo"], "addUrlEvents": true, "addUrlTypesMessages": true }, { "id": "987fcdeb-51k3-09j8-x543-864297539100", "enabled": true, "url": "https://outro-endpoint.com/webhook", "events": ["connection", "presence"], "excludeMessages": [], "addUrlEvents": false, "addUrlTypesMessages": false } ] ``` A resposta é sempre um array, mesmo quando há apenas um webhook configurado.' security: - InstanceToken: [] parameters: [] responses: "200": description: Configuração do webhook retornada com sucesso content: application/json: schema: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. example: - id: 123e4567-e89b-12d3-a456-426614174000 enabled: true url: https://example.com/webhook events: - messages - messages_update excludeMessages: - wasSentByApi - isGroupNo addUrlEvents: true addUrlTypesMessages: true - id: 987fcdeb-51k3-09j8-x543-864297539100 enabled: true url: https://outro-endpoint.com/webhook events: - connection - presence excludeMessages: [] addUrlEvents: false addUrlTypesMessages: false "401": description: Token inválido ou não fornecido content: application/json: schema: type: object properties: error: type: string example: missing token "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to process webhook data x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Entrega eventos reais da instância e do processamento de mensagens. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. post: tags: - Webhooks e SSE operationId: updateWebhook summary: Configurar Webhook da Instância description: 'Gerencia a configuração de webhooks para receber eventos em tempo real da instância. Permite gerenciar múltiplos webhooks por instância através do campo ID e action. ### 🚀 Modo Simples (Recomendado) **Uso mais fácil - sem complexidade de IDs**: - Não inclua `action` nem `id` no payload - Gerencia automaticamente um único webhook por instância - Cria novo ou atualiza o existente automaticamente - **Recomendado**: Sempre use `"excludeMessages": ["wasSentByApi"]` para evitar loops - **Exemplo**: `{"url": "https://meusite.com/webhook", "events": ["messages"], "excludeMessages": ["wasSentByApi"]}` ### 🧪 Sites para Testes (ordenados por qualidade) **Para testar webhooks durante desenvolvimento**: 1. **https://webhook.cool/** - ⭐ Melhor opção (sem rate limit, interface limpa) 2. **https://rbaskets.in/** - ⭐ Boa alternativa (confiável, baixo rate limit) 3. **https://webhook.site/** - ⚠️ Evitar se possível (rate limit agressivo) ### ⚙️ Modo Avançado (Para múltiplos webhooks) **Para usuários que precisam de múltiplos webhooks por instância**: 💡 **Dica**: Mesmo precisando de múltiplos webhooks, considere usar `addUrlEvents` no modo simples. Um único webhook pode receber diferentes tipos de eventos em URLs específicas (ex: `/webhook/message`, `/webhook/connection`), eliminando a necessidade de múltiplos webhooks. 1. **Criar Novo Webhook**: - Use `action: "add"` - Não inclua `id` no payload - O sistema gera ID automaticamente 2. **Atualizar Webhook Existente**: - Use `action: "update"` - Inclua o `id` do webhook no payload - Todos os campos serão atualizados 3. **Remover Webhook**: - Use `action: "delete"` - Inclua apenas o `id` do webhook - Outros campos são ignorados ### Eventos Disponíveis - `connection`: Alterações no estado da conexão - `history`: Recebimento de histórico de mensagens - `messages`: Novas mensagens recebidas - `messages_update`: Atualizações em mensagens existentes - `newsletter_messages`: Novos posts/mensagens de canais do WhatsApp Para views e reactions de canais, use a rota `/newsletter/updates`. - `call`: Eventos de chamadas VoIP - `contacts`: Atualizações na agenda de contatos - `presence`: Alterações no status de presença - `groups`: Modificações em grupos - `labels`: Gerenciamento de etiquetas - `chats`: Eventos de conversas - `chat_labels`: Alterações em etiquetas de conversas - `blocks`: Bloqueios/desbloqueios - `sender`: Atualizações de campanhas, quando inicia, e quando completa Os nomes acima são o contrato público estável. Aliases nativos recebidos de integrações antigas, como `group.participants`, `call.offer`, `label.association` e `message.reaction`, são aceitos na configuração e normalizados respectivamente para `groups`, `call`, `chat_labels` e `messages_update`. Qualquer nome desconhecido retorna HTTP 400 sem salvar parte da configuração. **Remover mensagens com base nos filtros**: - `wasSentByApi`: Mensagens originadas pela API ⚠️ **IMPORTANTE:** Use sempre este filtro para evitar loops em automações - `wasNotSentByApi`: Mensagens não originadas pela API - `fromMeYes`: Mensagens enviadas pelo usuário - `fromMeNo`: Mensagens recebidas de terceiros - `isGroupYes`: Mensagens em grupos - `isGroupNo`: Mensagens em conversas individuais 💡 **Prevenção de Loops**: Se você tem automações que enviam mensagens via API, sempre inclua `"excludeMessages": ["wasSentByApi"]` no seu webhook. Caso prefira receber esses eventos, certifique-se de que sua automação detecta mensagens enviadas pela própria API para não criar loops infinitos. **Ações Suportadas**: - `add`: Registrar novo webhook - `delete`: Remover webhook existente **Parâmetros de URL**: - `addUrlEvents` (boolean): Quando ativo, adiciona o tipo do evento como path parameter na URL. Exemplo: `https://api.example.com/webhook/{evento}` - `addUrlTypesMessages` (boolean): Quando ativo, adiciona o tipo da mensagem como path parameter na URL. Exemplo: `https://api.example.com/webhook/{tipo_mensagem}` **Combinações de Parâmetros**: - Ambos ativos: `https://api.example.com/webhook/{evento}/{tipo_mensagem}` Exemplo real: `https://api.example.com/webhook/message/conversation` - Apenas eventos: `https://api.example.com/webhook/message` - Apenas tipos: `https://api.example.com/webhook/conversation` **Notas Técnicas**: 1. Os parâmetros são adicionados na ordem: evento → tipo mensagem 2. A URL deve ser configurada para aceitar esses parâmetros dinâmicos 3. Funciona com qualquer combinação de eventos/mensagens' security: - InstanceToken: [] parameters: [] requestBody: content: application/json: schema: type: object oneOf: - title: Criar ou atualizar webhook required: - url not: required: - action properties: action: const: delete - title: Excluir webhook required: - action - id properties: action: const: delete properties: id: type: string description: ID único do webhook (necessário para update/delete) example: 123e4567-e89b-12d3-a456-426614174000 enabled: type: boolean description: Habilita/desabilita o webhook example: true url: type: string description: URL para receber os eventos example: https://example.com/webhook events: type: array description: Lista de eventos monitorados items: type: string enum: - connection - history - messages - messages_update - newsletter_messages - call - contacts - presence - groups - labels - chats - chat_labels - blocks - sender - message_limits excludeMessages: type: array description: Filtros para excluir tipos de mensagens items: type: string enum: - wasSentByApi - wasNotSentByApi - fromMeYes - fromMeNo - isGroupYes - isGroupNo addUrlEvents: type: boolean description: | Adiciona o tipo do evento como parâmetro na URL. - `false` (padrão): URL normal - `true`: Adiciona evento na URL (ex: `/webhook/message`) default: false addUrlTypesMessages: type: boolean description: > Adiciona o tipo da mensagem como parâmetro na URL. - `false` (padrão): URL normal - `true`: Adiciona tipo da mensagem (ex: `/webhook/conversation`) default: false action: type: string description: | Ação a ser executada: - add: criar novo webhook - update: atualizar webhook existente (requer id) - delete: remover webhook (requer apenas id) Se não informado, opera no modo simples (único webhook) enum: - add - update - delete example: enabled: true url: https://webhook.cool/example events: - messages - newsletter_messages - connection excludeMessages: - wasSentByApi responses: "200": description: Webhook configurado ou atualizado com sucesso content: application/json: schema: type: array items: type: object description: Estrutura descrita pelo exemplo desta operação. "400": description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: Invalid action "401": description: Token inválido ou não fornecido content: application/json: schema: type: object properties: error: type: string example: missing token "402": description: Assinatura inativa ou período de teste encerrado. content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: A instância não está conectada ao WhatsApp (código INSTANCE_NOT_CONNECTED). content: application/json: schema: $ref: "#/components/schemas/Error" "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" "500": description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Could not save webhook x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Entrega eventos reais da instância e do processamento de mensagens. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas. /webhook/errors: get: tags: - Webhooks e SSE operationId: getWebhookErrors summary: Ver últimos erros do webhook local description: 'Retorna os últimos 20 erros de entrega persistidos dos webhooks locais da instância autenticada. Cada item corresponde a uma entrega real em nova tentativa ou dead letter e inclui o ID estável da entrega, data/hora, URL de destino, evento, tipo do webhook (`local`), payload preservado, número de tentativas, status HTTP final quando existir e a mensagem de erro. Observações: - O histórico é persistente e sobrevive à reinicialização do processo. - Entregas concluídas com sucesso deixam de aparecer como erro. - `retryable=true` indica uma nova tentativa automática; dead letter exige replay manual. - O endpoint usa o mesmo `token` da instância. - Retorna apenas falhas dos webhooks locais da própria instância. - Falhas do webhook global ficam disponíveis separadamente em `/globalwebhook/errors` com `credencial administrativa`. Exemplo de consulta: ```bash curl -X GET "$BASE_URL/webhook/errors" \ -H "token: SUA_INSTANCIA_TOKEN" ```' security: - InstanceToken: [] parameters: [] responses: "200": description: Histórico retornado com sucesso content: application/json: schema: type: array items: type: object properties: delivery_id: type: string format: uuid event_id: type: string webhook_id: type: string created: type: string format: date-time example: 2026-03-23T15:04:05Z url: type: string example: https://example.com/webhook/messages type: type: string example: local event: type: string example: messages message_type: type: string example: text status_code: type: integer example: 502 attempts: type: integer example: 3 status: type: string enum: - pending - dead_letter retryable: type: boolean next_attempt_at: type: string format: date-time error: type: string example: "webhook returned non-success status: 502 Bad Gateway" payload: type: object example: - created: 2026-03-23T15:04:05Z delivery_id: 123e4567-e89b-12d3-a456-426614174000 event_id: evt_abc123 webhook_id: webhook_abc123 url: https://example.com/webhook/messages type: local event: messages message_type: text status_code: 502 attempts: 3 status: dead_letter retryable: false error: "webhook returned non-success status: 502 Bad Gateway" payload: EventType: messages token: instance-token "401": description: Token inválido ou não fornecido content: application/json: schema: type: object properties: error: type: string example: missing token "428": description: "Pré-condição ausente: aceite vigente ou chave Idempotency-Key/track_id obrigatória para esta mutação." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: Limite de requisições atingido (60 por minuto por credencial). A resposta traz limit e retryAfterSeconds. content: application/json: schema: $ref: "#/components/schemas/Error" x-relya-status: operational x-relya-status-label: Operacional x-relya-note: Entrega eventos reais da instância e do processamento de mensagens. x-relya-runtime-status: status: available available: true reason: Rota registrada no runtime deste release; sessao, permissao e prova ao vivo continuam sendo pre-condicoes separadas.