{ "openapi": "3.1.0", "info": { "title": "Wafly — API de WhatsApp", "version": "1.0.0", "description": "APIs da Wafly para WhatsApp por QR Code e API Oficial da Meta. A API Bridge usa Client-Token e credenciais da instância; a API do Produto usa Bearer JWT, sempre isolado pela conta autenticada.", "contact": { "name": "Suporte Wafly", "url": "https://wafly.com.br/api-docs" } }, "servers": [ { "url": "https://wafly.com.br", "description": "Produção" } ], "paths": { "/api-managment/external/instances": { "post": { "operationId": "partner-create-instance", "summary": "Criar instância ou obter exemplo", "description": "Disponível para contas ativas, incluindo parceiros. Sem assinatura Stripe ativa com cartão: HTTP 200, created=false e exampleResponse fictício. Para criação real, confirme acceptAutomaticBilling=true: HTTP 201, created=true e credenciais em data. Cada nova instância tem 72 horas antes da cobrança proporcional na assinatura existente. Cancele antes do vencimento para evitar a cobrança.\n\nTrate created=false como demonstração. As credenciais de exampleResponse nunca funcionam e a chamada não cria instâncias.\n\nBILLING_CONFIRMATION_REQUIRED: informe acceptAutomaticBilling=true somente para autorizar uma criação real. PROVISIONING_NOT_ENABLED: a criação real ainda não foi habilitada.\n\nO teste inicial sem cartão continua disponível pelo painel. Ser parceiro ou ter instância gratuita não habilita cobrança pela API.\n\nA expiração é individual, em milissegundos Unix, e não é renovada. Se o cartão ou a assinatura deixarem de ser válidos, a instância será suspensa.\n\nUse Client-Token de Segurança no painel. Não distribua o token da sua conta aos seus clientes finais.\n\nGuarde instance e token de data para usar os endpoints de mensagens, QR e webhooks existentes. Cada chamada real cria uma nova instância; não repita automaticamente após timeout. Consulte a listagem primeiro.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptAutomaticBilling": { "type": "boolean", "description": "Consentimento para cobrança automática após 3 dias. false ou omitido retorna somente exemplo.", "example": "false" }, "receivedCallbackUrl": { "type": "string", "description": "Webhook de mensagens recebidas." }, "deliveryCallbackUrl": { "type": "string", "description": "Webhook de entrega." }, "disconnectedCallbackUrl": { "type": "string", "description": "Webhook de desconexão." }, "messageStatusCallbackUrl": { "type": "string", "description": "Webhook de status." } } }, "example": { "acceptAutomaticBilling": false } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "created": false, "mode": "preview", "code": "ACTIVATION_REQUIRED", "message": "Nenhuma instância foi criada ou cobrada. Ative sua primeira instância pelo painel. O exemplo usa credenciais fictícias; a criação real terá o mesmo formato. O teste inicial no painel continua sem cartão.", "exampleResponse": { "created": true, "mode": "live", "code": "INSTANCE_CREATED", "message": "Instância criada. Após 3 dias, será adicionada à assinatura contratada com cobrança proporcional, se não for cancelada.", "data": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Exemplo", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000, "token": "EXAMPLE_TOKEN_NOT_VALID" } }, "nextAction": { "type": "ACTIVATE_FIRST_INSTANCE", "url": "/instances" } } } } }, "201": { "description": "Instância real criada", "content": { "application/json": { "example": { "created": true, "mode": "live", "code": "INSTANCE_CREATED", "message": "Instância criada. Após 3 dias, será adicionada à assinatura contratada com cobrança proporcional, se não for cancelada.", "data": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Exemplo", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000, "token": "EXAMPLE_TOKEN_NOT_VALID" } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } }, "get": { "operationId": "external-list-instances", "summary": "Listar minhas instâncias", "description": "Lista somente instâncias desta conta, sem tokens nem informações de infraestrutura.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página a partir de 1. Padrão: 1.", "schema": { "type": "integer", "description": "Página a partir de 1. Padrão: 1." } }, { "name": "limit", "in": "query", "required": false, "description": "Entre 1 e 100. Padrão: 20.", "schema": { "type": "integer", "description": "Entre 1 e 100. Padrão: 20." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Exemplo", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000 } ], "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } } }, "/api-managment/external/instances/{instance}": { "get": { "operationId": "external-get-instance", "summary": "Consultar instância", "description": "Retorna conexão, cobrança e vencimento registrados para esta instância. Sem token.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Exemplo", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } }, "patch": { "operationId": "external-rename-instance", "summary": "Renomear instância", "description": "Altera o nome de exibição. O código instance e as credenciais continuam iguais.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de exibição com 1 a 80 caracteres." } }, "required": [ "name" ] }, "example": { "name": "Atendimento" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Atendimento", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } }, "delete": { "operationId": "external-cancel-instance", "summary": "Cancelar instância", "description": "Cancela pelo gateway de pagamento. Antes de 72 horas, remove o teste sem adicionar à assinatura. Instâncias pagas seguem as regras de cancelamento e estorno da contratação; consulte cancellation-preview antes. cleanupPending=true indica que a cobrança já foi cancelada e a limpeza da sessão será repetida em segundo plano.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "success": true, "scheduled": false, "immediate": true, "refundIssued": false, "cleanupPending": false } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } } }, "/api-managment/external/instances/{instance}/credentials": { "get": { "operationId": "external-instance-credentials", "summary": "Consultar credenciais", "description": "Retorna o token apenas de uma instância pertencente à conta. Guarde as credenciais no servidor.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instance": "EXAMPLE_INSTANCE_NOT_VALID", "name": "Exemplo", "connected": false, "billingStatus": "trial", "isTrial": true, "expirationTime": 1893456000000, "token": "EXAMPLE_TOKEN_NOT_VALID" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } } }, "/api-managment/external/instances/{instance}/restart": { "post": { "operationId": "external-restart-instance", "summary": "Reiniciar instância", "description": "Reinicia uma instância com acesso ativo. Pode exigir novo QR code.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "success": true, "connected": false, "requiresQr": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } } }, "/api-managment/external/instances/{instance}/cancellation-preview": { "get": { "operationId": "external-cancellation-preview", "summary": "Consultar consequências do cancelamento", "description": "Mostra se o cancelamento é imediato ou agendado e as regras de estorno aplicáveis, antes de confirmar.", "tags": [ "Gerenciamento pela API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "Código da instância pertencente à conta.", "schema": { "type": "string", "description": "Código da instância pertencente à conta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "mode": "trial", "message": "Instância em teste: remoção imediata, sem cobrança.", "refund_full_instance": false, "within_instance_refund_period": false } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "403": { "description": "Conta inativa" }, "404": { "description": "Instância não encontrada nesta conta" }, "409": { "description": "Operação em andamento; consulte a instância antes de tentar novamente" }, "503": { "description": "Serviço temporariamente indisponível" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/status": { "get": { "operationId": "get-status", "summary": "Status da sessão", "description": "Retorna o estado atual da conexão da instância.\n\nValores possíveis: INITIALIZING | CONNECTED | CLOSED | QRCODE\n\nQRCODE = aguardando escaneamento; CONNECTED = ativo; CLOSED = desconectado.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": "CONNECTED" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/qr-code/image": { "get": { "operationId": "get-qr-code", "summary": "QR Code para conexão", "description": "Retorna o QR Code em base64 para autenticar o WhatsApp.\n\nSe a instância já estiver conectada, retorna { \"value\": \"connected\" }.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": "data:image/png;base64,iVBORw0KGgo..." } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/passkey-challenge": { "get": { "operationId": "passkey-challenge", "summary": "Desafio de passkey (WebAuthn)", "description": "Para contas do WhatsApp protegidas por passkey: após o QR ser escaneado, retorna o desafio WebAuthn que o navegador do dono da conta deve assinar.\n\nFluxo recomendado: use o botão \"Conectar com passkey\" na página da instância do painel, com a extensão Wafly Passkey Connector instalada — ela executa a assinatura automaticamente.\n\nA assinatura só pode ser feita numa página de origem whatsapp.com (regra do WebAuthn) — por isso a extensão é necessária.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/passkey-response": { "post": { "operationId": "passkey-response", "summary": "Enviar assinatura de passkey", "description": "Recebe a assertion WebAuthn assinada no navegador do dono da conta e conclui o pareamento no WhatsApp.\n\nEnvie o JSON da assertion EXATAMENTE como gerado pelo navegador (credential.toJSON(), base64url sem padding) — não reserializar.\n\nUse Content-Type: text/plain para preservar o corpo verbatim.\n\nO desafio é de uso único e o QR renova a cada ~20s: escaneie o QR e envie a assinatura em seguida (pode precisar de 1-2 tentativas).", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "accepted": true, "message": "assertion encaminhada ao WhatsApp" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/phone-exists-batch": { "post": { "operationId": "phone-exists-batch", "summary": "Verificar números no WhatsApp", "description": "Verifica em lote quais números possuem conta no WhatsApp.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phones": { "type": "array", "items": {}, "description": "Lista de números a verificar (formato internacional: 5511...).", "example": "[\"5511999999999\",\"5511888888888\"]" } }, "required": [ "phones" ] }, "example": { "phones": [ "5511999999999", "5511888888888" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": [ { "phone": "5511999999999", "exists": true }, { "phone": "5511888888888", "exists": false } ] } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/device": { "get": { "operationId": "get-device", "summary": "Informações do dispositivo", "description": "Retorna dados do dispositivo conectado ao WhatsApp.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/connect": { "post": { "operationId": "connect", "summary": "Conectar instância", "description": "Inicia ou reconecta a sessão da instância. Recomendado antes de obter QR Code ou código de pareamento.\n\nChame este endpoint antes de /pairing-code ou /qr-code quando a instância estiver desconectada.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "message": "Reconnect success" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/disconnect": { "get": { "operationId": "disconnect", "summary": "Desconectar instância", "description": "Encerra a sessão ativa do WhatsApp.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/restart": { "get": { "operationId": "restart", "summary": "Reiniciar instância", "description": "Reinicia a sessão sem desconectar o WhatsApp.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/queue": { "delete": { "operationId": "purge-message-queue", "summary": "Limpar fila de mensagens", "description": "Descarta de forma irreversível as mensagens de saída que ainda não foram entregues, usando o horário da chamada como corte.\n\nResposta HTTP 202: a operação foi aceita e pode levar até um minuto para se propagar.\n\nPause novos envios antes de chamar se precisar de um corte estrito.\n\nA API não informa uma quantidade removida porque o Pub/Sub não devolve essa contagem no seek.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "confirm", "in": "query", "required": true, "description": "Deve ser true para confirmar a limpeza irreversível.", "schema": { "type": "boolean", "description": "Deve ser true para confirmar a limpeza irreversível.", "example": "true" } } ], "responses": { "202": { "description": "Operação aceita", "content": { "application/json": { "example": { "value": true, "instance": "MINHA_INSTANCE", "discarded_before": "2026-09-24T16:56:25Z", "message": "Limpeza solicitada; mensagens anteriores ao horário de corte serão descartadas" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/pairing-code": { "get": { "operationId": "pairing-code", "summary": "Código de emparelhamento (GET)", "description": "Gera um código de pareamento para conectar o WhatsApp sem QR Code. O número deve ser enviado na query string.\n\nAlternativa ao QR Code para ambientes sem câmera.\n\nChame POST /connect antes se a instância estiver desconectada.\n\nNo WhatsApp: Aparelhos conectados → Conectar aparelho → Conectar com número de telefone.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Número de telefone da conta WhatsApp a conectar (formato internacional, ex: 5511999999999).", "schema": { "type": "string", "description": "Número de telefone da conta WhatsApp a conectar (formato internacional, ex: 5511999999999).", "example": "5511999999999" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "code": "ABCD-1234", "message": "Successfully requested pairing code" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "pairing-code-post", "summary": "Código de emparelhamento (POST)", "description": "Mesmo comportamento do GET: gera o código de pareamento. O número deve ser enviado na query string (?phone=).\n\nNão envie o telefone no body — use sempre o parâmetro de query ?phone=.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Número de telefone da conta WhatsApp a conectar (formato internacional, ex: 5511999999999).", "schema": { "type": "string", "description": "Número de telefone da conta WhatsApp a conectar (formato internacional, ex: 5511999999999).", "example": "5511999999999" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "code": "ABCD-1234", "message": "Successfully requested pairing code" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/restart-with-disconnect": { "post": { "operationId": "restart-with-disconnect", "summary": "Reiniciar com desconexão", "description": "Reinicia a sessão forçando desconexão do WhatsApp antes de reiniciar.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean", "description": "Se true, mantém a sessão conectada após reiniciar. Padrão: false." } } }, "example": { "connected": false } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/inbound-config": { "put": { "operationId": "set-inbound-config", "summary": "Agrupar mensagens picotadas (buffer)", "description": "Agrupa mensagens seguidas do mesmo contato em UMA chamada de webhook. Ninguém escreve um parágrafo no WhatsApp: a pessoa manda \"oi\", depois \"tudo bem?\", depois \"queria saber o preço\" — três webhooks, e um agente de IA responde três vezes. Com o buffer ligado, chega uma chamada só.\n\nO payload do webhook mantém a mesma estrutura: os textos chegam juntos em text.message, mais um campo informativo buffered. Quando só chega uma mensagem, o payload sai idêntico ao de antes, sem campo extra.\n\nMídia, reação e resposta de botão NUNCA são agrupadas — e se houver texto esperando na janela, ele é entregue ANTES delas, então a ordem da conversa nunca se inverte.\n\nValor fora dos limites não é aceito em silêncio: é ajustado e a correção volta no campo notes da resposta.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "buffer.enabled": { "type": "boolean", "description": "Liga o agrupamento. Sem configuração, a instância entrega um webhook por mensagem." }, "buffer.window_ms": { "type": "number", "description": "Janela de silêncio em ms. REINICIA a cada mensagem nova, então a entrega sai quando a pessoa para de digitar. Padrão 8000, máximo 20000." }, "buffer.max_wait_ms": { "type": "number", "description": "Teto absoluto desde a primeira mensagem, para quem digita sem parar não adiar a entrega para sempre. Padrão e máximo 30000." }, "buffer.max_messages": { "type": "number", "description": "Entrega imediatamente ao acumular N mensagens. Padrão 10, máximo 50." }, "buffer.mode": { "type": "string", "description": "concat (padrão) junta os textos no campo de sempre — sua integração não muda uma linha. batch adiciona o array bufferedMessages e muda o formato do payload.", "enum": [ "concat", "batch" ] }, "buffer.include_groups": { "type": "boolean", "description": "Estende o agrupamento a grupos. O agrupamento é por PARTICIPANTE: falas de pessoas diferentes nunca se misturam. Padrão false." } }, "required": [ "buffer.enabled" ] }, "example": { "buffer": { "enabled": true, "window_ms": 8000, "max_messages": 10, "mode": "concat" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "buffer": { "enabled": true, "window_ms": 8000, "max_wait_ms": 30000, "max_messages": 10, "mode": "concat", "include_groups": false }, "notes": [] } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "get": { "operationId": "get-inbound-config", "summary": "Consultar config de entrega", "description": "Retorna a configuração de entrega de mensagens recebidas. Sem configuração, a instância entrega uma chamada de webhook por mensagem. O campo source diz de onde veio a configuração efetiva: instance quando foi você que gravou, default quando veio do padrão da instância.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "source": "instance", "buffer": { "enabled": true, "window_ms": 8000, "mode": "concat" } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "delete": { "operationId": "delete-inbound-config", "summary": "Voltar ao padrão", "description": "Remove a configuração da instância e volta ao padrão. Atenção: voltar ao padrão não é o mesmo que desligar o agrupamento — a resposta traz a configuração efetiva resultante. Para desligar de forma explícita, use PUT com buffer.enabled = false.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/ai-config": { "put": { "operationId": "set-ai-config", "summary": "Transcrever áudio recebido (chave sua)", "description": "Liga a transcrição automática de áudio recebido. Metade da conversa no WhatsApp brasileiro é áudio, e um agente de IA não escuta — com isso ligado, o texto já chega no webhook e você não precisa montar download + speech-to-text. A chave do provedor é SUA: o custo cai na sua conta da OpenAI e a Wafly não cobra nada por isso.\n\nO webhook de áudio ganha um campo transcription com o texto: { \"status\": \"ok\", \"text\": \"...\", \"latency_ms\": 1180 }. O resto do payload nao muda.\n\nFalha nunca engole a mensagem: se o provedor recusar, o webhook sai igual ao de sempre com transcription.status = error e o motivo (invalid_api_key, quota_exceeded, cap_reached, audio_too_long, provider_timeout).\n\nA chave é gravada cifrada e vinculada à instância: o registro não funciona se for copiado para outra instância.\n\nInstância sem essa configuração não recebe nem o campo transcription — comportamento idêntico ao de antes.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "description": "Provedor de transcrição. Hoje apenas openai. Padrão: openai.", "enum": [ "openai" ] }, "api_key": { "type": "string", "description": "Sua chave do provedor. É gravada cifrada (AES-256-GCM) e NUNCA é devolvida: no GET vem mascarada. Envie vazio em chamadas seguintes para manter a chave já cadastrada e alterar só os demais campos." }, "transcription.enabled": { "type": "boolean", "description": "Liga a transcrição do áudio recebido." }, "transcription.model": { "type": "string", "description": "Modelo de transcrição. Padrão: whisper-1." }, "transcription.max_audio_seconds": { "type": "number", "description": "Ignora áudios mais longos que isso, protegendo você de custo inesperado. Padrão 300." }, "transcription.monthly_minutes_cap": { "type": "number", "description": "Teto de minutos transcritos por mês. Se você não informar, aplicamos 500 por padrão — deixar ilimitado faria você descobrir o custo pela fatura do provedor." } }, "required": [ "api_key", "transcription.enabled" ] }, "example": { "provider": "openai", "api_key": "sk-proj-...", "transcription": { "enabled": true, "max_audio_seconds": 300, "monthly_minutes_cap": 500 } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "provider": "openai", "api_key": "sk-••••••••x9f2", "transcription": { "enabled": true, "model": "whisper-1", "max_audio_seconds": 300, "monthly_minutes_cap": 500 }, "usage": { "month": "2026-07", "minutes_used": 12, "minutes_cap": 500 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "get": { "operationId": "get-ai-config", "summary": "Consultar config de transcrição", "description": "Retorna a configuração de transcrição e o consumo do mês. A chave nunca é devolvida — só a máscara.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "provider": "openai", "api_key": "sk-••••••••x9f2", "transcription": { "enabled": true, "model": "whisper-1" }, "usage": { "month": "2026-07", "minutes_used": 12, "minutes_cap": 500 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "delete": { "operationId": "delete-ai-config", "summary": "Remover chave e desligar transcrição", "description": "Apaga a credencial cadastrada e desliga a transcrição.", "tags": [ "Instância" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "removed": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-text": { "post": { "operationId": "send-text", "summary": "Enviar mensagem de texto", "description": "Envia uma mensagem de texto simples para um número privado, grupo ou newsletter/canal.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário. Número privado ex: 5511999999999 | Grupo: ID-group | Newsletter: ID@newsletter", "example": "5511999999999" }, "message": { "type": "string", "description": "Conteúdo da mensagem.", "example": "Olá! Mensagem via API Wafly" }, "delayMessage": { "type": "number", "description": "Tempo de espera em milissegundos antes de enviar (simula digitação).", "example": "1500" }, "messageId": { "type": "string", "description": "ID de uma mensagem existente para responder (reply)." }, "editMessageId": { "type": "string", "description": "ID de uma mensagem sua já enviada para editar o conteúdo." }, "fromMe": { "type": "boolean", "description": "Obrigatório junto de editMessageId: confirma que a mensagem a editar é sua. Sem ele a edição é ignorada.", "example": "true" }, "isGroup": { "type": "boolean", "description": "Declara que o destino é um grupo. Se true, o sufixo -group é adicionado ao phone quando faltar; se false e o phone for de grupo, a requisição é rejeitada.", "example": "false" }, "mentioned": { "type": "array", "items": {}, "description": "Lista de números mencionados na mensagem (apenas em grupos).", "example": "[\"5511999999999\"]" } }, "required": [ "phone", "message" ] }, "example": { "phone": "5511999999999", "message": "Olá! Mensagem via API Wafly" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-template": { "post": { "operationId": "send-template", "summary": "Enviar template oficial aprovado", "description": "Executa uma revisão local aprovada de template em uma instância com provider Oficial. Nome, idioma, WABA e ativos Meta são relidos no backend pelo templateId.\n\nDisponível somente para instâncias com provider Oficial.\n\nparameters e components são formatos alternativos e não podem ser enviados juntos com valores.\n\nBotões URL estáticos e telefone já pertencem ao template aprovado e não devem ser repetidos em components. Envie somente botões que exigem valor em tempo de execução, preservando o index da revisão.\n\nCOPY_CODE exige um COUPON_CODE de até 15 caracteres no envio.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Número individual do destinatário.", "example": "5511999999999" }, "templateId": { "type": "string", "description": "ID do template armazenado localmente.", "example": "template-local-id" }, "revision": { "type": "integer", "description": "Número positivo da revisão local aprovada.", "example": "1" }, "parameters": { "type": "array", "items": {}, "description": "Compatibilidade v1: até 100 valores interpretados exclusivamente como BODY/TEXT. Não use junto de components." }, "components": { "type": "array", "items": {}, "description": "Até 12 componentes tipados. Cada item aceita type (HEADER, BODY ou BUTTON), subType opcional (URL, QUICK_REPLY ou COPY_CODE), index opcional e parameters. Os parâmetros aceitam type TEXT, CURRENCY, DATE_TIME, IMAGE, VIDEO, DOCUMENT, LOCATION, PAYLOAD ou COUPON_CODE e o valor correspondente em text, currency, dateTime, media, location, payload ou couponCode." } }, "required": [ "phone", "templateId", "revision" ] }, "example": { "phone": "5511999999999", "templateId": "template-local-id", "revision": 1, "components": [ { "type": "BODY", "parameters": [ { "type": "TEXT", "text": "Maria" } ] }, { "type": "BUTTON", "subType": "QUICK_REPLY", "index": 0, "parameters": [ { "type": "PAYLOAD", "payload": "responder-123" } ] }, { "type": "BUTTON", "subType": "COPY_CODE", "index": 1, "parameters": [ { "type": "COUPON_CODE", "couponCode": "PROMO25" } ] } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "messageId": "3EB0XXXX", "instance": "MINHA_INSTANCE", "message": "" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-image": { "post": { "operationId": "send-image", "summary": "Enviar imagem", "description": "Envia uma imagem usando URL pública ou string base64.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário.", "example": "5511999999999" }, "image": { "type": "string", "description": "URL pública da imagem ou string base64 (data:image/jpeg;base64,...)", "example": "https://exemplo.com/imagem.jpg" }, "caption": { "type": "string", "description": "Legenda exibida abaixo da imagem." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "mentioned": { "type": "array", "items": {}, "description": "Números mencionados (apenas grupos)." } }, "required": [ "phone", "image" ] }, "example": { "phone": "5511999999999", "image": "https://exemplo.com/imagem.jpg", "caption": "Legenda opcional" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-audio": { "post": { "operationId": "send-audio", "summary": "Enviar áudio", "description": "Envia um arquivo de áudio (mp3/ogg) por URL ou base64.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "audio": { "type": "string", "description": "URL pública do áudio ou base64." }, "delayMessage": { "type": "number", "description": "Delay em ms antes de enviar." }, "messageId": { "type": "string", "description": "ID para reply." } }, "required": [ "phone", "audio" ] }, "example": { "phone": "5511999999999", "audio": "https://exemplo.com/audio.mp3" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-video": { "post": { "operationId": "send-video", "summary": "Enviar vídeo", "description": "Envia um vídeo por URL ou base64.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "video": { "type": "string", "description": "URL ou base64 do vídeo." }, "caption": { "type": "string", "description": "Legenda do vídeo." }, "messageId": { "type": "string", "description": "ID para reply." }, "isPtv": { "type": "boolean", "description": "Envia o vídeo como mensagem de vídeo circular (formato \"recadinho\").", "example": "true" }, "mentioned": { "type": "array", "items": {}, "description": "Lista de números mencionados (apenas em grupos)." } }, "required": [ "phone", "video" ] }, "example": { "phone": "5511999999999", "video": "https://exemplo.com/video.mp4", "caption": "Legenda opcional" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-document/{type}": { "post": { "operationId": "send-document", "summary": "Enviar documento", "description": "Envia um documento (PDF, XLSX, etc) por URL ou base64. O parâmetro de rota {type} define a extensão, ex: pdf.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Extensão do arquivo", "schema": { "type": "string", "description": "Extensão do arquivo", "enum": [ "pdf", "xlsx", "docx", "csv", "txt" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "document": { "type": "string", "description": "URL ou base64 do documento." }, "fileName": { "type": "string", "description": "Nome do arquivo exibido." }, "caption": { "type": "string", "description": "Legenda." }, "messageId": { "type": "string", "description": "ID para reply." } }, "required": [ "phone", "document" ] }, "example": { "phone": "5511999999999", "document": "https://exemplo.com/arquivo.pdf", "fileName": "relatorio.pdf" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-link": { "post": { "operationId": "send-link", "summary": "Enviar link com prévia", "description": "Envia um link com card de prévia (título, descrição e imagem).\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "message": { "type": "string", "description": "Texto que acompanha o link." }, "linkUrl": { "type": "string", "description": "URL do link." }, "title": { "type": "string", "description": "Título exibido no card." }, "linkDescription": { "type": "string", "description": "Descrição exibida no card." }, "delayMessage": { "type": "number", "description": "Delay em ms." } }, "required": [ "phone", "message", "linkUrl" ] }, "example": { "phone": "5511999999999", "message": "Confira nossa plataforma", "linkUrl": "https://wafly.com.br", "title": "Wafly", "linkDescription": "API WhatsApp gerenciada" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-poll": { "post": { "operationId": "send-poll", "summary": "Enviar enquete", "description": "Cria uma enquete com opções de resposta.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "message": { "type": "string", "description": "Pergunta da enquete." }, "poll": { "type": "array", "items": {}, "description": "Lista de opções da enquete.", "example": "[{\"optionName\":\"Sim\"},{\"optionName\":\"Não\"}]" }, "pollMaxOptions": { "type": "number", "description": "Máximo de opções que o usuário pode selecionar. Padrão: 1.", "example": "1" }, "messageId": { "type": "string", "description": "ID para reply." } }, "required": [ "phone", "message", "poll" ] }, "example": { "phone": "5511999999999", "message": "Qual sua cor favorita?", "poll": [ { "optionName": "Azul" }, { "optionName": "Verde" }, { "optionName": "Vermelho" } ], "pollMaxOptions": 1 } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-contacts": { "post": { "operationId": "send-contacts", "summary": "Enviar contato", "description": "Envia um card de contato.\n\nFormato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Destinatário." }, "contactPhone": { "type": "string", "description": "Número do contato a ser enviado." }, "contactName": { "type": "string", "description": "Nome do contato." }, "contacts": { "type": "array", "items": {}, "description": "Lista de números para enviar múltiplos contatos de uma vez." } }, "required": [ "phone" ] }, "example": { "phone": "5511999999999", "contactPhone": "5511888888888", "contactName": "João Silva" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "messageId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/delete-message": { "delete": { "operationId": "delete-message", "summary": "Deletar mensagem", "description": "Remove uma mensagem enviada do chat.\n\nA exclusão para todos (owner=true) só é possível dentro de 60 minutos do envio.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "messageId", "in": "query", "required": true, "description": "ID da mensagem a deletar.", "schema": { "type": "string", "description": "ID da mensagem a deletar." } }, { "name": "phone", "in": "query", "required": true, "description": "Destinatário do chat onde a mensagem foi enviada.", "schema": { "type": "string", "description": "Destinatário do chat onde a mensagem foi enviada." } }, { "name": "owner", "in": "query", "required": true, "description": "true para apagar para todos; false para apagar somente para você.", "schema": { "type": "boolean", "description": "true para apagar para todos; false para apagar somente para você." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/pin-message": { "post": { "operationId": "pin-message", "summary": "Fixar mensagem", "description": "Fixa ou desafixa uma mensagem no topo do chat.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Chat onde a mensagem está.", "example": "5511999999999" }, "messageId": { "type": "string", "description": "ID da mensagem a fixar.", "example": "77DF5293EBC176FFA6A88838E7A6AD83" }, "messageAction": { "type": "string", "description": "Fixar ou desafixar.", "enum": [ "pin", "unpin" ], "example": "pin" }, "pinMessageDuration": { "type": "string", "description": "Por quanto tempo a mensagem fica fixada.", "enum": [ "24_hours", "7_days", "30_days" ], "example": "7_days" }, "sender": { "type": "string", "description": "Autor da mensagem. Necessário quando o chat é um grupo.", "example": "5511888888888" } }, "required": [ "phone", "messageId", "messageAction", "pinMessageDuration" ] }, "example": { "phone": "5511999999999", "messageId": "77DF5293EBC176FFA6A88838E7A6AD83", "messageAction": "pin", "pinMessageDuration": "7_days" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-option-list": { "post": { "operationId": "send-option-list", "summary": "Enviar lista de opções", "description": "Envia uma mensagem interativa com lista de opções para o usuário selecionar.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "5511999999999" }, "message": { "type": "string", "description": "Texto exibido acima da lista." }, "optionList": { "type": "object", "description": "Objeto com title (string), buttonLabel (string) e options (array de { id, title, description })." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (apenas grupos)." } }, "required": [ "phone", "message", "optionList" ] }, "example": { "phone": "5511999999999", "message": "Escolha o que melhor descreve a Wafly:", "optionList": { "title": "Selecione uma opção abaixo:", "buttonLabel": "Clique aqui", "options": [ { "id": "1", "title": "Eficiência", "description": "A melhor plataforma de automação" }, { "id": "2", "title": "Suporte", "description": "Atendimento excepcional ao cliente" } ] } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-gif": { "post": { "operationId": "send-gif", "summary": "Enviar GIF", "description": "Envia um GIF via URL pública ou base64.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "5511999999999" }, "gif": { "type": "string", "description": "URL pública ou base64 do GIF." }, "caption": { "type": "string", "description": "Legenda exibida abaixo do GIF." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se a mensagem é do próprio usuário." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (grupos)." } }, "required": [ "phone", "gif" ] }, "example": { "phone": "5511999999999", "gif": "https://devzapp.com.br/v2/animation.gif", "caption": "Confira este GIF!" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-ptv": { "post": { "operationId": "send-ptv", "summary": "Enviar vídeo redondo (PTV)", "description": "Envia um vídeo no formato circular — aparece como vídeo redondo (PTV) no WhatsApp.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "5511999999999" }, "ptv": { "type": "string", "description": "URL pública ou base64 do vídeo." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se a mensagem é do próprio usuário." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (grupos)." } }, "required": [ "phone", "ptv" ] }, "example": { "phone": "5511999999999", "ptv": "https://devzapp.com.br/v2/video.mp4" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-event": { "post": { "operationId": "send-event", "summary": "Enviar evento", "description": "Envia um evento do WhatsApp com data, localização e link de chamada.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "5511999999999" }, "event": { "type": "object", "description": "Objeto do evento: { name, description, dateTime (ISO 8601), location: { name }, callLinkType, canceled }." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "editMessageId": { "type": "string", "description": "ID de um evento existente para editar." }, "fromMe": { "type": "boolean", "description": "true se a mensagem é do próprio usuário." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (grupos)." } }, "required": [ "phone", "event" ] }, "example": { "phone": "5511999999999", "event": { "name": "Webinar Wafly", "description": "Automação de WhatsApp com IA", "dateTime": "2026-04-01T10:00:00", "location": { "name": "Online" }, "callLinkType": "ZOOM", "canceled": false } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-button-actions": { "post": { "operationId": "send-button-actions", "summary": "Enviar botões de ação", "description": "Envia uma mensagem com botões que executam ações (ligar ou abrir URL).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "551199999999" }, "message": { "type": "string", "description": "Texto principal da mensagem." }, "title": { "type": "string", "description": "Título exibido no topo." }, "footer": { "type": "string", "description": "Rodapé exibido abaixo dos botões." }, "buttonActions": { "type": "array", "items": {}, "description": "Lista de botões. Cada item: { id, label, type (\"CALL\" | \"URL\"), phone (para CALL), url (para URL) }.", "enum": [ "CALL", "URL" ] }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se do próprio usuário." } }, "required": [ "phone", "buttonActions" ] }, "example": { "phone": "551199999999", "message": "Como podemos ajudar?", "title": "Atendimento", "footer": "Responda em segundos", "buttonActions": [ { "id": "1", "type": "URL", "label": "Visitar site", "url": "https://wafly.com.br" }, { "id": "2", "type": "CALL", "label": "Ligar agora", "phone": "551199999999" } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-button-list": { "post": { "operationId": "send-button-list", "summary": "Enviar lista de botões", "description": "Envia uma mensagem com lista de botões simples de resposta rápida.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "551199999999" }, "message": { "type": "string", "description": "Texto da mensagem." }, "buttonList": { "type": "object", "description": "Objeto: { image (URL opcional), video (URL opcional), buttons: [{ id, label }] }." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se do próprio usuário." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (grupos)." } }, "required": [ "phone", "buttonList" ] }, "example": { "phone": "551199999999", "message": "Z-API é bom?", "buttonList": { "image": "https://imagem.url/foto.jpg", "buttons": [ { "id": "sim", "label": "Sim!" }, { "id": "nao", "label": "Não" } ] } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-button-otp": { "post": { "operationId": "send-button-otp", "summary": "Enviar botão OTP", "description": "Envia uma mensagem com botão para copiar um código OTP (One-Time Password).", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "551199999999" }, "message": { "type": "string", "description": "Texto da mensagem." }, "code": { "type": "string", "description": "Código OTP a ser copiado pelo usuário." }, "image": { "type": "string", "description": "URL de imagem opcional." }, "buttonText": { "type": "string", "description": "Texto do botão de cópia. Padrão: \"Copiar código\"." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se do próprio usuário." } }, "required": [ "phone", "code" ] }, "example": { "phone": "551199999999", "message": "Seu código de verificação:", "code": "123456", "buttonText": "Copiar código" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-button-pix": { "post": { "operationId": "send-button-pix", "summary": "Enviar botão PIX", "description": "Envia uma mensagem com chave PIX e botão de pagamento.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "551199999999" }, "pixKey": { "type": "string", "description": "Chave PIX (e-mail, CPF, CNPJ, telefone ou chave aleatória)." }, "type": { "type": "string", "description": "Tipo da chave PIX.", "enum": [ "EMAIL", "CPF", "CNPJ", "PHONE", "EVP" ] }, "name": { "type": "string", "description": "Nome do recebedor/empresa exibido no card de pagamento." }, "totalAmount": { "type": "number", "description": "Valor exibido no card (ex.: 149.90). Sem valor, exibe R$ 0,00 e o pagador digita o valor." }, "description": { "type": "string", "description": "Descrição do item/cobrança exibida no card." }, "documentUrl": { "type": "string", "description": "URL de PDF de fatura para anexar (muda o formato para documento + botão copiar)." }, "documentTitle": { "type": "string", "description": "Título do PDF anexado." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se do próprio usuário." } }, "required": [ "phone", "pixKey" ] }, "example": { "phone": "551199999999", "pixKey": "pagamentos@wafly.com.br", "type": "EMAIL", "name": "Wafly", "totalAmount": 149.9, "description": "Plano mensal" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/send-carousel": { "post": { "operationId": "send-carousel", "summary": "Enviar carrossel", "description": "Envia um carrossel de cards com imagens e botões interativos.", "tags": [ "Mensagens" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Formato do destinatário: número privado (ex: 5511999999999), grupo (ID-group) ou newsletter/canal (ID@newsletter).", "example": "551199999999" }, "message": { "type": "string", "description": "Texto introdutório antes do carrossel." }, "carousel": { "type": "array", "items": {}, "description": "Lista de cards. Cada card: { text, image (URL), buttons: [{ id, label, type (\"URL\"|\"REPLY\"), url }] }." }, "messageId": { "type": "string", "description": "ID de mensagem para responder." }, "fromMe": { "type": "boolean", "description": "true se do próprio usuário." }, "mentioned": { "type": "array", "items": {}, "description": "Menções (grupos)." } }, "required": [ "phone", "carousel" ] }, "example": { "phone": "551199999999", "message": "Confira nossos planos:", "carousel": [ { "text": "Plano Starter", "image": "https://wafly.com.br/starter.jpg", "buttons": [ { "id": "b1", "label": "Saiba mais", "type": "URL", "url": "https://wafly.com.br/starter" } ] } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/external/official/instances/{instance}/token/{token}/templates": { "post": { "operationId": "official-template-create", "summary": "Criar template Oficial", "description": "Cria o template e, por padrão, valida e envia imediatamente para análise da Meta. Não aceite nem envie WABA ID, Phone Number ID ou token Meta.\n\nO templateId retornado é o ID local usado para consultar status e enviar mensagens.\n\nA aprovação é assíncrona; consulte o recurso até status APPROVED ou REJECTED.\n\nNão repita uma criação com nome e idioma diferentes após timeout sem consultar a lista primeiro.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome técnico em minúsculas e underscore.", "example": "confirmacao_agendamento" }, "language": { "type": "string", "description": "Idioma do template.", "example": "pt_BR" }, "category": { "type": "string", "description": "Categoria Meta.", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ], "example": "UTILITY" }, "components": { "type": "array", "items": {}, "description": "HEADER, BODY, FOOTER, BUTTONS, CAROUSEL ou LIMITED_TIME_OFFER conforme as regras da Meta." }, "submitToMeta": { "type": "boolean", "description": "Padrão true. Se false, mantém como rascunho local.", "example": "true" } }, "required": [ "name", "language", "category", "components" ] }, "example": { "name": "confirmacao_agendamento", "language": "pt_BR", "category": "UTILITY", "components": [ { "type": "BODY", "format": "TEXT", "text": "Olá {{1}}, seu agendamento está confirmado para {{2}}.", "variables": [ { "position": 1, "example": "Maria" }, { "position": 2, "example": "18/09 às 14h" } ], "buttons": [] } ], "submitToMeta": true } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "templateId": "template-local-id", "instanceId": "MINHA_INSTANCE", "name": "confirmacao_agendamento", "language": "pt_BR", "category": "UTILITY", "status": "PENDING", "revision": 1 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "get": { "operationId": "official-template-list-external", "summary": "Listar templates Oficiais", "description": "Lista somente os templates pertencentes à instância autenticada.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "page", "in": "query", "required": false, "description": "Página, iniciando em 1.", "schema": { "type": "integer", "description": "Página, iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página, máximo 100.", "schema": { "type": "integer", "description": "Itens por página, máximo 100.", "example": "20" } }, { "name": "status", "in": "query", "required": false, "description": "Filtro opcional de status.", "schema": { "type": "string", "description": "Filtro opcional de status." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/external/official/instances/{instance}/token/{token}/templates/{templateId}": { "get": { "operationId": "official-template-get-external", "summary": "Consultar template e aprovação", "description": "Retorna status, qualidade, eventual rejeição e componentes sem expor credenciais Meta.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "templateId", "in": "path", "required": true, "description": "ID local retornado pela Wafly.", "schema": { "type": "string", "description": "ID local retornado pela Wafly." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "patch": { "operationId": "official-template-update-external", "summary": "Editar rascunho Oficial", "description": "Atualiza somente templates ainda editáveis. Campos ausentes são preservados.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "templateId", "in": "path", "required": true, "description": "ID local do rascunho.", "schema": { "type": "string", "description": "ID local do rascunho." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome técnico." }, "language": { "type": "string", "description": "Novo idioma." }, "category": { "type": "string", "description": "Nova categoria." }, "components": { "type": "array", "items": {}, "description": "Lista completa de componentes." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "delete": { "operationId": "official-template-delete-external", "summary": "Excluir rascunho Oficial", "description": "Exclui somente um rascunho local que ainda pode ser alterado.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "templateId", "in": "path", "required": true, "description": "ID local do rascunho.", "schema": { "type": "string", "description": "ID local do rascunho." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/external/official/instances/{instance}/token/{token}/templates/{templateId}/validate": { "post": { "operationId": "official-template-validate-external", "summary": "Validar rascunho Oficial", "description": "Aplica as regras da Wafly e da Meta sem enviar o template.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "templateId", "in": "path", "required": true, "description": "ID local do rascunho.", "schema": { "type": "string", "description": "ID local do rascunho." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/external/official/instances/{instance}/token/{token}/templates/{templateId}/submit": { "post": { "operationId": "official-template-submit-external", "summary": "Enviar template à Meta", "description": "Submete uma revisão validada; repetir a chamada após sucesso é idempotente.", "tags": [ "Templates Oficiais — API" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "instance", "in": "path", "required": true, "description": "ID da instância Oficial.", "schema": { "type": "string", "description": "ID da instância Oficial." } }, { "name": "token", "in": "path", "required": true, "description": "Token secreto da instância.", "schema": { "type": "string", "description": "Token secreto da instância." } }, { "name": "templateId", "in": "path", "required": true, "description": "ID local validado.", "schema": { "type": "string", "description": "ID local validado." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/groups": { "get": { "operationId": "list-groups", "summary": "Listar grupos", "description": "Retorna a lista de grupos associados à instância com paginação.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Número da página. Padrão: 1.", "schema": { "type": "number", "description": "Número da página. Padrão: 1." } }, { "name": "pageSize", "in": "query", "required": false, "description": "Itens por página. Padrão: 20.", "schema": { "type": "number", "description": "Itens por página. Padrão: 20." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "groups": [ { "id": "120363XXXX-group", "name": "Grupo Exemplo", "participantsCount": 15 } ] } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/create-group": { "post": { "operationId": "create-group", "summary": "Criar grupo", "description": "Cria um novo grupo e adiciona participantes.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupName": { "type": "string", "description": "Nome do grupo." }, "phones": { "type": "array", "items": {}, "description": "Lista de números dos participantes iniciais.", "example": "[\"5511999999999\",\"5511888888888\"]" }, "autoInvite": { "type": "boolean", "description": "Se true, envia convite automático para participantes não-contatos." } }, "required": [ "groupName", "phones" ] }, "example": { "groupName": "Meu Grupo", "phones": [ "5511999999999", "5511888888888" ], "autoInvite": false } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true, "groupId": "120363XXXX-group" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/add-participant": { "post": { "operationId": "add-participant", "summary": "Adicionar participante", "description": "Adiciona um ou mais participantes a um grupo existente.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (formato: ID-group)." }, "phones": { "type": "array", "items": {}, "description": "Números a adicionar." }, "contacts": { "type": "string", "description": "Alternativa a phones: números separados por vírgula numa única string. Só é lido quando phones não vem preenchido.", "example": "\"5511777777777,5511888888888\"" }, "autoInvite": { "type": "boolean", "description": "Enviar convite automático se o participant não for contato." } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511777777777" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/remove-participant": { "post": { "operationId": "remove-participant", "summary": "Remover participante", "description": "Remove um participante do grupo.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo." }, "phones": { "type": "array", "items": {}, "description": "Números a remover. Sempre um array, mesmo para um único número.", "example": "[\"5511777777777\"]" } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511777777777" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-group-name": { "post": { "operationId": "update-group-name", "summary": "Alterar nome do grupo", "description": "Muda o nome de um grupo (requer ser administrador).", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (ID-group)." }, "groupName": { "type": "string", "description": "Novo nome do grupo." } }, "required": [ "groupId", "groupName" ] }, "example": { "groupId": "120363XXXX-group", "groupName": "Novo Nome do Grupo" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/add-admin": { "post": { "operationId": "add-admin", "summary": "Promover a administrador", "description": "Concede privilégios de administrador a um participante.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo." }, "phones": { "type": "array", "items": {}, "description": "Números a promover. Sempre um array, mesmo para um único número.", "example": "[\"5511999999999\"]" } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511999999999" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/remove-admin": { "post": { "operationId": "remove-admin", "summary": "Remover administrador", "description": "Remove os privilégios de administrador de um participante.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo." }, "phones": { "type": "array", "items": {}, "description": "Números a rebaixar. Sempre um array, mesmo para um único número.", "example": "[\"5511999999999\"]" } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511999999999" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-group-settings": { "post": { "operationId": "update-group-settings", "summary": "Atualizar configurações do grupo", "description": "Altera permissões do grupo como envio de mensagens e adição de membros.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "ID do grupo (ID-group)." }, "adminOnlyMessage": { "type": "boolean", "description": "true = somente admins enviam mensagens." }, "adminOnlySettings": { "type": "boolean", "description": "true = somente admins alteram as configurações." }, "requireAdminApproval": { "type": "boolean", "description": "true = novos membros precisam de aprovação de admin para entrar." }, "adminOnlyAddMember": { "type": "boolean", "description": "true = somente admins podem adicionar membros." } }, "required": [ "phone" ] }, "example": { "phone": "120363XXXX-group", "adminOnlyMessage": true, "requireAdminApproval": false } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/group/invite-link": { "get": { "operationId": "group-invite-link", "summary": "Obter link de convite", "description": "Retorna o link de convite do grupo.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "group_id", "in": "query", "required": true, "description": "ID do grupo (ID-group).", "schema": { "type": "string", "description": "ID do grupo (ID-group)." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": "https://chat.whatsapp.com/XXXXXXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/group-metadata/{phone}": { "get": { "operationId": "group-metadata", "summary": "Metadados do grupo", "description": "Retorna informações detalhadas do grupo incluindo participantes.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "phone", "in": "path", "required": true, "description": "ID do grupo (ID-group).", "schema": { "type": "string", "description": "ID do grupo (ID-group)." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/leave-group": { "post": { "operationId": "leave-group", "summary": "Sair do grupo", "description": "Remove a instância do grupo.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (ID-group)." } }, "required": [ "groupId" ] }, "example": { "groupId": "120363XXXX-group" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-group-photo": { "post": { "operationId": "update-group-photo", "summary": "Atualizar foto do grupo", "description": "Atualiza a foto do grupo usando base64 ou URL.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (ID-group)." }, "groupPhoto": { "type": "string", "description": "Foto em base64 ou URL." }, "image": { "type": "string", "description": "Alias de groupPhoto (base64 ou URL)." } }, "required": [ "groupId" ] }, "example": { "groupId": "120363XXXX-group", "image": "https://imagem.url/foto.jpg" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/group/photo": { "post": { "operationId": "group-photo-url", "summary": "Atualizar foto do grupo (por URL)", "description": "Atualiza a foto do grupo fornecendo uma URL pública de imagem.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (ID-group)." }, "photoUrl": { "type": "string", "description": "URL pública da imagem." }, "image": { "type": "string", "description": "Imagem em base64 (alternativa ao photoUrl)." } }, "required": [ "groupId" ] }, "example": { "groupId": "120363XXXX-group", "photoUrl": "https://imagem.url/foto.jpg" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/approve-participant": { "post": { "operationId": "approve-participant", "summary": "Aprovar solicitação de entrada", "description": "Aprova pedidos de participação em grupos com aprovação obrigatória habilitada.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo." }, "phones": { "type": "array", "items": {}, "description": "Números a aprovar." } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511777777777" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/reject-participant": { "post": { "operationId": "reject-participant", "summary": "Rejeitar solicitação de entrada", "description": "Rejeita pedidos de participação em grupos com aprovação obrigatória.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo." }, "phones": { "type": "array", "items": {}, "description": "Números a rejeitar." } }, "required": [ "groupId", "phones" ] }, "example": { "groupId": "120363XXXX-group", "phones": [ "5511777777777" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/redefine-invitation-link/{id}": { "post": { "operationId": "redefine-invitation-link", "summary": "Redefinir link de convite", "description": "Invalida o link de convite atual e gera um novo. Funciona para grupos e comunidades.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID do grupo ou comunidade.", "schema": { "type": "string", "description": "ID do grupo ou comunidade." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": "https://chat.whatsapp.com/NOVOID" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-group-description": { "post": { "operationId": "update-group-description", "summary": "Atualizar descrição do grupo", "description": "Define ou atualiza a descrição/bio do grupo.", "tags": [ "Grupos" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo (ID-group)." }, "groupDescription": { "type": "string", "description": "Novo texto da descrição (campo principal)." }, "description": { "type": "string", "description": "Alias de groupDescription (use um ou outro)." } }, "required": [ "groupId" ] }, "example": { "groupId": "120363XXXX-group", "groupDescription": "Grupo oficial de suporte Wafly" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter": { "get": { "operationId": "list-newsletters", "summary": "Listar newsletters", "description": "Retorna todas as newsletters da instância (próprias e seguidas).", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/create-newsletter": { "post": { "operationId": "create-newsletter", "summary": "Criar newsletter", "description": "Cria um novo canal/newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da newsletter." }, "description": { "type": "string", "description": "Descrição exibida no canal." } }, "required": [ "name" ] }, "example": { "name": "Meu Canal", "description": "Notícias e atualizações" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "newsletterId": "abcd1234@newsletter", "name": "Meu Canal" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/metadata/{newsletterId}": { "get": { "operationId": "newsletter-metadata", "summary": "Metadados da newsletter", "description": "Retorna informações detalhadas de uma newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter (@newsletter).", "schema": { "type": "string", "description": "ID da newsletter (@newsletter)." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/follow-newsletter": { "put": { "operationId": "follow-newsletter", "summary": "Seguir newsletter", "description": "A instância começa a seguir a newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." } }, "required": [ "id" ] }, "example": { "id": "abcd1234@newsletter" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/unfollow-newsletter": { "put": { "operationId": "unfollow-newsletter", "summary": "Deixar de seguir newsletter", "description": "A instância para de seguir a newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." } }, "required": [ "id" ] }, "example": { "id": "abcd1234@newsletter" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/settings/{newsletterId}": { "post": { "operationId": "newsletter-settings", "summary": "Configurações da newsletter", "description": "Atualiza as configurações de reação da newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter.", "schema": { "type": "string", "description": "ID da newsletter." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reactionCodes": { "type": "string", "description": "Tipo de reações permitidas.", "enum": [ "basic", "all" ] } } }, "example": { "reactionCodes": "all" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/mute-newsletter": { "put": { "operationId": "mute-newsletter", "summary": "Silenciar newsletter", "description": "Silencia as notificações de uma newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." } }, "required": [ "id" ] }, "example": { "id": "abcd1234@newsletter" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/delete-newsletter": { "delete": { "operationId": "delete-newsletter", "summary": "Deletar newsletter", "description": "Remove permanentemente uma newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." } }, "required": [ "id" ] }, "example": { "id": "abcd1234@newsletter" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/unmute-newsletter": { "put": { "operationId": "unmute-newsletter", "summary": "Reativar som da newsletter", "description": "Reativa as notificações de uma newsletter silenciada.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." } }, "required": [ "id" ] }, "example": { "id": "abcd1234@newsletter" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-newsletter-picture": { "post": { "operationId": "update-newsletter-picture", "summary": "Atualizar imagem da newsletter", "description": "Atualiza a foto/capa da newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." }, "pictureUrl": { "type": "string", "description": "URL pública da nova imagem." } }, "required": [ "id", "pictureUrl" ] }, "example": { "id": "abcd1234@newsletter", "pictureUrl": "https://imagens.exemplo.com/capa.jpg" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-newsletter-name": { "post": { "operationId": "update-newsletter-name", "summary": "Alterar nome da newsletter", "description": "Atualiza o nome/título da newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." }, "name": { "type": "string", "description": "Novo nome do canal." } }, "required": [ "id", "name" ] }, "example": { "id": "abcd1234@newsletter", "name": "Canal Wafly Oficial" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-newsletter-description": { "post": { "operationId": "update-newsletter-description", "summary": "Alterar descrição da newsletter", "description": "Atualiza a descrição exibida no canal.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da newsletter." }, "description": { "type": "string", "description": "Nova descrição do canal." } }, "required": [ "id", "description" ] }, "example": { "id": "abcd1234@newsletter", "description": "Notícias e novidades da Wafly" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/search-newsletter": { "post": { "operationId": "search-newsletter", "summary": "Buscar newsletters", "description": "Busca newsletters para descoberta/exploração com filtros de visualização e país.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "number", "description": "Máximo de resultados. Padrão: 50." }, "view": { "type": "string", "description": "Tipo de listagem.", "enum": [ "TRENDING", "POPULAR", "RECOMMENDED", "NEW" ] }, "searchText": { "type": "string", "description": "Texto de pesquisa livre." }, "filters": { "type": "object", "description": "Filtros adicionais: { countryCodes: string[] } — filtra por código de país (ex: [\"BR\"])." } } }, "example": { "limit": 20, "view": "TRENDING", "searchText": "tecnologia" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/accept-admin-invite/{newsletterId}": { "post": { "operationId": "newsletter-accept-admin-invite", "summary": "Aceitar convite de admin", "description": "Aceita um convite para se tornar administrador da newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter.", "schema": { "type": "string", "description": "ID da newsletter." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/remove-admin/{newsletterId}": { "post": { "operationId": "newsletter-remove-admin", "summary": "Remover administrador da newsletter", "description": "Remove os privilégios de administrador de um membro.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter.", "schema": { "type": "string", "description": "ID da newsletter." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Número do admin a remover." } }, "required": [ "phone" ] }, "example": { "phone": "5511999999999" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/revoke-admin-invite/{newsletterId}": { "post": { "operationId": "newsletter-revoke-admin-invite", "summary": "Revogar convite de admin", "description": "Cancela um convite de administrador pendente.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter.", "schema": { "type": "string", "description": "ID da newsletter." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Número cujo convite será revogado." } }, "required": [ "phone" ] }, "example": { "phone": "5511999999999" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/newsletter/transfer-ownership/{newsletterId}": { "post": { "operationId": "newsletter-transfer-ownership", "summary": "Transferir propriedade da newsletter", "description": "Transfere a titularidade (ownership) da newsletter para outro número.\n\nAção irreversível — a instância atual perderá o controle administrativo da newsletter.", "tags": [ "Newsletter / Canais" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "newsletterId", "in": "path", "required": true, "description": "ID da newsletter.", "schema": { "type": "string", "description": "ID da newsletter." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Número do novo proprietário." } }, "required": [ "phone" ] }, "example": { "phone": "5511888888888" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/chats": { "get": { "operationId": "list-chats", "summary": "Listar conversas", "description": "Retorna a lista de chats com paginação obrigatória.", "tags": [ "Chats" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "page", "in": "query", "required": true, "description": "Número da página.", "schema": { "type": "number", "description": "Número da página." } }, { "name": "pageSize", "in": "query", "required": true, "description": "Itens por página.", "schema": { "type": "number", "description": "Itens por página." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": [ { "id": "5511999999999", "name": "Maria Silva", "lastMessage": "Olá!", "timestamp": 1700000000 } ] } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/modify-chat": { "post": { "operationId": "modify-chat", "summary": "Marcar chat como lido/não lido", "description": "Altera o estado de leitura de uma conversa.", "tags": [ "Chats" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Chat a modificar.", "example": "5511999999999" }, "action": { "type": "string", "description": "Estado desejado do chat.", "enum": [ "read", "unread" ], "example": "read" } }, "required": [ "phone", "action" ] }, "example": { "phone": "5511999999999", "action": "read" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/chats/{phone}": { "get": { "operationId": "chat-metadata", "summary": "Metadados de um chat", "description": "Retorna informações detalhadas de uma conversa específica.", "tags": [ "Chats" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "phone", "in": "path", "required": true, "description": "Número ou ID do chat.", "schema": { "type": "string", "description": "Número ou ID do chat." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-webhook-received": { "put": { "operationId": "update-webhook-received", "summary": "Webhook — mensagem recebida", "description": "URL chamada sempre que a instância receber uma mensagem.", "tags": [ "Webhooks" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "URL de destino do webhook. Deixe vazio (\"\") para remover.", "example": "https://meuservidor.com/webhook/received" } }, "required": [ "value" ] }, "example": { "value": "https://meuservidor.com/webhook/received" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-webhook-delivery": { "put": { "operationId": "update-webhook-delivery", "summary": "Webhook — confirmação de entrega", "description": "URL chamada quando uma mensagem enviada é confirmada como entregue.", "tags": [ "Webhooks" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "URL de destino do webhook." } }, "required": [ "value" ] }, "example": { "value": "https://meuservidor.com/webhook/delivery" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-webhook-connected": { "put": { "operationId": "update-webhook-connected", "summary": "Webhook — instância conectada", "description": "URL chamada quando a instância se conecta ao WhatsApp.", "tags": [ "Webhooks" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "URL de destino." } }, "required": [ "value" ] }, "example": { "value": "https://meuservidor.com/webhook/connected" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/update-webhook-disconnected": { "put": { "operationId": "update-webhook-disconnected", "summary": "Webhook — instância desconectada", "description": "URL chamada quando a instância se desconecta.", "tags": [ "Webhooks" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "URL de destino." } }, "required": [ "value" ] }, "example": { "value": "https://meuservidor.com/webhook/disconnected" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities": { "get": { "operationId": "list-communities", "summary": "Listar comunidades", "description": "Retorna todas as comunidades da instância.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "create-community", "summary": "Criar comunidade", "description": "Cria uma nova comunidade com participantes iniciais.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da comunidade." }, "description": { "type": "string", "description": "Descrição." }, "participants": { "type": "array", "items": {}, "description": "Números iniciais." } }, "required": [ "name" ] }, "example": { "name": "Minha Comunidade", "description": "Grupos de clientes" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities/link": { "post": { "operationId": "link-community", "summary": "Vincular grupos à comunidade", "description": "Adiciona grupos existentes a uma comunidade.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "communityId": { "type": "string", "description": "ID da comunidade." }, "groupsPhones": { "type": "array", "items": {}, "description": "IDs dos grupos (ID-group)." } }, "required": [ "communityId", "groupsPhones" ] }, "example": { "communityId": "comID-group", "groupsPhones": [ "120363XXXX-group" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities/unlink": { "post": { "operationId": "unlink-community", "summary": "Desvincular grupos da comunidade", "description": "Remove grupos de uma comunidade.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "communityId": { "type": "string", "description": "ID da comunidade." }, "groupsPhones": { "type": "array", "items": {}, "description": "IDs dos grupos." } }, "required": [ "communityId", "groupsPhones" ] }, "example": { "communityId": "comID-group", "groupsPhones": [ "120363XXXX-group" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities-metadata/{communityId}": { "get": { "operationId": "community-metadata", "summary": "Metadados da comunidade", "description": "Retorna informações detalhadas da comunidade incluindo grupos vinculados e participantes.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "communityId", "in": "path", "required": true, "description": "ID da comunidade.", "schema": { "type": "string", "description": "ID da comunidade." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities/settings": { "post": { "operationId": "community-settings", "summary": "Configurações da comunidade", "description": "Atualiza permissões da comunidade, como quem pode adicionar novos grupos.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "communityId": { "type": "string", "description": "ID da comunidade." }, "whoCanAddNewGroups": { "type": "string", "description": "Define quem pode adicionar novos grupos à comunidade.", "enum": [ "admins", "all" ] } }, "required": [ "communityId", "whoCanAddNewGroups" ] }, "example": { "communityId": "comID-group", "whoCanAddNewGroups": "admins" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/communities/{communityId}": { "delete": { "operationId": "delete-community", "summary": "Desativar comunidade", "description": "Desativa e remove permanentemente uma comunidade.\n\nAção irreversível — todos os grupos vinculados serão desassociados da comunidade.", "tags": [ "Comunidades" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "communityId", "in": "path", "required": true, "description": "ID da comunidade.", "schema": { "type": "string", "description": "ID da comunidade." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/config": { "get": { "operationId": "call-config-get", "summary": "Ver configuração de chamadas", "description": "Retorna como a instância trata chamadas recebidas. onIncoming vazio significa que nada foi configurado e a ligação toca normalmente no celular.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "instanceId": "MINHA_INSTANCE", "onIncoming": "mp3", "mp3": { "url": "https://exemplo.com/recado.mp3", "hangupAfter": true }, "ai": { "voiceId": "pt-BR-female", "aiEndpoint": "https://meu-agente/voz" }, "human": { "notifyUrl": "https://meu-crm/chamada" } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "put": { "operationId": "call-config-set", "summary": "Configurar chamadas recebidas", "description": "Define o que fazer quando alguém liga para o número da instância.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.\n\nNos modos ai e human esta versão atende a ligação e dispara o webhook; o áudio de ida e volta com a IA ainda não está ligado.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onIncoming": { "type": "string", "description": "reject recusa a ligação; mp3 atende e toca o áudio configurado; ai atende e dispara o webhook ai_incoming; human dispara o webhook human_needed. Se ficar vazio, a ligação toca normalmente no celular.", "enum": [ "reject", "mp3", "ai", "human" ], "example": "mp3" }, "mp3": { "type": "object", "description": "Usado quando onIncoming=mp3. Campos: url (áudio a tocar) e hangupAfter (desligar ao terminar).", "example": "{ \"url\": \"https://exemplo.com/recado.mp3\", \"hangupAfter\": true }" }, "ai": { "type": "object", "description": "Usado quando onIncoming=ai. Campos: voiceId e aiEndpoint." }, "human": { "type": "object", "description": "Usado quando onIncoming=human. Campo: notifyUrl." } }, "required": [ "onIncoming" ] }, "example": { "onIncoming": "mp3", "mp3": { "url": "https://exemplo.com/recado.mp3", "hangupAfter": true } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "value": true } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/start": { "post": { "operationId": "call-start", "summary": "Iniciar chamada", "description": "Faz uma chamada de voz para um número.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.\n\nLigar para quem nunca falou com o seu número é o mesmo risco de bloqueio de qualquer contato frio.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Número a chamar.", "example": "5511999999999" }, "video": { "type": "boolean", "description": "Chamada de vídeo em vez de voz." }, "mp3Url": { "type": "string", "description": "Áudio a tocar assim que a chamada for atendida." }, "mp3Base64": { "type": "string", "description": "Alternativa a mp3Url, com o áudio embutido em base64." }, "hangupAfter": { "type": "boolean", "description": "Desliga automaticamente quando o áudio terminar." } }, "required": [ "phone" ] }, "example": { "phone": "5511999999999", "mp3Url": "https://exemplo.com/recado.mp3", "hangupAfter": true } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "callId": "3EB0XXXX" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/accept": { "post": { "operationId": "call-accept", "summary": "Atender chamada", "description": "Atende uma chamada em curso.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." } }, "required": [ "callId" ] }, "example": { "callId": "3EB0XXXX" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/reject": { "post": { "operationId": "call-reject", "summary": "Recusar chamada", "description": "Recusa uma chamada recebida.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." } }, "required": [ "callId" ] }, "example": { "callId": "3EB0XXXX" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/terminate": { "post": { "operationId": "call-terminate", "summary": "Encerrar chamada", "description": "Desliga uma chamada em andamento.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." } }, "required": [ "callId" ] }, "example": { "callId": "3EB0XXXX" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/play": { "post": { "operationId": "call-play", "summary": "Tocar áudio na chamada", "description": "Reproduz um MP3 dentro de uma chamada ativa.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." }, "url": { "type": "string", "description": "URL do MP3 a tocar." }, "base64": { "type": "string", "description": "Alternativa a url, com o áudio embutido." }, "hangupAfter": { "type": "boolean", "description": "Desliga quando o áudio terminar." } }, "required": [ "callId" ] }, "example": { "callId": "3EB0XXXX", "url": "https://exemplo.com/recado.mp3", "hangupAfter": true } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/say": { "post": { "operationId": "call-say", "summary": "Falar texto na chamada (TTS)", "description": "Converte texto em voz e reproduz dentro da chamada.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." }, "text": { "type": "string", "description": "Texto a ser falado." }, "voiceId": { "type": "string", "description": "Voz a usar na síntese." }, "hangupAfter": { "type": "boolean", "description": "Desliga quando terminar de falar." } }, "required": [ "callId", "text" ] }, "example": { "callId": "3EB0XXXX", "text": "Olá, sua entrega chega hoje às 14h." } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/webrtc": { "post": { "operationId": "call-webrtc", "summary": "Ponte WebRTC", "description": "Troca o SDP para ligar a chamada a um cliente WebRTC (ex.: atendimento humano pelo navegador).\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID da chamada." }, "sdpOffer": { "type": "string", "description": "SDP offer do cliente." } }, "required": [ "callId", "sdpOffer" ] }, "example": { "callId": "3EB0XXXX", "sdpOffer": "v=0\r\no=- ..." } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/{callId}/record/start": { "post": { "operationId": "call-record-start", "summary": "Iniciar gravação", "description": "Começa a gravar o áudio da chamada.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.\n\nGravar chamada exige base legal e, em geral, aviso ao interlocutor.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID da chamada.", "schema": { "type": "string", "description": "ID da chamada." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/{callId}/record/stop": { "post": { "operationId": "call-record-stop", "summary": "Parar gravação", "description": "Encerra a gravação em andamento.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID da chamada.", "schema": { "type": "string", "description": "ID da chamada." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/{callId}/recording": { "get": { "operationId": "call-recording", "summary": "Baixar gravação", "description": "Retorna o MP3 da chamada gravada. Responde 404 quando não há gravação para o callId.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.\n\nA resposta é o binário do áudio (audio/mpeg), não JSON.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID da chamada.", "schema": { "type": "string", "description": "ID da chamada." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-bridge-whats/instances/{instance}/token/{token}/call/{callId}/transcript": { "get": { "operationId": "call-transcript-get", "summary": "Ver transcrição", "description": "Retorna a transcrição da chamada, segmentada por quem falou.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID da chamada.", "schema": { "type": "string", "description": "ID da chamada." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "callId": "3EB0XXXX", "instanceId": "MINHA_INSTANCE", "segments": [ { "speaker": "caller", "text": "Alô?", "at": 1700000000000 }, { "speaker": "ai", "text": "Olá! Em que posso ajudar?", "at": 1700000002000 } ], "updated": 1700000002000 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "call-transcript-post", "summary": "Anexar transcrição", "description": "Adiciona segmentos à transcrição da chamada. Serve para quem roda o próprio motor de fala e quer guardar o resultado junto da chamada.\n\nBeta: as chamadas de voz precisam ser ativadas para a sua instância. Enquanto não estiverem, todos os endpoints desta seção respondem 503. Fale com o suporte para habilitar.", "tags": [ "Chamadas (beta)" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID da chamada.", "schema": { "type": "string", "description": "ID da chamada." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "segments": { "type": "array", "items": {}, "description": "Trechos da conversa. Cada item tem speaker (caller, ai ou agent), text e at (unix ms)." } }, "required": [ "segments" ] }, "example": { "segments": [ { "speaker": "caller", "text": "Alô?", "at": 1700000000000 } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/instances/{id}/capabilities": { "get": { "operationId": "product-instance-capabilities", "summary": "Conexões · Consultar capacidades", "description": "Mostra o que a conexão realmente pode fazer no provider atual. AVAILABLE libera o recurso; UNAVAILABLE ou PLANNED devem bloquear a ação na integração.\n\nCapacidade disponível não substitui a elegibilidade da conversa. Consulte também /v1/conversations/{conversationId}/eligibility antes do envio.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID interno da conexão retornado pela Wafly.", "schema": { "type": "string", "description": "ID interno da conexão retornado pela Wafly." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "provider": "OFFICIAL", "version": 5, "capabilities": [ { "name": "SEND_TEXT", "availability": "AVAILABLE", "reasonCode": null }, { "name": "SEND_TEMPLATE", "availability": "AVAILABLE", "reasonCode": null }, { "name": "SEND_FLOW", "availability": "AVAILABLE", "reasonCode": null }, { "name": "GROUPS", "availability": "UNAVAILABLE", "reasonCode": "NOT_SUPPORTED_BY_PROVIDER" } ] } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/instances/{id}/webhook-deliveries": { "get": { "operationId": "product-instance-webhook-deliveries", "summary": "Conexões · Histórico de entrega de webhook", "description": "Lista as tentativas mais recentes de entrega do webhook do cliente para esta conexão, com estado legível e próxima ação. Diagnóstico apenas: não dispara retry, replay ou teste de destino. Hoje só conexões QR/Flex têm este histórico; uma conexão Oficial responde supported=false.\n\ndestination nunca inclui query string nem segredo — é reduzido à origem (esquema+host) antes de sair do backend.\n\nwireVariant PRIMARY é o callback principal; LEGACY_101 é o envio secundário legado ao mesmo destino.\n\nsupported=false (com attempts=[]) significa que a capability não existe para o provider desta conexão, não que o histórico esteja vazio.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID interno da conexão retornado pela Wafly.", "schema": { "type": "string", "description": "ID interno da conexão retornado pela Wafly." } }, { "name": "limit", "in": "query", "required": false, "description": "Máximo de tentativas retornadas (o servidor aplica um teto e um padrão independentes do solicitado).", "schema": { "type": "integer", "description": "Máximo de tentativas retornadas (o servidor aplica um teto e um padrão independentes do solicitado).", "example": "20" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "supported": true, "limit": 20, "attempts": [ { "eventType": "DeliveryCallback", "wireVariant": "PRIMARY", "attemptSequence": 1, "destination": "https://cliente.example.com", "outcome": "FAILED", "httpStatus": 404, "failureReason": null, "state": "Destino não encontrado", "nextAction": "Verifique se a URL configurada ainda existe e aceita o método esperado", "attemptedAt": "2026-09-15T12:00:00Z" } ] } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/contacts": { "get": { "operationId": "product-contacts-list", "summary": "Contatos · Listar e pesquisar", "description": "Lista a agenda unificada da conta, incluindo contatos vinculados a conexões Oficial e Flex.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } }, { "name": "search", "in": "query", "required": false, "description": "Busca por nome, e-mail ou telefone.", "schema": { "type": "string", "description": "Busca por nome, e-mail ou telefone.", "example": "Maria" } }, { "name": "listId", "in": "query", "required": false, "description": "Filtra por lista ou segmento.", "schema": { "type": "string", "description": "Filtra por lista ou segmento." } }, { "name": "tag", "in": "query", "required": false, "description": "Filtra por tag.", "schema": { "type": "string", "description": "Filtra por tag." } }, { "name": "connectionId", "in": "query", "required": false, "description": "Filtra por conexão WhatsApp.", "schema": { "type": "string", "description": "Filtra por conexão WhatsApp." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "contact_01", "name": "Maria Silva", "email": "maria@empresa.com", "phone": "5511999999999", "identities": [ { "connectionId": "connection_01", "provider": "OFFICIAL", "channel": "WHATSAPP", "address": "5511999999999", "primary": true } ], "tags": [ "cliente" ], "customFields": { "plano": "pro" }, "listIds": [ "list_01" ], "consentStatus": "VERIFIED_ACTIVE", "consentTimeline": [], "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/contacts/{contactId}": { "get": { "operationId": "product-contacts-get", "summary": "Contatos · Consultar um contato", "description": "Retorna perfil, identidades por conexão, listas, campos personalizados e linha do tempo de consentimento.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "ID do contato na Wafly.", "schema": { "type": "string", "description": "ID do contato na Wafly." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "contact_01", "name": "Maria Silva", "email": "maria@empresa.com", "phone": "5511999999999", "identities": [ { "connectionId": "connection_01", "provider": "OFFICIAL", "channel": "WHATSAPP", "address": "5511999999999", "primary": true } ], "tags": [ "cliente" ], "customFields": { "plano": "pro" }, "listIds": [ "list_01" ], "consentStatus": "VERIFIED_ACTIVE", "consentTimeline": [], "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "patch": { "operationId": "product-contacts-patch", "summary": "Contatos · Atualizar perfil", "description": "Atualiza nome, e-mail, tags, campos, listas ou acrescenta um evento de consentimento.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "ID do contato na Wafly.", "schema": { "type": "string", "description": "ID do contato na Wafly." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome." }, "email": { "type": "string", "description": "Novo e-mail." }, "tags": { "type": "array", "items": {}, "description": "Conjunto completo de tags." }, "customFields": { "type": "object", "description": "Conjunto completo de campos personalizados." }, "listIds": { "type": "array", "items": {}, "description": "Conjunto completo de listas estáticas." }, "consent": { "type": "object", "description": "Novo evento de consentimento." } } }, "example": { "tags": [ "cliente", "vip" ], "customFields": { "plano": "enterprise" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "contact_01", "name": "Maria Silva", "email": "maria@empresa.com", "phone": "5511999999999", "identities": [ { "connectionId": "connection_01", "provider": "OFFICIAL", "channel": "WHATSAPP", "address": "5511999999999", "primary": true } ], "tags": [ "cliente" ], "customFields": { "plano": "pro" }, "listIds": [ "list_01" ], "consentStatus": "VERIFIED_ACTIVE", "consentTimeline": [], "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/contacts/upsert": { "post": { "operationId": "product-contacts-upsert", "summary": "Contatos · Criar ou atualizar", "description": "Faz upsert idempotente pela identidade da conexão. O accountId sempre vem do Bearer e nunca deve ser enviado no payload.\n\nO mesmo contrato também está disponível em POST /v1/contacts.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string", "description": "Conexão Oficial ou Flex que identifica o contato." }, "phone": { "type": "string", "description": "Número com DDI, somente dígitos.", "example": "5511999999999" }, "name": { "type": "string", "description": "Nome do contato." }, "email": { "type": "string", "description": "E-mail válido." }, "tags": { "type": "array", "items": {}, "description": "Tags para segmentação." }, "customFields": { "type": "object", "description": "Campos personalizados chave/valor." }, "listIds": { "type": "array", "items": {}, "description": "Listas estáticas associadas." }, "consent": { "type": "object", "description": "Evento auditável de consentimento." } }, "required": [ "connectionId", "phone" ] }, "example": { "connectionId": "connection_01", "phone": "5511999999999", "name": "Maria Silva", "email": "maria@empresa.com", "tags": [ "cliente" ], "customFields": { "plano": "pro" }, "listIds": [ "list_01" ], "consent": { "status": "VERIFIED_ACTIVE", "purpose": "WHATSAPP_MESSAGES", "source": "CHECKOUT", "evidenceRef": "order_123", "occurredAt": "2026-09-13T12:00:00Z" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "contact_01", "name": "Maria Silva", "email": "maria@empresa.com", "phone": "5511999999999", "identities": [ { "connectionId": "connection_01", "provider": "OFFICIAL", "channel": "WHATSAPP", "address": "5511999999999", "primary": true } ], "tags": [ "cliente" ], "customFields": { "plano": "pro" }, "listIds": [ "list_01" ], "consentStatus": "VERIFIED_ACTIVE", "consentTimeline": [], "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/contact-lists": { "get": { "operationId": "product-contact-lists-list", "summary": "Listas · Listar listas e segmentos", "description": "Lista audiências reutilizáveis com a contagem atual de contatos.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "list_01", "name": "Clientes ativos", "description": "Clientes com consentimento confirmado", "type": "DYNAMIC", "criteria": { "tagsAll": [ "cliente" ], "customFields": { "plano": "pro" }, "consentStatus": "VERIFIED_ACTIVE", "connectionId": "connection_01" }, "contactCount": 142, "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } ], "pagination": { "page": 1, "limit": 100, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "product-contact-lists-create", "summary": "Listas · Criar lista ou segmento", "description": "Cria uma lista STATIC ou um segmento DYNAMIC. Segmentos recalculam a audiência pelos critérios.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da lista." }, "description": { "type": "string", "description": "Descrição curta." }, "type": { "type": "string", "description": "STATIC ou DYNAMIC.", "enum": [ "STATIC", "DYNAMIC" ] }, "criteria": { "type": "object", "description": "Critérios para segmento dinâmico." } }, "required": [ "name" ] }, "example": { "name": "Clientes ativos", "description": "Clientes Pro com consentimento", "type": "DYNAMIC", "criteria": { "tagsAll": [ "cliente" ], "customFields": { "plano": "pro" }, "consentStatus": "VERIFIED_ACTIVE", "connectionId": "connection_01" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "list_01", "name": "Clientes ativos", "description": "Clientes com consentimento confirmado", "type": "DYNAMIC", "criteria": { "tagsAll": [ "cliente" ], "customFields": { "plano": "pro" }, "consentStatus": "VERIFIED_ACTIVE", "connectionId": "connection_01" }, "contactCount": 142, "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/contact-lists/{listId}": { "get": { "operationId": "product-contact-lists-get", "summary": "Listas · Consultar lista ou segmento", "description": "Retorna definição, critérios e contagem atual sem expor contatos fora da conta autenticada.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "description": "ID da lista ou segmento.", "schema": { "type": "string", "description": "ID da lista ou segmento." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "list_01", "name": "Clientes ativos", "description": "Clientes com consentimento confirmado", "type": "DYNAMIC", "criteria": { "tagsAll": [ "cliente" ], "customFields": { "plano": "pro" }, "consentStatus": "VERIFIED_ACTIVE", "connectionId": "connection_01" }, "contactCount": 142, "createdAt": "2026-09-13T12:00:00Z", "updatedAt": "2026-09-13T12:00:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations": { "get": { "operationId": "product-conversations-list", "summary": "Conversas · Listar", "description": "Lista conversas unificadas com provider, contato, última mensagem, não lidas e janela de atendimento.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } }, { "name": "instanceId", "in": "query", "required": false, "description": "Filtra por conexão.", "schema": { "type": "string", "description": "Filtra por conexão." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "conversation_01", "instanceId": "connection_01", "connectionName": "Suporte", "provider": "OFFICIAL", "contact": { "id": "contact_01", "name": "Maria", "phone": "5511999999999", "status": "RESOLVED" }, "lastMessage": { "direction": "INBOUND", "type": "TEXT", "status": "RECEIVED", "at": "2026-09-13T12:00:00Z" }, "serviceWindow": { "status": "OPEN", "expiresAt": "2026-09-14T12:00:00Z", "hours": 24 }, "unreadCount": 1, "updatedAt": "2026-09-13T12:00:00Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations/{conversationId}/messages": { "get": { "operationId": "product-conversations-messages", "summary": "Conversas · Listar mensagens", "description": "Retorna o histórico paginado de mensagens de uma conversa da conta.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa.", "schema": { "type": "string", "description": "ID da conversa." } }, { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "message_01", "direction": "OUTBOUND", "type": "TEXT", "content": { "text": "Olá, Maria!" }, "status": "DELIVERED", "failureCode": null, "occurredAt": "2026-09-13T12:01:00Z" } ], "pagination": { "page": 1, "limit": 50, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "product-conversations-send-text", "summary": "Conversas · Enviar texto", "description": "Envia texto pelo provider da conversa. Na Oficial, texto livre exige janela de atendimento elegível.\n\nChaves aceitam letras, números, ponto, underscore, dois-pontos e hífen. Reutilize a mesma chave no retry técnico.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa.", "schema": { "type": "string", "description": "ID da conversa." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Texto da mensagem." }, "idempotencyKey": { "type": "string", "description": "Chave estável de 8 a 200 caracteres para retry seguro." } }, "required": [ "text", "idempotencyKey" ] }, "example": { "text": "Olá, Maria! Como posso ajudar?", "idempotencyKey": "crm-message-0001" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "messageId": "message_01", "provider": "OFFICIAL", "providerMessageId": "wamid.example", "status": "ACCEPTED" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations/{conversationId}/eligibility": { "get": { "operationId": "product-conversations-eligibility", "summary": "Conversas · Verificar elegibilidade", "description": "Decide se o envio é permitido antes de enviar. Expõe janela, provider, disponibilidade do dispatch e motivo acionável.\n\nA Wafly nunca troca Oficial por Flex, ou Flex por Oficial, de forma silenciosa.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa.", "schema": { "type": "string", "description": "ID da conversa." } }, { "name": "messageType", "in": "query", "required": false, "description": "Formato a validar. O padrão é TEXT; use FLOW antes de enviar um formulário.", "schema": { "type": "string", "description": "Formato a validar. O padrão é TEXT; use FLOW antes de enviar um formulário.", "enum": [ "TEXT", "TEMPLATE", "IMAGE", "AUDIO", "VIDEO", "DOCUMENT", "STICKER", "LOCATION", "FLOW" ], "example": "TEXT" } }, { "name": "provider", "in": "query", "required": false, "description": "OFFICIAL ou FLEX. Se divergir da conversa, a chamada falha.", "schema": { "type": "string", "description": "OFFICIAL ou FLEX. Se divergir da conversa, a chamada falha.", "enum": [ "OFFICIAL", "FLEX" ] } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "conversationId": "conversation_01", "provider": "OFFICIAL", "messageKind": "TEXT", "mode": "SERVICE_WINDOW", "eligibleByPolicy": true, "dispatchReady": true, "reasonCode": null, "windowStatus": "OPEN", "windowExpiresAt": "2026-09-14T12:00:00Z", "providerFallback": false } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/official/flows/sendable": { "get": { "operationId": "product-official-flows-sendable", "summary": "Flows · Listar formulários enviáveis", "description": "Lista os Flows publicados que podem ser usados agora em uma conexão da API Oficial. Use o campo id retornado como flowId no envio; nunca envie o ID da Meta diretamente.\n\nTHROTTLED também pode aparecer: o Flow continua enviável, mas a Meta pode reduzir a velocidade. Rascunhos, bloqueados e descontinuados não são retornados.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "instanceId", "in": "query", "required": true, "description": "ID local da conexão Oficial.", "schema": { "type": "string", "description": "ID local da conexão Oficial.", "example": "connection_01" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": [ { "id": "flow_01", "instanceId": "connection_01", "name": "Agendar atendimento", "status": "PUBLISHED", "sendable": true } ] } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations/{conversationId}/read": { "post": { "operationId": "product-conversations-mark-read", "summary": "Conversas · Marcar como lida", "description": "Confirma somente as mensagens exibidas na inbox da Wafly. Não envia recibo de leitura ao WhatsApp.\n\nSe uma nova mensagem chegar durante a confirmação, ela permanece não lida.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa.", "schema": { "type": "string", "description": "ID da conversa." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seenCount": { "type": "integer", "description": "Quantidade não lida observada pelo cliente antes da confirmação." } }, "required": [ "seenCount" ] }, "example": { "seenCount": 3 } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "conversationId": "conversation_01", "unreadCount": 0 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations/{conversationId}/template-messages": { "post": { "operationId": "product-conversations-send-template", "summary": "Conversas · Enviar template", "description": "Envia uma revisão aprovada de template na conversa, inclusive fora da janela quando a política permitir.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa.", "schema": { "type": "string", "description": "ID da conversa." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "description": "ID local do template aprovado." }, "revision": { "type": "integer", "description": "Revisão local aprovada." }, "parameters": { "type": "array", "items": {}, "description": "Valores posicionais do BODY na ordem {{1}}, {{2}}, etc." }, "idempotencyKey": { "type": "string", "description": "Chave estável para retry sem duplicar." } }, "required": [ "templateId", "revision", "idempotencyKey" ] }, "example": { "templateId": "template_01", "revision": 2, "parameters": [ "Maria", "PRO" ], "idempotencyKey": "crm-template-0001" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "messageId": "message_02", "provider": "OFFICIAL", "providerMessageId": "wamid.example", "status": "ACCEPTED" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/conversations/{conversationId}/flow-messages": { "post": { "operationId": "product-conversations-send-flow", "summary": "Conversas · Enviar formulário do WhatsApp", "description": "Envia um WhatsApp Flow publicado como mensagem interativa pela conexão Oficial da conversa. O envio direto só é permitido enquanto a janela de atendimento de 24 horas estiver aberta ou perto de fechar.\n\nAntes do POST, consulte GET /v1/conversations/{conversationId}/eligibility?messageType=FLOW. Prossiga somente quando dispatchReady=true.\n\nSe a janela fechar, a Wafly responde OFFICIAL_TEMPLATE_REQUIRED e não troca o formato automaticamente. Envie explicitamente um template aprovado que contenha um botão FLOW pelo endpoint /template-messages.\n\nUma resposta ACCEPTED confirma que a Meta aceitou o envio, não que o contato abriu ou concluiu o formulário. Acompanhe o histórico e os eventos de status.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl --request POST 'https://wafly.com.br/api-managment/v1/conversations/SEU_CONVERSATION_ID/flow-messages' \\\n --header 'Authorization: Bearer SEU_BEARER_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"flowId\": \"flow_01\",\n \"cta\": \"Agendar agora\",\n \"bodyText\": \"Escolha o melhor horário para o seu atendimento.\",\n \"idempotencyKey\": \"crm-flow-20260914-0001\"\n }'" } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID da conversa na Wafly.", "schema": { "type": "string", "description": "ID da conversa na Wafly." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flowId": { "type": "string", "description": "ID local retornado por GET /official/flows/sendable." }, "cta": { "type": "string", "description": "Texto do botão que abre o formulário, com até 20 caracteres.", "example": "Agendar agora" }, "bodyText": { "type": "string", "description": "Mensagem que acompanha o formulário, com até 1024 caracteres." }, "headerText": { "type": "string", "description": "Título opcional, com até 60 caracteres." }, "footerText": { "type": "string", "description": "Rodapé opcional, com até 60 caracteres." }, "initialScreen": { "type": "string", "description": "Tela inicial. Torna-se obrigatório quando actionPayloadData é enviado." }, "actionPayloadData": { "type": "object", "description": "Até 20 valores iniciais escalares (texto, número ou booleano), com chaves alfanuméricas/underscore e até 512 caracteres por valor." }, "idempotencyKey": { "type": "string", "description": "Chave estável da intenção. Reutilize a mesma somente no retry técnico; nunca em outro envio." } }, "required": [ "flowId", "cta", "bodyText", "idempotencyKey" ] }, "example": { "flowId": "flow_01", "cta": "Agendar agora", "bodyText": "Escolha o melhor horário para o seu atendimento.", "headerText": "Agendamento", "footerText": "Leva menos de um minuto", "initialScreen": "APPOINTMENT", "actionPayloadData": { "contact_id": "contact_01", "is_customer": true }, "idempotencyKey": "crm-flow-20260914-0001" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "messageId": "crm-flow-20260914-0001", "provider": "OFFICIAL", "providerMessageId": "wamid.example", "status": "ACCEPTED" } } } }, "400": { "description": "Payload inválido, Flow inexistente/não enviável, conexão por QR Code ou limites de texto excedidos. Códigos comuns: FLOW_NOT_FOUND, FLOW_NOT_SENDABLE, FLOW_CTA_TOO_LONG, FLOW_BODY_TOO_LONG e MESSAGE_TYPE_NOT_SUPPORTED_BY_PROVIDER." }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" }, "404": { "description": "CONVERSATION_NOT_FOUND: a conversa não existe nesta conta." }, "409": { "description": "Janela fechada, conexão indisponível ou conflito de idempotência. Códigos comuns: OFFICIAL_TEMPLATE_REQUIRED, CONNECTION_NOT_READY e OFFICIAL_MESSAGE_IDEMPOTENCY_CONFLICT." }, "422": { "description": "META_MESSAGE_REJECTED: a Meta recusou o payload depois da validação local." }, "429": { "description": "PROVIDER_RATE_LIMITED: a Meta limitou temporariamente os envios." }, "503": { "description": "Provider ou dispatch temporariamente indisponível. Reutilize a mesma idempotencyKey apenas quando a resposta indicar retry seguro." } } } }, "/api-managment/v1/automations": { "get": { "operationId": "product-automations-list", "summary": "Automações · Listar", "description": "Lista automações da conta por status ou busca.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } }, { "name": "status", "in": "query", "required": false, "description": "DRAFT, ACTIVE, PAUSED ou ARCHIVED.", "schema": { "type": "string", "description": "DRAFT, ACTIVE, PAUSED ou ARCHIVED.", "enum": [ "DRAFT", "ACTIVE", "PAUSED", "ARCHIVED" ] } }, { "name": "search", "in": "query", "required": false, "description": "Busca em nome e descrição.", "schema": { "type": "string", "description": "Busca em nome e descrição." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "automation_01", "name": "Boas-vindas", "status": "ACTIVE", "trigger": { "type": "INBOUND", "config": { "instanceId": "connection_01" } }, "actions": [ { "id": "send-welcome", "type": "SEND", "config": { "text": "Olá!" } } ], "executionCount": 10, "completedCount": 9, "failedCount": 1 } ], "pagination": { "page": 1, "limit": 25, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "post": { "operationId": "product-automations-create", "summary": "Automações · Criar", "description": "Cria um fluxo com gatilho, ações ordenadas, cooldown e controle de reentrada.\n\nAtivar uma automação falha de forma explícita quando o motor estiver desabilitado. Webhooks aceitam somente HTTPS sem credenciais ou query.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da automação." }, "description": { "type": "string", "description": "Descrição." }, "status": { "type": "string", "description": "DRAFT, ACTIVE, PAUSED ou ARCHIVED." }, "trigger": { "type": "object", "description": "Gatilho INBOUND, TAG, FIELD, REPLY ou WINDOW." }, "actions": { "type": "array", "items": {}, "description": "De 1 a 20 ações SEND, WAIT, WEBHOOK, UPDATE_CONTACT ou ASSIGN." }, "cooldownSeconds": { "type": "integer", "description": "Intervalo de 0 a 86400 segundos." }, "allowReentry": { "type": "boolean", "description": "Permite reentrada concorrente do mesmo contexto." } }, "required": [ "name", "trigger", "actions" ] }, "example": { "name": "Boas-vindas", "status": "DRAFT", "trigger": { "type": "INBOUND", "config": { "instanceId": "connection_01", "provider": "OFFICIAL" } }, "actions": [ { "id": "wait-1", "type": "WAIT", "config": { "minutes": 1 } }, { "id": "send-1", "type": "SEND", "config": { "text": "Olá!" } } ], "cooldownSeconds": 300, "allowReentry": false } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "automation_01", "name": "Boas-vindas", "status": "DRAFT", "trigger": { "type": "INBOUND", "config": { "instanceId": "connection_01", "provider": "OFFICIAL" } }, "actions": [ { "id": "wait-1", "type": "WAIT", "config": { "minutes": 1 } }, { "id": "send-1", "type": "SEND", "config": { "text": "Olá!" } } ], "cooldownSeconds": 300, "allowReentry": false, "executionCount": 0, "completedCount": 0, "failedCount": 0 } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/automations/{automationId}": { "get": { "operationId": "product-automations-get", "summary": "Automações · Consultar", "description": "Consulta a definição e os contadores de uma automação.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "ID da automação.", "schema": { "type": "string", "description": "ID da automação." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } }, "patch": { "operationId": "product-automations-update", "summary": "Automações · Atualizar ou ativar", "description": "Atualiza apenas os campos enviados. Use status ACTIVE para ativar, ou PAUSED para pausar.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "ID da automação.", "schema": { "type": "string", "description": "ID da automação." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Novo nome." }, "description": { "type": "string", "description": "Nova descrição." }, "status": { "type": "string", "description": "DRAFT, ACTIVE, PAUSED ou ARCHIVED." }, "trigger": { "type": "object", "description": "Novo gatilho." }, "actions": { "type": "array", "items": {}, "description": "Nova sequência de ações." }, "cooldownSeconds": { "type": "integer", "description": "Novo cooldown." }, "allowReentry": { "type": "boolean", "description": "Novo controle de reentrada." } } }, "example": { "status": "ACTIVE" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": {} } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/automations/{automationId}/executions": { "get": { "operationId": "product-automations-executions", "summary": "Automações · Listar execuções", "description": "Mostra o histórico paginado de execuções, progresso e falhas acionáveis.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "ID da automação.", "schema": { "type": "string", "description": "ID da automação." } }, { "name": "page", "in": "query", "required": false, "description": "Página iniciando em 1.", "schema": { "type": "integer", "description": "Página iniciando em 1.", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Itens por página (máximo 100).", "schema": { "type": "integer", "description": "Itens por página (máximo 100).", "example": "25" } }, { "name": "status", "in": "query", "required": false, "description": "RUNNING, WAITING, COMPLETED, FAILED ou CANCELLED.", "schema": { "type": "string", "description": "RUNNING, WAITING, COMPLETED, FAILED ou CANCELLED." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "id": "execution_01", "automationId": "automation_01", "status": "COMPLETED", "contactId": "contact_01", "conversationId": "conversation_01", "currentActionIndex": 2, "errorCode": null, "errorMessage": null, "startedAt": "2026-09-13T12:00:00Z", "finishedAt": "2026-09-13T12:01:00Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "pages": 1 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/v1/analytics/messaging": { "get": { "operationId": "product-analytics-messaging", "summary": "Analytics · Resultados de mensagens", "description": "Agrega recebidas, aceitas, enviadas, entregues, lidas e falhas com série temporal e cortes por provider, conexão, campanha e conversa.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data inicial no formato YYYY-MM-DD.", "schema": { "type": "string", "description": "Data inicial no formato YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data final no formato YYYY-MM-DD.", "schema": { "type": "string", "description": "Data final no formato YYYY-MM-DD.", "example": "2026-09-13" } }, { "name": "instanceId", "in": "query", "required": false, "description": "Filtra por conexão.", "schema": { "type": "string", "description": "Filtra por conexão." } }, { "name": "provider", "in": "query", "required": false, "description": "OFFICIAL ou FLEX.", "schema": { "type": "string", "description": "OFFICIAL ou FLEX.", "enum": [ "OFFICIAL", "FLEX" ] } }, { "name": "campaignId", "in": "query", "required": false, "description": "Filtra por campanha.", "schema": { "type": "string", "description": "Filtra por campanha." } }, { "name": "conversationId", "in": "query", "required": false, "description": "Filtra por conversa.", "schema": { "type": "string", "description": "Filtra por conversa." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "summary": { "received": 30, "processing": 0, "accepted": 100, "sent": 98, "delivered": 94, "read": 71, "failed": 2 }, "timeSeries": [ { "date": "2026-09-13", "received": 30, "processing": 0, "accepted": 100, "sent": 98, "delivered": 94, "read": 71, "failed": 2 } ], "breakdowns": { "providers": [], "connections": [], "campaigns": [], "conversations": [] }, "from": "2026-09-01", "to": "2026-09-13", "updatedAt": "2026-09-13T12:05:00Z" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/audience-preflight": { "post": { "operationId": "product-campaign-audience-preflight", "summary": "Campanhas · Pré-validar lista", "description": "Calcula aptos, consentimento, inválidos, duplicados e limite de frequência sem criar uma audiência.\n\nUma nova intenção pode reenviar ao mesmo contato. O limite de frequência é uma política configurável, não uma deduplicação global.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactListId": { "type": "string", "description": "Lista ou segmento da mesma conta." }, "connectionId": { "type": "string", "description": "Conexão de destino." }, "frequencyCapDays": { "type": "integer", "description": "0 desativa o limite; 1 a 365 define a janela." }, "bypassFrequencyCap": { "type": "boolean", "description": "Ignora somente o limite de frequência." }, "bypassReason": { "type": "string", "description": "Motivo auditável exigido para bypass." }, "variableMapping": { "type": "object", "description": "Mapeia variavel_N para name, email, phone ou custom.campo." } }, "required": [ "contactListId", "connectionId" ] }, "example": { "contactListId": "list_01", "connectionId": "connection_01", "frequencyCapDays": 7, "bypassFrequencyCap": false, "variableMapping": { "variavel_1": "name", "variavel_2": "custom.plano" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "total": 150, "eligible": 120, "consentBlocked": 12, "invalid": 3, "duplicates": 5, "recent": 10, "frequencyCapped": 10, "suppressed": 30, "canBypassFrequencyCap": true, "reasonCounts": { "NO_CONSENT": 12, "FREQUENCY_CAP": 10 }, "snapshot": { "listId": "list_01", "listName": "Clientes ativos", "listType": "DYNAMIC", "fields": [ "name", "email", "phone", "custom.plano" ], "contactCount": 150, "generatedAt": "2026-09-13T12:00:00Z", "connectionId": "connection_01", "frequencyCapDays": 7, "frequencyCapBypassed": false, "variableMapping": { "variavel_1": "name", "variavel_2": "custom.plano" } }, "sample": [] } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/audience-imports/from-contact-list": { "post": { "operationId": "product-campaign-audience-materialize", "summary": "Campanhas · Materializar lista", "description": "Cria uma audiência imutável a partir da lista/segmento e preserva o snapshot usado em cada destinatário.\n\nA materialização depende da capability contactListsEnabled=true. Nunca reutilize uma chave de idempotência para uma campanha diferente.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactListId": { "type": "string", "description": "Lista ou segmento da mesma conta." }, "connectionId": { "type": "string", "description": "Conexão de destino." }, "idempotencyKey": { "type": "string", "description": "Mesma chave no retry técnico; nova chave para uma nova intenção." }, "frequencyCapDays": { "type": "integer", "description": "0 desativa o limite; 1 a 365 define a janela." }, "bypassFrequencyCap": { "type": "boolean", "description": "Ignora somente o limite de frequência." }, "bypassReason": { "type": "string", "description": "Motivo auditável exigido para bypass." }, "variableMapping": { "type": "object", "description": "Mapeamento validado no preflight." } }, "required": [ "contactListId", "connectionId", "idempotencyKey" ] }, "example": { "contactListId": "list_01", "connectionId": "connection_01", "idempotencyKey": "campaign-intent-20260913-0001", "frequencyCapDays": 7, "bypassFrequencyCap": false, "variableMapping": { "variavel_1": "name", "variavel_2": "custom.plano" } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "importSummary": { "importId": "audience_01", "status": "COMPLETED", "totalRecipients": 150, "eligibleRecipients": 120, "suppressedRecipients": 30, "failureCode": null, "idempotentReplay": false }, "preflight": { "total": 150, "eligible": 120, "consentBlocked": 12, "invalid": 3, "duplicates": 5, "recent": 10, "frequencyCapped": 10, "suppressed": 30, "canBypassFrequencyCap": true, "reasonCounts": { "NO_CONSENT": 12, "FREQUENCY_CAP": 10 } } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/drafts": { "post": { "operationId": "product-campaign-create-draft", "summary": "Campanhas · Criar rascunho", "description": "Cria uma campanha vinculada à audiência imutável. Para Flow em massa, use o ID local de um template aprovado que contenha botão FLOW; não use o flowId neste endpoint.\n\nO template precisa pertencer à mesma conexão e estar aprovado, sincronizado e na revisão corrente. Botão Flow estático não exige components nem parâmetros por contato.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Conexão usada na materialização da audiência." }, "name": { "type": "string", "description": "Nome da campanha, com até 120 caracteres." }, "provider": { "type": "string", "description": "OFFICIAL ou FLEX.", "enum": [ "OFFICIAL", "FLEX" ] }, "templateId": { "type": "string", "description": "Obrigatório na Oficial. ID local do template aprovado, inclusive o template com botão Flow." }, "templateRevision": { "type": "integer", "description": "Revisão corrente aprovada do template Oficial." }, "templateLanguage": { "type": "string", "description": "Idioma do template Oficial, por exemplo pt_BR." }, "messageText": { "type": "string", "description": "Mensagem livre da campanha Flex. Não enviar na Oficial." }, "idempotencyKey": { "type": "string", "description": "Chave única desta intenção de campanha." }, "audienceImportId": { "type": "string", "description": "importId devolvido ao materializar a lista." } }, "required": [ "instanceId", "name", "provider", "idempotencyKey", "audienceImportId" ] }, "example": { "instanceId": "connection_01", "name": "Cadastro de interessados", "provider": "OFFICIAL", "templateId": "template_with_flow_01", "templateRevision": 1, "templateLanguage": "pt_BR", "idempotencyKey": "campaign-flow-20260915-0001", "audienceImportId": "audience_01" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "campaign": { "id": "campaign_01", "version": 1, "status": "DRAFT", "provider": "OFFICIAL", "templateId": "template_with_flow_01", "audienceAttached": false }, "idempotentReplay": false } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/{campaignId}/audience/attach": { "post": { "operationId": "product-campaign-attach-audience", "summary": "Campanhas · Preparar destinatários", "description": "Copia a próxima página da audiência imutável para a campanha e valida a composição de cada destinatário sem enviar mensagens.\n\nRepita enquanto audienceAttached=false e failureCode=AUDIENCE_ATTACHMENT_INCOMPLETE. Pare imediatamente em qualquer outra falha.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "ID devolvido ao criar o rascunho.", "schema": { "type": "string", "description": "ID devolvido ao criar o rascunho." } }, { "name": "limit", "in": "query", "required": false, "description": "Quantidade por chamada; use até 500.", "schema": { "type": "integer", "description": "Quantidade por chamada; use até 500.", "example": "500" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "campaign": { "id": "campaign_01", "version": 2, "status": "READY", "audienceAttached": true }, "copiedThisCall": 120, "preview": { "composable": true, "failureCode": null, "retryable": false } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/{campaignId}/start": { "post": { "operationId": "product-campaign-start", "summary": "Campanhas · Iniciar envio", "description": "Inicia uma campanha READY. O envio usa o provider e o template fixados no rascunho; não existe fallback silencioso.\n\nEnvie em X-Wafly-Campaign-Version a versão recebida na última resposta. HTTP 409 indica versão desatualizada ou transição incompatível.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl --request POST 'https://wafly.com.br/api-managment/campaigns/campaign_01/start' \\\n --header 'Authorization: Bearer SEU_BEARER_TOKEN' \\\n --header 'X-Wafly-Campaign-Version: 2'" } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "ID da campanha pronta.", "schema": { "type": "string", "description": "ID da campanha pronta." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "id": "campaign_01", "version": 3, "status": "RUNNING", "provider": "OFFICIAL", "templateId": "template_with_flow_01" } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } }, "/api-managment/campaigns/{campaignId}/overview": { "get": { "operationId": "product-campaign-overview", "summary": "Campanhas · Acompanhar resultados", "description": "Retorna estado, totais e resultados persistidos da campanha, incluindo aceita, enviada, entregue, lida e falha.", "tags": [ "API do Produto (Oficial + Flex)" ], "security": [ { "productBearer": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "ID da campanha.", "schema": { "type": "string", "description": "ID da campanha." } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "campaign": { "id": "campaign_01", "status": "COMPLETED", "totalRecipients": 120 }, "metrics": { "suppressed": 0, "accepted": 120, "sent": 120, "delivered": 116, "read": 82, "failed": 4 } } } } }, "401": { "description": "Credenciais inválidas ou ausentes" }, "402": { "description": "Assinatura inadimplente ou trial expirado" } } } } }, "tags": [ { "name": "Gerenciamento pela API", "description": "Crie e gerencie as instâncias da sua conta com Client-Token. Sem cobrança habilitada, a criação devolve um exemplo sem provisionar recursos." }, { "name": "Instância", "description": "Gerenciamento de sessão: conexão, status, QR Code e dispositivo." }, { "name": "Mensagens", "description": "Envio de mensagens de texto, mídia, interativas e muito mais." }, { "name": "Templates Oficiais — API", "description": "Crie, consulte e envie templates à Meta usando apenas Client-Token e credenciais da instância. A Wafly resolve os IDs técnicos da Meta." }, { "name": "Grupos", "description": "Criação, gerenciamento e configurações de grupos WhatsApp." }, { "name": "Newsletter / Canais", "description": "Gerenciamento de newsletters e canais (@newsletter)." }, { "name": "Chats", "description": "Listagem e metadados de conversas." }, { "name": "Webhooks", "description": "Configuração de URLs de callback para eventos da instância." }, { "name": "Comunidades", "description": "Super-grupos: criação, gestão e configurações de comunidades." }, { "name": "Chamadas (beta)", "description": "Chamadas de voz por WhatsApp: atender, recusar, tocar áudio, falar por TTS, gravar e transcrever. Requer ativação." }, { "name": "API do Produto (Oficial + Flex)", "description": "Agenda, conversas, automações, resultados e campanhas em um contrato tenant-scoped. Use Bearer JWT na base /api-managment; o provider selecionado nunca recebe fallback silencioso." } ], "components": { "securitySchemes": { "clientToken": { "type": "apiKey", "in": "header", "name": "Client-Token" }, "productBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }